postmortem-writing

Overview of postmortem-writing skill

What postmortem-writing does

The postmortem-writing skill helps an agent produce structured, blameless incident postmortems with the parts teams usually forget under pressure: a clear timeline, root cause analysis, contributing factors, impact, and concrete follow-up actions. It is aimed at report writing after outages, degraded service, near-misses, data issues, or other incidents that deserve organizational learning rather than a loose summary.

Who should install postmortem-writing

This skill is a strong fit for:

• SRE, DevOps, platform, and incident response teams
• engineering managers who need consistent incident reports
• staff writing internal report-writing deliverables after outages
• teams trying to shift from blame-heavy retrospectives to systems thinking

If your main job is to turn messy incident notes into a usable postmortem, postmortem-writing is more targeted than a generic writing prompt.

The real job-to-be-done

Most users do not need help “writing a document” in the abstract. They need help turning logs, chat threads, alerts, and partial memory into a report that:

• explains what happened in plain language
• preserves chronology
• separates root cause from contributing factors
• avoids blaming individuals
• ends with actions that can actually be tracked

That is the practical value of the postmortem-writing skill.

What differentiates this skill from a normal prompt

The main differentiator is not fancy automation. It is editorial structure and incident-review discipline. The source material emphasizes:

• blameless framing
• explicit incident triggers for when a postmortem is warranted
• a timeline-first workflow
• root cause analysis over surface symptoms
• action items as the end product, not an afterthought

That makes the postmortem-writing skill useful when you want consistency and safer language, not just polished prose.

What to know before adopting

This skill is documentation-first. The repository evidence shows only SKILL.md, with no helper scripts, schemas, or reference files. That means postmortem-writing install is simple, but output quality depends heavily on the incident inputs you provide. If you expect automatic evidence gathering or ticket creation, this skill will not do that by itself.

How to Use postmortem-writing skill

postmortem-writing install context

Install it from the parent skill repository:

npx skills add https://github.com/wshobson/agents --skill postmortem-writing

Because the skill lives at plugins/incident-response/skills/postmortem-writing, you are installing a writing workflow and guidance layer, not a standalone incident platform.

Read this file first

Start with:

• SKILL.md

There are no supporting resources/, rules/, or scripts surfaced for this skill, so the fastest repository-reading path is simply to read SKILL.md end to end. That matters here because the value is in process guidance and framing, not code.

Best moments to invoke postmortem-writing

Use postmortem-writing usage when you already know an incident deserves a formal write-up, especially for:

• SEV1 or SEV2 incidents
• customer-facing outages longer than a trivial blip
• data loss or security issues
• near-misses with high severity potential
• novel failures or unusual operator intervention

If the event was minor and no learning or remediation is needed, a short incident note may be enough.

What input the skill needs

The skill works best when you provide raw incident material, not just “write a postmortem.” Useful inputs include:

• incident summary
• start and end times
• customer or system impact
• timeline of key events
• detection method
• mitigation steps
• suspected root cause
• known contributing factors
• unresolved questions
• follow-up actions already discussed

The more precise your chronology, the better the final report.

Turn a rough request into a strong prompt

Weak prompt:

• “Write a postmortem for yesterday’s outage.”

Strong prompt:

• “Use the postmortem-writing skill to draft a blameless postmortem for a 47-minute API outage on 2025-02-10. Include a minute-by-minute timeline, impact summary, root cause, contributing factors, what detection missed, and action items grouped by prevention, detection, and response. Mark uncertainties clearly instead of inventing details.”

Why this is better:

• it sets incident scope
• it requests blameless framing
• it asks for missing-but-important sections
• it allows uncertainty rather than hallucinated certainty

A practical prompt template

Use a prompt shape like this:

• Incident type: outage, degradation, security event, data incident, near-miss
• Severity: SEV level or equivalent
• Time window: start, detection, mitigation, resolution
• Impact: users, revenue, requests, data, internal operations
• Evidence: logs, alerts, chat notes, ticket excerpts
• Suspected cause: what failed and why
• Contributing factors: tooling, process, load, config, staffing, dependencies
• Desired output: executive summary, timeline, RCA, lessons learned, action items
• Tone constraint: blameless, factual, no named-person blame
• Unknowns: list them explicitly

This is the fastest way to improve postmortem-writing for Report Writing.

Suggested workflow for real incidents

A workable flow is:

1. Gather raw facts from incident notes and system evidence.
2. Ask the skill for a first-pass structured draft.
3. Review the timeline for sequencing errors.
4. Tighten root cause vs contributing factors.
5. Remove blame-oriented phrasing.
6. Add action items with owners and due dates outside the draft if needed.
7. Use the final report in the postmortem meeting.

This sequence matches how teams actually write after an incident: facts first, interpretation second, remediation last.

How to get better timelines

