| name | rote-troubleshooting |
| description | Diagnose repeated rote workflow failures without blind retries. Use after unchanged retries, missing model identity, wrong paths/endpoints, auth mismatches, jq errors, stale workspace context, lint/release failures, or direct-filesystem pitfalls.
|
rote-troubleshooting
All rote-<name> references in this document — including every name in the Handoff
Contract — are companion skills, never CLI commands (rote-shell is not rote shell).
Invoke them through the runtime's skill mechanism; only literal rote … commands run in a
terminal.
Use this skill when a rote task hits a repeated failure mode, an unchanged retry just failed, or the
next step is unclear after reading @@status, @@next, @@mandatory, warnings, and errors. Keep
commands sequential and prefer live guidance (rote start, rote guidance, rote grammar) before
guessing.
This skill changes the cause, route, inputs, configuration, or owner. It never repeats the same
failing command unchanged.
Use this skill after two failures in the same class even if the exact command changed. Same-class
failures include wrong cwd/workspace, wrong endpoint, missing auth, bad jq/query, wrong adapter
capability, play lint/runtime errors, and process evidence not being captured.
Recovery Loop
- Name the owning skill that failed and the exact command or gate that failed.
- Read the previous output again, including structured markers and cached response IDs.
- Classify the failure with the patterns below or live
rote guidance.
- Change one material input: arguments, adapter configuration, auth, cwd, workspace, play code,
environment, approval, or route owner.
- Return to the owning skill once the cause changes or the route changes.
Stop and ask one targeted question only when a missing credential, destructive approval, or model
identity cannot be inferred.
Troubleshooting is not a terminal state. After changing config, route, cwd, SDK state, or play code,
return to the owner with the failed command or gate to rerun. Do not final-answer from this skill
unless the result is a blocker that prevents any safe rote path.
Common Failure Patterns
| Symptom | Recovery |
|---|
| Missing model identity | In the workspace, run rote model set <model> --provider <provider> --confirmed-current when the current model/provider is known. If unknown, skip rather than fabricate unless the command requires it. |
| Wrong play path shape | Rerun rote play search "<intent>" --json and use the returned path verbatim. Do not construct play paths by hand. |
| Wrong endpoint form | Run rote inventory, then use endpoint names exactly as shown. Adapter sessions usually use adapter/<id>; shorthand commands use the adapter id with hyphens converted to underscores. |
| Adapter auth mismatch | Compare rote adapter catalog info <id>, rote adapter info <id>, and rote adapter keys <id>. Leave the workspace for adapter auth updates when rote says to. |
| Adapter base URL mismatch | Inspect installed adapter config before catalog install. If the installed provider-equivalent adapter has the wrong base URL, route to rote-adapter-config, repair it, then rerun the original probe/call. |
| Stale subagent workspace context | Do not delegate after workspace calls start. Require workspace name, response IDs, result, and save-gate status before continuing. |
| Catalog-search drift | Run rote adapter catalog search "<intent>" before direct MCP, WebFetch, curl, or scripts when no installed adapter fits. |
| Capability mismatch | Return to rote-task-routing, name the missing operation, and search or inspect adapters by capability. Do not keep using an adapter that only provides adjacent metadata. |
| jq pitfalls | Quote jq filters with single quotes, use -r only for raw strings, and check rote grammar query. Inspect whether the cached response is an error envelope before changing filters. |
| Play lint or release failures | Change play code, frontmatter, arguments, cwd, or environment before retrying. Never edit frontmatter status directly. |
rote deno run runtime or config failures | Inspect rote deno status, rote sdk status, , cwd, , import map, and SDK install state. Repair with , , or as appropriate. Do not switch to raw , , or ; that bypasses rote runtime setup, SDK imports, and provenance. If generated code imports from while is set elsewhere, fix the import to honor and rerun through . |
State Inspection Commands
Pick the group that matches the failure class — never walk the whole list hoping something turns
up:
- Guidance/syntax failures:
rote start, rote guidance agent essential, rote grammar <topic>.
- Workspace/cached-response failures:
rote workspace ls, then from inside the workspace
rote ls, rote workspace inspect meta, rote workspace inspect variables.
- Adapter failures:
rote adapter list.
- Play lifecycle failures:
rote play pending list, rote play list.
- Runtime/SDK failures:
rote sdk status, rote deno status.
For cached response errors, inspect the response before changing transformation code:
rote query is-error @N && rote query @N '$' -r
If those commands fail or the workspace metadata itself is corrupted, direct file inspection can be
used as a last-resort diagnostic, not as the normal data path.
Return Fields
Return these fields to the owning workflow skill:
- Owning skill and failed command or gate.
- Failure class and evidence from output or live guidance.
- Material change made or recommended.
- Route change, if any.
- Remaining blocker or targeted user question.
- Skill to resume:
rote-flow-run, rote-task-routing, rote-workspace, rote-flow-crystallization,
rote-flow-authoring, rote-command-patterns, rote-typescript-transformations, rote-registry,
rote-browse, or rote.
Handoff Contract
- Use when: a rote command, workflow gate, play lifecycle, workspace operation, browser route, or
registry operation fails repeatedly or would otherwise be retried unchanged.
- Preconditions: the failing owner, command/gate, previous output, and attempted inputs are known or
can be recovered from conversation, workspace state, or rote commands.
- Owns: failure classification, no-blind-retry discipline, recovery command selection, route changes,
and return-to-owner handoff once the cause changes.
- Hands off to: the owning workflow skill after recovery;
rote-command-patterns when syntax is the
blocker; rote-adapter-config when adapter settings must change; rote when installation, login,
or credentials are the blocker.
- Returns to: the skill that encountered the failure with cause, material change, remaining blocker,
and resume point.
- Stop when: the cause changes and the owner can retry, a safer route is selected, a targeted user
approval/credential is needed, or no rote path remains.
- Completion signal: changed input, changed route, named blocker, or owning skill resume point.
