Skip to content

feat(skills): add systematic-debugging — 6-phase structured debugging#24

Open
JYHTHEGREAT wants to merge 1 commit into
sangrokjung:mainfrom
JYHTHEGREAT:feat/systematic-debugging
Open

feat(skills): add systematic-debugging — 6-phase structured debugging#24
JYHTHEGREAT wants to merge 1 commit into
sangrokjung:mainfrom
JYHTHEGREAT:feat/systematic-debugging

Conversation

@JYHTHEGREAT

Copy link
Copy Markdown

Context

Contribution from jyh-system. The most common AI coding failure mode is "guess a fix → doesn't work → guess another → repeat". This skill structurally prevents that.

What This Adds

systematic-debugging skill — a 6-phase methodology that enforces root cause investigation before any fix.

The 6 Phases

  1. Quick Assessment — classify error, external research (5 min), branch decision
  2. Root Cause Investigation — read errors carefully, reproduce, check changes, trace data flow
  3. Pattern Analysis — find working similar code, compare, identify differences
  4. Hypothesis & Testing — single hypothesis, minimal test, clean state required
  5. Implementation — failing test first, single fix, verify
  6. Architecture Question — after 3 failed fixes, stop and escalate

Iron Law

Never propose a fix without root cause investigation.

Key Differentiators vs existing /debugging-strategies

  • External research mandatory (Phase 0) — don't rely on LLM self-knowledge
  • Fix counter — tracks attempts, auto-escalates at 3 failures
  • Clean state enforcement — no cumulative fixes, rollback between hypotheses
  • Red Flags checklist — catches common rationalizations ("let me just quickly fix this")

Supporting References

  • external-research-guide.md — structured lookup in official docs, GitHub Issues, Stack Overflow
  • root-cause-tracing.md — 5-step call stack backtracing methodology

Changes

  • skills/systematic-debugging/SKILL.md (185 lines)
  • skills/systematic-debugging/references/external-research-guide.md (68 lines)
  • skills/systematic-debugging/references/root-cause-tracing.md (73 lines)

Existing Code Impact

None. Pure addition. Can coexist with existing /debugging-strategies or replace it.

Test Plan

  • Trigger with an intentional build error → should run Phase 0 (classify + external research) before suggesting any fix
  • Simulate 3 failed fixes → should escalate to Phase 4.5 Architecture Question
  • Verify Red Flags detection when Claude tries to skip investigation

🤖 Generated with Claude Code

Structured debugging that prevents the most common AI coding failure:
guessing fixes without understanding root cause.

6 phases: Quick Assessment → Root Cause Investigation → Pattern
Analysis → Hypothesis Testing → Implementation → Architecture
Question (escalation after 3 failed fixes).

Includes supporting references:
- external-research-guide.md: official docs/GitHub lookup procedure
- root-cause-tracing.md: call stack backtracing methodology

Iron Law: "Never propose a fix without root cause investigation."

Based on production usage in jyh-system (~1 month, 6+ projects).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant