post_mortem

Generate a detailed post-mortem analysis after a debugging session or incident, capturing what failed, what worked, and lessons learned

Post-Mortem Generator

Generate a detailed post-mortem analysis after a debugging session or incident.

When to Use

Use this command after:

  • A debugging session that took longer than expected
  • An incident or outage
  • A complex problem that was finally resolved
  • Any situation where we want to capture lessons learned

Instructions

  1. Review the conversation history to identify:

    • The original problem/request
    • What was tried and failed
    • What finally worked
    • Time spent vs expected

  2. Generate a post-mortem document with these sections:

    Header

    • Date
    • Issue summary (one line)
    • Resolution time (actual vs expected)

    The Problem

    • Clear description of what the user wanted
    • Why it seemed simple

    What Went Wrong

    • Number each failure point
    • Include code snippets showing the problematic code/config
    • Explain WHY each approach failed

    The Solution

    • The actual fix (with code)
    • Why this worked when other approaches didn't

    What We Learned

    • Numbered list of technical lessons
    • Be specific and actionable

    What To Do Differently

    • Organized by phase: Before/During/After
    • Include specific commands or checks to run

    Time Cost

    • Honest assessment of wasted time
    • Root causes of the delay

    Key Takeaway

    • One memorable sentence summarizing the main lesson

  3. Save the document to docs/postmortem_[brief_description].md

  4. Ask the user if any lessons should be added to CLAUDE.md for future reference

Output Format

Use markdown with clear headers, code blocks, and bullet points. Keep it scannable but detailed enough to be useful months later.

Example Filename

  • postmortem_dashboard_width.md
  • postmortem_api_timeout.md
  • postmortem_deploy_failure.md