Incident Followup

Incident Followup

The postmortem composite. Runs after the bleed has stopped, not during.

The purpose is durability: a hotfix that ships without an ADR + regression test + captured memory will repeat itself within months. This composite makes that chain non-skippable.

When this fires

• Auto-queued by /hotfix Phase 10 (cherry-pick back to release) on success
• Manual: user says "postmortem", "incident review", "what did we learn"
• After a revert / rollback lands on main
• After a Sentry alert was acknowledged + suppressed without a code fix (the "we just bumped the ignore threshold" anti-pattern)

If less than 6 hours have passed since the incident and the user is still in mitigation mode, defer this composite — print a one-line reminder and exit: incident-followup queued: re-run after the bleed has fully stopped.

Workflow

Phase 1 — Scope the incident (always)

Gather, in this order:

• The triggering artifact: /hotfix PR URL, revert SHA, or Sentry issue URL
• Timeline: when it started, when detected, when mitigated (rough is fine)
• Blast radius: % of users / requests / regions affected (best estimate)
• The exact commit that introduced the regression, if known (use git log -S or git bisect only if cheap; otherwise mark as "unknown — see ADR")

Capture into a scratch incident packet at .claude/incidents/<date>-<slug>.md (create directory if missing). This packet is the input for the next phases.

Phase 2 — Root-cause research (adt-research)

Invoke adt-research with the failure mode as the query. Goal: find prior art — has this class of bug happened before in this repo or any of the user's tracked repos? Look for:

• Similar Sentry signatures in the last 12 months
• Past ADRs naming the same component
• Past skill outputs / handoffs that warned about this surface

If adt-research returns weak hits (cosine < 0.40 on the strongest match), note it in the incident packet — the lack of prior art is itself a signal that no one was watching this surface.

Phase 3 — Decision capture (adr-write)

Invoke adr-write. The ADR must answer:

• What happened (1 paragraph, blame-free)
• Why the existing safeguards (tests, types, review, CI) did not catch it
• What changes (code or process) prevent recurrence
• What is explicitly NOT being changed and why (cost/benefit)

Place the ADR under the repo's docs/adr/ or .agents/adr/ (whichever already exists; if neither, create docs/adr/). Number it sequentially.

Phase 4 — Regression test (generate-tests)

Invoke generate-tests scoped to the regressing code path. Requirements:

• The test must fail against the pre-hotfix HEAD (verify by checking out parent and running it once)
• The test must pass on the current HEAD
• It must live in the same suite as its neighbors (do not introduce a new integration tier just for this)
• Name it after the incident slug, not the bug detail: test_incident_<slug>

If a suitable test already exists in the hotfix PR, skip generation but verify the pre-hotfix-fail / post-hotfix-pass property holds. Note the verification in the incident packet.

Phase 5 — Security sweep (conditional)

Run security-sweep ONLY IF the root cause involved one of:

• Authentication, authorization, session handling
• User-controlled input crossing a trust boundary (SQL, shell, template, regex)
• Secret handling (envs, tokens, signing keys)
• Dependency with a known CVE
• Data exposure / leakage (logs, error messages, response payloads)

Skip and record security-sweep skipped: root cause is <category> if the incident was, e.g., a config drift, race condition in app logic, or external service outage.

Phase 6 — Knowledge capture (knowledge-loop)

Invoke knowledge-loop to:

• Write a project-scoped memory: incident-<slug>.md with type: project, linking [[adr-NNN]] and [[release-branch-model]] if relevant
• Update the repo's RAG index so future recall queries surface the ADR + test
• If the memory gotchas.md standard exists for this repo, append a one-liner

Phase 7 — Handoff (always)

Invoke handoff with the incident packet path + ADR path + test path + memory path bundled into the next-action block. This guarantees the next session can pick up if any later verification step (e.g., 7-day Sentry watch) is still pending.

Reconciliation block (mandatory output)

INCIDENT FOLLOWUP — <incident-slug>
  Scope:        <packet path>
  Prior art:    <n hits, top cosine, or "no prior art found">
  ADR:          <path> (decision: <one-line>)
  Regression:   <test path> (verified: pre-fail ✓ / post-pass ✓)
  Security:     <sweep result | skipped: <category>>
  Memory:       <memory path>
  Snapshot:     <handoff path>
  Open watch:   <e.g., "7-day Sentry re-occurrence check on <date>" or "none">

If any phase failed or was deferred, mark it explicitly ((deferred: <reason>) or (failed: <reason>)). Never silently skip — the contract is that every phase reports.

Stop conditions

• If Phase 4 cannot produce a failing-before-fix test (e.g., the regression is in a path that cannot be unit-tested), surface this as Regression: NOT POSSIBLE — needs manual <integration / e2e / chaos> test and continue. Do not block the chain; flag for the next session.
• If adt-research is unavailable (no RAG index for this repo), substitute with grep -r over recent commit messages + open issues, and note the fallback in the reconciliation block.
• Refuse to run if Phase 1 cannot identify a triggering artifact — there is nothing to be postmortem-of without it.

Negative rules

• Do NOT assign blame to a person in the ADR or memory. Always describe the failure as a system/process gap.
• Do NOT skip Phase 4 because "the fix is obvious". The regression test is the durable artifact; the fix code drifts.
• Do NOT mark the composite complete without a handoff — open watches are real and need to survive session boundaries.