Postmortems

Overview

A Postmortem is the structured retrospective on a resolved Incident. It captures what happened, why it happened, what we did, what we'll do differently, and the action items that came out of the discussion. Vigilo enforces a blameless workflow: the postmortem is keyed by the incident, owned by an author, drafted privately, and only flips to published when the author is explicitly ready.

Each Incident has at most one Postmortem via a OneToOneField. The postmortem lives at /ws/{slug}/incidents/{key}/postmortem and shares its breadcrumb with the parent incident.

Why it exists

Most teams skip postmortems because writing them is annoying. Vigilo cuts the friction by pre-populating the timeline from the incident's audit log, offering an AI root-cause first draft, and materialising action items as real Task rows you can assign, watch, and burn down. The artifact still belongs to a human — the AI doesn't publish — but the boilerplate cost drops from an hour to a few minutes.

The blameless framing is in the editor itself: the reminder banner on the root-cause field reads "Describe the system condition, not the human." The published view exposes the author and the action items but not the responders by name unless they appear in a postmortem field.

Key concepts

Postmortem — Workspace-scoped, one-to-one with Incident. Fields: summary, impact, root_cause, contributing_factors, what_went_well, what_to_improve, action_items (JSON array), timeline (JSON array), is_published, published_at, ai_draft_used, author.
draft vs published — is_published=False is the default; the row is visible to authors and admins. Setting is_published=True stamps published_at and makes the postmortem readable by anyone with incidents.read in the workspace.
timeline — JSON array of {at, source, label, actor, payload} entries, mirroring the incident's structured timeline. Auto-populated on postmortem creation (T1.9) and editable via the drag-reorder timeline editor (T2.9).
action_items — JSON array of {title, owner, due_date, status}. On publish, each entry is materialised as a Task with source_postmortem set (WB.31). Re-publishing is idempotent — existing tasks are not duplicated, only new entries spawn new tasks.
ai_draft_used — Boolean stamped True the first time Generate first draft (WA.3) fills the root_cause field. Surfaces in the published view as a small "AI-assisted draft" tag for transparency.

Common workflows

Creating a postmortem from an incident

From a resolved incident, click Open postmortem. The incident FSM moves from resolved to post_mortem and a new Postmortem row is created.
Vigilo auto-populates the postmortem's timeline from Incident.timeline so you start with the structured event list rather than a blank canvas.
The KB-suggest panel offers runbooks that the incident's tags match — useful for sourcing language for the contributing-factors section.

Drafting the root cause

Open the Root cause tab. The blameless reminder banner is the first thing you see.
Either write the analysis manually or click Generate first draft (WA.3). The AI is given the incident timeline, the linked change (if any), and recent similar incidents, and produces a 3-5 paragraph first draft into the root_cause field. The ai_draft_used flag is set.
Edit. The AI draft is a starting point; you are expected to correct, add context, and remove generic phrasing before publishing.

Editing the timeline

Open the Timeline tab. The auto-populated entries appear in chronological order.
Add entries via the Add event button (manual entries get source='manual').
Drag entries to reorder if the imported audit-log timestamps are misleading (e.g. a delayed Slack message that actually describes an earlier event).
Edit any entry's label or payload inline.

Adding action items

In the Action items section, click Add item. Fill in title, owner, due date.
Save. The item is stored in the postmortem's action_items JSON until publication.
On publish, each action item becomes a real Task (WB.31). Task assignees get a notification, the parent postmortem appears in the task's source field, and progress is visible in the postmortem's action-items panel as the linked tasks update.

Publishing

Review every section. Click Publish.
The publish guard refuses to overwrite an existing published version — if is_published is already True, the Publish button reads Re-publish and updates fields in place rather than spawning a new artifact.
is_published=True, published_at=now(). Action items materialise as Task rows. A postmortem.published event fires through dispatch_event so chat integrations can announce it.

Permissions

Viewers can read published postmortems but not drafts.
Engineers / responders can edit drafts of incidents they responded to and publish their own postmortems.
Authors (set on creation) can edit at any time, including post-publication corrections.
Admins / owners can edit any postmortem and unpublish (returns is_published=False and keeps published_at for history).

Troubleshooting

"Publish refused: existing published version" — The is_published flag is already True. Use Re-publish to update in place. If you genuinely want to start over, an admin can unpublish first.

Action items didn't become tasks — The action items array has empty title fields. Action items with blank titles are skipped on materialisation. Fill them in and re-publish.

The AI draft button is missing — The workspace doesn't have an AI integration configured, or the WORK_AI_DRAFT feature flag is off. Check Settings → Integrations → AI.

The timeline is empty — The parent incident never accumulated structured timeline events (e.g. an incident logged manually with no Slack lifecycle). Add entries manually via Add event.

The "AI-assisted draft" tag is on a postmortem I wrote myself — Clicking Generate first draft sets ai_draft_used even if you subsequently rewrote every word. The flag is conservative on purpose; clear it by editing the postmortem via the admin if it's misleading.