Debug Standard

Systematic root cause analysis for reproducible bugs.

When to Use

• Reproducible bugs

• Clear symptoms

• Standard complexity

Scope Escalation

If fix touches >5 files or shared component API, escalate to debug/deep .

Artifacts

• DEBUG-PLAN-[BUG-ID].md (optional)

• task.md updated via task_boundary

Approach

Phase 1: Observation & Reproduction

Document:

• Steps to Reproduce: Numbered list

• Expected Behavior: What should happen

• Actual Behavior: What happens instead

• Environment: Browser, OS, relevant state

Phase 2: Hypothesis & Investigation

Generate 3-4 hypotheses:

Hypothesis Confidence Evidence Needed Investigation

1 ... High Check X grep for pattern

2 ... Medium Trace Y Add logging

3 ... Low Log Z Run with --verbose

Phase 3: Root Cause & Fix

• Confirm root cause with evidence

• Plan fix using holistic principles

• Reflexion: Hostile QA — list 2-3 regression risks

Phase 4: Implementation

Apply fix, run verification:

• npm run lint

• npm run build

• User verifies in browser

Constraints

• Prefer holistic fixes over one-off patches

• Fix the pattern, not just the instance

• If fix fails, iterate (max 3 attempts)