Debugging Discipline

The Loop

1. REPRODUCE minimally
2. INSTRUMENT at the boundary (log exact bytes, not summaries)
3. DIFF pass vs fail — one variable at a time
4. FIX root cause
5. REGRESSION-TEST the trap
6. ENCODE the lesson here

Verified Traps

Trap	Symptom	Law
Workdir-less commands	Cannot find module E:\app.js	ALWAYS set workdir on repo-relative commands
Chained kill+relaunch	Stack dies mid-sequence, stale logs lie	ONE destructive action per call; verify zero between steps
Detached stdio ignore	Child produces no output; crashes invisible	Use pipe for stderr during debugging; switch to ignore only after stable
Stale origin/main ref	"Everything up-to-date" while remote is behind	git ls-remote is truth
.git/index.lock after abort	Commit fails "index.lock exists"	Remove stale lock after verifying no git proc running
Silent EADDRINUSE	New server dies, old zombie answers with old code	taskkill ALL, verify zero, THEN relaunch
LSP null vs error	result:null = valid empty; error object = bug	Treat differently
Strict zod rejects legacy keys	BAD_REQUEST unrecognized_keys	Contract-first: client sends exact contract keys
Dynamic DOM ids break static audits	ui-audit fails on createElement ids	Declare ids in HTML; JS updates existing nodes only
TDZ ordering	ReferenceError when const used before top-level declaration executes	Shared state declarations must precede init calls in app.js
Log metadata ignored	3 failed fix attempts blaming config files	READ THE TOOL'S OWN DEBUG LOG FIRST — npm's log said verbose cwd E:\ before any file blame was warranted; verify process cwd before rewriting files
Undeclared shared var	Feature silently dead (beforeunload handler threw ReferenceError on every fire)	Enable lint gates — eslint catches 49-reference undeclared vars in seconds; static analysis IS feature work
Scope-trapped helper	Click handler at module scope calls fn declared inside another function	Declarations used by top-level wiring must live at module scope
Fixed ports in tests	Test suite exits 1 only when production stack runs (bind EADDRINUSE)	Tests bind port 0 / probe freePort(); NEVER hardcode production ports (4173/4777-4779)
Twice-fail law	Same step failed twice in one session = guessing pattern	STOP at second failure. Research the mechanism, encode in aide-route-slice-sop or matching skill, THEN retry. Attempt #3 from memory is forbidden
Facade route-map cache	New route family 404s via :4777, works via :4778	Facade loads map at startup — restart facade after editing facade-route-map.json
Contracts regen order	CI arch gate fails openapi-drift on a commit whose routes "worked locally"	npm run contracts is LITERALLY the last edit before committing route/contract changes
Gate chains with ';'	Commit pushed despite failing tsc	Verification chains use && ONLY — failure must halt the chain

Server Won't Start — Systematic Checklist

Run these IN ORDER. Stop at the first one that reveals the problem.

1. node --check <entry-file>          → syntax OK?
2. node <entry-file>                  → run foreground, capture stderr
3. Check port availability            → netstat -ano | findstr :PORT
4. Check for zombie processes         → tasklist | findstr node
5. Check disk space                   → free RAM + disk
6. Check env vars                     → are required vars set?
7. Run with NODE_DEBUG=*              → verbose internal logging
8. strace-equivalent                  → Process Monitor on Windows

Integration

Feeds continuous-improvement-sop · verification-complete · process-hygiene-sop.