Premortem

premortem

Assume the change shipped and broke. Find out where, before writing it.

"Be careful" does nothing: it names no place to look. These ten questions name places. Each answer is one of three things, and nothing else counts:

• file:line showing it is already handled,
• the test that will prove it (named now, written with the change), or
• "Not handled, because ___", a reason the owner can accept or reject.

"N/A" is allowed only with the reason: "Twice: N/A, the handler is a pure read".

Size it to the change

• A copy or style change: one line covering all ten ("Words: checked X; rest N/A, no data or behaviour change").
• A normal feature: a line or two per question.
• Money, publishing, deletion, auth, background jobs, anything irreversible: a paragraph per question, and read the code for each, don't answer from memory.

0. Map what the change touches

First the task's scope (the rules' "Stay in the task's scope"). A change with no logic in it (a comment, a doc, a spelling fix: no behaviour changes and no label's meaning changes; when unsure, it is not one) writes one line, Scope: <the file or text>, no behaviour change, and goes on. Anything else draws it from the code, not from the prompt's words alone:

1. Name the goal and the feature or flow it is about, in the user's words.
2. Find where that feature lives: search the repo for the user's words and the feature's own names (pages, routes, jobs, workers, modules), and read the entry files.
3. From them, list the data they read and write (tables and fields, queues, events, vendor calls) and the shared code they call.
4. Add what reads or writes the same data or calls the same code (step 5's neighbors), the feature's other paths (by hand and on a schedule, one at a time and in bulk), the steps of the ending paths that handle what it creates or uses (every ending in step 6: cancel, refund, delete, disconnect, reconnect, expire, downgrade, a plan lapsed, a trial ending, replace, and the deletion of the whole account), every pair the repo's section lists as the same job in two places that the change touches or whose job it does, and the sentences that describe it (step 9).
5. Write it: Scope: <goal>. Inside: <features, flows and modules, by name>. Endings: <the steps of each step-6 ending (account deletion included) that handle what it creates or uses, or "none, because ___">. Outside: <the nearest features left out, by name, each with why the goal still holds without it>. Naming the endings and the nearest ones left out makes each border a decision, not an accident: one whose "why" fails goes inside.
6. Draw it again when the work finds something new it depends on (a table, a job, another caller): the scope grows because the work cannot be correct without it; say so in one line.

The map and the searches below stay inside it. Inside it by definition: the neighbors in step 5, the steps of the ending paths in step 6 that handle what the change creates or uses, the same job done in two places, the sentences in step 9, and any problem the change caused or made worse.

List every field or column, status value, option key, queue or topic, cron, event, endpoint, DTO property and outside service the change reads or writes. This list drives questions 1 to 10.

Name the repo each item lives in. In a main folder with many repos, the workspace section of the root AGENTS.md or CLAUDE.md says which repos use this one (a web app and a mobile app calling an API, a website quoting the app's prices): their readers are neighbors too. Read the repo's own section (its first-pass:project block) for extra cases and for the same job done in two places.

1. Twice

What happens when this runs two times: double-click, two tabs, the client retrying, the job queue retrying after a timeout, two instances of the worker, a webhook delivered again?

• Find the guard: a unique constraint, an idempotency key, a conditional update whose affected-row count is checked (UPDATE ... WHERE status = 'queued', 0 rows means stop), a lock held across the whole check-and-write.
• Read-then-write with no lock is not a guard. An in-memory flag is not a guard once there are two processes.
• Test: fire the same call twice at once (Promise.all, parallel requests, a job run twice) and assert one effect.

2. Halfway

Walk the code write by write. If the process dies right after each one (a deploy, a crash, out of memory), what state is left, and what does the retry do with it?

• A "done", "sent" or "claimed" marker written before the work means the retry skips work that never happened. Write it after, or in the same transaction.
• Two writes that must both happen belong in one transaction, or the second must be retryable from the first.
• Check the job's timeout against its longest real run: a job killed at its timeout while still working is retried while the first copy runs on.