# Postmortem > Create a postmortem draft from a Jira ticket. Reads the ticket, prefills the title and summary, and lays out the investigation sections to be filled during the working session. Pass --no-prefill to leave the summary empty too. Usage: /postmortem MLID-XXXX [--no-prefill] ["symptom description"] - Skill: `alejandrogomezforte/postmortem` (Agent Skill) - Install (CLI): `npx skillmds@latest add alejandrogomezforte/postmortem` - Raw SKILL.md: https://api.skillmd.com/api/skills/alejandrogomezforte/postmortem/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: alejandrogomezforte (https://skillmd.com/u/alejandrogomezforte) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/alejandrogomezforte/postmortem --- # /postmortem $ARGUMENTS You are creating a **postmortem draft** — the document that records why a bug happened, what the data and code showed, and what was done about it. The postmortem is written **during a working session**, not up front. At most the title and the summary come from the Jira ticket. Every other section is laid out empty with a guideline, because the user fills them with you as the investigation proceeds: hypotheses get raised and discarded, real records get pasted in, code gets read, and a conclusion and fix emerge at the end. Your job here is to produce that scaffold. You are not investigating yet. The skill runs in one of two modes, chosen by a flag on the command line: - **Prefill** (default) — section 1 carries a summary drawn from the ticket and from `SYMPTOM`. - **Scaffold** (`--no-prefill`) — the title and header block are still filled, and section 1 joins sections 2 through 7 as a guideline line. Use this when the ticket describes the report rather than the failure, when the reported symptom turns out to be wrong, or when you would rather write the summary yourself once the session has shown what actually happened. ## Step 0 — Parse arguments `$ARGUMENTS` contains the raw input. Split it into: - **`TASK_ID`**: the first whitespace-separated token (e.g., `MLID-2799`). - **`PREFILL`**: `false` when the token immediately after `TASK_ID` is `--no-prefill`, `--blank` or `--raw`; `true` otherwise. Consume the flag token when present — it is never part of `SYMPTOM`. - **`SYMPTOM`**: everything remaining, with surrounding quotes (`"..."` or `'...'`) stripped. May be empty. `SYMPTOM` is the **observed symptom in the user's own words**. Jira tickets for bugs often describe the report rather than what was actually seen, so when `SYMPTOM` is given it takes priority for both the filename slug and the framing of the summary. `SYMPTOM` still drives the slug and the title when `PREFILL` is `false` — naming the file is not analysis. What the flag turns off is the written summary in section 1. **Never ask the user which mode to use.** The flag is the whole answer: absent means prefill, present means scaffold. If the user writes something flag-like that you do not recognise, treat it as `SYMPTOM` and say so when you report. ## Step 1 — Decide the filename The output file is `docs/agomez/postmortem/{TASK_ID}-{slug}.md`. Build `{slug}` as three to six lowercase words joined by hyphens, describing the **symptom**, not the fix: - If `SYMPTOM` is non-empty, derive the slug from it — for example `orders grid blanks out on the drug column` becomes `orders-grid-blanks-on-drug-column`. - Otherwise derive it from the Jira summary. Good slugs read like the thing a person would search for months later: `drug-cell-crash-on-no-value-filter`, `unassigned-to-assigned-skips-notification-backfill`. Avoid words that carry no signal, such as `bug`, `issue`, `problem` or `fix`. ## Step 2 — Check whether the file already exists Check for a file matching `docs/agomez/postmortem/{TASK_ID}-*.md` — the existing slug may differ from the one you just built, so match on the ticket ID. **If one exists, STOP and ask the user** which they want: 1. Overwrite the existing file 2. Write to a `-v2` variant of the name instead 3. Abort Never overwrite without an explicit answer. A postmortem accumulates a whole session of investigation; a re-run must not be able to erase it. ## Step 3 — Read the Jira ticket Use the Atlassian MCP to read issue `TASK_ID`. Cloud ID: `958cb046-2571-47a5-a29b-8baa0bee65b2`. Extract: - Summary and description - Steps to reproduce, expected behaviour and actual behaviour, when the ticket follows the project bug-report format - Issue type and parent epic link - Comments, when they carry reproduction detail or environment information Read the ticket in **both modes**. When `PREFILL` is `false` you still need the summary to build the slug and the title if `SYMPTOM` was not given — that part is mechanical transcription, not analysis, so it is always filled. **Do NOT investigate.** No codebase reading, no Mongo queries, no log reading, no root-cause claims. Those belong to the session that follows, with the user driving. A postmortem whose conclusion was written before the investigation is worthless. If the ticket is thin — which is common for bugs reported verbally — say so in the summary and rely on `SYMPTOM`. ## Step 4 — Write the postmortem boilerplate Write the file using the template below. The **title**, the PHI notice and the reference block are filled in **both modes**. Sections 2 through 7 always hold a single italic guideline line describing what goes there. Those guidelines are working instructions for the session, and they stay in place until the user replaces them. Section 1 depends on `PREFILL`: - **`true` (default)** — write the summary from the ticket and from `SYMPTOM`, as described in the template. - **`false`** — section 1 becomes a guideline line like the others: `_To fill: what was reported and what was observed, in three to six sentences. The failure only — no cause, no fix._` Write no prose, and do not leave the `<...>` placeholder in place. Add `> Scaffold only — the summary was not prefilled from Jira.` below the reference block and above the horizontal rule, so a reader months later knows the emptiness was chosen, not an oversight. ### Template ```markdown # [{TASK_ID}] Postmortem: > **PHI notice:** Internal database identifiers (order id, patient id, drug id, > provider NPI, document id, notification id, staff user ids) are retained — these are > internal reference keys, not patient persona or clinical data. Free-text > patient-descriptive content has been removed. Staff are referred to by role. - **Status**: Investigating - **Jira**: [{TASK_ID}](https://localinfusion.atlassian.net/browse/{TASK_ID}) - **Date detected**: - **Environment**: - **Related files**: _to be filled during the session_ > Scaffold only — the summary was not prefilled from Jira. --- ## 1. Summary ## 2. Hypothesis _What we currently believe is causing this, and why. Written and revised together during the session. Keep discarded hypotheses with a short note on what ruled them out — the ones we eliminated are part of the record._ ## 3. Data structures involved _Which collections, tables and documents take part in this failure, and how they relate to each other. Names and relationships only — no schemas, no field-by-field listings._ ## 4. Data relevant to the bug _The actual records that show the failure: the queries or filters used, and the values they returned. Real content, not structure. Redact free-text patient-descriptive fields; internal identifiers stay, per the PHI notice above._ ## 5. Code relevant to the bug _The code paths that produce the failure: file paths and the functions or components involved, with only the few lines that matter. Reference code by path and symbol name, not by line number._ ## 6. Conclusion _The confirmed cause, stated so a reader who was not in the session understands it. Cover three things: what the error was, why it happened, and why it surfaced now rather than earlier._ ## 7. Fix _What was changed, where, and on which branch. Note whether a data repair or backfill was needed alongside the code change, how the fix was verified, and anything that would stop this class of failure from recurring._ ``` ### Filling rules - Replace `<...>` placeholders in the title and the reference block in both modes, and in section 1 when `PREFILL` is `true`. Leave sections 2 through 7 as their italic guideline line — do not pre-answer them, do not add empty sub-headings, do not add tables. - Never ship an angle-bracket placeholder. In scaffold mode section 1 holds its `_To fill:_` line, not `<...>`. - The PHI notice is always emitted, even before any real data is present. It sets the rule for what gets pasted in later. - `Status` is always `Investigating` in both modes — the scaffold marker is its own line. - `Date detected` is left for the user. The ticket creation date is not the detection date and must not be assumed. - Dates use `MM/DD/YYYY`. - Spell identifiers out and avoid abbreviations and idioms — this document is read later by people who were not in the session. ## Step 5 — Report and stop Print the path of the file you wrote, and which mode you used — `summary prefilled from Jira` or `scaffold only` — and stop. Do not echo the document into the conversation and do not begin investigating. Naming the mode matters: it is the user's only confirmation that the flag parsed the way they intended. If you fell back on an unrecognised flag-like token and treated it as `SYMPTOM`, say that here too — that fallback also changes the slug, so it is worth catching immediately. Tell the user the scaffold is ready and that the remaining sections get filled together as the session proceeds. ## Boundaries - **No investigation at creation time.** The ticket is the only input, plus `SYMPTOM` when given. Code, database and logs are for the session that follows. - **The mode is chosen by the flag, never by you and never by a question.** Prefill is the default. `--no-prefill` suppresses the written summary in section 1; it never suppresses the title, the PHI notice or the reference block, and it never changes the filename or the section list. - **Never state a cause you have not confirmed.** A hypothesis lives in section 2 and is labelled as one. Section 6 is written only after evidence exists. - **Never decide alone.** Every judgement during the session — which hypothesis to pursue, which fix to apply, whether the evidence is sufficient — is the user's call. Offer options and reasoning; do not resolve. - **Respect PHI.** Internal identifiers are retained; free-text patient-descriptive and clinical content is removed. Staff are referred to by role, never by name. - **No implementation code in this document.** The fix section describes what changed and where; the code itself lives in the branch.