⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
fix-the-class
Bug-fix routine that fixes the whole class of bug, not just the reported instance. Use for any bug report, failing production behaviour, monitoring alert, audit finding or review finding that does real harm (a smaller review finding goes on the item's list, as ship-check says), and whenever the same kind of bug has been seen before. Reproduces it with a failing test, names the failure class, searches the task's scope for the same pattern (the whole codebase when the user's own prompt asks for the fix, not when it is picked from a task's list), fixes or records every hit, and adds the rule, invariant, helper or check that stops it coming back.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
first-pass
first-pass makes a coding agent check the code around a change, not only the lines it writes, and prove its work before it calls anything done. It's a Claude Code plugin; Cursor, Codex and other agents get the same rules and skills (the hooks are Claude Code only). You set it up once, in the folder that holds your repos.
What it does
- Before code, the agent answers ten questions about the change against the real code:
what happens if it runs twice, stops halfway, or an outside service times out; which
other code uses the same data; what the user sees when it fails. Each answer is a
file:line, a test, or a gap you decide to accept. - While building, anything the task didn't ask for (a helper, a cap, a retry, an option) has to earn its place. The agent asks whether it needs to exist, leaves it out when nothing requires it, and lists it under "Not built" so you can ask for it. During the work, a review finding gets fixed only when it does real harm or stops the change doing its job; the rest come to you as one list at the end, to pick from.
- On the task you gave, the agent first writes the task's scope from your prompt and the
code around it: the feature, everything that uses the same data, the rest of the same
flow, and the steps that cancel or delete what it creates. Its searches and reviews stay
inside that scope. A serious problem it happens to see
elsewhere gets one line in the report (and one in that repo's list of known breaks when it
breaks one of its rules), and nothing else; anything the change itself breaks
counts as inside, wherever it is.
/first-pass:hulklifts the scope for one task, so it looks everywhere. - Before "done", a second agent that didn't write the code reviews it in a fresh
context. "Done" needs a test that failed before the change and CI's checks passing in a
clean checkout (or, with
/first-pass:quick, the checks the change can affect); anything less is reported as built, not done. - On a bug, it fixes the whole class: it reproduces the bug, finds the same pattern in the task's scope, and adds the check that stops it coming back.
- On a pull request,
/first-pass:reviewchecks your own branch before you ask for review, or a teammate's PRs across several repos. Every finding comes with its proof or is marked unproven, and it never posts to GitHub./first-pass:review hulk <what>reviews with the scope lifted, so it looks everywhere. - In every session, hooks send back a "done" that has no evidence behind it (edits made through the shell count too), run each repo's own hooks from the shared folder, and say what drifted since setup.
- In replies (optional, you choose at setup): plain, short answers. The first line says what happened or what you need to do, in everyday words, without the names from inside the work, and the reply ends with only what you have to do or decide.
What it helps with
- Bugs next to the change: the other code path that writes the same field, the webhook that arrives twice, the error that shows up as an empty list.
- "Fixed" and "verified" that only meant "it compiles and the mocks pass".
- An agent reviewing its own work in the same context that wrote it.
- Many repos opened from one folder, where each repo's own rules and hooks don't load.
- Prompts like "be 100% sure", which change how sure the answer sounds, not what gets checked.
- Code nobody asked for: the extra cache layer, guard or option that becomes one more thing to maintain, and the next thing to break.
- Replies too long, or too full of the agent's own names for things, to follow once you've looked away.
/plugin marketplace add joetawil7/first-pass
/plugin install first-pass@first-pass
Then, in the folder where you start your sessions: /first-pass:setup-first-pass.
Why I made this
I built a product feature by feature with Claude Code. Every feature request ended with some version of "make sure the code is correct and bug free, cover all gaps, be 100% sure." Then I ran a full audit. It found 318 issues, 25 of them high severity.
When I sorted them, only 45 were mistakes in the lines being written. The rest were in the code around those lines:
| What went wrong | Issues |
|---|---|
| Another code path using the same data was not updated | 54 |
| Runs twice, runs at the same time, or stops halfway | 54 |
| An outside service fails or is slow, and the error is hidden | 45 |
| A plain mistake in the code itself | 45 |
| Time, units, rounding | 26 |
| Scale: no limit, no index, lists that stop at one page | 25 |
| Endings: cancel, delete, expire, reconnect, downgrade | 19 |
| UI, help, legal or pricing text that says what the code doesn't do | 18 |
| Pipeline: CI red, no tests against a real database | 17 |
| Hostile user or uncapped cost | 15 |
(One private codebase, sorted by hand with one cause per issue. Your mix will differ.)
Several of these had been found by earlier audits and fixed. Each fix patched one spot, and nothing carried the lesson into the next session.
"Be 100% sure" changed how sure the answers sounded. It never made the agent open the other file that writes the same field, or ask what happens when the webhook arrives twice. So first-pass names those checks, and asks for proof before anything is called done:
- Ten questions before code (the pre-mortem): twice, halfway, outside call, failure is
not empty, neighbors, endings, money, hostile user, words, scale and time. Each answer is
a
file:line, a test, or "Not handled, because ___" for you to accept. - A reviewer that didn't write the code. Models are poor at catching their own mistakes
in the context that made them (Huang et al., 2024),
so the
breakeragent reviews each change in a fresh context, starting from the other code paths that touch the same data. - "Done" means a test that failed before the change, the breaker's review, and CI's own
checks passing in a clean checkout (or, with
/first-pass:quick, the checks the change can affect). Short of that, it's reported as built, not done. - A UI change is looked at running before it's called done: the web at a desktop and a phone width, an app on each device class it ships to, with the browsers, simulators and devices this machine has. Setup writes them down in the machine block, and for each UI repo says what is missing to look at it (a Playwright browser, a simulator, a device tool) with its install command; it installs only what you say yes to.
- Local runs that reach real people are named. Setup looks for what each repo could send for real (email, SMS, push, payments, publishing) and the switches that stop it, says "unknown" where it can't tell, and the standing yes for heavy runs never covers such a run.
- Bugs get fixed as a class: reproduce, find the same pattern in the task's scope (the whole codebase when your own prompt asks for that fix, not when you pick it from a task's list), and add the helper, constraint or check that stops it coming back.
What's in it
| Piece | What it does | When |
|---|---|---|
premortem | The ten questions, answered against the code | Before code |
breaker (agent) | Fresh-context review of the diff and of every other path touching the same data; concrete findings on |
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/fix-the-class/SKILL.md5.9 KBupstream ↗
--- name: fix-the-class description: Bug-fix routine that fixes the whole class of bug, not just the reported instance. Use for any bug report, failing production behaviour, monitoring alert, audit finding or review finding that does real harm (a smaller review finding goes on the item's list, as ship-check says), and whenever the same kind of bug has been seen before. Reproduces it with a failing test, names the failure class, searches the task's scope for the same pattern (the whole codebase when the user's own prompt asks for the fix, not when it is picked from a task's list), fixes or records every hit, and adds the rule, invariant, helper or check that stops it coming back. --- # 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). 2. **A database constraint** (a unique index that makes "twice" impossible). 3. **A check that fails CI** (a lint rule or test that finds the pattern, like a vendor call without a timeout). 4. **An invariant** in `INVARIANTS.md`, with what now holds it. 5. **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 ```README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/joetawil7-first-pass-skills-fix-the-class.md