Write a postmortem for a regression that escaped to production, broke real users, and traces back to a design flaw worth documenting for future implementors. Only invoke after confirming no existing postmortem or doc covers the same root cause.
All of the following must be true:
docs/postmortems/ for existing write-ups covering the same root cause. Check .github/instructions/ for rules that already encode the lesson. If covered, stop.Do not write a postmortem for:
Before writing a single line, answer these questions:
Write the file in docs/postmortems/ with a descriptive filename (e.g., regression-fs0229-bstream-misalignment.md).
Use this outline:
Two to three sentences. What broke, who was affected, what the root cause was.
What did users actually see? Include the exact error message or observable behavior. Someone searching for this error should find this doc.
Explain the design assumption that was violated. Keep it high-level enough that someone unfamiliar with the specific code can follow. Use short code snippets only if they clarify the mechanism — not to show the full diff.
How did this get past code review, CI, and testing? Be specific: "The test suite only exercised single-TFM builds" is useful. "Testing was insufficient" is not.
Brief description of what changed and why it restores the invariant. Link to the PR.
Table of relevant PRs/dates showing how the bug was introduced, exposed, and fixed. Include latent periods where the bug existed but was masked.
What has been or should be added to prevent recurrence: tests, agentic instructions, CI changes, code review checklists. Link to the specific artifacts (e.g., the .github/instructions/ file that encodes the lesson).
Identify the trigger paths. Determine which source files, when changed, would risk repeating this class of bug. Be specific — e.g., src/Compiler/TypedTree/TypedTreePickle.{fs,fsi}, not "the compiler". These are the files where a future contributor needs to see the lesson.
Create or update an instruction file. Check .github/instructions/ for an existing instruction file whose applyTo covers those paths. If one exists, add a reference to your postmortem. If none exists, create one with an applyTo scoped to exactly those paths:
---
applyTo:
- "src/Compiler/Path/To/File.{fs,fsi}"
---
The instruction file should encode the generalized rule (not the incident details). Link the postmortem as a "see also" for deeper context. The postmortem explains why the rule exists; the instruction file tells agents what to do when editing those files.
Do not create instructions without path scoping. A postmortem lesson that applies "everywhere" is too vague to be actionable. If you can't name the files where the lesson matters, the postmortem may not meet the threshold for this skill.
Update docs/postmortems/README.md if it maintains an index.