version: "1.0.0" name: incident-report description: >- Turn the current session's incident research/debugging into a report at docs/reports/. Use when the user has been investigating an incident or bug in a customer-facing service and wants it written up — "write an incident report", "document this incident", "write up what happened", "create a postmortem", or /incident-report. Captures what broke, when, customer impact, root cause, and mitigations/long-term fixes.

Incident Report

Write up an incident you have been researching or debugging in the current session into a report at docs/reports/<yyyy-mm-dd>-<slug>.md. The session is the source — do not start a fresh investigation.

Input

The material is what this session already established: symptoms, logs, HAR captures, code paths, root causes. Read back over the conversation and assemble it. If a required field (below) has no answer in the session, ask the user rather than guessing — an unverified timeline or impact claim is worse than a gap.

Gather metadata

• Date/slug — date +%F for the filename prefix; do not guess.
• Author — git config user.name.
• Slug — short kebab-case of the incident (e.g.

race-conditions-draft-creation).

Distinguish incident from bug report

An incident degraded a customer-facing service — it has a detection time and a period of impact. If the session describes a bug that was found but never degraded production, say so and write it up as a plain bug report (drop Severity, Detection, and the Timeline's mitigated/resolved rows).

Verify before asserting

Cite every factual claim: path/to/file.go:42 for code, log timestamps for events, capture filenames for evidence. A claim you cannot cite is labelled "unverified assumption" with how to verify it. Before finalizing, confirm each path:line still resolves.

Report template

Follow `conventions-markdown` and `../shared/CONCISE-PROSE.md`.

# {Incident Title}
 
-**Date:** {date +%F}
-**Author:** {git config user.name}
-**Severity:** {SEV1–4 or your scale — state the scale}
-**Status:** {Investigating | Mitigated | Resolved}
-**Service:** {customer-facing service affected}
-**Customer(s):** {impacted customers/tenants, or "all"}
 
## Summary
 
{What broke and the customer-visible effect — one paragraph.}
 
## Timeline
 
All times UTC.
 
| Time      | Event                                        |
| --------- | -------------------------------------------- |
| {ts}      | Incident began (first bad behaviour)         |
| {ts}      | Detected ({how — alert, customer report})    |
| {ts}      | Mitigated ({what stopped the bleeding})      |
| {ts}      | Resolved                                     |
 
## Impact
 
{Who was affected, how many, for how long. Data loss? Correctness?
Availability? Quantify where the session gives numbers.}
 
## Root Cause
 
{The underlying cause, not the symptom. One subsection per distinct
cause if there are several.}
 
### Evidence
 
{Logs, HAR captures, metrics that pin the cause — in fenced `txt`
blocks with timestamps. Quote the exact error strings.}
 
### Affected Code
 
-`path/to/file.go:LINE` — {what this does in the failure}
 
## Remediation
 
### Mitigation (short-term)
 
{What was or should be done immediately to stop customer impact —
rollback, feature flag, rate limit, config change.}
 
### Long-term Fix
 
{The durable fix that prevents recurrence — code change, concurrency
guard, schema change. Link to a plan if one exists:
`docs/plans/...`.}
 
### Prevention
 
{Detection, tests, or process gaps that let this reach customers —
missing alert, absent integration test, no canary. What closes them.}
 
## Notes & Caveats
 
-{Open questions, unrelated findings, unverified assumptions.}

Finish

Report the written path. If a long-term fix warrants a plan, offer to invoke `project-plan`.