obsidian-owl/sw-debug

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 |