systematic-debugging

Systematic Debugging

Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

This skill is the direct entry point for all bug fixes — no need to run ecw:risk-classifier first.

Announce at start: "Using ecw:systematic-debugging for root cause investigation."

When to Use

Use for ANY technical issue:

• Test failures
• Bugs in production
• Unexpected behavior
• Performance problems
• Build failures
• Integration issues

Use this ESPECIALLY when:

• Under time pressure (emergencies make guessing tempting)
• "Just one quick fix" seems obvious
• You've already tried multiple fixes
• Previous fix didn't work

Don't skip when:

• Issue seems simple (simple bugs have root causes too)
• You're in a hurry (rushing guarantees rework)

Workflow Integration

When invoked as the bug fix entry point, create session-state immediately after announcing start:

1. Read skills/risk-classifier/session-state-format.md for the JSON schema.
2. Read skills/risk-classifier/workflow-routes.yml — find the route where type: bug and extract its chain.
3. Write .claude/ecw/session-data/{workflow-id}/session-state.json with:
   • change_type: "bug"
   • routing: the chain array from step 2
   • next: second element of chain, resolved via skill_metadata[*].routing_aliases if needed
   • current_phase: "systematic-debugging"

Generate {workflow-id} as {YYYYMMDD}-{xxxx} (same convention as risk-classifier; use currentDate system-reminder for the date).

biz-impact-analysis and knowledge-track are not in the default bug chain — invoke them manually if the fix has broader impact.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you haven't completed the initial investigation, you cannot propose fixes.

The Four Phases

You MUST complete each phase before proceeding to the next. Read the supplementary files for full per-phase instructions:

• Phase 1: Initial Investigation — ./prompts/investigation-steps.md (read error messages, reproduce, check changes, gather evidence, domain cross-reference, trace data flow, write checkpoint)
• Phase 2: Pattern Analysis — ./prompts/analysis-and-fix.md Phase 2 section (find working examples, compare against references, identify differences, understand dependencies)
• Phase 3: Hypothesis and Testing — ./prompts/analysis-and-fix.md Phase 3 section (form single hypothesis, test minimally, verify, escalate when stuck)
• Phase 4: Implementation — ./prompts/analysis-and-fix.md Phase 4 section (create failing test, implement single fix, verify, escalate on repeated failure, question architecture after 3+ failures)