Gotchas

The bugs that survive tsc, the linter, and the first green test run. Both humans and LLMs miss them for the same reason: the code is locally well-formed, and the failure lives in the gap between what a call looks like it does and what the runtime, network, or clean checkout actually does.

If a failure path returns a valid-looking value, you do not have error handling. You have a bug that hides.

If state changes before the work that can fail, a failure leaves the UI and the data talking about different worlds.

Source checks and dates: SOURCES.md.

Procedure

1. Read the diff or the files under review, plus .gitignore, package.json scripts, and the test files that cover the change.
2. Walk the five lenses in the table below. Only load the resource file for a lens that touches the code in front of you.
3. For every async action, trace two paths on paper before running anything:
   • What happens when the network, parser, or worker rejects halfway through?
   • What happens when the user clicks twice and the first call settles after the second?
4. Check the proof. A green test counts only if it ran after the last edit, hit the real code path, and fails when the fix is reverted.

read the diff
      |
      +-- calls fetch, fs, clipboard, timers, URL, worker, JSON? --> web-and-runtime.md
      |
      +-- sets state around an await, or shares module state? ----> state-and-async.md
      |
      +-- has try/catch, fallbacks, defaults, or quiet returns? ---> silent-failures.md
      |
      +-- touches build, public/, env, hooks, or package.json? ----> fresh-clone.md
      |
      +-- adds or edits tests, mocks, or assertions? --------------> false-green-tests.md

Where to read

The traps that slip past review most often

Review checklist

• Every catch either rethrows with context, sets a visible error state, or documents why silence is safe
• No fallback returns fake or sample data that looks like live data
• State that describes the active resource updates only after the async load or mutation commits
• In-flight work is cancelled when superseded, and an aborted run writes no state in then, catch, or finally
• No request-scoped user, auth, or mutable query state lives at module scope on the server
• fetch checks both response.ok and, when probing static assets or binary files, Content-Type
• Removing a control from the UI also removes its keyboard shortcut and command-palette entry
• A fresh clone without gitignored build artifacts either generates them or disables the dependent controls with a clear hint
• Tests were run after the final edit, without piping away the exit code, and fail when the production fix is reverted