Define the observed failure
Start with a precise description of what should happen and what actually happens. Record the affected clients, when the problem occurs, and whether it can be reproduced.
A useful symptom is specific: an application loads but a request to its dependency fails. “The system is down” leaves too many possibilities open.
Map the dependency path
Identify the boundaries a request crosses: client, name resolution, network path, authentication, application, and downstream service. Each boundary is an opportunity to gather evidence.
For a private AI application, a reachable login page does not establish that a model is loaded or that inference is healthy.
Change one variable at a time
Write a hypothesis and choose a check that can support or weaken it. Preserve the initial state, make a bounded change, observe the result, and record the outcome.
Avoid interpreting an unrelated successful test as proof that the whole path works. A basic reachability check answers a narrower question than a real application transaction.
Keep evidence and interpretation separate
Use three distinct statements in working notes:
- Observation: what a command, log, or reproduction showed.
- Hypothesis: what might explain the observation.
- Validation: what additional check would distinguish competing explanations.
An observation may be accurate while the first explanation is wrong. Keeping them separate makes revisions easier.
Confirm the recovery
Repeat the original failing action. Check likely side effects and confirm that a restart or session change has not merely hidden the fault temporarily.
Document the cause only to the extent the evidence supports it. If the mechanism remains uncertain, say so and retain the next diagnostic step.
Publication note
This is general guidance, not a report of a workplace incident. Published examples should omit private addresses, customer information, credentials, and internal operational details.