# Incident Roles: - Responder - Lead ## Intent Boss, the on-call engineer, supplies as one input an incident report: what broke, when, and what was observed. Captain retains that report exactly as received and relays it as `` to every prompt below. The playbook is the plan stage for an incident: it records the incident and turns it into an intent for the fix; no one in this playbook changes code, configuration, or any live environment. The incident record is one Markdown file under docs/incidents/, and the intent record is one Markdown file under specs/intents/; every commit lands on the current branch, and no existing commit is rewritten. Captain shall use the repository-effect receipt as the authoritative identity of every commit. At most two Lead review rounds run: the first reviews the records commit, the second reviews Responder's fix commit. ## External Behavior ### INCIDENT-1 Where Responder asks the on-call one question and waits, Boss's answer resumes this same behavior. When Boss reports an incident, Captain shall prompt Responder: > Turn the incident in the on-call's report below into an incident record and an intent record for its fix. > If the report does not say what broke, when it started, or what was observed, ask the on-call one question and wait for the answer. > Read specs/, the code of the affected services, their deploy manifests, and the commits on the current branch around the time the incident started; every change on this branch rolls out through GitOps canaries, so a recent change is a suspect until the evidence clears it. > Change no code, configuration, or deploy manifest, and never touch a live environment; this step only records. > > Write the incident record as one Markdown file under docs/incidents/, named with the incident's start date and a short kebab-case name, e.g. 2026-10-11-checkout-timeouts.md. > Give it these sections: Summary; Timeline; Impact; Root-cause hypothesis; Follow-up. > In Timeline, list every event in order, each with its date and time and time zone: start, detection, each action taken, mitigation, and resolution where known; mark a time that is estimated as estimated. > In Impact, state who and what was affected, for how long, and how much, with numbers where the report gives them. > In Root-cause hypothesis, state the hypothesis and its evidence from the repository: each code path involved, by file and function, and any commit that introduced or exposed it, by hash; say what the evidence does not yet establish. > In Follow-up, name the intent record by its id. > > Write the intent record for the fix as one Markdown file under specs/intents/, following specs/meta.md where the repository has one: name it with the next unused three-digit number and a short kebab-case name, so its id is IR-. > Give it these sections: Status, set to Proposed; Intent, citing the incident record by path; Deliverables, with checkboxes; Tasks, numbered, each sized to one commit; and Verification. > In Verification, write acceptance checks that would catch a recurrence: each check names the code path it exercises, the condition from the incident it reproduces, and the result that shows the fault is gone, and each would fail against the code as it stands today. > > Commit both records together in one commit on the current branch; never rewrite an existing commit. > Report the incident record's path, the intent record's id, and the commit hash. > > > On-call report: Results: - `recorded`: Responder committed the incident record and the intent record in one commit on the current branch. Output shall include `latestCommit: `, `incidentPath: `, `intentId: `, and `responderOutput: `. ### INCIDENT-2 When Responder commits the records, at the first review round, Captain shall prompt Lead: > A review begins for the incident record and the intent record committed for the incident below. > Read the records commit, both records, specs/, and the code and commits the incident record cites. > > > On-call report: > > Incident record: > > Intent record: > > Records commit: > > Responder report: > > Check that every timeline entry has a date and a time with its time zone, and that the timeline agrees with the on-call's report. > Check that the root-cause hypothesis names the code involved, by file and function, that each cited file, function, and commit exists in the repository, and that the cited code supports the hypothesis. > Check that every acceptance check in the intent record would catch a recurrence: it exercises the cited code path under the incident's condition and would fail against the code as it stands today. > Check that the incident record and the intent record cite each other. > Raise a finding for every place a check fails, and only for failed checks — not for wording or style. > Number your findings, and for each name the record and the section it concerns. > If every check passes, say plainly that the records have no findings. > Do not edit files or commit; report findings only. Results: - `hasFindings`: Lead raised one or more numbered findings; a progress report or a promise of a later review supports no review outcome. Output shall include `leadOutput: `. - `noFindings`: Lead affirmatively reported that every check passes and the records have no findings; a progress report or a promise of a later review supports no review outcome. On this outcome the playbook ends reporting the incident as recorded and its intent as ready for /shape or /code, returning the incident record's path, the intent record's id, and the latest commit hash. ### INCIDENT-3 Where Responder asks the on-call one question and waits, Boss's answer resumes this same behavior. When Lead raises findings in the first review round, Captain shall prompt Responder: > Fix every numbered Lead finding below in the incident record or the intent record. > Keep the incident record's path and the intent record's id unchanged. > Change no code, configuration, or deploy manifest, and never touch a live environment. > If a finding cannot be fixed from the on-call's report and the repository, ask the on-call one question and wait for the answer. > Commit the fixes in one new commit on the current branch; never rewrite an existing commit. > Report, by finding number, what you changed, and the new commit hash. > > > On-call report: > > Incident record: > > Intent record: > > Lead findings: Results: - `fixed`: Responder committed the fixes in one new commit on the current branch. Output shall include `latestCommit: ` and `responderOutput: `. ### INCIDENT-4 When Responder commits fixes after the first review round, at the second and last review round, Captain shall prompt Lead: > A second review round begins for the records below, with particular attention to the fix commit. > Read the fix commit and both records as they now stand, and check that each of your previous findings is resolved. > > > On-call report: > > Incident record: > > Intent record: > > Fix commit: > > Your previous findings: > > Responder report: > > Check that every timeline entry has a date and a time with its time zone, and that the timeline agrees with the on-call's report. > Check that the root-cause hypothesis names the code involved, by file and function, that each cited file, function, and commit exists in the repository, and that the cited code supports the hypothesis. > Check that every acceptance check in the intent record would catch a recurrence: it exercises the cited code path under the incident's condition and would fail against the code as it stands today. > Check that the incident record and the intent record cite each other. > Raise a finding for every place a check fails, and only for failed checks — not for wording or style. > Number your findings, and for each name the record and the section it concerns. > If every check passes, say plainly that the records have no findings. > Do not edit files or commit; report findings only. Results: - `hasFindings`: Lead raised one or more numbered findings; a progress report or a promise of a later review supports no review outcome. Output shall include `leadOutput: `. The review limit is reached: Boss is not asked, and the playbook ends reporting the records as not cleared, returning the incident record's path, the intent record's id, the latest commit hash, and Lead's unresolved numbered findings. - `noFindings`: Lead affirmatively reported that every check passes and the records have no findings; a progress report or a promise of a later review supports no review outcome. On this outcome the playbook ends reporting the incident as recorded and its intent as ready for /shape or /code, returning the incident record's path, the intent record's id, and the latest commit hash.