Skip to content
Back to search

first-pass

Rules and checks that make Claude Code look around a change, not just at the lines it writes: ten questions before code, a reviewer that didn't write it, proof before done, bugs fixed as a class.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/joetawil7--first-pass/badge.svg)](/listings/joetawil7--first-pass)

HTML

<a href="/listings/joetawil7--first-pass"><img src="/api/listings/joetawil7--first-pass/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code

/plugin marketplace add joetawil7/first-pass
/plugin install first-pass@first-pass

From a terminal: `claude plugin marketplace add joetawil7/first-pass`, then `claude plugin install first-pass@first-pass`. To update later: `claude plugin marketplace update first-pass`, then `claude plugin update first-pass@first-pass`.

The hooks need Node.js 18 or later on your PATH. The tests run on Windows and Linux.

Cursor, Codex and other agents

npx skills add joetawil7/first-pass -a cursor --copy        # this project
npx skills add joetawil7/first-pass -a cursor --copy -g     # every project

This uses the [skills CLI](https://github.com/vercel-labs/skills). Swap `-a cursor` for your agent (`-a codex`, `-a windsurf`, ...). `--copy` writes real files instead of symlinks, which Windows checkouts turn into plain text. Don't add `-a claude-code` if you use the plugin, or you'll get every skill twice. Other tools get the rules and skills; the hooks are Claude Code's.

Then run setup once

In the folder where your sessions start: `/first-pass:setup-first-pass` (or `/setup-first-pass` outside Claude Code). It looks through your repos, asks only what the code can't tell it (which repos have a UI, which depend on which, which repo hooks to run), and writes the files above. Re-run it after an update: your own text, each repo's section and `INVARIANTS.md` are kept.

Teammates

Once a repo's files are committed, every teammate's agent loads its section. Tell setup which repos people open on their own: those also get the rules and a copy of the breaker. Each person installs the skills: the plugin for Claude Code, the `npx skills` line for Cursor.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "first-pass",
  4. "description": "Ship it right on the first pass.",
  5. "owner": {
  6. "name": "joetawil7",
  7. "url": "https://github.com/joetawil7"
  8. },
  9. "plugins": [
  10. {
  11. "name": "first-pass",
  12. "description": "Makes your coding agent look around a change: ten questions before code, a reviewer that didn't write it, proof before done, bugs fixed as a class, and your habit words mapped to real checks.",
  13. "source": "./",
  14. "category": "development"
  15. }
  16. ]
  17. }
