Skip to content

POSTMORTEM_TEMPLATE.md

Latest commit

 

History

History
76 lines (52 loc) · 3.5 KB

POSTMORTEM_TEMPLATE.md

File metadata and controls

76 lines (52 loc) · 3.5 KB
Raw

Postmortem template

Copy this file to docs/incidents/<YYYY-MM-DD>-<slug>.md and fill in. The slug is short kebab-case (e.g. 2026-04-30-uniprot-features-shape-drift). Keep blameless-incident discipline: name systems, not people. Link the fix PR; never edit a landed postmortem to retract — append corrections instead.

Header

  • Incident date / time (UTC):
  • Detected by: (nightly integration.yml, user report, internal review, …)
  • Severity: S0 (silent data corruption) · S1 (tool returns wrong answer) · S2 (tool fails-loudly, agent retries) · S3 (cosmetic / log-only)
  • Status: open · mitigated · resolved · monitoring
  • Maintainer on point: Santiago Maniches (ORCID 0009-0005-6480-1987)
  • Fix PR: (URL)
  • Affected versions: (e.g. v1.0.1 – v1.0.3, fixed in v1.0.4)

Summary

Two or three sentences. What broke, what the user-visible effect was, and how it was fixed. A reader who only reads this section should be able to decide whether their environment was affected.

Timeline (UTC)

Bullet list of events in chronological order. Be specific — timestamps to the minute, log lines verbatim where useful.

  • YYYY-MM-DDTHH:MM —
  • YYYY-MM-DDTHH:MM —
  • YYYY-MM-DDTHH:MM —

Root cause

Single paragraph. The technical thing that failed — what changed, why it broke us, not who-changed-it. If multiple causes contributed, list them as a numbered chain (cause 1 ⇒ cause 2 ⇒ user-visible effect).

Impact

Dimension Value
Tools affected (e.g. uniprot_get_features, uniprot_get_variants)
Users affected (installs / agents / pipelines)
Provenance integrity did any record become non-reproducible? Y/N
Window of impact _from <detected> to <fix landed>, _
Remediation required from users (none / re-run query / pin to fixed version)

Detection

  • What alerted us: (integration.yml opened a integration-drift issue / user filed report #N / internal --self-test failure)
  • Time-to-detect: (from breakage to alert)
  • Test that caught it / should have caught it:
  • If not caught automatically: what test would have caught it earlier? Add it in the same PR as the fix.

Resolution

What was changed, in flat declarative prose. Reference commit SHAs, not commit messages. Include the diff summary if the fix was small.

src/uniprot_mcp/client.py    | <stat>
tests/contract/...           | <stat>

Follow-up actions

  • Test added: (name + path)
  • Monitoring added: (workflow / alert / metric)
  • Documentation updated: (README / ARCHITECTURE / THREAT_MODEL)
  • INCIDENT_LOG.md entry appended
  • Upstream report filed (if a UniProt-side fix is needed): (link)
  • Compatibility shim status: (temporary, with sunset commit; or permanent)

Lessons learned

Two or three bullets. What does future-us need to know? Examples:

  • A response field we treated as required was actually optional in the spec — add .get() defaults across this category of fields.
  • The integration suite ran nightly but only on one accession; widen the canary to N accessions across organism kingdoms.
  • The Provenance record carries the upstream URL but not the response hash; if we add response_sha256 we can detect this earlier.

Compliance officer view

Would a regulated bio-pharma compliance officer reading this postmortem in 2030 trust the project? Answer in one paragraph. If "no", what additional evidence is required? File those as Follow-up actions above.