This skill should be used when the user reports a "bug", "not working", "fix this", "debug", "test failing", or when investigating unexpected behavior. Four-phase framework ensuring root cause understanding before attempting solutions.
When you report a bug, "not working", or "test failing", this skill enforces a four-phase framework: investigate root cause, analyze patterns, test hypotheses minimally, then implement fixes with failing tests first. It prevents random fixes by requiring you to understand the problem before proposing solutions.
/plugin marketplace add pproenca/dot-claude/plugin install dev-workflow@pproencaThis skill is limited to using the following tools:
references/phase-details.mdreferences/rationalizations.mdAnnounce at start: "I'm using the systematic-debugging skill to investigate this issue."
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
Violating the letter of this process is violating the spirit of debugging.
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
BEFORE attempting ANY fix:
For deep call stack errors, use root-cause-tracing skill.
For multi-component systems, add diagnostic instrumentation at each boundary before proposing fixes.
Fix the root cause, not the symptom:
Create failing test case
Implement single fix
Verify fix
If fix doesn't work
When catching these thoughts:
All mean: STOP. Return to Phase 1.
If 3+ fixes failed: Question the architecture (see below).
| Phase | Key Activities | Success Criteria |
|---|---|---|
| 1. Root Cause | Read errors, reproduce, trace | Understand WHAT and WHY |
| 2. Pattern | Find working examples, compare | Identify differences |
| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis |
| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass |
Pattern indicating architectural problem:
This is NOT a failed hypothesis - this is a wrong architecture.
STOP and question fundamentals:
BEFORE attempting Fix #4:
1. Have I tried 3+ fixes for this issue?
If YES → STOP
2. Does each fix reveal a new problem?
If YES → Architecture problem, not bug
3. Questions to ask:
- Is this pattern fundamentally sound?
- Are we "sticking with it through sheer inertia"?
- Should we refactor architecture vs. continue fixing symptoms?
4. Discuss with human partner before attempting more fixes
Do NOT:
DO:
For detailed guidance:
references/phase-details.md - Expanded phase proceduresreferences/rationalizations.md - Common excuses and rebuttals| Excuse | Reality |
|---|---|
| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
| Approach | Outcome |
|---|---|
| Systematic debugging | 15-30 minutes to fix |
| Random fixes approach | 2-3 hours of thrashing |
| First-time fix rate (systematic) | 95% |
| First-time fix rate (random) | 40% |
| New bugs introduced (systematic) | Near zero |
| New bugs introduced (random) | Common |
The math is clear: Systematic beats random every time.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.