Skip to content
Skills Library
Programming · Building & coding

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

Licence
MIT
Last repository change
15.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

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

  1. Checklist
  2. 1. Pin down the symptom
  3. 2. Reproduce it
  4. 3. Find the root cause — and prove it
  5. 4. Propose the fix — the one pause
  6. 5. Fix it
  7. 6. Verify, keep the docs true, add the changelog line
  8. 7. Learnings, PR, discovered work
  9. Hand back
  10. When it is on fire
Original SKILL.md headings · 168 lines, 1,484 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.