fix-a-bug
Skill2 starsChanged 52 days agoMITView on GitHub
Fix something FoolProof already does wrong — reproducing it before reading any code, turning that reproduction into a test that fails first, proving a cause instead of guessing at one, and sweeping for the same shape elsewhere. It is drawn at stages 1, 2 and 3, because a fault can arrive while framing, while writing, or out of a red gate — use when the owner reports the bot getting something wrong, when a checkup finding becomes the next phase, when a gate goes red for a reason its own message does not explain, and when a fault turns up in passing during work that came for something else.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- phnx-labs/rush-mcptheir own version, first seen Nov 16, 2026
- xai-org/xai-cookbooktheir own version, first seen Oct 13, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- xai-org/xai-cookbook★ 637same name
- phnx-labs/rush-mcp★ 0same 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 repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-a-featureSkill
- add-repository-methodSkill
- finish-phaseSkill
- refresh-the-picturesSkill
- retrospectiveSkill
- update-the-design-pageSkill
- write-a-commitSkill
- write-a-docSkill
- write-an-e2e-scenarioSkill
- write-a-specSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Every other skill here is written for work that is new: it starts from what somebody wants and ends at a gate.
- Very specific: line 98
Read the evidence that already exists before producing more: Every check here writes under reports/, and re-running one to re-read its own …
- Distinctive: line 151
Name the gate that should have caught it: Every gate in this project exists because something got past the ones before it, and a shipped …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.
Files
Fixing something that already went wrong
Stages 1, 2 and 3 of how a change becomes a release.
Nobody hands you this skill. The owner says what should be different, not which kind of work it is — and most of the ways in here never reach an owner at all. Reading a request as a fault rather than as something not built yet is yours, before this opens.
Every other skill here is written for work that is new: it starts from what somebody wants and ends at a gate. A fault starts from the other end — the thing already exists, already passed every gate, and shipped anyway. So the expensive question is never how do I fix it. It is what is actually true, and every rule below buys an answer to that before any code is touched.
The output is a diff like any other, and it replaces no gate. Reproducing and sweeping frame the phase; the failing test is the first thing built, so this joins at stage 2.
Reproduce before you read the code
Reading the code first produces a theory, and then the code confirms it — because you are now reading with an answer in hand. What that finds is a fault, plausibly shaped, sitting near the real one. Reproduce first and the code is read against something that cannot be talked out of its position.
The reproduction is the smallest input that still shows it. Shrinking it is not tidiness: each thing removed that does not stop the fault is a thing proven irrelevant, and what is left when nothing more can go is very close to the cause.
Reproduce on the platform it happened on. A fault reproduced somewhere else is a different fault wearing the same description. Both times a lock file has broken this project, every local gate was green and only the Linux runner failed — the machine was the variable, and no amount of reading on Windows would have shown it. When the platform cannot be reached, say that the reproduction is partial rather than treating the local run as one.
Being unable to reproduce it is a finding, and it is reported as one. It is
never a licence to fix the most suspicious-looking line: a fix with no reproduction
behind it cannot be shown to have worked, so it buys nothing but the feeling of
having acted. If the report came from a real chat, the evening it happened in can
be read back — node scripts/tools/tools.ts evening <chat id>, under gate 3a of
finish-phase, which is also where the rule about snapshotting the database lives.
The failing test is the reproduction, made permanent
Write it before the fix, and watch it fail. A test written afterwards is written against code that already works, so it asserts what the code does rather than what the bug was — and it passes on the first run, which proves only that it was aimed at whatever it was pointed at. Watching it go red first is the only moment that proves it can see the fault at all.
Read the failure message, not just the colour. A test that fails for a second, unrelated reason is green light with extra steps: it will pass once the fix lands and would have passed with no fix at all.
Put it at the layer where the fault is still visible as data. This is the rule
that decides whether the test is worth anything. A ten-player e2e scenario stayed
green through the entire life of the truncation bug it was later used to describe,
because a scenario holds a rasterized PNG and can only assert that a picture arrived,
how wide it is, and that it fits — the truncation lived in the SVG, where it is still
a string, and only a spec holding that string could ever have caught it. Ask what
form the fault takes before choosing a file to put the test in; write-a-spec has
the rest, and it applies here unchanged.
Proving a cause
Measure before the third hypothesis. Two guesses is thinking; a third means the search has no ground under it, and the way out is an experiment rather than a better guess. Stryker's worker count was argued twice and settled by one run at each setting, in running the mutation gate.
A number out of an instrument nobody has proven is not a measurement. The first
output of a new check, a new script, a new query is a claim about the instrument
before it is a claim about the code. One written here to ask whether every
TECH-DEBT.md entry names a trigger reported thirteen entries missing one, and the
number went to the owner as a finding; the file was in fact clean, and the check had
never been shown a trigger phrased if, the next time or with the next phase
that. Calibrate against cases whose answer you already know before quoting it, and
when it does cry wolf, widen its vocabulary rather than rewording its subject to
suit it.
A gate that stays green proves nothing about a fault it cannot see. When the
theory is that some check should have caught this, break the thing deliberately and
watch it go red — the probe goes in through an edit, and the proof is the output,
not the intention. Breaking today's file only proves the rule fires on today's file,
which is the easy half; the probe that matters changes the shape of what the rule
reads — reorder, rename, leave a field out, hand it a format it has never seen. A
rule written to catch silent failures failed silently in its first hour: it read an
<img> only when src, width and height came in that order, so a class in
front of them dropped the image out of every check, weighing included, without a
word. A rule that cannot parse its subject must say so rather than skip it.
Read the evidence that already exists before producing more. Every check here
writes under reports/, and re-running one to re-read its own output is the
canonical waste in this project — the rule and the trap underneath it, where a
reporter flag silently leaves the previous run's report on disk, are in running the
mutation gate. A long run's console
output is only ever a tail, so a number wanted from the middle of one is saved while
it runs, not recovered by running it again.
The sweep: one occurrence is a report, not a count
A fault almost never has exactly one site, because it came from a habit rather than
a typo. The same lost backslash has reached this repository twice — once inside a
check-docs rule whose path split then could not do its job and reported nothing
forever, and once more caught a substring from shipping. TECH-DEBT.md, under Half
of check-docs is proven once, has both and a third of the same shape. Copying a
render call to a second module left its font guard behind, and CLAUDE.md has what
that would have committed, beside the rule about refusing at construction.
So the last step of understanding a fault is grep for its shape, not for its
symptom — the wrong call, the missing guard, the assumption — across src/,
scripts/, e2e/, .claude/ and the documents. Two traps make that grep lie:
\bis ASCII-only, andproject/no-ascii-word-boundaryrefuses a pattern that carries both; a search typed by hand still has to spell the boundary as(?<![\p{L}\p{N}]).- A name that changed has callers no compiler sees.
check-docsfails a document naming a path, annpm runscript or ascripts/tools/tools.tsverb that does not exist; a changed function name still rots in silence.
What the sweep finds goes into the phase's size before any of it is fixed.
A fault found while doing something else
Deciding this belongs here, not with the owner — the size of the phase was agreed
without it, and carrying every stray finding back is what makes a flow need
babysitting. The line is the files this diff already changes — git diff
--name-only, not a judgement about what was opened or read:
- a fault inside them — fix it, and the phase absorbs it;
- a fault outside them —
TECH-DEBT.mdwith the trigger that would make it worth doing.
The sweep above guarantees this line gets straddled: fix the occurrences already in the diff, and let one debt entry name the rest, so the count lives on disk.
The rule is about work, not words. A stale sentence in a file this phase now cites is corrected where it stands — a debt entry would cost more lines than the fix.
Then say which happened in the closing message. A silent widening and a silent deferral look identical from the outside, and both look like nothing was found.
What the fix owes afterwards
Name the gate that should have caught it. Every gate in this project exists because something got past the ones before it, and a shipped bug is the only evidence that can say which one is blind. The answer belongs in the retrospective at stage 6, phrased as what it would take for that gate to see the fault — not as a resolution to be more careful.
A bug that got past the units is one of the things that earns an e2e scenario.
write-an-e2e-scenario has the list and the bar; the fault having crossed a real
seam is the evidence it asks for.
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.

