THE GITHTML FIELD GUIDE
Troubleshooting decision tree template with discriminating checks
A troubleshooting decision tree should ask questions whose answers meaningfully narrow the problem. Begin with observable symptoms, use safe checks, and make each branch lead to a next investigation or an escalation. Preserve an unknown path so missing evidence does not force readers into a confident but unsupported diagnosis.
Choose questions that separate causes
An illustrative download failure can mean the file was never generated, the authorization failed, or the reader could not display it. Asking whether the expected artifact exists separates different investigations more effectively than asking whether the system is broken. Google's troubleshooting chapter explains hypothesis-driven diagnosis; apply that idea by stating what each observation can and cannot rule out. Keep environment and timing visible because a healthy check against a different account or deployment may say little about the reported failure.
Write a text-first branch pattern
Use a repeated structure: question, observation method, yes branch, no branch, and unknown branch. For the illustrative question does the export record show complete, the yes path might inspect delivery metadata, the no path might inspect processing status, and unknown might require authorized access from the service owner. Do not turn the tree into a collection of commands that change state. If a later action requires intervention, link the approved runbook and state the authority boundary. Every branch should retain enough context for another responder to understand the reasoning.
- Question: ask for a specific observation, not an opinion about the cause.
- Evidence: state where the observation comes from and what timestamp matters.
- Exit: define when to stop and what information to hand to the next owner.
Test the branches with real ambiguity
Walk the tree using a known historical case and a case with incomplete evidence. If both lead to the same recommendation without examining meaningful differences, revise the questions. Remove dead ends and circular links. Avoid embedding frequently changing contact details in many branches; reference one maintained escalation section instead. In HTML, nested headings or short numbered sections can be easier to read than a giant flowchart on a phone. If a visual tree is included, provide the same branch logic in text so the procedure remains accessible.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.