How I troubleshoot
How I Work
When something breaks, I try to understand it before I change anything, and leave notes the next person can follow.
Understand
What is being reported
Signal
Pin down the actual symptom.
Restate the symptom in the reporter's words, then reproduce it or ask for the exact error, time and steps.
Scope
Establish who and what is affected.
Who, which environment, since when, and what changed. A narrow scope points at causes; a wide one points at shared dependencies.
Reported“The page won’t load.”
- Who?
- one user · a team · everyone
- Where?
- one browser · one region · all
- Since?
- first seen · last known good
- Changed?
- deploy · config · dependency
Investigate
Where the evidence is
Evidence
Inspect requests, logs, state and configuration.
Read the request trace, the status codes, the logs around the failure and the configuration actually in effect.
Hypothesis
Name a cause that one check could rule out.
Say what I think is wrong in a way a single check could disprove, so the next step is a test and not a guess.
- DNS8 ms
- Connect12 ms
- TLS14 ms
- Waiting52 ms
- Download8 ms
GET /api/orders status 504
upstream timeout after 30 sValidate
What the check shows
Test
Choose the smallest useful check.
Change one thing, or measure one thing, and say beforehand what result would confirm or rule out the hypothesis.
Result
Record what changed and what did not.
Write down the observed result next to the expected one, including the checks that came back clean.
Ifa stale cache is the cause, bypassing it will fix the request.
| Check | Expected | Observed |
|---|---|---|
| Cache bypassed | 200 | 200 (match) |
| Other region | 504 | 504 (match) |
| Config in effect | v2 | v1 (differs) |
Decide
What happens next
Next decision
Investigate, mitigate or escalate with evidence.
Pick one path. Escalate with the trace, the scope and what is already ruled out, not just a description.
Resolution
Distinguish workaround from root cause.
Say plainly whether the fix removes the cause or only the symptom, and what would bring the problem back.
- Investigatethe evidence cannot yet explain it
- Mitigateusers are affected and a safe workaround exists
- Escalateit needs access or ownership I do not have
Workaround symptom gone, cause remainsRoot cause cause removed and verified
Close
What is left behind
Communication
Explain knowns, unknowns, next action and next update.
Four short lines the other person can act on: what is known, what is not, what happens next and when they will hear again.
Documentation
Leave a reproducible diagnostic and validation path.
Record how to reproduce it, how it was checked and how the fix was confirmed, so the next person starts from a runbook.
- Known
- what the evidence shows
- Unknown
- what is still open
- Next action
- what happens now
- Next update
- when they hear again
RunbookReproduce→Check→Fix→Verify