joetawil7/first-pass/fix-the-class

fix-the-class

A fix that guards only the spot where the bug was found invites the same bug in the next feature. Audits that find the same bug twice are the sign. Fix the instance, then the class.

1. Reproduce

Write a test that fails the way the report says, at the lowest layer that reproduces it end to end (see ship-check step 2). No test, no fix: if it cannot be reproduced, say what was tried and stop.

2. Name the class

Which pre-mortem question did the original change fail? Twice, halfway, outside call, failure-is-not-empty, neighbors, endings, money, hostile user, words, scale and time. Which invariant in INVARIANTS.md does it break? If none fits, the invariant is missing: draft it.

State the pattern in one sentence that can be searched for, for example:

• "a status check outside the transaction that then writes" (twice)
• "a done-marker saved before the work" (halfway)
• "a vendor call with no timeout" or "a committing call retried on 5xx" (outside call)
• "a query result checked for loading but not for error" (failure is not empty)
• "the delete path skips what the disconnect path releases" (neighbors)
• "a refund with no record of which charge it refunds" (money)

3. Search for the pattern

Search the task's scope for other instances (the rules' "Stay in the task's scope"): the code it covers, everything that reads or writes the same data, and in a main folder every repo the workspace section says shares that code, data or vendor (the same bug is often copied between a web app and a mobile app, or between two services calling one vendor). When the user's own prompt asks for this bug's fix, or the user lifted the scope with hulk, the scope is the whole codebase: the repo and every repo that shares its code, data or vendor. A fix the user picks from a task's end list is not such a prompt: it keeps that task's scope. Examples by class:

• Twice: read-then-write on the same row (find then update without a lock or

conditional WHERE), counts compared to limits before inserting.

• Halfway: status = 'done' / sent = true / claimed written before the call it

describes.

• Outside call: fetch calls, HTTP client calls and SDK constructors without a

timeout option; retry wrappers around calls that commit.

• Failure is not empty: catch blocks that return [], null or a default; UI

queries that read isLoading and not isError.

• Neighbors: every writer of the field or status involved; every path that does the

same job (all delete paths, all clients of the vendor, all branches by type).

• Money: every refund or credit path; every paid call and its cap.
• Scale and time: queries without a limit; new Date() or calendar-month math where a

user's timezone or a billing period is meant.

List every hit with file:line and a verdict: same bug, safe (why), or unsure.

4. Pre-mortem the fix

The fix is a change too, and it can break something the bug never touched: a lock that leaves an order stuck when the vendor fails, or a guard that also blocks a second payment the customer really meant. Before the first edit to the fix (the failing tests from step 1 come first), run the premortem skill on the fix and on the fixes planned for the other hits, sized by its own rules. Its ten questions go against the fixed code, the bug's own question included: step 2 named it for the old code, and here the answer says what now stops the bug in every form it takes (for a double charge: two tabs, a retry, two instances). If a pre-mortem of this fix was written earlier in the session, point to it and add what it does not cover: the other hits' fixes, and anything about the fix that changed since. A pre-mortem of other work, such as the feature the bug is in, does not count.

5. Fix or record every hit

• Same bug and in scope: fix it, each with a failing-first test.
• Same bug outside the task's scope (seen in passing, never searched for): when it does real

harm, one line in the report marked "outside this task", with file:line, and a Known breaks line in that repo's INVARIANTS.md when it breaks one; nothing else is edited for it.

6. Make it hard to do again

Pick the strongest prevention that fits inside the task's scope, and propose or build it (one that would reach outside the scope is proposed in one line, not built):

1. A shared helper that is the only way to do the thing (one vendor-call function that

always sets a timeout and an idempotency key; one refund function keyed by the charge; one claim function that fails on 0 rows; one delete path used by every caller).

1. A database constraint (a unique index that makes "twice" impossible).
2. A check that fails CI (a lint rule or test that finds the pattern, like a vendor call

without a timeout).

1. An invariant in INVARIANTS.md, with what now holds it.
2. A rule in the project's instruction file, as a last resort: rules are advisory,

checks are enforced.

A prevention you build is part of the fix: add it to the step 4 pre-mortem before building it.

7. Finish with ship-check

Run the ship-check skill. The report adds:

Class: <pre-mortem question> / <invariant>
Pattern: <the searchable sentence>
Other hits: <n fixed, n recorded, n safe>, each with file:line
Prevention: <helper | constraint | check | invariant | rule>, and where