README.md · README · 403 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # first-pass
  2. [![validate](https://github.com/joetawil7/first-pass/actions/workflows/validate.yml/badge.svg)](https://github.com/joetawil7/first-pass/actions/workflows/validate.yml)
  3. [![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  4. first-pass makes a coding agent check the code around a change, not only the lines it
  5. writes, and prove its work before it calls anything done. It's a Claude Code plugin;
  6. Cursor, Codex and other agents get the same rules and skills (the hooks are Claude Code
  7. only). You set it up once, in the folder that holds your repos.
  8. **What it does**
  9. - **Before code,** the agent answers ten questions about the change against the real code:
  10. what happens if it runs twice, stops halfway, or an outside service times out; which
  11. other code uses the same data; what the user sees when it fails. Each answer is a
  12. `file:line`, a test, or a gap you decide to accept.
  13. - **While building,** anything the task didn't ask for (a helper, a cap, a retry, an option)
  14. has to earn its place. The agent asks whether it needs to exist, leaves it out when
  15. nothing requires it, and lists it under "Not built" so you can ask for it. During the
  16. work, a review finding gets fixed only when it does real harm or stops the change doing its
  17. job; the rest come to you as one list at the end, to pick from.
  18. - **On the task you gave,** the agent first writes the task's scope from your prompt and the
  19. code around it: the feature, everything that uses the same data, the rest of the same
  20. flow, and the steps that cancel or delete what it creates. Its searches and reviews stay
  21. inside that scope. A serious problem it happens to see
  22. elsewhere gets one line in the report (and one in that repo's list of known breaks when it
  23. breaks one of its rules), and nothing else; anything the change itself breaks
  24. counts as inside, wherever it is. `/first-pass:hulk` lifts the
  25. scope for one task, so it looks everywhere.
  26. - **Before "done",** a second agent that didn't write the code reviews it in a fresh
  27. context. "Done" needs a test that failed before the change and CI's checks passing in a
  28. clean checkout (or, with `/first-pass:quick`, the checks the change can affect); anything less is reported as built, not done.
  29. - **On a bug,** it fixes the whole class: it reproduces the bug, finds the same pattern in
  30. the task's scope, and adds the check that stops it coming back.
  31. - **On a pull request,** `/first-pass:review` checks your own branch before you ask for
  32. review, or a teammate's PRs across several repos. Every finding comes with its proof or
  33. is marked unproven, and it never posts to GitHub. `/first-pass:review hulk <what>` reviews
  34. with the scope lifted, so it looks everywhere.
  35. - **In every session,** hooks send back a "done" that has no evidence behind it (edits made
  36. through the shell count too), run each repo's own hooks from the shared folder, and say
  37. what drifted since setup.
  38. - **In replies** (optional, you choose at setup): plain, short answers. The first line says
  39. what happened or what you need to do, in everyday words, without the names from inside
  40. the work, and the reply ends with only what you have to do or decide.
  41. **What it helps with**
  42. - Bugs next to the change: the other code path that writes the same field, the webhook
  43. that arrives twice, the error that shows up as an empty list.
  44. - "Fixed" and "verified" that only meant "it compiles and the mocks pass".
  45. - An agent reviewing its own work in the same context that wrote it.
  46. - Many repos opened from one folder, where each repo's own rules and hooks don't load.
  47. - Prompts like "be 100% sure", which change how sure the answer sounds, not what gets
  48. checked.
  49. - Code nobody asked for: the extra cache layer, guard or option that becomes one more thing
  50. to maintain, and the next thing to break.
  51. - Replies too long, or too full of the agent's own names for things, to follow once you've
  52. looked away.
  53. ```
  54. /plugin marketplace add joetawil7/first-pass
  55. /plugin install first-pass@first-pass
  56. ```
  57. Then, in the folder where you start your sessions: `/first-pass:setup-first-pass`.
  58. ## Why I made this
  59. I built a product feature by feature with Claude Code. Every feature request ended with
  60. some version of "make sure the code is correct and bug free, cover all gaps, be 100% sure."
  61. Then I ran a full audit. It found **318 issues, 25 of them high severity.**
  62. When I sorted them, only 45 were mistakes in the lines being written. The rest were in the
  63. code around those lines:
  64. | What went wrong | Issues |
  65. | ----------------------------------------------------------------- | -----: |
  66. | Another code path using the same data was not updated | 54 |
  67. | Runs twice, runs at the same time, or stops halfway | 54 |
  68. | An outside service fails or is slow, and the error is hidden | 45 |
  69. | A plain mistake in the code itself | 45 |
  70. | Time, units, rounding | 26 |
  71. | Scale: no limit, no index, lists that stop at one page | 25 |
  72. | Endings: cancel, delete, expire, reconnect, downgrade | 19 |
  73. | UI, help, legal or pricing text that says what the code doesn't do | 18 |
  74. | Pipeline: CI red, no tests against a real database | 17 |
  75. | Hostile user or uncapped cost | 15 |
  76. (One private codebase, sorted by hand with one cause per issue. Your mix will differ.)
  77. Several of these had been found by earlier audits and fixed. Each fix patched one spot,
  78. and nothing carried the lesson into the next session.
  79. "Be 100% sure" changed how sure the answers sounded. It never made the agent open the other
  80. file that writes the same field, or ask what happens when the webhook arrives twice. So
  81. first-pass names those checks, and asks for proof before anything is called done:
  82. - **Ten questions before code** (the pre-mortem): twice, halfway, outside call, failure is
  83. not empty, neighbors, endings, money, hostile user, words, scale and time. Each answer is
  84. a `file:line`, a test, or "Not handled, because ___" for you to accept.
  85. - **A reviewer that didn't write the code.** Models are poor at catching their own mistakes
  86. in the context that made them ([Huang et al., 2024](https://arxiv.org/abs/2310.01798)),
  87. so the `breaker` agent reviews each change in a fresh context, starting from the other
  88. code paths that touch the same data.
  89. - **"Done" means a test that failed before the change**, the breaker's review, and CI's own
  90. 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.
  91. - **A UI change is looked at running** before it's called done: the web at a desktop and a
  92. phone width, an app on each device class it ships to, with the browsers, simulators and
  93. devices this machine has. Setup writes them down in the machine block, and for each UI
  94. repo says what is missing to look at it (a Playwright browser, a simulator, a device tool)
  95. with its install command; it installs only what you say yes to.
  96. - **Local runs that reach real people are named.** Setup looks for what each repo could send
  97. for real (email, SMS, push, payments, publishing) and the switches that stop it, says
  98. "unknown" where it can't tell, and the standing yes for heavy runs never covers such a run.
  99. - **Bugs get fixed as a class**: reproduce, find the same pattern in the task's scope (the
  100. whole codebase when your own prompt asks for that fix, not when you pick it from a task's
  101. list), and add the
  102. helper, constraint or check that stops it coming back.
  103. ## What's in it
  104. | Piece | What it does | When |
  105. | --- | --- | --- |
  106. | `premortem` | The ten questions, answered against the code | Before code |
  107. | `breaker` (agent) | Fresh-context review of the diff and of every other path touching the same data; concrete findings only | Before done |
  108. | `ship-check` | The definition of done, ending in a report where every "Verified" line says what was run and its result | Before done |
  109. | `fix-the-class` | Reproduce, name the class, search for it in the task's scope (everywhere when your own prompt asks for that fix, not when you pick it from a task's list), run the ten questions on the fix, fix or record each hit, make it hard to repeat | On any bug |
  110. | `setup-first-pass` | Writes the rules once, a map of your repos, and a section per repo with its real commands, test limits and a drafted `INVARIANTS.md` | Once, then to update |
  111. | `habit-words` | Reads what you typed in your recent sessions and maps words like "be 100% sure" to the checks they should mean | At setup, then when due |
  112. | `sharpen` | Rewrites the prompt you type after it: numbered asks, habit words turned into checks, names and numbers kept exactly. Shows you the rewrite, then works from it | Only when you type it |
  113. | `review` | Reviews your own branch before you ask for review (type nothing after it), or a teammate's PRs, several repos at once. Checks the change against its ticket, judges the failed checks and every Bugbot comment, runs the breaker, traces the other code that uses what changed, proves each finding or marks it unproven, and says what the merge needs and how to check the deploy. Reads GitHub and never posts; pushes a fix only on your yes | Only when you type it |
  114. | `jev` | Sets up the optional Jev judge (TypeSafe's decision model), which `ship-check` asks whether a review finding is real harm, which small ones to fix now, and what proof a small fix needs | Only when you type it |
  115. | `hulk` | Lifts the task's scope for one task: searches, reviews and bug hunts go across the whole codebase, and problems found anywhere are handled as usual (for a pull request: `/first-pass:review hulk <what>`) | Only when you type it |
  116. | `quick` | Quick mode, until `/first-pass:quick off`: instead of CI's full checks, a change runs format, lint, types, build, its own tests and every unit, integration, flow and browser test that reaches what it touched; the rest of the suite is left for a full run, such as your pull request's CI | Only when you type it |
  117. | Parts runner | Runs CI's checks on your machine in the parts your repo's `.first-pass/parts.json` names (setup drafts it from CI): stages in order, a stage's parts side by side, each with its own port, run-named databases and logs, through your memory-capped runner if you named one (with one repo and no main folder, one part at a time inside it). It stops only what it started, and a part that needs another refuses to run until that one passed on the same checkout; `--tests` gives the steps that take a test list only chosen files, and `--no-tests` runs a part's other steps without them | When `ship-check` runs CI's checks |
  118. | Hooks | Run each repo's own hooks from the main folder, send back a "done" with no evidence, say what drifted at session start, and hold `sharpen`'s work until its rewrite is shown | Every session |
  119. ## If you keep all your repos in one folder
  120. A lot of us open one folder with every repo in it and start each session there. Claude Code
  121. then finds agents, skills and hooks only in that folder and above it: a repo's own
  122. `.claude/agents`, its `.claude/settings.json` hooks and its `.cursor/rules/*.mdc` imports
  123. never load, and its CLAUDE.md loads only once a file in it is read. first-pass is built for
  124. that:
  125. - **One set of rules at the root**, in `AGENTS.md` (imported by `CLAUDE.md`), loaded from
  126. the first message and updated in one place.
  127. - **A section per repo**, written from what setup finds in it: CI's exact commands, how to
  128. run one test, what the real tests need running, test limits, where its user-facing words
  129. live, and the same job done in two places. It loads when work reaches that repo.
  130. - **Each repo's own hooks still run.** Setup lists them and you approve each one. An
  131. approval pins the hook and every file in its script's folder: if a pull changes one, the
  132. hook pauses until you approve it again, and you and the agent are both told.
  133. - **Drift is reported at session start**: a repo's CI changed since its section was written,
  134. a new repo appeared, a hook was paused, a Cursor rule's copy fell behind, the rules are
  135. older than the plugin.
  136. - **One repo on its own works too**: setup writes the rules and the section into that repo.
  137. ## Your habit words
  138. Most of us have words we type out of habit: "be 100% sure", "don't assume", "full review",
  139. "all fine, right?". They name no place to look, so the answer sounds more certain without
  140. anything more being checked.
  141. `habit-words` reads what you typed in your last 20 Claude Code sessions, shows how often you
  142. use each phrase, what went wrong after it, and what to say instead. Then it writes a short
  143. block that maps each phrase to the checks it should trigger. You never have to type them
  144. again, and if you do, they mean the checks, not a more confident tone.
  145. What it reads and keeps:
  146. - Only your own transcripts in `~/.claude/projects`, and only what you typed, plus the end
  147. of the agent's reply before each prompt that pushes back on it. Tool output, pasted text,
  148. notifications and script-started runs are left out.
  149. - Anything that looks like a key, token, password, email or phone number is replaced before
  150. the text goes into a temp file (best effort, so the skill also never quotes one). The
  151. skill deletes the file when it's done.
  152. - The block holds only your phrases and the checks, and never goes into a file your
  153. teammates share.
  154. ## What it writes to your machine
  155. - `AGENTS.md` and `CLAUDE.md` at the root (the rules and, if you want them, the reply style
  156. and your habit words), and a section in each repo's `CLAUDE.md` or
  157. `AGENTS.md`, all between `first-pass` markers. Outside the markers it adds only import
  158. lines, and it lists each one it adds.
  159. - The machine block in your `~/.claude/CLAUDE.md`, in every mode: this machine's answer on
  160. heavy runs (in every project on it, except a server, a worker or an end-to-end or integration
  161. run in a repo with no first-pass section, or whose real-people line says "unknown" or is
  162. missing, which asks first), how a run is bounded and stopped here (a wrapper named there is
  163. the one the parts runner starts each part through in a main folder), and what can look at a UI (browsers,
  164. simulators, emulators, device tools) or is missing for it. It describes your machine only, so it never goes in
  165. a file your teammates share.
  166. - `INVARIANTS.md` in each repo (a draft for you to review), `.first-pass/workspace.json` at
  167. the root, and `.claude/cursor-rules/*.md` copies where a repo imports `.mdc` files.
  168. - `.first-pass/parts.json` in a repo whose CI checks split into parts, for the parts runner, and
  169. the runner's logs, marks and lock files in `first-pass-parts` in the system temp folder. They
  170. stay there after a run, so you can read them. Delete the folder only when no run is going:
  171. a killed run's leftovers (a file it wrote in the checkout, a test database) are cleaned up by
  172. the next run of that part only while its record is there.
  173. - A small state folder in `~/.claude/plugins/data/` for the hooks, and a temp file while
  174. `habit-words` runs, deleted when it's done.
  175. - `~/.claude/first-pass/jev.json`, only if you set up the Jev judge: which variable holds
  176. your key, and for which repos. Never the key itself.
  177. Setup never commits or pushes, and sends nothing anywhere except one test request per key
  178. to TypeSafe if you set up the Jev judge: you review the files and commit them. The plugin's own
  179. scripts make no network calls and read no keys or tokens from your environment (the parts
  180. runner runs your repo's own test commands, reads only the keys its recipe names from your
  181. repo's env file, and checks only that a test server on this machine answers), with one
  182. exception you have to switch on: the Jev judge reads the one key you named and sends review
  183. findings (with secrets, emails and phone numbers blanked) to TypeSafe's API, from
  184. `ship-check` and `jev`. Setup's survey reads only the variable names in the example env files
  185. a repo commits (`.env.example` and the like), never a value and never your real `.env`. Besides that, the only skill that reaches a server is `review`: it
  186. reads the PRs, checks and comments through your own `gh` login, and it pushes a fix only
  187. when you picked that fix and said yes to the push.
  188. ## Install
  189. ### Claude Code
  190. ```
  191. /plugin marketplace add joetawil7/first-pass
  192. /plugin install first-pass@first-pass
  193. ```
  194. From a terminal: `claude plugin marketplace add joetawil7/first-pass`, then
  195. `claude plugin install first-pass@first-pass`. To update later:
  196. `claude plugin marketplace update first-pass`, then `claude plugin update first-pass@first-pass`.
  197. The hooks need Node.js 18 or later on your PATH. The tests run on Windows and Linux.
  198. ### Cursor, Codex and other agents
  199. ```
  200. npx skills add joetawil7/first-pass -a cursor --copy # this project
  201. npx skills add joetawil7/first-pass -a cursor --copy -g # every project
  202. ```
  203. This uses the [skills CLI](https://github.com/vercel-labs/skills). Swap `-a cursor` for your
  204. agent (`-a codex`, `-a windsurf`, ...). `--copy` writes real files instead of symlinks,
  205. which Windows checkouts turn into plain text. Don't add `-a claude-code` if you use the
  206. plugin, or you'll get every skill twice. Other tools get the rules and skills; the hooks are
  207. Claude Code's.
  208. ### Then run setup once
  209. In the folder where your sessions start: `/first-pass:setup-first-pass` (or
  210. `/setup-first-pass` outside Claude Code). It looks through your repos, asks only what the
  211. code can't tell it (which repos have a UI, which depend on which, which repo hooks to run),
  212. and writes the files above. Re-run it after an update: your own text, each repo's section and
  213. `INVARIANTS.md` are kept.
  214. ### Teammates
  215. Once a repo's files are committed, every teammate's agent loads its section. Tell setup
  216. which repos people open on their own: those also get the rules and a copy of the breaker.
  217. Each person installs the skills: the plugin for Claude Code, the `npx skills` line for
  218. Cursor.
  219. ## Day to day
  220. 1. **Plan.** Ask for the change. The agent runs the pre-mortem before it edits. Read the
  221. "Not handled, because" lines: those are your calls.
  222. 2. **Build**, with the tests the pre-mortem named, each one failing on the old code first.
  223. 3. **Done.** `ship-check` runs the breaker and, while it works, CI's checks in a clean
  224. checkout (in CI's own parts side by side, when the repo has a parts recipe), when your repo's test limits and your machine's limit on heavy runs at once allow both. Nothing is committed to your
  225. branch before the review's result is handled unless you say to ship it as it is, and
  226. nothing is called done before it either way. Then it reports
  227. `Verified: <what was run> → <result>` and what wasn't verified.
  228. 4. **Bug.** `fix-the-class` fixes the one you found, the others like it, and adds the check
  229. that stops the next one.
  230. 5. **Review.** On your own branch, `/first-pass:review` with nothing after it reviews your
  231. work against its base, its PR, its checks and the ticket in the branch name, and ends
  232. with what to fix before you ask for review. On a teammate's PR, add the links and what's
  233. live, for example *"/first-pass:review backend#147 web#151, live today: no agency
  234. workspaces"*: the same checks, plus a message you can send the developer. Every finding
  235. comes with its proof, or is marked unproven, and says whether users can hit it today. A
  236. PR from a fork or an outside contributor is read, never run, unless you say yes, since
  237. running it would run a stranger's code with your logins. The report also says what
  238. changes for users, what the merge needs (a new app build, env vars, migrations, deploy
  239. order), what to check after the deploy, and which of the ten questions and which
  240. neighboring code were checked. It reads GitHub but never posts, and it fixes something
  241. only when you pick it after the report.
  242. Instead of "make sure it's bug free", try: *"Run the pre-mortem, show me the tests that fail
  243. without the change, and list what you didn't verify."*
  244. Or write the prompt the way you would anyway and put `/first-pass:sharpen` in front of it
  245. (`/sharpen` in Cursor). It splits a message that mixes three asks into a numbered list,
  246. turns the habit words into the checks they stand for, shows you the rewrite, and works from
  247. that. It stops to ask only when it would have to guess, and it never adds work you didn't
  248. ask for. In Claude Code a hook holds back edits, shell commands, subagents, MCP tools,
  249. publishing, scheduling and other skills until the rewrite is on screen (reading files is
  250. never held back): with the
  251. instruction alone, the rewrite was skipped in 7 of my 11 test runs.
  252. If you have a [TypeSafe](https://docs.typesafe.ai) API key, `/first-pass:jev` turns on a
  253. second opinion for `ship-check`: Jev, a model that only picks from a list and says how sure
  254. it is, judges whether each review finding is real harm, which small ones are worth fixing
  255. now, and what proof a small fix needs (the checks alone, a unit test, a real-database test
  256. or a browser test). It is cheap and fast, but when I had it sort 269 audit issues it gave
  257. more weight to how many people meet an issue than to how bad the harm is. So it can make a
  258. finding serious, never clear one the reviewer called serious, and when it is unsure or
  259. fails, the rules decide as if it weren't there.
  260. ## How the rules were tested
  261. I test a rule the way I'd test code: fresh Claude Code sessions and agents (Opus, high
  262. effort) that load nothing else, hidden checks they never see, and judges who read the
  263. output blind.
  264. - **Less code nobody asked for.** 52 runs on two tasks (add caching to a product page, add
  265. coupons to a checkout). The runs compared first-pass alone, first-pass with
  266. [ponytail](https://github.com/DietrichGebert/ponytail), and versions of the "does it need
  267. to exist?" rule.
  268. - Every hidden correctness check passed in every run, except one about declined cards.
  269. That check failed in 15 of the 32 coupon runs, across every setup, and it tested my
  270. fake payment gateway more than the code.
  271. - On caching, a blind judge counted about 10 lines per run that nobody asked for with
  272. first-pass alone, and 3 with the rules that ship.
  273. - On coupons, the code added after the reviewer's findings went from 6 lines per run to 3.
  274. - The tests the agent wrote caught 18 of 18 planted bugs with the shipped rules. With
  275. ponytail installed, 2 of 30 got past them.
  276. - One rule I expected to help, "a promise in the docs counts as a real need", made the
  277. code about 40% bigger, so it's not in.
  278. - **Plain replies.** 10 real replies were rewritten under the old and the new reply rules.
  279. Two fresh judges, reading like a smart 15-year-old, picked the new version 16 times out
  280. of 20, rated it clearer (3.3 vs 3.0 out of 5) and got lost on fewer phrases (150 vs 175).
  281. The catch: 7 times it held back something that mattered, so the rule now says never to
  282. hold back a risk, a failure or a decision that's yours.
  283. - **The reviewer still reports every bug in the change** (measured before 0.6's scope
  284. rule). In 3 runs on a small change with 8 planted
  285. bugs, all 8 were in every review and in every final reply.
  286. These are small samples on small tasks. They show the rules do what they say, not how much
  287. they help on your code.
  288. ## What it won't do
  289. - **It's slower per change.** A test that fails first, a second agent's review and CI in a
  290. clean checkout take time and tokens. On a small demo repo, fixing one double-charge bug
  291. with `fix-the-class` and then running `ship-check` used about $29 at API list prices
  292. (three reviewer passes). The trade is fewer rounds after "done". The pre-mortem scales
  293. with the change: a copy tweak answers it in one line. To keep the cost down, a prompt with
  294. several items builds them all first, then reviews them while CI's full checks run in one
  295. clean checkout holding them all. A later fix reruns only the checks it can affect, and the
  296. full checks run once more on the final change: nothing is committed before them unless you
  297. say to ship it as it is, and nothing is called done before they pass. `/first-pass:quick`
  298. trades the full checks for the ones the change can affect and leaves the rest of the suite
  299. for a full run, such as your pull request's CI. During the work, only serious findings (money, data, something done twice or sent
  300. wrong, security, legal, a crash, stuck work, the change not doing its job) are fixed and
  301. checked again; those only a rare path reaches, found after the first review, are collected
  302. and fixed together in one batch with one review, and a rare one that batch's review or a later
  303. review of the same change finds comes to you first on the list instead of starting another
  304. round; nothing ships until you answer, and the change stays not done while it's unfixed. The smaller ones
  305. come to you once, as one list at the end, and the ones you pick get one review together.
  306. Before this, a reviewer finding a small case, a question to you, a fix and another review
  307. of that fix could chain for hours: in one two-day stretch, about a third of 84 reviews
  308. found only small points, and most of them still started another round.
  309. Questions to you wait until nothing else can move (`sharpen` and setup still ask before
  310. they start, and a failed commit, push or deploy still stops the work at once): each one stops the session until you
  311. answer, and in three sessions over three days, 17 of 70 sets of questions waited an hour or
  312. more. So the agent first does every part that doesn't depend on your answer, then asks
  313. what's left in one set.
  314. - **It won't make code bug free.** The aim is fewer and smaller escapes: no high-severity
  315. ones, no bug class found twice. This is version 0.9, so that's the design, not a measured
  316. result yet.
  317. - **Rules alone fade.** The fixes that last are the ones `fix-the-class` pushes toward: a
  318. shared helper that's the only way to do a thing, a database constraint, a CI check.
  319. - **Shell edits are seen late, and not all of them.** A file a shell command changes
  320. (`sed -i`, a heredoc, a copy, a formatter) is found at the end of the turn, from
  321. `git status` and the file's time, so the done check and end-of-turn hooks see it; hooks
  322. that run after each edit don't. Not seen: files git ignores; on Windows, a copy
  323. (`Copy-Item`, `copy`) over a file git showed no change in, which keeps the source's
  324. times; writes from a command still running in the background after it returned; from a
  325. main folder, a repo the command neither runs in, `cd`s into nor names a path in; and, in
  326. a single repo, any other repo. Counted anyway: a file rewritten with the same content
  327. (`git stash`, then `git stash pop`); another program's write or delete while a shell
  328. command runs; and after you refuse a command, writes until your next prompt. A delete is
  329. dated by its folder, so a later change in the same folder can count or hide it.
  330. ## Related
  331. - [superpowers](https://github.com/obra/superpowers): a full development method for coding
  332. agents, as skills.
  333. - [anthropics/skills](https://github.com/anthropics/skills): Anthropic's examples of skills.
  334. - [ponytail](https://github.com/DietrichGebert/ponytail): makes coding agents write less
  335. code. first-pass's "does it need to exist?" rule came from testing against it.
  336. - [i-have-adhd](https://github.com/ayghri/i-have-adhd): replies shaped so you can act on
  337. them. first-pass's reply rules borrow its check of the first and last lines.
  338. - Huang et al., [Large Language Models Cannot Self-Correct Reasoning Yet](https://arxiv.org/abs/2310.01798) (ICLR 2024)
  339. - Tambon et al., [Bugs in Large Language Models Generated Code](https://arxiv.org/abs/2403.08937)
  340. - Anthropic, [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices)
  341. ## Feedback
  342. If you try it and it gets in your way, [open an issue](https://github.com/joetawil7/first-pass/issues)
  343. and tell me where. Reports of a bug that got past all of this are the most useful kind.
  344. ## License
  345. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.