| name | debug-session |
| version | 2.9.1 |
| description | Use when the user reports a bug, error, or unexpected behavior that needs investigation. |
| trigger | manual |
| depends-on | [] |
| references | ["references/root-cause-tracing.md","references/condition-based-waiting.md","references/error-recovery.md"] |
| micro-components | {"phase-4":["record-failure"]} |
| disable-model-invocation | true |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Bash, WebSearch |
| argument-hint | [error-description] |
debug-session
Skill metrics: Emit a start event to the activity log:
echo "{\"type\":\"skill\",\"event\":\"start\",\"skill\":\"debug-session\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> docs/sessions/.activity-log.jsonl
Debug session for: $ARGUMENTS
Failure State Persistence
At each phase transition, write docs/sessions/.failure-state.md with YAML frontmatter so the Stop hook and /continue can programmatically detect incomplete workflows.
At workflow start (Phase 1 entry):
---
status: active
skill: debug-session
phase: "1"
phase_name: "Root Cause Investigation"
started_at: "[ISO-8601 timestamp from date -u +%Y-%m-%dT%H:%M:%SZ]"
story: "[from $ARGUMENTS — the error description]"
branch: "[from git branch --show-current]"
next_action: "Reproduce error and trace root cause"
files_modified: []
---
Error: [error description]
Root cause: not yet identified
Hypothesis: none
Fix attempts: 0
Files investigated: [list as investigation proceeds]
At each phase transition: Update the frontmatter fields: , , , and append to . Update the Context section with investigation progress (root cause, hypothesis, fix attempts).
Check if the error area is governed by an accepted ADR. If so, the fix MUST respect that decision — propose a fix within the ADR's constraints rather than working around the architectural choice. If the ADR itself is the root cause, flag it for supersession rather than silently violating it.
Do NOT attempt any fix until the root cause is identified with evidence. "I think it might be X" without evidence is NOT identification. Show: where the bug is, why it happens, and what incorrect state or logic causes it.
Search for known issues before deep analysis — someone may have already solved this:
After 3 failed fix attempts: STOP. Return to Phase 1 and re-trace from scratch. The root cause identification was likely wrong. Consult `references/error-recovery.md` — search for `## Phase 3`.
