gotchas

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