agentkitcoagentkitco/agentkit-dev-skills/skills/repro-first-debugging/SKILL.md

repro-first-debugging

Skill0 starsChanged 14 days agoMITView on GitHub

Debug by reproducing the failure first, then forming and testing hypotheses before editing code. Use when asked to fix a bug, a failing test, a crash or unexpected behavior.

In this repository12 other files it gives its agents.
- agents-md-auditSkill
- brag-doc-from-gitSkill
- dependency-upgradeSkill
- explain-codebaseSkill
- pr-descriptionSkill
- prove-it-ranSkill
- review-my-diffSkill
- safe-refactorSkill
- security-quick-reviewSkill
- session-handoffSkill
- write-agents-mdSkill
- write-subagentSkill

The file

We split this skill into the rules it gives an agent

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

≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Reproduce it: Run the failing test or the smallest command that triggers it.
line 17
Distinctive:
List hypotheses: Write two or three plausible causes, each with the evidence that would confirm or kill it.
line 19
Very specific:
Test the hypotheses, cheapest first: Read the code path, add temporary logging or assertions, bisect (git bisect or by reverting suspects), …
line 20
Very specific:
Look for siblings: Search for the same pattern elsewhere (rg) and report, but do not change unrelated code without asking.
line 23
Distinctive:
No code edits before step 2 succeeds, unless the user explicitly asks for a blind fix.
line 39
Distinctive:
Never delete or weaken a test to make it pass.
line 40
Distinctive:
Never claim success without showing a command that failed before and passes now.
line 41
Distinctive:
If three hypotheses fail, stop and report what you know and what you need.
line 42

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

Reproduce first, then fix

Goal: fix the cause, prove the fix, and avoid editing on a guess.

Process

Restate the failure in one line: expected behavior, actual behavior, where it was seen. Ask for the error text, steps or input if they are missing. Do not start from a vague description.
Reproduce it. Run the failing test or the smallest command that triggers it. Capture the exact output. If you cannot reproduce it, stop and report what you tried; do not "fix" something you cannot see fail.
Shrink it. Reduce to the smallest input or test that still fails. Prefer turning the reproduction into an automated failing test in the project's test framework.
List hypotheses. Write two or three plausible causes, each with the evidence that would confirm or kill it. Rank by likelihood and cost to check.
Test the hypotheses, cheapest first. Read the code path, add temporary logging or assertions, bisect (git bisect or by reverting suspects), check recent changes (git log -p -- <path>). Record what each check showed. Remove temporary logging afterwards.
Fix the cause, not the symptom. Make the smallest change that explains the evidence. If the fix needs a workaround, say so and why.
Prove it. The failing test now passes; run the nearby tests and the full suite if fast. Show the before and after output.
Look for siblings. Search for the same pattern elsewhere (rg) and report, but do not change unrelated code without asking.

Report

Failure: <expected vs actual>
Reproduction: <command> -> <output summary>
Root cause: <what and why, with file:line>
Evidence: <the checks that confirmed it, and the hypotheses ruled out>
Fix: <summary of the change>
Verification: <failing test now passes; commands and results>
Related risks: <similar code found, not changed>

Rules

No code edits before step 2 succeeds, unless the user explicitly asks for a blind fix.
Never delete or weaken a test to make it pass.
Never claim success without showing a command that failed before and passes now.
If three hypotheses fail, stop and report what you know and what you need.

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.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

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