agentleFS
Sign inStart free
jp-solumhealthjp-solumhealth/jpstack/postmortem/SKILL.md

postmortem

Skill0 starsChanged 18 days agoMITView on GitHub

Capture and consult lessons from past failures so the same mistake never happens twice. AUTO-TRIGGER (1) before starting any non-trivial task — read INDEX.md and load lessons whose tags match the task; (2) whenever the user expresses frustration, says "this doesn't match", "not the same", "why so long", "this is wrong", "not good", "didn't work", asks for a retry on the same artifact, or any task requires more than 2 iterations to land — write a new lesson. Also trigger on phrases "postmortem", "post mortem", "lessons learned", "what went wrong", "review what happened", "retro for this task". Lessons live at ~/Documents/Claude/Skills/jpstack/postmortem/lessons/ and are indexed in INDEX.md by tag.

We split this skill into the rules it gives an agent

9 rules. 0 are common, 8 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 40 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write a new postmortem entry when ANY of these happen:

    line 18
  2. Distinctive:

    If you're unsure whether to write one, write one.

    line 29
  3. Distinctive:

    Read relevant lessons BEFORE starting work when:

    line 33
  4. Distinctive:

    When in doubt, scan INDEX.md anyway — it's small and fast.

    line 42
  5. Very specific:

    After writing the file, append a one-line entry to INDEX.md under the appropriate section.

    line 81
  6. Distinctive:

    Always state which lessons you applied: When you start a task that matches a tag, say: "Applying lessons: [link]" before doing the work.

    line 93
  7. Distinctive:

    One lesson per root cause: If a task had two root causes, write two lessons.

    line 94
  8. Distinctive:

    Update existing lessons: If a new instance refines a known rule, edit the existing file and bump the date — don't fragment.

    line 95
  9. Distinctive:

    Lessons override defaults: If a lesson says "do X", that beats your training instinct.

    line 97

“Common” is measured: kept by at least 6 in 10 of the 40 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Postmortem Skill

A persistent failure log. The whole point: never repeat a mistake.

Two modes

READ mode (consult before work). Before starting any non-trivial task — especially file conversions, design work, API integrations, sales doc generation, anything that touched a sharp edge before — open INDEX.md, scan for tags that match the task, and read the matching lesson files. Apply what you learned BEFORE writing code, not after the user pushes back.

WRITE mode (capture after a struggle). If the user expressed frustration, the task took multiple iterations, you delivered something wrong before getting it right, or the user asked "why did this take so long" — stop and write a postmortem. Do this even if the task ultimately succeeded. Successful-after-three-tries is still a failure mode worth recording.

When to write (auto-trigger conditions)

Write a new postmortem entry when ANY of these happen:

  • User says: "doesn't match", "not the same", "this is wrong", "not good", "didn't work", "still off", "look like garbage", "you missed", "broken", or any clearly unhappy tone about the output.
  • User asks the same task twice with corrections.
  • You needed ≥ 3 iterations to land the deliverable.
  • You delivered, declared done, and the user pushed back.
  • Tooling did something surprising (extracted wrong data, silent fallback, library bug).
  • A heuristic or assumption you made turned out wrong.
  • You used the wrong tool, font, color, endpoint, or path.
  • A skill or library you trusted gave you false metadata (e.g., PDF reports color X but actually renders Y).

If you're unsure whether to write one, write one. The cost of an extra entry is tiny; the cost of repeating a mistake is real frustration.

When to read (auto-trigger conditions)

Read relevant lessons BEFORE starting work when:

  • The task is a document conversion (PDF/DOCX/PPTX/XLSX in or out).
  • The task involves fonts, colors, layout, or visual fidelity.
  • The task touches an external API, integration, or service the team uses.
  • The task touches an area where a postmortem tag matches.
  • The user says "do this again", "another one of these", or references a past task.
  • You're about to do something that historically went wrong (check INDEX.md tags).

When in doubt, scan INDEX.md anyway — it's small and fast.

How to write a lesson

Lesson files live at lessons/YYYY-MM-DD_short-slug.md. Use this template:

---
date: YYYY-MM-DD
task: <one-line description of what the user asked for>
outcome: <succeeded after N tries / partial / failed>
tags: [tag1, tag2, tag3]
---

