| name | routr-debug |
| description | Find and fix bugs step by step (reproduce → locate → fix). Use when: errors, crashes, test failures, 'debug this', 'why is this broken', stack trace, root cause, flaky test. Not for: a known fix ready to commit (→ routr-ship); understanding code with no bug (→ routr-explore). |
routr-debug
Goal: reproduce → localize → hypothesize → verify fix. Minimize tokens while maximizing signal.
When to activate
- Errors, crashes, exceptions, stack traces
- Failing or flaky tests
- Unexpected behavior or regressions
- User says debug, trace, investigate, root cause
Do not activate
- Ready to commit a known fix →
routr-ship
- Open-ended "how does X work" →
routr-explore
- Security audit →
routr-security
- Visual redesign →
routr-frontend
Iron law
No fixes without root cause investigation first.
0. Bootstrap
Read if present (install from routr-catalog/references/skill-registry.md):
| Order | Skill | Tier |
|---|
| 1 | systematic-debugging | required |
| 2 | diagnosing-bugs | recommended |
| 3 | symdex-code-search | recommended |
| 4 | lean-ctx | recommended |
| 5 | context-degradation | optional — agent confused mid-session |
Budget gate: read required + recommended only for routine bugs. Pull an optional child solely when its stated signal fires (e.g. context-degradation only if the agent is mid-session confused). Never load all five for a simple fix.
If systematic-debugging missing → read routr-depth-debug OR references/fallback.md.
Optional: caveman at lite intensity for terse progress only.
Skip: frontend-design, caveman-compress, open-ended exploration without a symptom.
1. Symptom lock (low freedom)
2. Locate (medium freedom)
Before whole-file reads — see workflow.md:
- SymDex: symbol search, routes, callers/callees
- lean-ctx:
signatures or map → lines:N-M for hot paths only
3. Hypothesis loop (medium freedom)
For each hypothesis:
- State prediction in one sentence
- Read minimal evidence
- Confirm or eliminate
- Max 3 parallel hypotheses; prune dead ends
4. Fix discipline (low freedom)
- Smallest change addressing root cause
- No drive-by refactors
- Frontend visual bug:
routr-frontend CSS sections only
5. Verify
- Re-run reproduction or failing test
- SymDex callers graph for blast radius
Output format
## Debug report
**Symptom:** …
**Root cause:** …
**Fix:** …
**Verified:** yes/no — how
Handoff
Root cause fixed → STOP here. Do not commit from within routr-debug — re-route to routr-ship (fresh) so shipping runs its own verification. Chain: routr-debug → routr-ship → routr-deploy.
References
Anti-patterns
- Reading entire large files before SymDex/lean-ctx narrow pass
- Fixing without reproduction
- Loading all context-engineering skills for a simple null-pointer fix
