Feedback from a full production build: opaque-500 service-role gap, activation prechecks, enum discovery, teardown ordering

[wms2537]

Context

Feedback from using the skill end-to-end to build & operate a production BytePlus
project (ModelArk, veFaaS Cloud Sandbox, TOS, APIG, RDS PostgreSQL,
VikingDB/Viking Memory, Message Queue for Kafka, KMS). The operating contract
worked well; the items below are where I lost the most time, roughly ranked by
cost. Concrete repro details included so they're actionable.

Suggested improvements

1. Opaque 500 on a create API often means a missing service-linked role — make this a documented signature

bp kafka CreateInstance returned inconsistent, undiagnosable InternalError
500s (and occasional 400s) even with fully docs-correct parameters. After ~7
attempts, the real cause turned out to be an un-authorized cross-service IAM
role (ServiceRoleForKafka, granting Kafka access to vpc + tos). The CLI/API
never surfaces this; only the console does, by redirecting the create flow to
console.byteplus.com/iam/service/attach_role/?ServiceName=Kafka ("Cross-service
access request" → "Authorize Now").

Ask: add guidance — "opaque 500 on a create API with correct params ⇒ suspect
a missing ServiceRoleFor<Service>; check the console create flow or IAM before
retrying the billable API." A table of which services need which service-linked
roles would be ideal. This is the single biggest gap: the failure mode is silent
and pushes you toward exactly the trial-and-error the skill warns against.

2. Service activation as a first-class precheck

KMS returned KMS_ServiceNotOpen; there is no CLI activation (console "Open now"
only). The skill mentions UI-only activation exists, but a concrete step would
help: "before first use, if you see *_ServiceNotOpen, direct the user to the
console to activate, then resume," plus a known list of activation-gated
services (KMS, ModelArk, Kafka, …).

3. Enum/spec discovery + JS-rendered docs

Valid values for ComputeSpec / Version / StorageType / KeyringType etc.
are not in bp <svc> <action> --help, and docs.byteplus.com pages are
SPA/JS-rendered so automated fetch frequently returns empty. Recommend the skill:
(a) point to a machine-readable source for enum values (API Explorer / OpenAPI /
Go SDK constants), and (b) warn that the doc site isn't reliably fetchable —
prefer the API doc's example request body verbatim.

4. Always use --body for nested params

--ChargeInfo.ChargeType PostPaid (dotted nested flag) produced a 500; the same
call with a nested --body JSON worked. The skill says "prefer --body for
complex requests" — strengthen to: "dotted nested flags (--A.B) are unreliable
for object/array params; always use --body."

5. List/AZ parameter quirks

bp kafka DescribeInstances requires PageNumber/PageSize (400 otherwise);
CreateInstance wants ZoneId (string), not Zones. Worth noting: describe/list
actions often need pagination params, and AZ param names vary — call the service's
DescribeAvailabilityZones first.

6. Value-format violations map to opaque 400/500s

A Kafka manager password containing # returned a 500; the same call with @
succeeded. Credential/password fields have undocumented character-class rules
that surface as opaque errors — recommend copying the doc's example value pattern.

7. Teardown ordering

DeleteInstance failed with OperationDenied.InstanceNotEmpty until the topic
and public address were deleted first, and the EIP wouldn't ReleaseEipAddress
until the public address was gone. The cleanup section could add: delete attached
children (topics, public addresses) → parent instance → EIP, and expect async
propagation between steps.

What worked well (please keep)

• Read-before-write / verify-after-write discipline.
• Mandatory cost disclosure before billable resources (kept the whole session
  spend-safe; clean, verified teardown at the end).
• Three-hyphen fixed flags (---region/---profile) and one structured --body.
• "Identify the single minimal UI step (activation / role consent) and resume" —
  exactly the right pattern for the console-only prerequisites in Bump actions/checkout from 4.3.1 to 7.0.0 #1/Bump actions/setup-python from 5.6.0 to 6.3.0 #2.

[wms2537]

Implemented and pushed in 4a8e88e.

The skill now covers:

• prerequisite-first handling for opaque create errors and ServiceRoleForKafka;
• programmatic CreateServiceLinkedRole discovery with explicit IAM approval;
• KMS service-activation handling;
• enum, AZ, pagination, and JavaScript-doc retrieval fallbacks;
• mandatory structured bodies for nested non-secret inputs and protected SDK handling for passwords;
• dependency-ordered Kafka/public-address/EIP teardown; and
• a forward evaluation and regression tests for this scenario.

I deliberately did not encode the observed # versus @ password behavior as a stable rule because current authoritative constraints must be retrieved and secrets must not be trialed through visible CLI arguments. All 68 offline tests, Ruff, compile checks, and the public-tree scan passed locally.