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 callability.location 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, rote grammar deno, cwd, ROTE_HOME, import map, and SDK install state. Repair with rote deno install, rote sdk install, or rote sdk upgrade as appropriate. Do not switch to raw deno, $ROTE_HOME/bin/deno, or /tmp/.../bin/deno; that bypasses rote runtime setup, SDK imports, and provenance. If generated code imports from $HOME/.rote while ROTE_HOME is set elsewhere, fix the import to honor ROTE_HOME and rerun through rote deno run. |
| Shell expansion prompts |
Quote user-provided strings and jq filters. Run one rote command at a time so prompts and errors are visible. |
| Untracked process evidence |
Switch to rote-shell: rerun through rote proc run, capture files/stdout/stderr, and query the saved response before using the result in an artifact or completion claim. |
| Direct filesystem inspection pitfalls |
Inspect workspace state and cached responses through rote commands before reading managed files directly. Direct .rote/responses/@N.json reads are allowed only when rote-native query/state commands cannot expose the data needed to diagnose the failure; record that reason and return to rote commands once recovered. |
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: use
rote workspace ls as inventory. Enter only Complete
rows rendered as active or empty; stop on every Needs attention row instead of running cd
or rote ls against it. From inside an enterable workspace, run rote ls,
rote workspace inspect meta, and 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.
1---2name: rote-troubleshooting3description: 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.4---56# rote-troubleshooting78All `rote-<name>` references in this document — including every name in the Handoff9Contract — are companion **skills**, never CLI commands (`rote-shell` is not `rote shell`).10Invoke them through the runtime's skill mechanism; only literal `rote …` commands run in a11terminal.1213Use this skill when a rote task hits a repeated failure mode, an unchanged retry just failed, or the14next step is unclear after reading `@@status`, `@@next`, `@@mandatory`, warnings, and errors. Keep15commands sequential and prefer live guidance (`rote start`, `rote guidance`, `rote grammar`) before16guessing.1718This skill changes the cause, route, inputs, configuration, or owner. It never repeats the same19failing command unchanged.2021Use this skill after two failures in the same class even if the exact command changed. Same-class22failures include wrong cwd/workspace, wrong endpoint, missing auth, bad jq/query, wrong adapter23capability, play lint/runtime errors, and process evidence not being captured.2425## Recovery Loop26271. Name the owning skill that failed and the exact command or gate that failed.282. Read the previous output again, including structured markers and cached response IDs.293. Classify the failure with the patterns below or live `rote guidance`.304. Change one material input: arguments, adapter configuration, auth, cwd, workspace, play code,31 environment, approval, or route owner.325. Return to the owning skill once the cause changes or the route changes.3334Stop and ask one targeted question only when a missing credential, destructive approval, or model35identity cannot be inferred.3637Troubleshooting is not a terminal state. After changing config, route, cwd, SDK state, or play code,38return to the owner with the failed command or gate to rerun. Do not final-answer from this skill39unless the result is a blocker that prevents any safe rote path.4041## Common Failure Patterns4243| Symptom | Recovery |44| --- | --- |45| 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. |46| Wrong play path shape | Rerun `rote play search "<intent>" --json` and use the returned `callability.location` verbatim. Do not construct play paths by hand. |47| 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. |48| 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. |49| 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. |50| Stale subagent workspace context | Do not delegate after workspace calls start. Require workspace name, response IDs, result, and save-gate status before continuing. |51| Catalog-search drift | Run `rote adapter catalog search "<intent>"` before direct MCP, WebFetch, curl, or scripts when no installed adapter fits. |52| 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. |53| 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. |54| Play lint or release failures | Change play code, frontmatter, arguments, cwd, or environment before retrying. Never edit frontmatter `status` directly. |55| `rote deno run` runtime or config failures | Inspect `rote deno status`, `rote sdk status`, `rote grammar deno`, cwd, `ROTE_HOME`, import map, and SDK install state. Repair with `rote deno install`, `rote sdk install`, or `rote sdk upgrade` as appropriate. Do not switch to raw `deno`, `$ROTE_HOME/bin/deno`, or `/tmp/.../bin/deno`; that bypasses rote runtime setup, SDK imports, and provenance. If generated code imports from `$HOME/.rote` while `ROTE_HOME` is set elsewhere, fix the import to honor `ROTE_HOME` and rerun through `rote deno run`. |56| Shell expansion prompts | Quote user-provided strings and jq filters. Run one rote command at a time so prompts and errors are visible. |57| Untracked process evidence | Switch to `rote-shell`: rerun through `rote proc run`, capture files/stdout/stderr, and query the saved response before using the result in an artifact or completion claim. |58| Direct filesystem inspection pitfalls | Inspect workspace state and cached responses through rote commands before reading managed files directly. Direct `.rote/responses/@N.json` reads are allowed only when rote-native query/state commands cannot expose the data needed to diagnose the failure; record that reason and return to rote commands once recovered. |5960## State Inspection Commands6162Pick the group that matches the failure class — never walk the whole list hoping something turns63up:6465- Guidance/syntax failures: `rote start`, `rote guidance agent essential`, `rote grammar <topic>`.66- Workspace/cached-response failures: use `rote workspace ls` as inventory. Enter only `Complete`67 rows rendered as `active` or `empty`; stop on every `Needs attention` row instead of running `cd`68 or `rote ls` against it. From inside an enterable workspace, run `rote ls`,69 `rote workspace inspect meta`, and `rote workspace inspect variables`.70- Adapter failures: `rote adapter list`.71- Play lifecycle failures: `rote play pending list`, `rote play list`.72- Runtime/SDK failures: `rote sdk status`, `rote deno status`.7374For cached response errors, inspect the response before changing transformation code:7576```bash77rote query is-error @N && rote query @N '$' -r78```7980If those commands fail or the workspace metadata itself is corrupted, direct file inspection can be81used as a last-resort diagnostic, not as the normal data path.8283## Return Fields8485Return these fields to the owning workflow skill:8687- Owning skill and failed command or gate.88- Failure class and evidence from output or live guidance.89- Material change made or recommended.90- Route change, if any.91- Remaining blocker or targeted user question.92- Skill to resume: `rote-flow-run`, `rote-task-routing`, `rote-workspace`, `rote-flow-crystallization`,93 `rote-flow-authoring`, `rote-command-patterns`, `rote-typescript-transformations`, `rote-registry`,94 `rote-browse`, or `rote`.9596## Handoff Contract9798- Use when: a rote command, workflow gate, play lifecycle, workspace operation, browser route, or99 registry operation fails repeatedly or would otherwise be retried unchanged.100- Preconditions: the failing owner, command/gate, previous output, and attempted inputs are known or101 can be recovered from conversation, workspace state, or rote commands.102- Owns: failure classification, no-blind-retry discipline, recovery command selection, route changes,103 and return-to-owner handoff once the cause changes.104- Hands off to: the owning workflow skill after recovery; `rote-command-patterns` when syntax is the105 blocker; `rote-adapter-config` when adapter settings must change; `rote` when installation, login,106 or credentials are the blocker.107- Returns to: the skill that encountered the failure with cause, material change, remaining blocker,108 and resume point.109- Stop when: the cause changes and the owner can retry, a safer route is selected, a targeted user110 approval/credential is needed, or no rote path remains.111- Completion signal: changed input, changed route, named blocker, or owning skill resume point.
modiqo