## What the user asked for

<verbatim if possible — paraphrase only if the original was long>

## What I did first (the wrong path)

<concrete description: tools used, assumptions made, output produced>

## Why it was wrong

<root cause — not symptoms. "I trusted X metadata" not "the output looked bad">

## What actually worked

<the fix that landed it. Be specific: library calls, parameter values, file paths>

## The rule for next time

<short, imperative, copy-pastable. e.g. "Never trust PyMuPDF span color for visually styled PDFs — always sample the rendered pixels.">

## Signals to watch for

<what would have told me earlier that I was on the wrong path>

After writing the file, append a one-line entry to INDEX.md under the appropriate section. Keep INDEX.md alphabetized by tag for fast scanning.

How to read lessons

  1. Open INDEX.md.
  2. Scan tags relevant to the current task.
  3. Open every matched lesson file. Read at minimum: "The rule for next time" and "Signals to watch for".
  4. Apply the rules in your plan. State explicitly in your message what lessons you're applying so the user sees the carryover.

Important behavior rules

  • Don't apologize and move on. Apologies don't prevent recurrence. Lessons do.
  • Always state which lessons you applied. When you start a task that matches a tag, say: "Applying lessons: [link]" before doing the work.
  • One lesson per root cause. If a task had two root causes, write two lessons.
  • Update existing lessons. If a new instance refines a known rule, edit the existing file and bump the date — don't fragment.
  • Never delete lessons. They're the moat against regression. If a lesson is obsolete, mark it with superseded: <new-file> in frontmatter, but keep it.
  • Lessons override defaults. If a lesson says "do X", that beats your training instinct.

Files

  • INDEX.md — tag-indexed list of lessons. Read first.
  • lessons/*.md — individual postmortems.

Download now (ZIP)

  • Other versions44 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 44

    1. dotnet/fsharp★ 4.3ksame name
    2. SethGammon/Citadel★ 927same name
    3. boshu2/agentops★ 452same name
    4. flonat/flonat-research★ 145same name
    5. neurofoo/agent-skills★ 111same name
    6. Dimon94/dverity★ 107same name
    7. Dimon94/skills★ 107same name
    8. EthanReedLabs/sulde★ 99same name
    9. Hongyu-yu/matsci-ai-skills★ 19same name
    10. Hassaan146/claude-skills★ 18same name

    34 more not listed

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Used alongsideProjects with it also use hypothesis-driven-debugging, status-report and 10 more.

    Other files people use alongside this one.

    Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
    • Sturla22Skill

      hypothesis-driven-debugging

      Debug by ranking concrete hypotheses and running discriminating checks. Use when a bug is hard to localize, many plausible failure points exist, logs are noisy or misleading, a symptom appears intermittently, or trial-and-error edits haven't worked.

      Also in 3 projects that use this

    • AnthropicSkill

      status-report

      Generate a status report with KPIs, risks, and action items. Use when writing a weekly or monthly update for leadership, summarizing project health with green/yellow/red status, surfacing risks and decisions that need stakeholder attention, or turning a pile of project tracker activity into a readable narrative.

      Also in 3 projects that use this

    • seongjaeryuSkill

      organize

      Organize knowledge into Sets

      Also in 3 projects that use this

    • SaluteYBSkill

      skill-eval

      Evaluate, tune, and regression-check AgentSkills. Use when creating a new skill or improving an existing one and you need structured should-trigger, should-not-trigger, boundary-case, and execution-quality examples. Also use when auditing overlapping skills and sharpening trigger descriptions before release.

      Also in 3 projects that use this

    • neurofooSkill

      premortem

      Pre-mortem analysis that imagines a plan has failed, then works backward to identify causes and preventions. Use before launches, major decisions, or risky initiatives to surface hidden risks.

      Also in 3 projects that use this

    • AnthropicSkill

      incident-response

      Run an incident response workflow — triage, communicate, and write postmortem. Trigger with "we have an incident", "production is down", an alert that needs severity assessment, a status update mid-incident, or when writing a blameless postmortem after resolution.

      Also in 4 projects that use this

  • In this repository31 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free