| name | diagnose |
| description | Systematic 4-phase debugging for skills, hooks, lifecycle, and overnight runner issues. Use when: "fix this bug", "why is this failing", "make this test pass", "skill not working", "hook not running", "diagnose this", or unexpected agentic-layer behavior. Finds root cause, fixes, and verifies.
|
Systematic Debugging
Rule
ALWAYS find root cause before attempting fixes. No fixes without completing Phase 1.
References
Read only the reference for what you're doing right now — don't preload all of them.
- Phase 1 detail:
${CLAUDE_SKILL_DIR}/references/phase-1-investigation.md
- Phase 4 §5 (team investigation):
${CLAUDE_SKILL_DIR}/references/phase-4-team-investigation.md
- Debug-session artifact:
${CLAUDE_SKILL_DIR}/references/debug-session-artifact.md
- Supporting techniques:
${CLAUDE_SKILL_DIR}/references/techniques.md
- Common rationalizations:
${CLAUDE_SKILL_DIR}/references/rationalizations.md
The Four Phases
After each phase, write or update the debug session artifact — In progress through Phases 1–3, Resolved or Escalated at Phase 4. See ${CLAUDE_SKILL_DIR}/references/debug-session-artifact.md for location, format, and timing.
Phase 1: Root Cause Investigation
- Read errors fully: file paths, line numbers, exit codes. For hooks, separate the hook script's errors from the wrapped tool's.
- Reproduce consistently; treat context (sandbox vs. non-sandbox, overnight vs. interactive) as a clue, not noise.
- Check recent changes — git diff, recent commits, skill or hook redeploys.
- Gather evidence at component boundaries before proposing fixes. See
${CLAUDE_SKILL_DIR}/references/phase-1-investigation.md §4 for the boundary checklist.
- Trace backward to root cause; fix at the source, not the symptom. See
${CLAUDE_SKILL_DIR}/references/techniques.md (Backward Root-Cause Tracing).
- Optional: if 2+ plausible theories exist and a human is available, consider a competing-hypotheses team instead of testing sequentially — skip in autonomous contexts. See
${CLAUDE_SKILL_DIR}/references/phase-1-investigation.md §6.
Phase 2: Pattern Analysis
- Find a working example (similar skill, passing hook, healthy lifecycle) and diff it against the broken one, down to frontmatter and structure — no difference is too small to matter.
- Check dependencies — paths, env vars, permissions, session state, timing assumptions.
Phase 3: Hypothesis and Testing
- Form one hypothesis: "I think X is the root cause because Y" — specific file paths, env vars, exact mismatches.
- Test minimally — smallest possible change, one variable at a time.
- Verify: worked → Phase 4; didn't → new hypothesis.
- When you don't know, say so — gather more evidence (back to Phase 1) rather than guessing.
Phase 4: Implementation
- State the confirmed root cause and where it is before writing any fix.
- Implement one change addressing it — no bundled refactoring or "while I'm here" fixes.
- Verify: test the specific behavior that was failing, then check adjacent behavior.
- If it doesn't work, stop and count fix attempts. < 3: return to Phase 1. ≥ 3: team investigation before a 4th attempt — see
${CLAUDE_SKILL_DIR}/references/phase-4-team-investigation.md.
Lifecycle Escalation Boundary
Debug and lifecycle escalation are different mechanisms. Debug escalation: fires during implementation after 3 failed fixes on an architecturally-resistant bug, and runs a team investigation then an architecture discussion. Lifecycle escalation: fires at phase transitions (Research→Spec, Spec→Plan) when scope or complexity exceeds the estimate, and prompts the user to escalate to the Complex tier.
/cortex-core:diagnose on a failed lifecycle task is a pre-retry step, not a replacement for the lifecycle's own phase gates.
Red Flags — Stop and Follow Process
If you catch yourself thinking any of these, stop and return to Phase 1:
- "Quick fix for now, investigate later" / "just try X and see" / "add multiple changes at once and see what happens"
- "It's probably X" or "this might work" — proposed without evidence, or before completing the backward trace
- Each fix reveals a new problem in a different place
If 3+ fixes failed: see ${CLAUDE_SKILL_DIR}/references/phase-4-team-investigation.md before a 4th attempt.
For the catalog of excuses to recognize and rebut, see ${CLAUDE_SKILL_DIR}/references/rationalizations.md.
