Debug Systematically

Look at the real bytes before theorising

A hook silently stopped parsing its input. The plausible causes were all wrong. One probe settled it:

console.log([...raw].slice(0, 8).map(c => c.charCodeAt(0)).join(','));
// 65279,123,34,112,...   <- a UTF-8 BOM

JSON.parse was throwing on a byte-order mark, and a catch was swallowing it into a fallback. Two minutes of observation beat twenty of hypothesis.

When something "looks right" but behaves wrong, suspect what you cannot see: invisible characters, encoding, escaping, whitespace, line endings.

A silent catch is where bugs hide

try { return JSON.parse(read(p)); } catch { return {}; }

That line destroyed a user's config. The failure had no symptom until much later, in a different place. Catch blocks that swallow errors convert a loud failure into a quiet corruption — the worst trade in debugging.

Log it, surface it, or refuse. Never silently substitute a default for an error.

Check derived state

After redacting secrets from a record's text, they were still on disk — the search index built from the pre-redaction text was persisted alongside it.

The obvious field was fixed; the derived copy was not. Ask: what else was computed from this, cached from this, logged from this, or indexed from this?

Fix causes, not symptoms

A duplicate-detection check never fired. The symptomatic fix is to add a second check. The actual cause was that JSON.stringify escapes quotes, so a substring match against a quoted path could never succeed. The real fix was to stop string-matching serialized data and compare a structural tag instead.

When a fix feels like it is compensating for something, it usually is.

Suspect your test before your code

Several failures here were wrong expectations, not wrong implementations:

• "delegation loses on a warm cache" — it does not; output price dominates
• "this prompt has a positive signal" — it did not
• "durability should be 7" — the mtime window was inflating it

When a test fails, decide which side is wrong before changing either. Never weaken an assertion to get green.

Reproduce in isolation

The installer's data-loss bug only appeared in a sandbox with a realistic pre-existing config. Unit tests all passed. If a bug will not reproduce, the harness is probably too clean — add the messy real-world condition.

When the measurement disagrees with the outcome

Establish which one to trust before acting. A score of 0/10 on work that was clearly done meant the metric was broken, not the work. A later score of 1/10 was correct and the earlier 7/10 had been the lie.