/debug

name: debug
description: >-
  Use when encountering any bug, test failure, build break, or unexpected behavior — runs a 4-phase
  systematic debugging process before proposing any fix. Iron Law: NO FIXES WITHOUT ROOT CAUSE
  INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference.
model: inherit
color: red
user-invocable: true
argument-hint: "[bug-description-or-issue-ref]"
tools: Read, Grep, Glob, Bash, Write

Debug Skill

> 4-phase root-cause investigation. Iron Law: no fix without root cause.

Invocation

The user invokes `/debug` with arguments: **$ARGUMENTS**.

The optional argument is a short bug description or issue reference (e.g. `"test timeout in CI"` or `#408`). If absent, inspect recent errors and `git log` to surface the most likely candidate, then confirm it with the user before starting Phase 1.

The four phases (Root Cause → Pattern → Impact → Solution) run in order, and the Phase-1 artifact at `.orchestrator/debug/<session-id>-<sequence>.md` is written before any fix code exists — it is a prerequisite for Phase 4, not optional documentation.

When to use

• Any test failure (unit, integration, E2E)
• Build break or compile error
• Runtime exception in production code
• Performance regression
• Integration issue between modules
• "It worked yesterday" bugs

When NOT to use

• Feature implementation (use `/plan` or wave-executor)
• Pure refactoring with no broken behavior
• Style/lint fixes with no behavioral impact

Phase 0: Bootstrap Gate (Session Orchestrator only)

The gate belongs to the Session Orchestrator plugin. First look for its gate file at `../_shared/bootstrap-gate.md`, resolved against this skill's base directory (the directory that contains this SKILL.md), never against the project working directory. The project you work on is usually a different repo, so a lookup relative to the working directory proves nothing. Inside the plugin the same file is named `skills/_shared/bootstrap-gate.md` from the plugin root.

• **The file exists** (this skill runs as part of Session Orchestrator): read it and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.
• **The file does not exist** (this skill was installed on its own, without the plugin): there is nothing to bootstrap. Skip Phase 0 and continue to Phase 1.

<HARD-GATE> When the gate file exists, do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints. A gate file missing from this skill's base directory (checked as above) is the only reason to skip Phase 0; urgency, a small bug or a request to skip are not. </HARD-GATE>

The Iron Law

> **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**

No matter how obvious the fix looks, complete Phase 1 (Root Cause Investigation) and produce the artifact BEFORE writing any fix code. This is non-negotiable.

The "2-hour obviously a typo" case has been the root cause of every multi-day debugging session in every project's history. Treat the obvious fix as a hypothesis to verify, not a conclusion to act on.

Phase 1: Root Cause Investigation

1.1 Read the error carefully

Quote the exact error message, full stack trace, and exit code in the artifact. Do not paraphrase. Paraphrasing introduces your assumptions before investigation begins.

1.2 Reproduce reliably

Document the exact command and environment that triggers it. If reproduction is flaky, that itself is a data point — write down the failure rate.

# minimum reproduction attempt
<exact command>
# env: Node version, OS, env vars relevant to the failure

1.3 Check recent changes

git log --oneline -20
git diff HEAD~5..HEAD -- <affected paths>

Identify the smallest set of commits that could have introduced this. Do not assume the most recent commit is the culprit without checking.

1.4 Instrument every component boundary

Add temporary logging at each input/output point along the failing path's modules. Capture actual values, not assumptions about what they should be. Run with instrumentation in place and record results.

1.5 Trace data flow backward

Start from the failure point and walk upstream. At each step, verify what you think is true with an actual Read or Bash call. "I assume X is Y" is not data.

Phase 1 artifact

Write to `.orchestrator/debug/<session-id>-<sequence>.md` (sequence = 1, 2, 3 within session). Without a Session Orchestrator session there is no session id: use today's date (`YYYY-MM-DD`) in its place.

**Artifact MUST be written before proceeding to Phase 2.** See "Artifact contract" section below.

Phase 2: Pattern Identification

After the Phase 1 artifact is written:

• Is this a recurrence of a previously fixed bug? Search `git log --all --grep="<symptom keyword>"`.
• Is there a class of bug this exemplifies (race condition, off-by-one, null check, encoding, async ordering)?
• Is there a missing test that would have caught this? Identify what the test would look like.
• Search the codebase for similar patterns:

  grep -rn "<suspect pattern>" --include="*.ts" --include="*.mjs"
  git grep "<symbol>"

Record findings in the artifact's Phase 2 section.

**Optional operator-side companion:** `/tmux-layout --layout debug` renders a 4-pane layout (scratch shell + `npm test --watch` + `tail -F .orchestrator/debug/*.md` + `watch -n 2 'git diff --stat'`) so you can observe hypothesis tests, debug artifacts, and diff progression peripherally. Pure observability — the `/debug` skill works identically with or without the layout (per ADR-0007 + GitLab #562).

Phase 3: Impact Analysis

• What else does the root-caused code touch?

  grep -rn "<function or symbol name>"

• What other code paths could share the same root cause?
• Will the fix break anything else? Id