fixing-bugs
Skill2 starsChanged 3 months agoMITView on GitHub
Fix a bug using strict TDD — UNDERSTAND → REPRODUCE (RED) → VERIFY RED → FIX → VERIFY GREEN → VALIDATE → REFACTOR. Use when the user reports a bug, asks to fix something, mentions a Sentry/error/regression, or pastes a stack trace. Bugs require a failing test that proves the bug existed before any code change. For building new features use developing-features-tdd; for non-TDD code work use developing-features.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- adobe/react-spectrum-chartstheir own version, first seen Nov 9, 2026
- medusajs/medusatheir own version, first seen Oct 8, 2026
- withzombies/hyperpowerstheir own version, first seen Mar 30, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- medusajs/medusa★ 37ksame name
- adobe/react-spectrum-charts★ 133same name
- withzombies/hyperpowers★ 80same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository19 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- api-designSkill
- building-frontend-uiSkill
- debugging-agent-runsSkill
- developing-featuresSkill
- developing-features-tddSkill
- documenting-featuresSkill
- ensuring-cross-platformSkill
- evaluating-ai-outputSkill
- exploratory-testingSkill
- playwright-cliSkill
- reviewing-codeSkill
- running-agent-loopsSkill
- security-reviewSkill
- threat-modelingSkill
- validating-in-realitySkill
- writing-prdSkill
- writing-pull-requestsSkill
- writing-testsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. 0 are common, 18 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
18
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Never fix a bug before proving it exists with a failing test.
- Very specific: line 33
If you skip steps or change the order, the fix is invalid.
- Distinctive: line 46
If you can't extract all four → ask for clarification, don't guess.
- Distinctive: line 61
Do not open the editor and start changing things.
- Distinctive: line 82
Run the test. It MUST fail.
- Distinctive: line 91
If the test passes before the fix, one of three things is true:
- Distinctive: line 97
If the test fails for a different reason than the report:
- Distinctive: line 103
Don't proceed to FIX until the failure reason is clean.
- Distinctive: line 120
Follow existing codebase patterns: Before writing the fix, search for similar error handling or patterns already established.
- Distinctive: line 145
Run the same test from Phase 2.
- Distinctive: line 155
If it still fails, the fix is wrong or incomplete.
- Distinctive: line 159
Run the full test suite. All tests must pass.
- Distinctive: line 161
If a pre-existing test breaks:
- Distinctive: line 181
Only if the fix introduced duplication or reduced clarity.
- Distinctive: line 187
Never delete a bug-fix test unless the feature it tests is removed.
- Distinctive: line 189
If a bug comes back, either the test was deleted, the test was too narrow, or someone overrode it.
- Distinctive: line 195
Correlation context is mandatory: Every new log includes IDs (request, conversation, user, resource) that let a future investigator trace …
- Distinctive: line 197
Follow the codebase convention: Check the existing logging style in the file before adding a new statement.
- Very specific: line 198
Platform context for platform bugs: If the root cause was OS-specific, include platform=sys.platform (or equivalent) in the log.
- Distinctive: line 206
If your fix would violate a code quality rule → find a different approach.
- Very specific: line 210
Before closing the task, ask: *did I encounter a bug pattern, framework quirk, OS trap, or recurring shape that wasn't in this SKILL.md or …
“Common” is measured: kept by at least 6 in 10 of the 3 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.
Files
Fixing Bugs
Never fix a bug before proving it exists with a failing test. The fix is only valid if a test transitions from RED (failing) to GREEN (passing).
Read first (always)
List learnings/ and read every file relevant to the current bug. Project-specific test conventions, framework quirks, recurring bug patterns, or hot zones live there and override the defaults in this SKILL.md. If a learning conflicts with this file, the learning wins — mention it to the user.
Tradeoff — when to apply, when to lighten up
Apply the full cycle for any defect in production code the user is reporting (Sentry alert, support ticket, "this broke", regression). The discipline pays off because the test becomes a permanent sentinel against the same bug returning.
Lighten the formality only when fixing a typo, a build script, or a one-off script the user explicitly labels as throwaway. Even then, run the test suite afterwards.
The cycle (strict order)
1. UNDERSTAND → Read the bug report; identify expected vs actual; locate the OS/platform
2. REPRODUCE → Write a failing test that triggers the EXACT error path
3. VERIFY RED → Run the test; it MUST fail for the reason in the bug report
4. FIX → Write the MINIMUM code change to make the test pass
5. VERIFY GREEN → Run the same test; it MUST now pass
6. VALIDATE → Run the FULL suite (CI matrix if platform-suspect); nothing else breaks
7. REFACTOR → Optional; only if the fix introduced duplication. Tests stay GREENIf you skip steps or change the order, the fix is invalid. Full per-phase detail in references/cycle.md.
Phase 1 — UNDERSTAND
Decompose the bug report:
GIVEN: <precondition / initial state>
WHEN: <action that triggers the bug>
THEN: <what actually happens — the bug>
EXPECTED: <what should happen — the fix target>If you can't extract all four → ask for clarification, don't guess.
Identify the platform dimension. Bug reports rarely state the OS. Check user agent, Sentry tags, container image, support metadata. Bugs in the following areas are platform-suspect by default — filesystem operations, text encoding / line endings, subprocess / shell, temp / config dir resolution, process signals, networking. If the bug is platform-suspect, the test must run on the affected OS in Phase 3.
Pick an investigation technique (full list in references/investigation.md):
| Technique | When |
| Read error logs | Always start here |
| Reproduce locally | Always — if you can't reproduce, you can't fix |
git bisect | The bug is a regression and you don't know which commit broke it |
git log / git blame | You need the history of the affected code |
| Debugger / breakpoints | You need to inspect runtime state |
| 5 Whys | Bug is recurring or the surface cause looks too simple |
Do not open the editor and start changing things. Systematic investigation beats trial-and-error.
Phase 2 — REPRODUCE
The test is the proof the bug exists. No test = no proof = no fix.
The test must:
- Reproduce the exact scenario from the bug report.
- Exercise the exact error path — not a similar one. If the report says
GeneratorExit, your test triggersGeneratorExit, notCancelledError. - Assert the expected behavior, not the buggy behavior.
- Fail before the fix.
- Pass after the fix.
- Fail with a message consistent with the bug report.
Naming: should_[expected_behavior]_when_[condition_that_triggered_bug]. Examples and full quality rules in references/cycle.md.
→ verify: the test exercises the precise code path described in the stack trace or repro steps, and the failure message names the bug.
Phase 3 — VERIFY RED
Run the test. It MUST fail. Document:
TEST: <name>
STATUS: FAILED
ERROR: <actual error or assertion message>
MATCHES BUG REPORT: Yes — <one-line tie-back to the report>If the test passes before the fix, one of three things is true:
- The bug isn't reproducible with your scenario → revisit Phase 1.
- The assertions are wrong → revisit Phase 2.
- The bug is already fixed in the current code → confirm against the latest and close the ticket.
If the test fails for a different reason than the report:
- Setup error in Arrange → fix the fixture.
- The bug has a different root cause → revisit Phase 1.
- Mocks or fakes are wrong → check them.
Don't proceed to FIX until the failure reason is clean.
Phase 4 — FIX
Change the minimum code necessary. Do not refactor, optimize, or add features in the same diff.
Root cause analysis (write this down before coding):
ROOT CAUSE:
File: <path>
Function: <name>
Line: <number>
Issue: <one-line explanation of why the bug occurs>
Fix: <one-line description of the minimum change>Follow existing codebase patterns. Before writing the fix, search for similar error handling or patterns already established. If prior art exists (e.g., another function already handles the same exception type), follow that pattern.
Pre-existing issues discovered during the fix:
| Situation | Action |
| Pre-existing issue is in the lines you're touching and trivial to fix | Fix it in the same PR, note "pre-existing fix" in description |
| Pre-existing issue is adjacent and involves moderate refactoring | Separate commit in the same PR, or a follow-up ticket |
| Pre-existing issue is in a different area | Separate ticket — don't touch it here |
The test: does fixing this pre-existing issue make my bug fix safer or easier to review? If yes, include it (separate commit). If no, ticket it.
Scope rules:
| Allowed | Not allowed |
| Fix the root cause of the reported bug | Refactor the entire module |
| Add a guard clause for the edge case | Rewrite the function "for clarity" |
| Correct a conditional logic error | Change the API contract |
| Fix an off-by-one error | Add new parameters or endpoints |
| Handle a missing null check | Reorganize the file structure |
| Fix a pre-existing issue in the lines you're touching (note in PR) | Fix pre-existing issues in unrelated areas |
Phase 5 — VERIFY GREEN
Run the same test from Phase 2. It MUST now pass. Document:
TEST: <name>
STATUS: PASSED
BEFORE FIX: <failure message>
AFTER FIX: <pass>
ROOT CAUSE: <one-line>If it still fails, the fix is wrong or incomplete. Don't proceed to VALIDATE.
Phase 6 — VALIDATE
Run the full test suite. All tests must pass.
If a pre-existing test breaks:
- Analyze — is the breaking test correct, or was it asserting the buggy behavior as correct?
- If the test was wrong (it locked in the bug) → fix the test in the same PR, document why.
- If the test was right → your fix has a side effect. Return to Phase 4.
- Never delete a failing test to make CI green.
Cross-platform validation. If the bug was platform-suspect, the test must be green on every supported OS, not just yours. Run through CI on the affected OS before declaring done. If the suite didn't previously run on that OS, extending the CI matrix is part of this fix, not "a follow-up PR". See ensuring-cross-platform skill.
Regression checklist:
- New bug-fix test passes (GREEN).
- All existing unit tests pass.
- All existing integration tests pass (if applicable).
- No new warnings.
- Linter, formatter, type checker pass.
- CI matrix passes on every supported OS.
Phase 7 — REFACTOR (optional)
Only if the fix introduced duplication or reduced clarity. Tests must stay GREEN. Small steps. Re-run tests after each. Separate commit from the fix.
The bug-fix test is permanent
The test you wrote in Phase 2 is the permanent sentinel against this bug returning. Recurring bugs are one of the most common problems in software. Without a test, a future refactor can silently reintroduce the exact same defect.
- Never delete a bug-fix test unless the feature it tests is removed.
- Bug-fix tests must run in CI/CD on every build and PR.
- If a bug comes back, either the test was deleted, the test was too narrow, or someone overrode it. Investigate, don't just re-fix.
Logging quality in bug fixes
A bug fix often adds log statements (error handlers, fallback paths, disconnection events). These logs must meet the same quality bar as any other production code.
- Correlation context is mandatory. Every new log includes IDs (request, conversation, user, resource) that let a future investigator trace the event.
- Event names are unique. Two different error conditions must NOT log the same event name — collisions break filtering in Sentry/CloudWatch/Datadog.
- Follow the codebase convention. Check the existing logging style in the file before adding a new statement.
- Platform context for platform bugs. If the root cause was OS-specific, include
platform=sys.platform(or equivalent) in the log.
Full guidance in developing-features/references/observability.md.
Code quality still applies
A bug fix does NOT exempt you from project standards. All developing-features rules apply: no PII in logs, no secrets, file structure hard limits, strong typing, no silent failures, linters/formatters pass.
If your fix would violate a code quality rule → find a different approach.
Final step: capture a learning
Before closing the task, ask: did I encounter a bug pattern, framework quirk, OS trap, or recurring shape that wasn't in this SKILL.md or references/? If yes, append a learnings/YYYY-MM-DD-slug.md. If no, skip.
Pay particular attention to bug clusters: if the same kind of bug keeps recurring (off-by-one, null pointer, timezone, encoding), the learning should describe the systemic root cause and where to prevent it, not just this instance.
Output format
- Root cause analysis — WHERE, WHY, WHAT (concise, 3–5 lines). Include 5 Whys for complex or recurring bugs.
- Characterization tests (if applicable) — capture existing behavior as a safety net.
- Failing test — the test that reproduces the bug (RED).
- Fix — the minimum code change.
- Passing test — confirmation the same test now passes (GREEN).
- Regression check — confirmation all existing tests pass.
- Brief explanation — what was changed and why, in 2–3 bullets.
- Investigation notes (complex bugs) — what was investigated and ruled out.
See also
skills/validating-in-reality— when the user provides a cURL/repro, also prove the fix against the running system (request before/after, DB state, E2E).references/cycle.md— phase-by-phase detail and examples (test naming, AAA structure, exact-error-path rule).references/investigation.md—git bisectautomation, 5 Whys, debugging journal, bug clustering.references/checklist.md— full bug-fix checklist + commit format + PR description rules + edge cases (multiple bugs, untested code, integration-only, regressions).developing-featuresskill — code quality / SOLID / file structure / security / observability rules that apply during the fix.developing-features-tddskill — broader TDD reference; bugs are TDD's narrow case.ensuring-cross-platformskill — required when the bug is platform-suspect.learnings/— project-specific bug patterns, hot zones, recurring traps accumulated over time.
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
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.

