Systematic debugging

Skill itseffi/agentic-os/.agents/skills/systematic-debugging

Agentic personal OS to automate high-leverage workflows with Codex, Claude Code, Pi, OpenClaw and other coding agents/ runtime platforms.

Install

npx -y skills add itseffi/agentic-os --skill systematic-debugging

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.

What its author says it does

Copied from the file, not written here

Four-phase debugging process - root cause first, then fix. Use when encountering bugs or unexpected behavior.

SKILL.md

3.1 KB, as published. Nobody here has run it

Systematic Debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you haven't completed Phase 1, you cannot propose fixes.

The Four Phases

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

Read Error Messages Carefully
- Don't skip past errors or warnings
- Read stack traces completely
- Note line numbers, file paths, error codes
Reproduce Consistently
- Can you trigger it reliably?
- What are the exact steps?
- If not reproducible, gather more data
Check Recent Changes
- Git diff, recent commits
- New dependencies, config changes
- Environmental differences
Trace Data Flow
- Where does bad value originate?
- What called this with bad value?
- Keep tracing up until you find the source

Phase 2: Pattern Analysis

Find Working Examples
- Locate similar working code in same codebase
Compare Against References
- Read reference implementation completely
- Don't skim - read every line
Identify Differences
- What's different between working and broken?
- List every difference, however small

Phase 3: Hypothesis and Testing

Form Single Hypothesis
- State clearly: "I think X is the root cause because Y"
- Write it down
Test Minimally
- Make the SMALLEST possible change
- One variable at a time
Verify Before Continuing
- Did it work? Yes -> Phase 4
- Didn't work? Form NEW hypothesis
- DON'T add more fixes on top

Phase 4: Implementation

Create Failing Test Case
- Use the tdd.md skill
Implement Single Fix
- ONE change at a time
- No "while I'm here" improvements
Verify Fix
- Test passes now?
- No other tests broken?
If 3+ Fixes Failed: Question Architecture
- Is this pattern fundamentally sound?
- Should we refactor vs continue fixing symptoms?
- Discuss before attempting more fixes

Red Flags - STOP and Follow Process

"Quick fix for now, investigate later"
"Just try changing X and see if it works"
"I don't fully understand but this might work"
Proposing solutions before tracing data flow
"One more fix attempt" (when already tried 2+)

ALL mean: STOP. Return to Phase 1.

Quick Reference

Phase	Key Activities	Success Criteria
1. Root Cause	Read errors, reproduce, check changes	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

When to Use

Use this skill when the task directly matches the workflow described above.

When Not to Use

Do not use this skill when the request is unrelated, low-stakes, or better handled by a simpler direct response.

Gives 8 of the 12 instructions most debug triage skills give

Counted across 839 of the 1,149 authors here whose files we hold, read 2026-08-06

investigate root cause before proposing any fixhere, and in 102 of 839, across 65 files
read error messages completelyhere, and in 90 of 839, across 48 files
create a failing test case before fixinghere, and in 84 of 839, across 44 files
reproduce the issue consistentlyhere, and in 82 of 839, across 40 files
change one variable at a timein 82 of 839, across 42 files
check recent changeshere, and in 74 of 839, across 35 files
write the regression test before fixingin 74 of 839, across 36 files
fix the root cause not the symptomin 60 of 839, across 43 files
implement a single fix at a timehere, and in 59 of 839, across 20 files
trace data flow backward to the sourcehere, and in 50 of 839, across 20 files
remove all debug instrumentationin 49 of 839, across 13 files
form a single hypothesishere, and in 48 of 839, across 18 files

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.