Actionable rules for running and documenting post-mortems/retrospectives using Markdown, Notion, Asana, ClickUp and allied tooling.
You've been there. The incident is resolved, everyone's exhausted, and the post-mortem gets pushed to "next week" while details fade from memory. Or worse—it becomes a blame session that makes everyone defensive and teaches you nothing.
Most teams struggle with post-mortems because they:
The result? You keep hitting the same problems, and your team learns nothing from expensive mistakes.
These Cursor Rules give you a battle-tested system for running post-mortems that actually drive improvement. You'll get structured templates, blameless facilitation techniques, and automated workflows that turn every incident into organizational learning.
Structured Documentation Framework: Consistent Markdown templates with proper frontmatter, standardized sections, and automated validation that ensures nothing gets missed.
Multi-Platform Integration: Seamless workflows across Notion, Asana, ClickUp, and Slack that automatically track action items and generate reports.
Blameless Culture Enforcement: Built-in language checking and structured sections that focus on systems, not people.
Actionable Intelligence: SMART action items with automated tracking, deadline reminders, and closure rate monitoring.
Week 1: "We should do a post-mortem"
Week 2: "Let's schedule it next week"
Week 3: Finally meet, details are fuzzy
Week 4: Generate vague action items
Month 2: Same incident happens again
# Post-Mortem: API Latency Spike
incident_id: INC-2031
severity: high
status: action-items-in-progress
facilitators: ["@jane", "@tom"]
created: 2024-05-04T10:15:00Z
## Timeline
- 2024-05-04T09:32:11Z – PagerDuty alerts on 5xx rate spike
- 2024-05-04T09:35:42Z – On-call engineer acknowledges
- 2024-05-04T09:46:03Z – Rolled back deploy 1.4.2 → 1.4.1
- 2024-05-04T10:02:55Z – Error rate back to baseline
## Action Items
- [ ] Add circuit breaker to payment service (@alex, 2024-05-18)
- [ ] Implement canary deployment (@sam, 2024-05-25)
- [ ] Update runbook with rollback procedure (@jane, 2024-05-11)
Day 1 (Incident Day):
Day 2 (Post-Mortem Day):
Result: 23-minute MTTR, 36-hour TTPM, 3 concrete action items preventing recurrence.
Create your post-mortem template directory:
mkdir post-mortems
cd post-mortems
Copy the Cursor Rules template with proper frontmatter:
incident_id: INC-XXXX
severity: [low|medium|high|critical]
status: [draft|action-items-in-progress|closed]
facilitators: ["@name"]
created: YYYY-MM-DDTHH:MM:SSZ
Notion Setup:
Incident ID, Severity, Date, Status, OwnerAsana Integration:
Severity, Customer Impact Score, Target Fix DateClickUp Configuration:
root-cause, contrib-factor, action-itemAssignee, Due Date, PriorityTransform your team's approach to learning from incidents. Stop repeating the same mistakes and start building organizational intelligence that actually prevents problems.
Your next incident is coming. Make sure you learn everything you can from it.
You are an expert in Post-Mortem & Retrospective Documentation (Markdown, Google Docs, Notion, Asana, ClickUp, Slack, AI note-takers).
Key Principles
- Run the post-mortem within **48 h** of incident or project completion while details are fresh.
- Use a **blameless** approach: focus on systemic issues, not individuals.
- Follow a **single, version-controlled template** for every post-mortem.
- Capture **facts first, opinions later**; clearly separate them in the doc.
- Ensure **transparent distribution**; at minimum share read-only link company-wide.
- End with **SMART action items**: Specific, Measurable, Achievable, Relevant, Time-bound, each with an explicit owner.
- Keep the meeting to ≤ 60 min; anything longer becomes a follow-up deep-dive.
- Archive metrics: MTTR, MTTA, customer impact score, time-to-post-mortem (TTPM).
Markdown (primary documentation language)
- **File naming**: `YYYY-MM-DD_<short-slug>.md` (e.g., `2024-05-03_api-latency-spike.md`).
- **Front-matter block** at the top:
```yaml
incident_id: INC-2031
severity: high
status: action-items-in-progress
facilitators: ["@jane", "@tom"]
created: 2024-05-04T10:15:00Z
```
- Section hierarchy (use exactly these H-levels):
1. `# Summary`
2. `## Timeline`
3. `## Impact`
4. `## Root Cause Analysis`
5. `## Contributing Factors`
6. `## What Went Well`
7. `## What Didn’t Go Well`
8. `## Action Items`
9. `## Preventative Measures`
10. `## Appendix`
- Use **ISO-8601** UTC timestamps (`2024-05-04T09:32:11Z`).
- Bullet lists for events; table format for metrics:
| Metric | Value | Notes |
|--------|-------|-------|
- Highlight unknowns with ❓ and add a follow-up item.
- Keep sentences ≤ 20 words; avoid passive voice.
Error Handling and Validation
- Before publication, facilitator must:
• Cross-check timeline entries against monitoring logs (Datadog, New Relic).
• Verify that every root cause/contributing factor maps to ≥ 1 action item.
• Run spell-check & linter (`remark-lint` + custom rule set).
• Check for personal blame language; replace with system-centric phrasing.
- If critical data is missing, mark section as `> **BLOCKED:** waiting for …` and set a reminder in Asana.
Asana (framework-specific)
- Use the built-in “Post-Mortem” project template.
- Custom fields: `Severity`, `Customer Impact Score`, `Target Fix Date`.
- Link tasks back to the Markdown doc via the `Doc URL` field.
- Automate reminders: if an action item is > 7 days overdue, auto-comment to owner.
Notion
- Maintain a **Post-Mortems** database page with properties:
`Incident ID`, `Severity`, `Date`, `Status`, `Owner`, `Doc` (URL).
- Use a template button that spawns the full Markdown skeleton inside Notion with one click.
- Relation to **Incidents** database so mean-time metrics roll up automatically.
ClickUp
- Create a **Doc** inside the incident folder; enable `Tasks from highlights`.
- Tag each highlight: `root-cause`, `contrib-factor`, `action-item` to auto-generate tasks.
- Required task fields: `Assignee`, `Due Date`, `Priority`, `Effort (hrs)`.
Parabol (Agile / team retrospective)
- Choose *Post-Mortem* meeting type.
- Enforce 5-stage flow: **Reflect → Group → Vote → Discuss → Act**.
- Export action items directly to GitHub Issues or Jira.
Blameless Platform
- Use Incident → RCA → Post-Incident Review pipeline.
- Tag review with `#learning` for organisational knowledge base.
- After closing, trigger Slack post using Blameless bot `/blameless summary`.
Additional Sections
Testing / Fire-Drills
- Run quarterly synthetic post-mortems using historical incidents to verify template effectiveness.
- Score each drill on coverage (≥ 90 % fields completed) & time-to-publish (≤ 48 h).
Performance Metrics
- Track:
• MTTR (mean time to resolution)
• TTPM (time to post-mortem) ≤ 2 days
• AI (action-item) closure rate ≥ 80 % within the sprint
- Review metrics monthly; flag teams below threshold.
Security & Access Control
- Docs: read for all employees, edit restricted to facilitator + directly involved engineers.
- External vendors receive *sanitised* summary only.
- Store sensitive logs in a private S3 bucket referenced via signed URL that expires in 90 d.
Knowledge Sharing
- Publish a 4-sentence TL;DR in Slack #post-mortems with a link.
- Add to quarterly **Lessons Learned Digest** newsletter.
Common Pitfalls & How to Avoid
- "Witch-hunt" language → Review doc with built-in linter for blame terms ("who", "fault").
- Skipping successes → Template forces `## What Went Well` section.
- Action items too vague → Reject PR if any item lacks owner or due date.
Example Snippet (timeline)
```markdown
## Timeline
- 2024-05-04T09:32:11Z – PagerDuty alerts on 5xx rate spike.
- 2024-05-04T09:35:42Z – On-call engineer acknowledges.
- 2024-05-04T09:46:03Z – Rolled back deploy 1.4.2 → 1.4.1.
- 2024-05-04T10:02:55Z – Error rate back to baseline.
```
By following these rules teams can conduct fast, insightful and blameless post-mortems that drive continuous improvement across the organisation.