01 · Environment
Command not found / wrong version
Run Get-Command/which and version output. Confirm fresh terminal PATH before reinstalling anything.
Handbook · error playbook
Locate the failing boundary before changing code.
Start from the exact symptom. The first question is not “what fix should I paste?” but “which layer can actually produce this symptom?”
02 · Process/OS
Port already in use
Find the listening PID, identify the process, then stop or reconfigure the correct service.
03 · Browser/network boundary
CORS error
Check the actual browser Origin, API allow-list, credentials mode, preflight response, and whether the request reaches the API.
04 · Authentication
401 Unauthorized
Verify Authorization/cookie presence, token format, expiry, issuer/project, and server-side verification.
05 · Authorization
403 Forbidden
Identity is usually known; inspect resource membership/role/permission evidence and policy decision.
06 · Routing or disclosure policy
404 for known record
First prove route/method; then verify resource lookup and whether authorization intentionally masks existence.
07 · Database connectivity
Prisma P1001 / connection failure
Check host/port/DNS, connection mode/pooler, credentials, firewall/service status, then retry a minimal connection.
08 · Schema history
Migration drift/conflict
Compare migration history, target database state, and branch changes. Do not delete migrations casually in shared environments.
09 · Server-state cache
Stale TanStack Query UI
Inspect query key, staleTime, mutation invalidation/update, filter params, and whether data was copied into local state.
10 · Mutation reconciliation
Optimistic item snaps back
Inspect snapshot/rollback, server response, invalidation timing, temporary IDs, and concurrent mutation ordering.
11 · Container process
Docker container exits immediately
Read docker logs, inspect command/entrypoint/env, and run the process interactively if safe.
12 · Reproducibility
GitHub Actions works locally but fails CI
Compare Node/pnpm versions, frozen lockfile, workspace scripts, environment/secrets, OS assumptions, and path case sensitivity.
13 · Deployment boundary
Production works in preview but not custom domain
Check DNS/TLS, configured origins/redirect URLs, public API base URL, CORS, and environment selection.
Universal loop: reproduce → capture exact evidence → locate earliest failing boundary → one hypothesis → one change → rerun same reproduction → document root cause.