Debug Runbook

Symptom-first workflow

Every debugging session follows the same loop:

1. Symptom — What does the user see? Exact error, behavior, or absence of expected behavior.
2. Boundary — Where does the problem live? Client, edge worker, database, third-party service, CI pipeline.
3. Tool — Pick the right data source for that boundary (see table below).
4. Query — Pull logs, errors, events, or state from that source.
5. Interpret — Read the data. Identify root cause vs. symptom.
6. Fix — Address the root cause only. No workarounds, no band-aids.

Do NOT skip step 1. The user's description of the symptom determines which tool to reach for. Do NOT start by reading source code — start by reading production data.

Data source reference