postmortem · diff
git:20260911.c655850 to git:20260911.66323ac
53 added, 65 removed. Audit A to A.
---
name: postmortem
description: 'Test a retrospective causal question against outcome evidence. Use when: a postmortem is explicitly requested; finishing a task does not require a report or lesson.'
practices:
- sre
- lean-startup
hexagonal_role: domain
- consumes:
- - verdict.v2
+ consumes: []
produces:
- postmortem-report.md
context_rel: []
skill_api_version: 1
user-invocable: true
disable-model-invocation: true
metadata:
capabilities: [postmortem]
effects: [write_postmortem_report]
canonical_status: canonical
disposition: keep_strategy
tier: judgment
dependencies: []
context:
window: fork
intent:
mode: task
sections:
exclude:
- HISTORY
- output_contract: 'YYYY-MM-DD-postmortem-<topic>.md — markdown causal analysis (causal question, pinned inputs, timeline, hypotheses, counterfactuals, unknowns, experiments)'
+ output_contract: 'concise inline causal analysis; a requested durable report is YYYY-MM-DD-postmortem-<topic>.md in caller-selected protected external non-Git storage'
---
# Postmortem
- > **Purpose:** Answer an explicit retrospective causal question using the
- > already-validated outcome and evidence.
+ Answer an explicit retrospective causal question about a completed or stopped
+ goal, session or change using its actual intent, outcome and judgment evidence.
## Prompt
```text
- Postmortem: verdict .agents/ao/verdicts/2026-08-30-cli-regen.json shows
- NOT_PROVEN then PASS after we added a mutating-check guard to
- skills/validate/scripts/validate.sh. Did that guard actually cause the
- fix, or did the flaky CI runner just stop flaking that day?
+ Postmortem this stopped change using its accepted intent, native session,
+ check results and reviewer messages. Which correction cycles were avoidable,
+ and which checks were necessary? No verdict file was saved. Answer inline.
```
- ## It's working if
-
- Observable in the trace, without reading the prose:
-
- - The report pins the exact `verdict.v2` id and the causal question before
- the timeline section.
- - A claim promoted to cause cites its mechanism, evidence, and
- counterfactual together under the report's `hypotheses` list.
- - A claim resting only on symptom cessation is listed under `unknowns`,
- not promoted to cause.
- - The report lands at
- `.agents/scratch/postmortem/YYYY-MM-DD-postmortem-<topic>.md` and
- `bash skills/postmortem/scripts/validate.sh` exits 0.
-
## Critical Constraints
- - Because proof and causal inference are different judgments, Postmortem is retrospective causal analysis, not the general learning umbrella and not a completion gate.
- - It consumes immutable Validate verdict evidence and does not re-run acceptance validation because Validate already owns that proof.
- - Treat causal statements as hypotheses because causal confidence must survive
- alternatives. Separate observed sequence, contributing conditions,
- counterfactuals, and unknowns.
- - A correlation is not promoted to cause without evidence that discriminates
- plausible alternatives.
- - Because the caller owns delivery decisions, do not rewrite proof, operate
- tracker state, change the remaining plan, or promote a rule. Return evidence
- to the caller.
- - Empty or inconclusive analysis is valid; manufacture neither certainty nor a
- lesson to make the retrospective feel useful.
+ - Postmortem is retrospective causal analysis, not the general learning umbrella
+ or a completion gate: acceptance proof and causal inference are different judgments.
+ - Existing verdicts and native judgments remain unchanged. It does not re-run acceptance validation
+ or fabricate missing proof to enable a retrospective. An existing `verdict.v2`
+ is optional evidence; its absence does not exclude a stopped or unvalidated subject.
+ - Because the caller owns subsequent action, do not rewrite proof, operate
+ tracker state, change the remaining plan, reopen work or promote a rule.
+ - Empty or inconclusive analysis is valid; recommend no change when warranted.
+ Manufacture neither certainty nor a lesson.
## Workflow
- 1. Pin the verdict, subject evidence, and explicit causal
- question.
- 2. Reconstruct the evidence-backed timeline without importing hidden author
- reasoning as fact.
- 3. List candidate contributing conditions and at least one plausible
- alternative explanation.
- 4. Test each claim against cited evidence and a counterfactual: what should
- differ if the claim were false?
- 5. Optionally use independent judges to challenge contested causal claims.
- 6. Emit a report containing supported claims, rejected claims, unknowns,
- evidence references, and suggested experiments. Stop.
+ 1. Pin the explicit question, accepted intent, subject identity, actual outcome
+ and available judgment. Cite native work/session references, commits, checks
+ and reviewer messages as applicable; cite an existing verdict by exact id.
+ Keep missing evidence explicit before drawing conclusions.
+ 2. Reconstruct only the relevant evidence-backed timeline. Keep delivered
+ behavior, failed/stopped work and process output distinct; hidden author
+ reasoning is not fact. Missing judgment is not a PASS or a FAIL.
+ 3. Separate delivered facts from causal hypotheses. Test contributing conditions
+ against cited evidence, at least one
+ plausible alternative and a counterfactual. Distinguish necessary validation
+ and compatibility work from avoidable rework; repeated review alone proves no waste.
+ 4. For time/token claims, state source, interval, units, included/excluded actors
+ and uncertainty. Separate elapsed time, overlapping work and accounting scopes;
+ never equate totals with waste, savings or money without supporting evidence.
+ 5. Optionally seek independent support or challenge for contested causal claims
+ within caller authority. Return supported/rejected claims, unknowns and at
+ most three supported changes with limits or small suggested experiments. Stop;
+ suggestions do not authorize implementation.
## Correlation-to-cause discrimination
- A fix is proven when the mechanism is demonstrated, not when symptoms stop.
+ Treat causal statements as hypotheses until the mechanism is demonstrated.
Promoting a claim from correlation to cause requires all three:
- a stated mechanism — the specific path by which the condition produced the
outcome, in terms a reader could check against the subject;
- discriminating evidence — an observation that the mechanism predicts and at
least one plausible alternative does not;
- a counterfactual test — what should have differed if the claim were false,
with the cited evidence showing it did differ.
- Symptom disappearance after a change satisfies none of these on its own: the
- change and the recovery may share an unobserved cause, or the symptom may be
- intermittent. The named failure mode is post-hoc fix attribution — "we
- changed X and the failure stopped, therefore X was the cause." Claims backed
- only by symptom cessation stay in the report as correlations with the
- untested alternatives listed, and the suggested experiment is the
- discrimination that would settle them. Stop condition: every supported causal
- claim in the report carries all three elements with citations; anything less
- is filed under correlations or unknowns, never silently promoted.
+ Post-hoc fix attribution — "we changed X and the failure stopped, therefore X
+ was the cause" — satisfies none of these alone. The symptom may be intermittent,
+ or recovery and the change may share an unobserved cause. Keep such claims as
+ correlations with untested alternatives and a suggested discriminating experiment.
+ Every supported causal claim needs all three elements with citations; anything
+ less stays a correlation or unknown.
## Output Specification
- - **Artifact directory:** `.agents/scratch/postmortem/`.
- - **Filename convention:** `YYYY-MM-DD-postmortem-<topic>.md`.
- - **Serialization/schema format:** Markdown with causal question, pinned inputs,
- timeline, hypotheses, evidence, counterfactuals, unknowns, and experiments.
- - **Validator command:** `bash skills/postmortem/scripts/validate.sh`.
- - **Downstream handoff:** Learn or the caller may consume the analysis; they own
- any bookkeeping, promotion, planning, or delivery decision.
+ - Default to concise inline Markdown: question, pinned inputs, relevant timeline,
+ hypotheses/evidence/counterfactuals, unknowns and bounded suggestions. No mandatory report or worksheet.
+ - Only when requested, save `YYYY-MM-DD-postmortem-<topic>.md` in caller-selected
+ protected external non-Git storage. Missing routing does not authorize a
+ repository fallback; preserve existing requested evidence under owner policy.
+ - `bash skills/postmortem/scripts/validate.sh` checks package structure and
+ contract markers. It does not inspect report truth, causal support or acceptance.
+ - The caller owns bookkeeping, planning and delivery. Optional
+ [Memory](../memory/SKILL.md) owns any separately authorized curation, support
+ and destination-disclosure review; retrospective evidence cannot promote itself.
## Quality Checklist
- - [ ] The causal question and immutable inputs are pinned.
+ - [ ] The causal question and actual inputs are pinned; gaps are explicit.
- [ ] Supported and rejected claims cite discriminating evidence.
- [ ] Alternatives, counterfactuals, and unknowns remain visible.
- [ ] The report stops short of proof, planning, tracker, and delivery authority.
- Executable behavior is in [postmortem.feature](references/postmortem.feature).
+ Behavior examples are in [postmortem.feature](references/postmortem.feature).