Report a failure and verify the fix
Use this workflow when a command fails, a result does not satisfy the request, or documented steps cannot be completed. An exit code of 0 can still produce a partial or inaccurate result. Start with the failing workflow URL and step, then send the expected and actual result to Orchestor.
Identify the failing step and prepare a reproduction without secrets. Show the report before sending it to Orchestor feedback, then keep the receipt ID.
1. Identify the failing stage
Use setup diagnosis to inspect authentication, workspace selection, permissions, and the actual read. If correcting an argument or target resolves the issue, return that result. Report a remaining defect, behavior that contradicts the contract, or instructions that cannot be followed.
Follow API errors and retry instructions. If a write outcome is unknown, read it back or use the original idempotency key. Do not repeat it with a new key. Empty data, authentication failures, and unimplemented proposed commands are not automatically product defects.
2. Prepare a reproducible report
Keep the following information within the 2,000-character message limit. The destination is Orchestor feedback intake.
| Information | What to record |
|---|---|
| Starting point | Workflow URL, failed step, and the user’s objective |
| Environment | Observed CLI version, OS, and agent |
| Reproduction | Redacted command, target type, and minimum required steps |
| Expected and actual | Expected output, observed error code or symptom, and timestamp |
| Evidence | A request ID returned by the response or an actual run ID; mark unavailable values explicitly |
| Attempts | Checks, retries, their results, and available workarounds |
Exclude API keys, authorization headers, environment dumps, complete conversations, and customer answer text. Present a reviewable report and send it when the user has requested submission or granted standing permission. If automatic reporting is disabled, return only the draft. Remove sensitive content before sending; do not rely only on server redaction.
client_context stores predefined fields such as url, route, app_revision, and locale. Arbitrary workflow_id and run_id fields are discarded. Include these references in message for now. Set conversation_id only for an actual Orchestor conversation, not another system’s run ID.
Save this JSON as feedback.json, replacing bracketed text with verified information.
{
"category": "slow-or-broken",
"message": "Workflow: /cli/workflows/install-first-read\nStep: [failed step]\nCLI/OS/agent: [measured versions]\nReproduce: [redacted command]\nExpected: [expected result]\nActual: [error and time]\nRequest/run ID: [observed ID or unavailable]\nAttempted: [checks and results]",
"client_context": {
"route": "/cli/workflows/install-first-read",
"locale": "en"
}
}Choose inaccurate for inaccurate output, instruction-not-followed for instruction mismatch, out-of-scope for the wrong subject, slow-or-broken for operational failures, or other. See the feedbacks reference for the category contract.
When using --stdin, the JSON category satisfies the required body field, so do not repeat it as --category. Use --category when sending the body through flags only.
3. Review and submit
Authenticated submission is the default. If authentication works, select the Workspace for the report. If login itself fails, use --anonymous. Anonymous submission does not use a saved API key, browser cookie, or configured Workspace. You cannot combine it with --workspace or --screenshot-file-ids.
Replace WORKSPACE_ID with the report target. Generate a key once for this report and keep it locally with the report for retries. This is an idempotency key, not an API key.
FEEDBACK_IDEMPOTENCY_KEY=$(node -p 'crypto.randomUUID()')
orc feedbacks create --stdin --workspace WORKSPACE_ID --dry-run < feedback.jsonAfter reviewing the content and workspace, submit it. Replace WORKSPACE_ID with the report target.
orc feedbacks create --stdin --workspace WORKSPACE_ID \
--idempotency-key "$FEEDBACK_IDEMPOTENCY_KEY" --json < feedback.jsonSave the returned feedback_id. It proves intake, not notification delivery or resolution. If a timeout leaves the outcome unknown, retry with the same body, workspace, and key. Idempotency keys are retained for 24 hours. Use a new key for a different report with a changed body.
If you cannot log in, submit the same reviewed report anonymously. This example does not need a browser cookie or API key.
orc feedbacks create --anonymous --category slow-or-broken --stdin \
--idempotency-key "$FEEDBACK_IDEMPOTENCY_KEY" --json < feedback.jsonIf submission fails, retain the report locally and return “not sent” with the reason. Do not recursively submit feedback about feedback-submission failures.
4. Check intake and verify the fix
Workspace owners can inspect recent reports. Other users should keep the creation receipt because this list requires owner access.
orc feedbacks list --workspace WORKSPACE_ID --jsonThe list returns the newest 20 reports. Absence from that list alone does not prove failed submission. Stored statuses are new, triaged, and resolved; the CLI has no status-update command.
When a fixed version is available, repeat the original workflow with the same target, input, and expected result. Record the receipt ID, tested version, rerun result, and remaining issues. Neither an intake receipt nor a resolved label proves that the reproduction now succeeds.