Editorial review pendingon version support under review
Action boundary
Before you act
- Expected result
- A redacted incident record separates observed facts, evidence locations, and hypotheses.
- Failure mode
- A restart, config edit, or broad log dump overwrites the evidence needed to understand the symptom.
- Rollback
- Stop intervention, preserve the current record locally, and escalate using the stated stop condition.
The first rule
A symptom is not a diagnosis. “The gateway stopped replying” is an observation. “The gateway has a bad configuration” is a guess. Write the first one down; earn the second with evidence.
Record before you intervene
Create a short incident record with six fields:
- What changed for the person using the system?
- When did it begin, including timezone?
- What changed shortly before the symptom?
- Which boundary appears affected: client, channel, gateway, service, configuration, or local state?
- What evidence is available now, and where is it stored?
- What action would make the evidence less trustworthy?
Use the installed CLI’s current help and the release-specific runbook to choose any doctor, status, service, or log collection command. Do not copy a command from this fixture into a production terminal. Capture the command version, command line with secrets removed, timestamp, relevant output window, and exit status.
Lab: the 15-minute incident envelope
Use a synthetic failure: a channel cannot reach the service after an intentional configuration change. Create an incident record, then collect only the minimum evidence needed to tell whether the failure is upstream, local service, configuration, or persisted state. Put tokens, full payloads, user identifiers, and private paths behind a redaction marker.
Check: another operator should be able to identify the next evidence step without reading your mind. If they cannot, the record is not ready.
Checkpoint
A teammate proposes restarting first because it is quick. The correct response is to preserve the relevant time window and current status first, unless the approved incident runbook says the impact requires an immediate safety action. Speed is not a substitute for a record.
Learner artifact
Draw a split-panel figure titled “Observation versus hypothesis.” The left panel shows timestamps, status, and redacted log markers; the right panel shows unproven causes marked as hypotheses. Its text alternative says that facts guide the next check while hypotheses do not justify destructive action.
Lesson checkpoint
Ready to move on?
Mark this lesson complete when you can apply its outcome without relying on the examples above.