Key takeaway
A proposed fix, a completed change and evidence that it worked are different records. Preserve their links and verification scope instead of treating a closed incident as a universal remedy.
Can a later engineer follow the corrective action?
Choose one incident and ask a reviewer to trace the observed failure, the causal explanation, the proposed response and the evidence of follow-through. A polished narrative can explain what the team believed while omitting whether its actions happened. A tracker can show closure while omitting what was tested. The useful archive keeps both layers interpretable.
Google’s SRE Workbook describes action items with owners, tracking and verifiable end states. W3C’s non-normative PROV overview describes information about entities, activities and people involved in producing data. Those references motivate the review questions here. This article does not claim that the example implements PROV, follows every Google practice or demonstrates better reliability.
A rollback restores service but leaves the corrective question open
The following hypothetical incident, I-021, involves a job queue that stopped progressing after a software change. A rollback restores processing. The postmortem proposes a bounded retry change. An implementation appears in release R6, and a controlled replay later meets its stated criterion. Production follow-up evidence is not included in the retained illustration.
The completed ledger below deliberately separates restoration from prevention. It also distinguishes a causal hypothesis from a verified explanation. Nothing about the passing replay proves that every recurrence path is eliminated, and the absent production observation remains an explicit gap.
| Record | Illustrative linked evidence | Meaning |
|---|---|---|
| Failure | I-021; queue progression stopped | Observed symptom in the scenario |
| Hypothesis | Retry behavior implicated; review note H3 | Explanation proposed, scope retained |
| Mitigation | Rollback M2; processing resumed | Service restoration recorded |
| Action | Retry change A7; owner and criterion assigned | Plan, not completed prevention |
| Implementation | R6 linked to A7 | Change completed in identified release |
| Verification | Replay V4 met stated criterion; production follow-up absent | Bounded test result, wider effect unverified |
Give each action an inspectable end state
Instead of an unbounded action such as “improve resilience,” write the result that an internal reviewer must be able to inspect. Keep the owner, tracking reference, priority and criterion with the action. Retain whether it was proposed, accepted, implemented, verified under a specified test, abandoned or still open. If the tracker label combines these states, create a separate annotation with a documented meaning.
For I-021, the annotation “R6 implemented; replay V4 passed; production follow-up not present” is useful without pretending that the action is fully evidenced in every environment. A reviewer can request the missing observation or narrow the proposed use to implementation-and-test histories. Preserve an unsuccessful earlier test if it explains why the criterion or change was revised.
Version the explanation as well as the code
Incident analysis can change after an investigation. Keep an original hypothesis separate from a revised explanation and identify the evidence behind the revision. A summary written weeks later should not look like a contemporaneous observation. Identify whether a record is an original note, a human synthesis or a machine-generated summary.
W3C’s provenance context is useful here as a vocabulary starting point, not as a prescribed ledger. In the hypothetical sequence, H3 and V4 have different roles: H3 explains a suspected mechanism, while V4 records a test. A join between them shows which hypothesis was tested; it does not convert the hypothesis into fact. State when an archive contains only final postmortems and lacks revision history.
Describe the history without revealing the system
An initial metadata description can list incident categories, retained periods, action links and evidence states. It need not include customer logs, authentication material, network paths, current vulnerabilities or proprietary architecture. Review examples and attachments with the responsible technical and contractual owners before any external scope is considered.
Transformation can also destroy explanatory context. If excluding a restricted dependency makes the causal narrative unintelligible, narrow the scope rather than guessing a generic substitute. Record what is omitted and which conclusions can no longer be drawn. Aliases for services or staff may help organize a review, but they do not certify confidentiality or anonymity. No real incident or source-system connection is submitted through this website.
- Keep restoration, action implementation and verification distinct.
- State the test environment and the evidence it does not cover.
- Retain hypothesis revisions and failed tests when authorized and relevant.
- Hold restricted logs, attachments and live-system details outside initial metadata.
Use the ledger to decide whether external preparation is justified
If the company can trace only proposals, describe a postmortem archive with unverified actions. If it can also trace implementations and tests, document those evidence layers and limits. Both descriptions can be honest; neither proves that a receiving program wants the material.
An internal incident-learning project and optional external preparation have separate purposes. Use the readiness tool to identify missing links, and due diligence to clarify a potential evaluator’s question. VOID can explore a permissioned route and named introduction, without claiming possession of logs or a seller-negotiation mandate. Any later evaluation package needs separate rights and handling decisions, followed by a separate license decision if a deal is actually proposed.