agentsclimarketplace
Sign in

Systematic debugging

Skill aiskillstore/marketplace/skills/dmjgilbert/systematic-debugging

Four-phase root cause investigation before attempting fixes. Use when debugging bugs, test failures, or unexpected behavior.From its SKILL.md

Install
npx -y skills add aiskillstore/marketplace --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.

SKILL.md

2.5 KB, 537 tokens by cl100k_base, as published. Nobody here has run it

Systematic Debugging

ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

When to Use

  • Encountering bugs or test failures
  • Unexpected behavior in code
  • Before proposing any fix

The Four Phases

Phase 1: Root Cause Investigation

Before proposing any solution:

  1. Read error messages thoroughly - Don't skip warnings or stack traces; they often contain exact solutions
  2. Reproduce consistently - Verify you can trigger the issue reliably with documented steps
  3. Check recent changes - Examine git diff, dependencies, and configuration modifications
  4. Gather diagnostic evidence - In multi-component systems, add instrumentation at component boundaries
  5. Trace data flow - Backward trace from the error to find where bad values originate

Phase 2: Pattern Analysis

Establish the pattern before fixing:

  1. Locate similar working code in the codebase
  2. Read reference implementations completely (not skimmed)
  3. List every difference between working and broken code
  4. Understand all dependencies and assumptions

Phase 3: Hypothesis Testing

Apply scientific method:

  1. State your hypothesis clearly: "I believe X is failing because Y, evidenced by Z"
  2. Test with the smallest possible change
  3. Change only ONE variable at a time
  4. Verify results before proceeding

Phase 4: Implementation

Fix the root cause systematically:

  1. Create a failing test case first (TDD)
  2. Implement a single fix addressing only the root cause
  3. Verify the fix resolves the issue without breaking other tests
  4. If fix doesn't work, return to Phase 1

Red Flags - STOP Immediately

  • Proposing fixes without understanding the issue
  • Attempting multiple simultaneous changes
  • Assuming problems without verification
  • Skipping evidence gathering
  • Making "quick fixes" before investigation

When 3+ Fixes Fail

STOP. This signals an architectural problem, not a fixable bug:

  1. Do not attempt another fix
  2. Return to Phase 1
  3. Question whether the underlying pattern/design is sound
  4. Ask: "Should we refactor architecture vs. continue fixing symptoms?"

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

Results

Systematic approach: 15-30 minutes to resolution with 95% first-time success vs. Trial-and-error: 2-3 hours of thrashing with 40% success and new bugs introduced

What ships with it: 1 file

8.9 KB alongside SKILL.md

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.