“Retry the export” is difficult to follow when the operator cannot tell whether a previous attempt already finished. A runbook needs to address that state before prescribing another attempt.
Start with the facts the operator is allowed to use
This original fictional export service has four supplied operational rules:
- R1: the operator can inspect a job's state and its output record.
- R2: Complete means the output record exists and its record count matches the approved request count.
- R3: Paused means the job awaits service-owner review. The operator is not authorized to resume it.
- R4: A request may already have completed even if its notification did not arrive.
No command syntax, dashboard URL, retry policy or emergency permission has been supplied. The runbook should not invent any of them.
A practical first draft is:
Goal: establish the state of one export whose notification is missing.
Entry: you have the request's job ID and approved request count.
1. Inspect that job's recorded state and output record using the
approved inspection method [OWNER TO SUPPLY METHOD].
2. If Complete and the output count matches, record the output reference
and count. Do not create another export for this notification issue.
3. If Complete but the count differs, preserve both counts and refer
the discrepancy to the service owner. Completion is unresolved.
4. If Paused, preserve the state and ask the service owner to review it.
Do not resume the job under this runbook.
5. For any other state, stop here and obtain the documented procedure.
Success: the existing output and approved count agree, or the unresolved
state has been handed to the service owner with the job ID and evidence.
The second success condition completes the operator's limited task; it does not declare that the export completed. Keep those outcomes distinct in the handoff.
Diátaxis's how-to guidance, checked October 24, 2026, describes documentation organized around a practical goal. A technical reference answers a different need: the exact inputs and outputs of a tool.
Ask for each branch to show its basis
Draft an operator runbook from the supplied approved facts.
Operator role and goal: [ENTER]
Entry conditions and required identifiers: [ENTER]
Approved source rules with IDs: [PASTE]
Permitted actions and exact commands, if supplied: [PASTE]
Observable success and stop conditions: [PASTE]
Escalation owner or documented route: [ENTER OR UNKNOWN]
Write an ordered procedure. Tie each decision and action to a source
rule. Include paths for missing evidence and unexpected states.
Keep a proposed improvement separate from the approved procedure.
Do not invent commands, URLs, retries, permissions or successful runs.
Mark missing operational instructions explicitly. Draft only;
do not run the procedure, change a job or notify anyone.
This structure follows OpenAI's prompting guidance. The purpose of the rule IDs is to make review possible. They do not establish that the supplied policy is current.
Walk the draft through an awkward state
For the fictional rules, test Complete with matching counts, Complete with different counts, Paused, and an unrecognized state. The Paused path must never acquire a resume command through an editorial rewrite. The mismatched-count path must not become success merely because its state label says Complete.
Have an operator who did not write the draft describe what they would inspect and when they would stop. Replace each missing method with the service owner's maintained instruction before operational use. Record the policy version and the environment in which any rehearsal actually occurs.
Keep the accepted runbook with the team's operating documentation. For code comments or API field rules, use the separate code documentation guide or API documentation guide. A runbook should finish the operator's task without quietly expanding what the operator may do.