proof-fix
/proof-fix
Use when something is broken — finds the root cause before changing anything, confirms it, fixes it with a test that proves it, and opens a PR. The path every bug takes, instead of spec and work. Part of every bug
- Author
- jsamitt ↗
- Repository
- proof-claude-plugin ↗
- Licence
- MIT
- Last repository change
- 15.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when something is broken — finds the root cause before changing anything, confirms it, fixes it with a test that proves it, and opens a PR. The path every bug takes, instead of spec and work. Part of every bug
Original author description
Use when something is broken — finds the root cause before changing anything, confirms it, fixes it with a test that proves it, and opens a PR. The path every bug takes, instead of spec and work. Part of every bug
How it works
- Checklist
- 1. Pin down the symptom
- 2. Reproduce it
- 3. Find the root cause — and prove it
- 4. Propose the fix — the one pause
- 5. Fix it
- 6. Verify, keep the docs true, add the changelog line
- 7. Learnings, PR, discovered work
- Hand back
- When it is on fire
SKILL.md preview
---
name: proof-fix
description: Use when something is broken — finds the root cause before changing anything, confirms it, fixes it with a test that proves it, and opens a PR. The path every bug takes, instead of spec and work. Part of every bug
model: opus
---
# Fix
For bugs. A feature starts from what should exist; a bug starts from something that
does not work, and the expensive mistake is fixing the symptom. So this skill has one
rule above all others:
> **No fix without the root cause.** A fix that does not address the cause moves the bug
> somewhere harder to find.
```
/proof-fix "the paywall stays open after subscribing"
/proof-fix 31 # a bug that already has an issue
```
Read `_partials/config.md`, `_partials/voice.md`, `_partials/priority.md` and
`_partials/builder.md` first.
Then `project.docs`, and any `learnings.file` entries touching the area — say which you
are applying.
## Checklist
1. Pin down the symptom; file or claim the issue
2. Reproduce it
3. Find the root cause — and prove it
4. Propose the fix, with a recommended builder — **pause for approval**
5. Fix it — in the builder you chose, or here — with a test that fails before and passes after
6. Verify, keep the docs true, add the changelog line
7. Learnings, PR, discovered work
## 1. Pin down the symptom
Get it concrete before touching anything: what happens, what should happen, where, for
whom, how often, and since when. One question at a time. *"The paywall is broken"* is
not a symptom; *"after a successful purchase on iPhone the paywall stays open with the
Subscribe button still showing"* is.
Also establish **severity**, because it changes what comes first:
- Does it lose or corrupt data, take money wrongly, expose something private, or break
for every user? That is urgent — see *When it is on fire* below.
- Otherwise it is ordinary: rate it per `_partials/priority.md`. For a bug, value is the
cost of leaving it broken — who hits it and how badly.
**If there is no issue**, first check whether it is already reported — the light overlap
check in `_partials/overlap.md`. A match means working that issue instead, with the new
details added as a comment; a match that was closed as fixed may mean the bug came back,
which is worth saying before you look for the cause. Only then create one: the symptom
as the title, the details in the body, the `bug` label, and the P-label from the rating.
**If there is one**, read it. Already `in_progress` with a checkpoint: this is a resume
(see *Resuming* in step 5). Already `in_progress` with no checkpoint: it was claimed
some other way, so stop and ask rather than guessing. Otherwise, claim it: `in_progress`
on, board to `in_dev`, per `_partials/board.md`.
## 2. Reproduce it
Make it happen, on purpose, before changing any code. A bug you cannot reproduce is a
bug you cannot confirm you fixed.
- Best: a failing automated test that shows the bug. It becomes the regression test.
- Next: exact steps that trigger it every time.
- If only the user can trigger it — on a device, with their account, in production —
write the exact steps and **ask them to confirm**, rather than guessing.
- If it will not reproduce: say so, gather more evidence (logs, the exact inputs), or add
logging so it can be caught next time. Do not fix what you cannot see.
## 3. Find the root cause — and prove it
Trace from the symptom back to the cause:
- Read the code on the path. Follow the data, not the function names.
- **Check what changed recently** in the files involved. Was this working before? A
regression means the cause is probably in that change.
- **Check the history of the area.** If this is the third bug in the same files, that is
worth saying out loud: it is a design problem, not bad luck.
- Common shapes worth checking against: a missing guard on an empty or null value; state
updated in one place and read stale in another; timing between two things that assume
an order; behaviour that differs between the test environment and the real one; a
cached value that outlives what it describes.
Then state it as one testable sentence: **"Root cause: …"** — and **prove it** before
fixing it. A log line, an assertion, or the failing test showing exactly what you
predicted. A hypothesis you have not checked is a guess.
**Three strikes.** If three hypotheses turn out wrong, stop and ask, with options:
keep going with a named new hypothesis, add logging and wait for it to happen again, or
treat it as a design problem that needs a spec. Do not try a fourth guess silently.
**Stay in the area.** Once the cause is found, edit only what the fix needs. Anything
else you notice goes on the discovered-work list.
## 4. Propose the fix — the one pause
Present, per `_partials/voice.md`:
- **What was wrong** — for the user, then the cause in a sentence
- **The fix** — the smallest change that removes the cause
- **Blast radius** — which files, and what else could be affected. If it touches **more
than five files**, say so plainly and offer to split it or look for a narrower fix: a
bug fix that sprawls is usually treating several things at once
- **How it will be proven** — the test, or the exact repro steps
- **Recommended builder** — last, as one line, per `_partials/builder.md`. The root cause
is proven by now, so the rating rests on the actual fix, not a guess about it
Then wait for approval. After that, run to a PR without stopping, as `/proof-work` does.
## 5. Fix it
**Who fixes** follows the approval, per `_partials/builder.md`: the `proof-builder` agent
on the chosen model, given the root cause and the reproduction, or this session for
`approve, here`. The rules below hold either way.
The smallest change that removes the cause. **Not** the symptom: no special-casing the
one input that failed, no retry around something that should not fail, no "for now".
**Write a regression test** that fails without the fix and passes with it. Run it both
ways and say so — a test that passes either way proves nothing. If `commands.test` is
null there is nowhere to put one: describe the manual repro check instead, and add
"no automated tests for this area" to discovered work.
Commit with `(refs #{n})`. Keep the checkpoint note current, per `/proof-work`,
including its **Builder** and **Plan** lines; the plan comment for a fix also holds the
root cause and the reproduction.
**Resuming.** A bug issue that is already `in_progress` with a checkpoint resumes as
`/proof-work` does (its section 1, and `_partials/builder.md` section 5): reconcile with
the branch's commits, then carry on from *Next* on the checkpoint's builder. The root
cause is already proven; do not re-investigate it unless the reproduction no longer
fails the way the plan comment says.
## 6. Verify, keep the docs true, add the changelog line
- Run `verify.steps` yourself, in this session — with a builder, after it reports done;
failures go back to it, and two failed fix attempts escalate to Opus, per
`_partials/builder.md`. Re-run the original reproduction and confirm it is gone. Surface
`verify.manual` for the user — never claim a manual check.
- **Docs:** if the bug came from a doc being wrong, or the fix changes documented
behaviour, fix the doc in the same change. Per the docs step in `/proof-work`.
- **Changelog:** per `_partials/changelog.md`, add a line under **Fixed** — the experience
that was broken, and what it does now.
## 7. Learnings, PR, discovered work
- **Learnings:** include any the builder reported. The root cause is almost always a
learning — it was invisible, or it would not have been a bug. Post a **Build** capture per `_partials/learnings.md`,
written as a gotcha: the condition and the consequence. If the area keeps breaking,
say that too; it is the most useful thing the record can hold.
- **PR:** as in `/proof-work`, with a **Root cause** section above the verification:
what was wrong, why, and how the test proves it is fixed. Board → `in_review`.
- **Discovered work:** per `_partials/discovered.md`.
## Hand back
The PR URL, the root cause in one line, and the verification results — including what
still needs a human check.
Then **ask what to do next**, per `_partials/chain.md` — never start the next step unasked. The next link is the same as after
`/proof-work`: review.
## When it is on fire
If users are losing data, money is being taken wrongly, or the app is down: stopping the
harm comes first, and it is allowed to be a mitigation rather than a fix — turning a
feature off, reverting the change that caused it. Say clearly that it is a mitigation,
ship it through the normal PR, and **leave the issue open** for the root cause, which then
gets this whole process. A mitigation that quietly becomes the permanent fix is how the
same fire starts twice.
Versions
The database has no other skills named proof-fix.
Database snapshot: 13.11.2026 · package version 7d3f1014bcba (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100fix
Use when fixing a bug test-first: write a failing test to reproduce it, find the root cause, fix, and add a regression test. - 100dev-bug
Use for bugs and debugging. Triggers include "bug", "debug", "why is X happening", "not working", "this is broken". Two entries, both covered - a bug is listed, or debugging only (may find no bug). Reproduces first, explains in plain terms, finds the root cause from evidence,… - 100bug-fix
Fix a Device bug the project's way - reproduce it, write a small failing test, find the root cause, fix it, prove the test now passes. Use for any bug report or broken feature; escalates to a spec when the cause or fix is not obvious. - 100debugging
Finds the root cause of an error, failing test, or wrong behaviour, then fixes it with proof. Use when something is broken, a test fails, or output is unexpected. - 100fix-issue
Fix a GitHub issue in NeMo Speech (NVIDIA-NeMo/Speech). Read the issue, reproduce the bug with a failing test, implement the fix, and verify tests pass. Only opens a PR if the user explicitly asks for it. - 95fix
Fix one bug from the board without an iteration - failing test first, smallest fix, one PR. "all" fixes every Ready bug, several at once while slots and room allow. Use when asked to fix a bug issue.