agentleFS
Sign inStart free
AbdullahMalik17AbdullahMalik17/Digital-FTE/.claude/skills/systematic-debugging/SKILL.md

systematic-debugging

Skill12 starsChanged 36 days agoMITView on GitHub

Systematic methodology for debugging bugs, test failures, and unexpected behavior. Use when encountering any technical issue before proposing fixes. Covers root cause investigation, pattern analysis, hypothesis testing, and fix implementation. Use ESPECIALLY when under time pressure, "just one quick fix" seems obvious, or you've already tried multiple fixes. NOT for exploratory code reading.

We split this skill into the rules it gives an agent

11 rules. 7 are common, 4 are distinctive, and 0 are very specific to this project.

  • 7

    Common

    Most of the 167 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Common:

    Core principle: ALWAYS find root cause before attempting fixes.

    line 15
  2. Common:

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

    line 23
  3. Common:

    Don't skip past errors or warnings

    line 34
  4. Common:

    Read stack traces completely

    line 35
  5. Common:

    If not reproducible, gather more data - don't guess

    line 41
  6. Distinctive:

    When system has multiple components (CI -> build -> signing, API -> service -> database):

    line 50
  7. Distinctive:

    Compare Against References: - Read reference implementations COMPLETELY, don't skim

    line 71
  8. Distinctive:

    Verify Fix: - Test passes? No regressions?

    line 85
  9. Common:

    If < 3: Return to Phase 1, re-analyze

    line 89
  10. Common:

    If you catch yourself thinking:

    line 105
  11. Distinctive:

    When you fix a bug, validate at EVERY layer:

    line 121

“Common” is measured: kept by at least 6 in 10 of the 167 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Systematic Debugging

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.

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:

  1. Read Error Messages Carefully
    • Don't skip past errors or warnings
    • Read stack traces completely
    • Note line numbers, file paths, error codes
  2. Reproduce Consistently
    • Can you trigger it reliably?
    • What are the exact steps?
    • If not reproducible, gather more data - don't guess
  3. Check Recent Changes
    • Git diff, recent commits
    • New dependencies, config changes
    • Environmental differences

  4. Gather Evidence in Multi-Component Systems

    When system has multiple components (CI -> build -> signing, API -> service -> database):

    For EACH component boundary:
  - Log what data enters component
  - Log what data exits component
  - Verify environment/config propagation

Run once to gather evidence showing WHERE it breaks
THEN analyze to identify failing component

  5. Trace Data Flow

    See references/root-cause-tracing.md for backward tracing technique.

    Quick version: Where does bad value originate? Keep tracing up until you find the source. Fix at source, not symptom.

Phase 2: Pattern Analysis

  1. Find Working Examples - Locate similar working code in same codebase
  2. Compare Against References - Read reference implementations COMPLETELY, don't skim
  3. Identify Differences - List every difference between working and broken
  4. Understand Dependencies - What settings, config, environment assumptions?

Phase 3: Hypothesis and Testing

  1. Form Single Hypothesis - "I think X is the root cause because Y"
  2. Test Minimally - SMALLEST possible change, one variable at a time
  3. Verify Before Continuing - Worked? Phase 4. Didn't? NEW hypothesis, don't stack fixes

Phase 4: Implementation

  1. Create Failing Test Case - Simplest reproduction, automated if possible
  2. Implement Single Fix - ONE change, no "while I'm here" improvements
  3. Verify Fix - Test passes? No regressions?
  4. If Fix Doesn't Work:
    • Count: How many fixes have you tried?
    • If < 3: Return to Phase 1, re-analyze
    • If >= 3: STOP and question the architecture

  5. If 3+ Fixes Failed: Question Architecture

    Pattern indicating architectural problem:

    • Each fix reveals new shared state/coupling
    • Fixes require "massive refactoring"
    • Each fix creates new symptoms elsewhere

    STOP. Discuss with user before attempting more fixes.

Red Flags - STOP and Follow Process

If you catch yourself thinking:

  • "Quick fix for now, investigate later"
  • "Just try changing X and see"
  • "Add multiple changes, run tests"
  • "I'm confident it's X, let me fix that"
  • "One more fix attempt" (when already tried 2+)
  • Proposing solutions before tracing data flow

ALL of these mean: STOP. Return to Phase 1.

Supporting Techniques

Defense-in-Depth

When you fix a bug, validate at EVERY layer:

LayerPurposeExample
Entry PointReject invalid input at API boundaryif (!dir) throw new Error('dir required')
Business LogicEnsure data makes sense for operationValidate before processing
Environment GuardsPrevent dangerous ops in specific contextsRefuse git init outside tmpdir in tests
Debug InstrumentationCapture context for forensicsLog with stack trace before dangerous ops

Single validation feels sufficient, but different code paths bypass it. Make bugs structurally impossible.

Condition-Based Waiting

Flaky tests guess at timing. Wait for actual conditions instead:

# BAD: Guessing at timing
await asyncio.sleep(0.05)
result = get_result()

# GOOD: Wait for condition
await wait_for(lambda: get_result() is not None)
result = get_result()

Pattern:

async def wait_for(condition, timeout_ms=5000):
    start = time.time()
    while True:
        if condition():
            return
        if (time.time() - start) * 1000 > timeout_ms:
            raise TimeoutError("Condition not met")
        await asyncio.sleep(0.01)  # Poll every 10ms

Common Rationalizations

ExcuseReality
"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 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.

Verification

Run: python scripts/verify.py

References

  • references/root-cause-tracing.md - Trace bugs backward through call stack

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free