Menu
Four-phase debugging methodology with root cause analysis. Use when investigating bugs, fixing test failures, or troubleshooting unexpected behavior. Emphasizes NO FIXES WITHOUT ROOT CAUSE FIRST.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
This skill should be used when the user asks to "create AGENTS.md", "update AGENTS.md", "maintain agent docs", "set up CLAUDE.md", or needs to keep agent instructions concise. Guides discovery of local skills and enforces minimal documentation style.
This skill should be used when the user asks ANYTHING that will elicit a response. Guides verbosity of output.
Use when listing files, searching file contents, finding files by name, or viewing files in terminal. Replace slow standard tools (ls, grep, find, cat) with faster modern alternatives.
Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Use when asked to "simplify code", "clean up code", "refactor for clarity", "improve readability", or review recently modified code for elegance. Focuses on project-specific best practices.
Core component library and design system patterns. Use when building UI, using design tokens, or working with the component library.
Single entry-point orchestrator that detects task type and dispatches to the right klh-* skill. Use when the user says "dispatch", "klh this", or gives a task that could match multiple skills.
| name | systematic-debugging |
| description | Four-phase debugging methodology with root cause analysis. Use when investigating bugs, fixing test failures, or troubleshooting unexpected behavior. Emphasizes NO FIXES WITHOUT ROOT CAUSE FIRST. |
Part of klh/skills — personal agent skills by Klaus L. Hougesen. Install:
npx skills add klh/skills --skill systematic-debugging
Four-phase debugging methodology with root cause analysis. Emphasizes NO FIXES WITHOUT ROOT CAUSE FIRST.
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
Never apply symptom-focused patches that mask underlying problems. Understand WHY something fails before attempting to fix it.
Before touching any code:
Root Cause Tracing Technique:
1. Observe the symptom - Where does the error manifest?
2. Find immediate cause - Which code directly produces the error?
3. Ask "What called this?" - Map the call chain upward
4. Keep tracing up - Follow invalid data backward through the stack
5. Find original trigger - Where did the problem actually start?
Key principle: Never fix problems solely where errors appear—always trace to the original trigger.
Apply the scientific method:
Critical rule: If THREE or more fixes fail consecutively, STOP. This signals architectural problems requiring discussion, not more patches.
Stop immediately if you catch yourself thinking:
Consecutive fixes revealing new problems in different areas indicates architectural issues:
1. Read the FULL error message and stack trace
2. Identify which assertion failed and why
3. Check test setup - is the test environment correct?
4. Check test data - are mocks/fixtures correct?
5. Trace to the source of unexpected value
1. Capture the full stack trace
2. Identify the line that throws
3. Check what values are undefined/null
4. Trace backward to find where bad value originated
5. Add validation at the source
1. Use git bisect to find the breaking commit
2. Compare the change with previous working version
3. Identify what assumption changed
4. Fix at the source of the assumption violation
1. Look for race conditions
2. Check for shared mutable state
3. Examine async operation ordering
4. Look for timing dependencies
5. Add deterministic waits or proper synchronization
Before claiming a bug is fixed:
Systematic debugging achieves ~95% first-time fix rate vs ~40% with ad-hoc approaches.
Signs you're doing it right: