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

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.

3. Outside call

For every call to another service (API, vendor, email, payment, storage, model):

• Deadline: an explicit timeout. Library defaults are often minutes or none.
• Ambiguity: after a timeout, a dropped connection or a 5xx, could the call already have happened (posted, charged, sent)? If yes: an idempotency key, or look it up before retrying. Never retry a committing call blind.
• Failure handling: which errors are retryable, which are final, and does a final one reach the user?

4. Failure is not empty

• Can a failed load render as "nothing here", "not configured" or an empty list? The user must see an error and a way to retry.
• Can a failed read be treated as empty and then written back (a failed fetch of a list, then saving the list with one new item, erases the rest)?
• Every catch that swallows: does the error reach monitoring at a level someone will see?

5. Neighbors

For every item on the map from step 0, search the whole repo (backend, frontend, workers, scripts, migrations, tests, docs) and every repo that uses it for other readers and writers:

grep -rn "<column_or_field>" --include=*.<ext> <repo> <each repo that uses it>
grep -rn "'<status_value>'" <repo>
grep -rn "<queue_or_event_name>" <repo> <each repo that uses it>

List each neighbor in the plan and say what it needs: nothing (why), a change, or a test. Look hardest for the same job done in two places: two paths that delete, two clients for one vendor, a webhook and a reconcile job, a single-item path and a bulk path, an API and an admin script. The change usually updates one of them.

6. Endings

What does this do, and what happens to what it created, on: cancel, delete (the record and the whole account), disconnect, reconnect, expire, downgrade, plan lapsed or cancelled, trial end, replace? Is anything left running, charged, stored or promised?

7. Money

For every paid call (a vendor, a model, a third-party API) and every credit, quota or charge:

• Who pays, and what caps it? The cap must be enforced in the database, atomically.
• What refunds it on failure or cancel, can the refund run twice, does it go back where the charge came from?
• Does what the user pays cover what it costs, at the worst case, not the average?

8. Hostile user

• Is auth checked, and the size limited, before the input is read or buffered?
• Can a cap be beaten by parallel calls, or by delete-and-redo?
• Are links, tokens and OAuth states single-use and short-lived?
• Does any user-controlled text reach a prompt, a query, a shell, a file path or HTML without the matching guard?

9. Words

Search every place user-facing words live (UI strings, emails and notifications, help center, docs, marketing, pricing and legal pages, API error messages) for sentences about what this changes. Each is still true, or changes with the code. List them.

10. Scale and time

• Every query: a limit, and an index for its filter. Lists that stop at the first page (20, 50, 100 rows) silently hide the rest.
• Loops that run one query per row.
• Times: the user's or account's timezone, not the server's or the browser's. Periods: the billing period, not the calendar month. Daylight saving, month ends, leap days.

Invariants

If the repo has INVARIANTS.md, name every invariant the change touches and how it stays true. If the change creates a new rule the whole system must keep, add it there.

Output

Put this in the plan, before the first edit:

Pre-mortem: <change>
Touches: <the map from step 0>
1 Twice: <file:line | test | Not handled, because ...>
2 Halfway: ...
3 Outside call: ...
4 Failure is not empty: ...
5 Neighbors: <each neighbor: what it needs>
6 Endings: ...
7 Money: ...
8 Hostile user: ...
9 Words: <each sentence: file, still true or changing>
10 Scale and time: ...
Invariants: <each touched, and how it holds>
Tests to write: <the list, each failing on the old code>

Every "Not handled, because" is shown to the owner before building, not buried in the plan.