agentleFS
Sign inStart free
zekhoizekhoi/claude/.agents/skills/kit-debugging/SKILL.md

kit-debugging

Skill0 starsChanged 20 days agoMITView on GitHub

Systematically debug a failure by reproducing it, isolating the root cause, fixing it, and verifying the fix. Use when the user reports a bug, error, failing test, crash, regression, or unexpected behavior and wants it diagnosed or fixed, including intermittent or production-only problems they ask you to fix. Do not use for code review, new feature work, or performance tuning without a concrete failure.

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 8 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    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. Distinctive:

    If you cannot reproduce it, report what you tried and ask for the missing information instead of guessing at a fix.

    line 14
  2. Distinctive:

    Read the code on the failing path.

    line 18
  3. Distinctive:

    Check whether the same cause affects other call sites.

    line 20
  4. Distinctive:

    Add or keep a regression test that fails without the fix.

    line 25
  5. Distinctive:

    Remove temporary logging and debugging code.

    line 26
  6. Distinctive:

    Do not suppress the error, widen types, retry blindly, or weaken tests to make the symptom disappear.

    line 27
  7. Distinctive:

    Run the reproduction, the regression test, and the relevant existing tests.

    line 31
  8. Distinctive:

    Use: "The checkout test started failing after the last merge." "Users get a 500 when uploading a PNG."

    line 36

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “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

Debugging

Find the root cause before changing code. A fix without a reproduction is a guess.

1. Reproduce

  • Collect the exact symptom: error message, stack trace, failing command, inputs, environment, and what changed recently.
  • Reproduce it with the smallest reliable command, preferably an existing or new failing test.
  • If you cannot reproduce it, report what you tried and ask for the missing information instead of guessing at a fix.

2. Isolate

  • Read the code on the failing path. Form one hypothesis at a time and test it with evidence: logs, assertions, a debugger, a narrower test, or git bisect for regressions.
  • Distinguish the root cause from the symptom. Ask why the bad state was possible, not only where it surfaced.
  • Check whether the same cause affects other call sites.

3. Fix

  • Make the smallest change that fixes the root cause, following project conventions.
  • Add or keep a regression test that fails without the fix.
  • Remove temporary logging and debugging code.
  • Do not suppress the error, widen types, retry blindly, or weaken tests to make the symptom disappear.

4. Verify and report

  • Run the reproduction, the regression test, and the relevant existing tests.
  • Report the root cause, the fix, the evidence that it works, and any related risks or follow-ups. If verification could not run, say so.

Examples

  • Use: "The checkout test started failing after the last merge." "Users get a 500 when uploading a PNG."
  • Skip: "Review this PR." (code review) "Make the dashboard load faster." (no concrete failure)

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