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

# [{TASK_ID}] Postmortem: <symptom in plain words>

> **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**: <MM/DD/YYYY — to be filled>
- **Environment**: <production | staging | local — to be filled>
- **Related files**: _to be filled during the session_

<!-- Include this line ONLY when PREFILL is false -->
> Scaffold only — the summary was not prefilled from Jira.

---

## 1. Summary

<What was reported and what was observed, in three to six sentences, from the ticket
and from SYMPTOM when given. Describe the failure only — no cause, no fix.
State plainly whatever the ticket leaves unknown.>

## 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.