Timeline quality usually determines whether the document feels trustworthy. Give the skill timestamped bullets such as:

• 09:14 UTC: latency alert fired
• 09:16 UTC: on-call acknowledged
• 09:21 UTC: deploy rollback started
• 09:37 UTC: error rate returned to baseline

Without this, even a good postmortem-writing guide cannot reliably reconstruct causality.

How to ask for better root cause analysis

Do not ask only for “the root cause.” Ask for:

• immediate cause
• deeper systemic factors
• why safeguards failed
• why detection or escalation was late
• what made the failure possible

This keeps the output from collapsing into “a bad deploy happened,” which is usually too shallow to be useful.

How to keep the write-up blameless

The skill explicitly centers blameless culture. Reinforce that in your prompt:

• ask it to focus on system conditions, not individual fault
• request neutral wording
• ask it to separate human actions from organizational and technical context

For example, prefer:

• “The deployment process allowed an unsafe config change to reach production”
  over:
• “An engineer pushed the wrong setting”

What this skill does not provide

The postmortem-writing skill does not appear to include:

• automated data collection
• incident timeline extraction from tools
• ticket syncing
• severity classification logic beyond general guidance
• organization-specific templates out of the box

Plan to supply your own context and adapt the output to your incident program.

postmortem-writing skill FAQ

Is postmortem-writing better than a normal LLM prompt?

Usually yes, if your main problem is structure and discipline. A normal prompt can generate a postmortem, but it often misses incident triggers, blameless framing, or the distinction between root cause and contributing factors. postmortem-writing gives the agent a clearer operating pattern.

Is this suitable for beginners?

Yes. It is beginner-friendly because it is guidance-heavy and does not require custom tooling. But beginners still need to bring the factual incident record. The skill improves writing quality and review structure; it does not replace incident investigation.

When should I not use postmortem-writing?

Skip it when:

• the event does not justify a full postmortem
• you need a real-time incident commander, not a writer
• you lack basic facts and are still actively debugging
• your organization needs a strict proprietary template that this skill cannot match without heavy adaptation

Does postmortem-writing work only for engineering outages?

No. It is best aligned with technical incidents, but the framework also fits security incidents, data mishaps, operational failures, and serious near-misses as long as you can provide a timeline, impact, and corrective actions.

Can I use postmortem-writing for executive summaries?

Yes, but do not stop there. Executives usually need a short summary, while responders need the full timeline and action plan. Ask the skill to produce both a concise summary and the complete report.

Does the skill help with action items?

Yes, indirectly. The source guidance emphasizes actionable follow-up items. You will get better results if you ask for actions grouped by category such as prevention, detection, response, and process improvement.

How to Improve postmortem-writing skill

Give postmortem-writing better evidence, not just better instructions

The biggest quality lever is input fidelity. Paste in:

• timestamps
• customer impact metrics
• alert names
• mitigation steps
• known unknowns

Rich evidence beats elaborate meta-instructions.

Separate facts from interpretation

A common failure mode is mixing assumptions into the timeline. Provide two blocks:

• confirmed facts
• hypotheses or open questions

This helps postmortem-writing usage stay accurate while still surfacing uncertainty.

Ask for missing sections explicitly

If your first draft is too generic, request the missing sections by name:

• “Add a ‘What went well’ section”
• “Separate contributing factors from root cause”
• “Rewrite action items so each is specific and testable”

Concrete revision requests improve results faster than “make it better.”

Prevent shallow action items

Weak postmortems end with vague actions like “improve monitoring.” Ask the skill to make each action:

• specific
• assignable
• linked to a failure mode
• measurable or testable

For example:

• “Add an alert for queue lag over 5 minutes in region us-east-1”
  is better than:
• “Improve alerting”

Watch for blame creeping back in

Even with a blameless skill, source material from chats or notes may contain blame-heavy language. Review for wording that over-focuses on a person rather than system conditions, incentives, tooling, review gaps, or operational context.

Iterate in two passes for higher-quality output

A reliable pattern is:

1. first pass for factual structure
2. second pass for analysis and actions

This avoids forcing the model to invent polished reasoning before the chronology is stable.

Adapt the output to your team’s postmortem maturity

If your team is early-stage, ask postmortem-writing for a simple format with timeline, impact, causes, and actions. If your team is mature, ask for deeper sections like detection gaps, escalation effectiveness, recovery tradeoffs, and systemic lessons. The same skill can support both, but only if you set the expected depth.

Improve report-writing outcomes after the first draft

To get stronger postmortem-writing for Report Writing results, do a final review against four questions:

• Would a new team member understand what happened?
• Is the timeline precise enough to audit?
• Does the analysis explain why defenses failed?
• Are the actions concrete enough to reduce recurrence?

If any answer is no, revise the prompt with that gap rather than rerunning blindly.