Debugging

The protocol exists because the failure mode is universal: changing several things at once, then not knowing which one helped.

The order, and do not skip

1. Read the error exactly. Every word. undefined and null are different bugs with different causes. "Cannot read property x of undefined" names the property and that is usually the whole answer.

2. Go to the file and line in the trace before doing anything else. Not a grep for something similar. The actual frame. If there is no stack trace, get one before theorizing; a bug report without one is a rumor.

3. Check the assumption. Print the variable. Is it the shape you believed? Most bugs are a value being a different type, a different case, or absent, and are invisible to reasoning about the code because the code reads correctly.

4. Search the exact message. Framework, exact string, year. Someone has hit it.

5. Check for a breaking change. Read the migration guide for the version actually installed, not the version remembered.

6. git diff against the last working state. The bug lives in the diff. This step alone solves most "it used to work" reports and it is the one most often skipped.

7. git bisect if still lost, then read that commit properly.

Never change several things at once, and never delete and rewrite before understanding why it broke. A rewrite that works for reasons nobody understands is the same bug with a longer fuse.

Tracing a flow

To follow data end to end: name the entry point, then read each function in the chain in full rather than skimming for the interesting line.

Mark three things as you go, because they are where flows actually break:

• Where the data changes shape: parsed, validated, serialized, renamed
• Where it could be lost: a swallowed error, an early return, a default that silently replaces a missing value
• Where ownership changes: one module handing to another, a queue, a network hop, a process boundary

Report it as the chain, file by file, with the shape at each step. A trace that lists files without saying what the data looks like at each one has not traced anything.

When it is fixed

Write the test that would have caught it, and check the same mistake is not sitting in three other places. A fix applied to only the instance that was reported is a promise to debug it again.