debug

<user_request> $ARGUMENTS </user_request>

<value_banner> Display ONCE at the start of the command:

/dev:debug — Structured Debugging Workflow Beyond what Claude does natively, this command adds:

• 3 depth levels: quick patch / systematic 6-phase debug / production-grade TDD fix
• Fault localization with stack trace, keyword, and AST strategies
• Auto-inference detects the right depth from your description
• Escalation: quick-patch auto-upgrades when complexity grows

For quick debugging, just ask Claude directly. </value_banner>

<critical_override> THIS COMMAND OVERRIDES THE CLAUDE.md TASK ROUTING TABLE FOR AGENT SELECTION.

Routing rules for this command only:

• Stack detection → dev:stack-detector agent
• Error analysis → dev:debugger agent (standard debug path only, via skill)
• Applying fixes → dev:developer agent

QUICK-PATCH: root cause analysis is INLINE (no agent delegation) DO NOT use code-analysis:detective (READ-ONLY agent, not for fixing) </critical_override>

<scope_selection> MANDATORY: Determine debugging scope before starting.

Auto-inference rules (skip the question when any of these match):

• Stack trace present + single file mentioned → Quick patch
• Keywords: "production", "critical", "intermittent", "uncertain root cause" → /dev:fix
• Keywords: "root cause", "investigate first", "systematic" → Standard debug
• Simple error message with obvious single-location cause → Quick patch
• --downgrade flag in $ARGUMENTS → Standard debug (bypass all inference)
• Default (none of the above): Ask user

If auto-inference cannot determine scope, use AskUserQuestion with these options:

• Quick patch: "Fast: stack trace → inline analysis → patch. Auto-escalates if scope grows."
• Standard debug: "Thorough: reproduce → localize (3 strategies) → root cause → patch → validate"
• Production-grade fix: "Full TDD + multimodel review. Run /dev:fix for this depth."

Decision:

• "Quick patch" → execute the Quick-Patch Workflow below
• "Standard debug" → load dev:systematic-debugging and follow workflow.md exactly
• "Production-grade fix" → output: "Scope: Production-grade fix. Run /dev:fix {bug description} for the full TDD + review workflow." then STOP </scope_selection>

<quick_patch_workflow> Execute this workflow inline when scope = Quick patch.

Phase 0: Initialize

• Follow dev:systematic-debugging → session-setup.md for session setup (prefix: "dev-debug-quickfix")
• Parse flags from $ARGUMENTS:
  • --review: opt-in multimodel patch quality vote at Phase 4
  • --tdd: write RED test before applying patch
  • --interactive: approval gate before PATCH phase

Phase 1: REPRODUCE

• Use context from session-setup.md
• If reproduction steps were provided in $ARGUMENTS, attempt reproduction via Bash
• Document reproduction result in session

Phase 2: LOCALIZE (Strategy A — stack trace first)

• If stack trace present: extract file:line with Grep, Read ±20 lines of surrounding context
• If no stack trace: fall back to keyword search across codebase with Grep
• Write localization.md to session directory

Escalation check #1: if candidates span > 3 files → offer upgrade to Standard debug

Phase 3: PLAN (inline root cause — no agent delegation)

• Perform root cause analysis directly in this context
• Generate: hypothesis, fix approach, files to modify
• Self-critique checklist:
  • MINIMAL_CHANGE: is the fix as small as possible?
  • ROOT_CAUSE_NOT_SYMPTOM: does this fix the cause, not mask it?
  • REGRESSION_SAFETY: what existing behavior could break?
  • TEST_COVERAGE: is there a test that would catch this?
  • REGRESSION_RISK: LOW / MEDIUM / HIGH
  • COMPETING_HYPOTHESES: YES / NO
• Write root-cause.md to session directory