/sw-debug

name: sw-debug
description: >-
  Investigation-first debugging workflow. Scopes the problem, delegates root
  cause analysis, produces a diagnosis report, and applies fix/log/defer autonomously.
argument-hint: "[problem description]"
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
  - Task

Specwright Debug

Goal

First-class debugging path. Scope the problem, investigate concurrently, diagnose with evidence, then decide: fix it now, log it, or defer. Operates autonomously, applying `protocols/decision.md` for the fix/log/defer decision.

Inputs

• Problem description (argument or recent error context)
• Initial evidence: error messages, logs, failing test output
• `{projectArtifactsRoot}/config.json` — `backlog.type` and `backlog.label`
• Codebase files — read during investigation

Outputs

• `diagnosis.md` at `{workArtifactsRoot}/{id}/diagnosis.md` — always produced
• `spec.md` at `{workArtifactsRoot}/{id}/spec.md` — Fix path only (2-3 acceptance criteria)
• `decisions.md` at `{workArtifactsRoot}/{id}/decisions.md` — fix/log/defer decision recorded per `protocols/decision.md`

Constraints

**Stage boundary (LOW freedom):** Follow `protocols/stage-boundary.md`. Investigate and diagnose. NEVER write code, run tests, branch, or commit. Fix path: produce spec.md, handoff to `/sw-build`.

**Scope (MEDIUM freedom):**

• If argument provided, use it. If no argument, infer from recent error context

(last failed command, error output in conversation). If genuinely undetermined, apply DISAMBIGUATION: choose the most likely problem from available context.

• Collect evidence: error messages, stack traces, failing tests. Define boundary.

**Investigate (HIGH freedom):** Delegate concurrently per `protocols/delegation.md`: `specwright-researcher` (code context, call paths) and `specwright-architect` (root cause, blast radius).

**Diagnose (MEDIUM freedom):** Write `diagnosis.md`: Problem (observed vs expected), Root Cause (confidence level, file:line evidence), Blast Radius (affected / not affected), Fix Approach (high-level), Alternatives Considered. If agents return insufficient evidence: produce low-confidence diagnosis and note the gap in decisions.md.

**Decision (MEDIUM freedom):** Apply `protocols/decision.md` DISAMBIGUATION + reversibility:

• Fix spans ≤3 files with local architectural scope → **Fix it now** (Type 2). Write

spec.md, handoff to `/sw-build`.

• Fix spans >3 files or crosses architectural boundaries → **halt and recommend

`/sw-design`** (Type 1 — structural scope).

• Known pattern (matches patterns.md entry) → **Log it** as BL-{n} per `protocols/backlog.md`.
• Requires design-level decisions → **Defer** as BL-{n} with `defer` tag.

Record the decision in decisions.md.

**State (LOW freedom):** Follow `protocols/state.md`. Work ID: `debug-{short-description}`.

Protocol References

• `protocols/stage-boundary.md` -- scope and handoff
• `protocols/decision.md` -- autonomous decision framework (fix/log/defer)
• `protocols/state.md` -- workflow state updates
• `protocols/delegation.md` -- concurrent delegation
• `protocols/backlog.md` -- backlog items

Failure Modes

| Condition | Action | |-----------|--------| | No problem description or context | Apply DISAMBIGUATION from conversation history. Record interpretation. | | Agents return no evidence | Low-confidence diagnosis. Apply fix/log/defer per reversibility. | | Fix is architectural (>3 files) | Halt. Recommend `/sw-design`. | | Compaction during investigation | Re-run investigation; diagnosis.md rebuilt from scratch |