skilldrop-cli 0.16.14 → 0.16.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.14",
+  "version": "0.16.16",
   "description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs/dev-team/loops/release/LOOP.md

@@ -29,8 +29,8 @@ being folded into either neighbour.
    checks rollback, detection, response, measured targets, data and privacy, comms and
    exposure, each with evidence. `REVISE` returns to `plan`, and the report names which gap to
    close and which skill closes it. A missing rollback is `BLOCKED` on its own.
-3. **Announce only once it is ready.** `release-notes` drafts the customer-facing and
-   internal notes from the git range. Writing them before G3 risks announcing a launch that
+3. **Announce only once it is ready.** `release-notes` drafts the notes for each audience
+   you name from the git range, with nothing the log doesn't say. Writing them before G3 risks announcing a launch that
    then does not happen.
 4. **A human decides at G3.1.** The release owner decides whether to ship *now*, given
    timing, freeze windows and on-call coverage. When that decision is contested, use

package/packs/dev-team/loops/release/loop.json

@@ -1,7 +1,7 @@
 {
   "$comment": "RFC-0031. Covers the step between build (ends at merge, G2.1) and operate (starts at instrument). Its gates are G3 and G3.1: the whole number places the loop in the lifecycle (discover G0 through operate G4), and a decimal is a second gate inside the same loop (RFC-0044).",
   "name": "release",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Take merged code to live users through a planned, reversible rollout — plan the phases and the rollback, judge readiness on evidence, draft the release notes, then a human makes the go/no-go call. Use when the user has merged a change and asks how to roll it out, whether they are ready to launch, or for a go/no-go decision.",
   "entrypoint": "LOOP.md",
   "kind": "loop",

package/packs/dev-team/skills/release-notes/SKILL.md

@@ -1,69 +1,96 @@
 ---
 name: release-notes
-description: Turn git history between two refs into release notes — a customer-facing version written in reader benefits and an internal Keep-a-Changelog version with commit traceability, breaking changes always first. Use when the user wants release notes, a changelog, "what's in this release", a deploy announcement, or to summarize changes since the last tag.
+description: Write release notes from a git log, a list of merged PRs or rough notes about what changed — for the audience and in the format the user names (a customer changelog page, an email, an in-app "what's new", store text, a CHANGELOG.md entry). Says nothing the input doesn't, writes a vague change only as far as it was described, puts breaking changes and anything the reader must do first, and keeps internal noise and working notes out of the text. Use when the user wants release notes, a changelog entry, "what's in this release", a deploy announcement, or to summarise changes since the last tag.
 ---
 
 # release-notes
 
-Converts commit history into two artifacts with different readers: **customer-facing release notes** (benefits, no commit-speak) and an **internal changelog** (Keep a Changelog format, every line traceable to a commit). The rule that drives everything: write for the reader who didn't make the change.
+**The rule: nothing goes in the notes that the log or the user didn't say.** A release note is
+read as a promise. The agent's habit is to make a vague commit sound finished: "tweaked onboarding"
+becomes "onboarding is now simpler", a half-remembered fix gets a symptom, a reverted feature
+gets announced because its commit is in the range. Each of those reads exactly like a real
+change, and a customer will hold you to it. This skill's job is to write only what the input
+supports, as far as it supports it.
 
 ## How to respond
 
-**Four rules come before the steps and outrank them:**
-
-- **Answer what was asked, first.** Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
-- **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
-- **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
-- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
-- **For this skill:** Write one set of notes for the audience the user named. Add the second, internal version only when they ask for both. Use the product's name only if they gave it, and count commits and pull requests from the list in front of you.
-
-1. **Resolve the range.** Default: last tag to HEAD (`git describe --tags --abbrev=0`). If no tags exist, ask for a start ref or take the user's two refs. State the resolved range at the top of the output: "`v1.4.0..HEAD`, 37 commits, 2026-05-02 → 2026-06-10".
-
-2. **Gather the raw material.** `git log <range> --no-merges --pretty='%h|%s|%an|%ad' --date=short` for the commit list; `git log <range> --stat` only when a subject line is too vague to classify. Where the `gh` CLI is available and the repo uses PRs, prefer PR titles over commit subjects (`gh pr list --state merged --search "merged:>={date}"`) — they're written closer to reader language. Don't require `gh`; commits alone are enough.
-
-3. **Classify every change** into Keep-a-Changelog categories plus one local bucket:
-   - **Added / Changed / Fixed / Deprecated / Removed / Security** — reader-visible
-   - **Internal** — refactors, CI, deps, tests; appears in the internal changelog, never in customer notes
-   - **Needs review** — can't tell what it does from the commit; goes in a list for the user, never guessed into customer notes
-
-4. **Hoist breaking changes and migrations to the top** of both artifacts, each with an **Action required** line. A breaking change buried under "Changed" is the cardinal failure of release notes. Detect via `BREAKING`, `!:` conventional-commit markers, migration files, major dependency bumps, and removed public API — and say which signal triggered the flag.
-
-5. **Rewrite, don't transcribe.** Each customer-facing line states what the reader can now do or no longer suffers. ✅ *"Fixed a crash when exporting reports with more than 10,000 rows"* — ❌ *"fix NPE in ReportExporter.flush()"*. Drop ticket numbers and author names from customer notes; keep both in the internal changelog with the short hash on every line.
-
-6. **Emit both artifacts** with [`templates/release-notes.md`](templates/release-notes.md): customer notes first, internal changelog second, then the **Needs review** list. If the user wants only one artifact, emit that one — but the needs-review list is never optional.
-
-## Useful references in this skill
-
-- [`templates/release-notes.md`](templates/release-notes.md) — both artifact skeletons plus the classification cheat-sheet
+1. **Find out what actually shipped.** Read the whole range or list before writing a line.
+   - A change that was reverted later in the same range did not ship. Leave it out.
+   - A later commit can narrow or contradict an earlier one ("partial fix", a figure revised,
+     a date moved). Write the final state, not the first claim.
+   - Where you have a repo and no list, take the range from the last tag to HEAD
+     (`git describe --tags --abbrev=0`, then `git log <tag>..HEAD --no-merges`). Read a commit's
+     body or diff only when its subject is too vague to tell what it does.
+
+2. **Find what breaks or needs action, wherever it is said.** A breaking change is often not
+   marked: a removed option in a PR description, a renamed setting in a commit body, an old
+   endpoint "no longer accepted". Each one goes first, with the step the reader has to take,
+   written for how this audience gets the release. Customers of a hosted service upgrade
+   nothing; they need to know what stops working and what to do instead. A library's users
+   need the version and the migration.
+
+3. **Write only as far as each change was described.** "Fixed a bug in exports" stays that
+   vague if that's all the input says. Don't add a symptom, a cause, a number, a date, a
+   version, a PR number or a count the input doesn't give. A change you can't tell the meaning
+   of stays out of the notes and goes in the short list in step 6.
+
+4. **Write for this reader, in this format.** Use the channel, length and tone the user asked
+   for: a customer changelog page, an email, a pop-up of a few lines, store text with a
+   character limit, or the repo's own CHANGELOG style if there is one. Say what the reader can
+   now do or no longer suffers ✅ *"Exports with more than 10,000 rows no longer fail"*, not
+   what the code does ❌ *"fix NPE in ReportExporter.flush()"*. Use the product name only if
+   you were given it.
+
+5. **Leave internal work out of anything a customer reads.** CI, refactors, tests, dependency
+   bumps, typo fixes and tooling are not news, not even as "various improvements". In an
+   internal changelog they may appear if the repo's existing style includes them.
+
+6. **Hand back the notes, then at most a few lines for the user.** The notes are clean: no
+   commit range, commit count, hashes, "flagged by" notes, or review lists inside them unless
+   the user's format asks for hashes (an internal CHANGELOG often does). After the notes, list
+   once, briefly, what you left out and why: changes too vague to describe, claims the log
+   contradicts, anything the user should confirm before publishing.
+
+7. **Deliver from what you have.** With a log, a list or notes, write the notes and state any
+   assumption about audience or format in one line. Ask first only when there is nothing to
+   work from.
 
 ## Quality bar
 
-- **Breaking changes are first, with an action.** Every breaking entry has "Action required: …" a reader can execute. No action identifiable → it goes to Needs review, not to the top section unverified.
-- **No commit-speak in customer notes.** Class names, function names, internal service names, and ticket IDs are all signals the line wasn't rewritten.
-- **Every internal-changelog line ends in a short hash** (and PR number when available). A claim nobody can trace is a claim nobody can verify.
-- **Internal noise stays internal.** Dependency bumps, refactors, CI, and test-only changes never appear in customer notes — not even as "various improvements".
-- **Nothing is guessed.** A vague commit ("fix stuff", "wip") lands in Needs review with its hash; the skill never invents a user-facing meaning for it.
-- **The range is stated.** Refs, commit count, and date span at the top — so a reader knows exactly what window the notes cover.
+- **Nothing in the notes goes beyond the input.** No invented feature, behaviour, symptom,
+  figure, date, version, PR number or count.
+- **Reverted and superseded changes don't appear;** the final state does.
+- **Breaking changes and required actions come first,** found from the text as well as the
+  markers, with an action that fits how the audience gets the release.
+- **Internal noise is absent from customer text.**
+- **The format, length and tone are the ones the user asked for,** and the notes carry no
+  working notes.
+- **Vague items are left out or kept vague, and named once to the user.**
 
 ## When to use this skill
 
 - ✅ Cutting a release and writing "what's new" for users or customers
-- ✅ Maintaining `CHANGELOG.md` between versions
-- ✅ A deploy/release announcement for internal stakeholders
-- ✅ "Summarize everything merged since the last tag"
+- ✅ A `CHANGELOG.md` entry between versions
+- ✅ A deploy or release announcement for internal stakeholders
+- ✅ "Summarise everything merged since the last tag"
 
 ## When NOT to use this skill
 
 - ❌ A single PR description — that's one change; use `pr-description-writer`
 - ❌ Reviewing the changes for quality or risk — that's `devils-advocate` / `sonar-review`
-- ❌ Stakeholder narrative about *why* the release matters strategically — feed the notes to `exec-summary`
-- ❌ Generating commit messages going forward — this skill reads history, it doesn't write it
+- ❌ A narrative about *why* the release matters strategically — feed the notes to `exec-summary`
+- ❌ Writing commit messages going forward — this skill reads history, it doesn't write it
 
 ## Anti-patterns to avoid
 
-- ❌ **Transcribing commit subjects with bullets in front.** That's `git log` with extra steps — the rewrite into reader language is the entire job.
-- ❌ **"Various bug fixes and improvements."** Either the fix is worth a line or it's internal; the vague catch-all is neither.
-- ❌ **Burying a breaking change** in the middle of "Changed" because the commit didn't shout about it. The detection signals exist precisely for quiet breaks.
-- ❌ **Padding a thin release.** Two real changes get two lines. Inflating with internal noise to look substantial erodes trust in every future release note.
-- ❌ **Marketing adjectives.** "Blazing-fast", "completely redesigned", "supercharged" — state the measurable change ("export is ~3× faster on large reports") or state nothing.
-- ❌ **Silently skipping unparseable commits.** They go to Needs review; the count of skipped commits is part of the output.
+- ❌ **Finishing a vague change.** "Looked at the search thing" becomes "search is faster".
+  Keep it as vague as it was, or leave it out and say so.
+- ❌ **Announcing reverted work.** A commit in the range is not a change that shipped.
+- ❌ **Burying a quiet break.** No `!:` marker doesn't mean nothing broke; read the bodies.
+- ❌ **"Various bug fixes and improvements."** Either a fix is worth a line or it's internal.
+- ❌ **The working notes in the text.** Ranges, counts, hashes, "flagged by", a "Needs review"
+  table in a customer email.
+- ❌ **A changelog where an email was asked for.** Headings and bullets in a two-paragraph
+  member update.
+- ❌ **Marketing adjectives.** "Blazing-fast", "completely redesigned": state the measured
+  change the input gives, or nothing.

package/packs/dev-team/skills/release-notes/evals/evals.json

@@ -5,12 +5,12 @@
       "id": 1,
       "prompt": "Write release notes for v2.4.0 from this log (range v2.3.0..HEAD, 2026-08-12 to 2026-09-28):\n\na1b2c3d|feat: bulk CSV import for contacts (#412)\ne4f5a6b|fix: NPE in ReportExporter.flush() when >10k rows (#418)\nc7d8e9f|feat!: remove legacy /v1/contacts endpoint (#420)\n0a1b2c3|chore(deps): bump lodash 4.17.20 -> 4.17.21\n4d5e6f7|refactor: extract ExportService\n8a9b0c1|fix stuff\n2d3e4f5|perf: cache tenant settings, report export ~3x faster (#425)",
       "assertions": [
-        "States the range, commit count (7), and date span at the top",
-        "The removal of /v1/contacts is hoisted to the top of both artifacts with an 'Action required' line and names the !: marker that flagged it",
+        "Delivers the notes from the log without stopping to ask who they are for, stating any assumption about the audience in a line",
+        "The removal of /v1/contacts comes first, with the step API users must take",
         "Customer notes contain no commit-speak — no ReportExporter.flush(), class names, ticket numbers, or author names",
-        "The lodash bump and the ExportService refactor appear only in the internal changelog, never in customer notes, not even as 'various improvements'",
-        "Every internal changelog line ends with its short hash, plus PR number where present",
-        "The vague 'fix stuff' commit (8a9b0c1) goes in the Needs review list with its hash, not guessed into customer notes",
+        "The lodash bump and the ExportService refactor do not appear in customer-facing notes, not even as 'various improvements'",
+        "The notes carry no working notes: no commit range, commit count, hashes or review lists in customer-facing text",
+        "The vague 'fix stuff' commit is not given an invented meaning in the notes, and is named to the user outside them",
         "No marketing adjectives; the performance line states the measured change (~3x faster export) rather than 'blazing fast'",
         "Does not invent features or fixes not present in the log"
       ]
@@ -72,6 +72,34 @@
         "It does not invent crash counts, percentages, a release date for Android, or features that are not in the list",
         "The store text itself is short: about 100 words or fewer per store"
       ]
+    },
+    {
+      "id": 6,
+      "held_out": "2026-10-17",
+      "prompt": "Our next Quillmoor release goes out tomorrow. Quillmoor is our invoicing app for freelancers and small studios, and some of our customers use our API. The git log since the last release is in `git-log.txt`. Write the customer-facing release notes for our public changelog page: Markdown, 200 words max. I want them ready to paste.",
+      "assertions": [
+        "The webhook payload change (`amount` now an integer in minor units, `client_name` renamed to `client.display_name`) is in the notes and comes before every other change, worded so a customer with a webhook integration can tell they must update their handler",
+        "The Swiss QR-bill feature is not presented as part of the release, since it was reverted in the same range",
+        "No internal-only work appears in the notes: no CI changes, dependency bumps, test fixtures, the auth/session refactor, feature-flag removal, release checklist, or typo fixes in comments or CONTRIBUTING",
+        "The 'misc fixes from Henrike's QA pass' and 'sync stuff' commits are either left out or mentioned no more specifically than general small fixes; no particular behaviour, such as a sync feature, is attributed to them",
+        "Does not invent anything absent from the log or request: no version number, release date, PR or ticket number, count of changes, or figure such as how much faster the invoice list is",
+        "Covers at least six of these seven customer-visible changes: duplicating an invoice, receipt photos from a phone's browser, the client-portal ZIP download, no more reminders for invoices marked paid offline, the VAT rounding fix, the due date column in CSV export, and the faster invoice list",
+        "The pasteable notes are 200 words or fewer and in Markdown, are delivered without first stopping to ask questions, and contain no working notes about what was left out or why"
+      ]
+    },
+    {
+      "id": 7,
+      "held_out": "2026-10-17",
+      "prompt": "I run the Bramblegate Tool Library, it's a volunteer thing where members borrow tools through our little app. My nephew does the app and he did a bunch of stuff this month. From memory:\n\n- you can reserve tools a week ahead now instead of 3 days? I think a week\n- the login code by text message, he fixed that, people were complaining it didn't arrive\n- something about late fees, he changed how they work, I need to check with him but basically you get a reminder before it's late now\n- everyone has to re-accept the borrowing agreement next time they log in because the committee updated it\n- new photos on the tool pages\n- also a lot of backend stuff I don't understand\n\nCan you write the text for the \"What's new\" pop-up members see when they open the app? It's a small box, so 75 words max.",
+      "assertions": [
+        "Re-accepting the updated borrowing agreement at next log-in comes first in the pop-up text and is stated as something the member will have to do",
+        "Does not invent details: no late-fee amounts, no number of days before the due date that the reminder arrives, no reservation window other than a week, no cause for the login problem, no date, and no change that is not in the notes",
+        "The late-fee item goes only as far as described, a reminder before an item is late, and does not claim fees were raised, lowered or removed",
+        "The 'backend stuff' is not in the pop-up text, and nothing specific is claimed about it",
+        "Mentions reserving further ahead, the fixed text-message login code, and the new tool photos",
+        "The pop-up text is 75 words or fewer and in plain language for library members, with no developer jargon such as 'backend', 'OTP' or 'SMS verification flow'",
+        "Delivers the pop-up text without first stopping to ask for confirmation; any suggestion to check details with the developer sits outside the pop-up text"
+      ]
     }
   ]
 }

package/packs/dev-team/skills/release-notes/evals/files/6/git-log.txt

@@ -0,0 +1,136 @@
+commit 0d1f6b8
+Author: Jun Okafor
+
+    chore(release): scaffold release checklist
+
+commit a4c91e0
+Author: Odile Brandt
+
+    chore(ci): cache node_modules between workflow runs
+
+commit 7d2b33f
+Author: Tomasz Wereszka
+
+    Revert "feat(invoices): Swiss QR-bill block on PDF invoices"
+
+    This reverts commit 3e8f10b. The bank validator rejects our reference
+    field. Pulling it until we can test against real QR scanners.
+
+commit e01f5c9
+Author: Marisol Quintero
+
+    fix(reminders): stop sending payment reminders for invoices marked paid offline
+
+    Invoices marked "paid by bank transfer" by hand were still getting the
+    automatic reminder email sent to the client.
+
+commit 5bb7a20
+Author: Tomasz Wereszka
+
+    misc fixes from Henrike's QA pass
+
+commit c33d9e4
+Author: Jun Okafor
+
+    chore(deps): bump pdfkit from 0.13.0 to 0.15.1
+
+commit 2f6a811
+Author: Marisol Quintero
+
+    feat(expenses): attach receipt photos to expenses from your phone's browser
+
+    Camera upload on mobile web. JPG, PNG and HEIC, up to 10 MB each.
+
+commit 88e0b4c
+Author: Jun Okafor
+
+    refactor(webhooks): normalise payload serializer
+
+    Moves all webhook payloads onto the shared serializer. Side effect:
+    `amount` on invoice.created and invoice.paid is now an integer in minor
+    units (cents) instead of a decimal string, to match the REST API, and
+    `client_name` is renamed to `client.display_name`. Anyone parsing our
+    webhooks has to update their handler. There is no compatibility flag.
+
+commit 41d7f02
+Author: Tomasz Wereszka
+
+    test: add fixtures for multi-currency invoices
+
+commit 3e8f10b
+Author: Tomasz Wereszka
+
+    feat(invoices): Swiss QR-bill block on PDF invoices
+
+    Adds the QR payment slip to the bottom of PDF invoices for clients
+    with a Swiss address.
+
+commit b9a2e6c
+Author: Odile Brandt
+
+    sync stuff
+
+commit 6c1d8a5
+Author: Marisol Quintero
+
+    feat(invoices): duplicate an invoice from the invoice menu
+
+    Copies line items, client and tax settings. The new invoice gets the
+    next invoice number and today's date.
+
+commit d57e3b1
+Author: Jun Okafor
+
+    perf(dashboard): faster invoice list for accounts with lots of invoices
+
+    Paginate server-side instead of fetching every invoice up front.
+
+commit 0ae4f9c
+Author: Odile Brandt
+
+    docs: fix typo in CONTRIBUTING
+
+commit f62c0d8
+Author: Marisol Quintero
+
+    fix(tax): VAT total off by a cent on long invoices
+
+    Totals on invoices with many line items could be off by 0.01 because
+    we rounded each line instead of the total.
+
+commit 19b7e44
+Author: Jun Okafor
+
+    chore: remove unused feature flag new_sidebar_v1
+
+commit ab30c6e
+Author: Tomasz Wereszka
+
+    fix(export): CSV export now includes the due date column
+
+commit 7e5d1f2
+Author: Odile Brandt
+
+    ci: run e2e suite on Node 22
+
+commit 2c94b8d
+Author: Jun Okafor
+
+    refactor(auth): extract session middleware
+
+commit 95f0a3c
+Author: Marisol Quintero
+
+    feat(portal): clients can download all their paid invoices as one ZIP
+
+    New "Download all" button on the client portal's invoice page.
+
+commit 4b6e7d9
+Author: Odile Brandt
+
+    chore(deps-dev): bump eslint to 9.12
+
+commit e8c2a05
+Author: Tomasz Wereszka
+
+    chore: fix typos in code comments

package/packs/dev-team/skills/release-notes/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "release-notes",
-  "version": "0.1.2",
-  "description": "Turn git history between two refs into release notes — a customer-facing version written in reader benefits and an internal Keep-a-Changelog version with commit traceability, breaking changes always first. Use when the user wants release notes, a changelog, \"what's in this release\", a deploy announcement, or to summarize changes since the last tag.",
+  "version": "0.2.0",
+  "description": "Write release notes from a git log, a list of merged PRs or rough notes about what changed — for the audience and in the format the user names (a customer changelog page, an email, an in-app \"what's new\", store text, a CHANGELOG.md entry). Says nothing the input doesn't, writes a vague change only as far as it was described, puts breaking changes and anything the reader must do first, and keeps internal noise and working notes out of the text. Use when the user wants release notes, a changelog entry, \"what's in this release\", a deploy announcement, or to summarise changes since the last tag.",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["devils-advocate", "exec-summary", "pr-description-writer", "sonar-review"],
   "tags": ["release-notes", "changelog", "git", "release", "deploy", "communication"],
-  "model": { "tier": "standard", "rationale": "Classifies commits and rewrites them for a reader. The audience translation needs judgment; escalate via large-input on very long ranges." }
+  "model": { "tier": "standard", "rationale": "Reads a range for what really shipped and rewrites it for one reader. The audience translation needs judgment; escalate via large-input on very long ranges." }
 }

package/packs/sre-oncall/pack.json

@@ -45,7 +45,7 @@
       {
         "skill": "postmortem-generator",
         "you_do": "Paste the incident thread, pager timeline and notes once it is over.",
-        "you_get": "A blameless postmortem with quantified impact, a UTC timeline showing detection and mitigation gaps, contributing factors, up to eight action items, and runbook deltas phrased as edits.",
+        "you_get": "A blameless postmortem at the length you ask for: the cause as the change and the missing check, never a person; who or what noticed first and how late; checkable follow-ups; and the runbook edits the incident showed were needed.",
         "decide": "Gate G4, a human call: PROCEED closes it, PROCEED WITH CONDITIONS closes it with named follow-ups, REVISE sends the deltas back to the runbook."
       },
       {

package/packs/sre-oncall/skills/postmortem-generator/SKILL.md

@@ -1,74 +1,99 @@
 ---
 name: postmortem-generator
-description: Generate a blameless incident postmortem from raw material (Slack thread, pager timeline, notes) — quantified impact, UTC timeline with detection/mitigation gaps, contributing factors instead of a single root cause, and ≤8 verifiable action items. Use after an incident or outage when the user needs a postmortem, RCA, incident review, or "lessons learned" doc.
+description: Write a blameless incident postmortem from the raw material (chat scrollback, alert history, timeline, notes) for the audience and length the user names — the cause stated as the change and the gap that let it through, never a person even when the notes name one; who or what noticed first and how late; known kept apart from still-unknown; and follow-up actions that close the gap. Invents no times, figures, owners or severities. Use after an incident or outage when the user needs a postmortem, RCA, incident review, a plain explanation for a non-technical reader, or "lessons learned" doc.
 ---
 
 # postmortem-generator
 
-Turns the debris of an incident — Slack scrollback, pager entries, half-remembered timestamps — into a postmortem the next on-caller learns from. Blameless is structural here, not a tone: the doc names systems and gaps, never people and mistakes. The operate-phase counterpart to `runbook-generator`, which consumes this skill's runbook-delta output.
+**The rule: name the change and the missing check, never the person.** Incident notes are
+written in the heat of it: "Dana's deploy broke it", "Sam forgot the flag". The agent's habit
+is to carry that framing straight into the document, and a postmortem that names someone as
+the cause teaches everyone to hide the next mistake. The cause is always a condition: what
+made the error easy to make, hard to catch and quick to spread. People appear only doing
+response work, by role ("the on-call engineer rolled back at 14:32"), and that holds even when
+the user's own message points at someone.
 
-## How to respond
-
-**Four rules come before the steps and outrank them:**
-
-- **Answer what was asked, first.** Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
-- **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
-- **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
-- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
-- **For this skill:** With no timeline, logs or notes to work from, ask for them in two sentences and name the three things you most need. Don't describe your working directory or your template.
-
-1. **Ingest the raw material.** Slack threads, pager/alert timelines, deploy logs, prose recollections — all valid. Ask at most 2 questions, and spend them on impact quantification ("how many users / requests / minutes?") — it's the data people forget fastest and the section read first. Everything else unknown gets a visible `[missing]` tag, never a vague sentence papering over it.
-
-2. **Strip blame structurally while drafting.** People appear only as roles performing response actions ("on-call engineer rolled back at 14:32"). Errors are attributed to the system that allowed them. ✅ *"A malformed config value passed review and deploy; no validation step checks this field"* — ❌ *"Dave pushed a bad config"*. If the source material is finger-pointy, translate it; the postmortem is the cleaned record.
-
-3. **Build the timeline in UTC** with one row per event (timestamp, what happened, source). Then compute and state the two gaps that matter:
-   - **Detection gap** — impact start → first human aware. If users noticed before monitoring did, say so in those words.
-   - **Mitigation gap** — detection → impact ended.
-   The timeline ends at "impact over", not "everyone went to bed"; cleanup goes under follow-ups.
+A second rule sits beside it: **say plainly who or what noticed first, and how late.** If a
+customer, a support ticket or a member of staff found the problem before any alert did, that
+is the most useful sentence in the document: ✅ *"Two teachers reported the gradebook down 40
+minutes before any alert fired."* Don't write "alerting worked" when it didn't.
 
-4. **Write contributing factors, not a root cause.** Minimum 2, typically 3–5, using "why was that possible?" chains. **"Human error" is banned as a factor** — it is always the start of a question, never the answer: what made the error easy to make, hard to catch, and fast to propagate? Each factor states the condition, not the act.
-
-5. **Force the three honesty lists**: what went well (so it gets repeated), what went poorly (response-side, not cause-side), and **where we got lucky** — the near-misses that would have made this worse. The lucky list is mandatory; an incident with no luck involved hasn't been examined closely.
-
-6. **Cap action items at 8**, each with: owner (role, not name), class (**prevent** recurrence / **detect** faster / **mitigate** faster), and a verifiable done-condition. ✅ *"Config deploys reject values failing schema validation — verified by a test deploy of a malformed value"* — ❌ *"Improve config safety"*. If the analysis surfaces 15 candidates, pick the 8 with the best leverage and list the rest as "considered, not taken" with one line each on why.
-
-7. **End with runbook deltas** — the specific sections of the service runbook this incident proves wrong or missing, phrased as edits ready for `runbook-generator` or a human to apply.
-
-8. **Emit with [`templates/postmortem.md`](templates/postmortem.md)** in one message, summary first: severity, duration, quantified impact, and the one-sentence cause a director can repeat.
-
-## Useful references in this skill
+## How to respond
 
-- [`templates/postmortem.md`](templates/postmortem.md) — the full doc skeleton with the gap calculations and action-item table
+1. **Fit the audience and length they asked for.** "Half a page for the board", "a note for
+   customers", "two pages max", "the full incident review": that is the format. A
+   short version is what happened, why it was possible, how it was found, and what changes.
+   The full form in [`templates/postmortem.md`](templates/postmortem.md) is for when they ask
+   for a full review or an incident-review meeting doc.
+
+2. **Build the timeline from the material.** Use the events that changed what users saw:
+   impact starts, first noticed, mitigation, impact ends. Use the timezone the material uses
+   unless asked otherwise, and state it. Compute the gaps that matter (start to noticed,
+   noticed to fixed) only from times you have.
+
+3. **Keep what is known apart from what is still being investigated.** Write the cause the
+   evidence supports, and name anything not yet confirmed as open.
+
+4. **Write the causes as conditions, more than one where the material shows more than one.**
+   For each: the condition, and why it made the incident possible or worse. ✅ *"A config value
+   passed review and deploy; nothing validates that field."* ❌ *"Human error"*, ❌ *"should
+   have been more careful"*. Don't invent extra causes to make up a number.
+
+5. **Follow-ups that close the gap.** Each action says what changes and how anyone could tell
+   it's done: ✅ *"Config deploys reject values that fail the schema, checked by a test deploy
+   of a bad value."* ❌ *"Improve config safety."* Give an owner or date only if the material
+   gives one; otherwise write "no owner yet". A few strong actions beat a long list.
+
+6. **Runbook changes, when the incident proved a procedure wrong or missing.** Phrase each as
+   a concrete edit to the runbook section it affects, ready for someone to apply. Leave them
+   out of a short version for a non-technical audience unless asked.
+
+7. **Say only what the material supports.** No affected-customer count, revenue or SLA-credit
+   figure, severity level, owner or time that isn't in it, even when a stakeholder asked for
+   one. Where a number was asked for and the material can't give it, say what it does show
+   ("12 customers have written in so far") and what would settle it. Never leave
+   `[missing]` or blank fields in the document; list what is still unknown once, briefly,
+   after it.
+
+8. **Deliver from what you have.** With notes to work from, write it and state any assumption
+   in one line. With nothing to work from, ask in two sentences for the timeline, how it was
+   noticed, and what was done.
 
 ## Quality bar
 
-- **Impact is numbers or `[missing]`.** Duration, users/requests affected, SLO burn, revenue if known. "Significant impact" is not a measurement.
-- **No person is named in a causal sentence.** Roles appear in response actions only. One named-blame sentence fails the doc.
-- **Detection and mitigation gaps are computed and stated.** They are the two numbers the next incident will be judged against.
-- **At least 2 contributing factors, zero of them "human error".** A single root cause means the chain of "why was that possible?" stopped one question early.
-- **Every action item is verifiable and owned.** A reader can check it's done without asking anyone's opinion; an item without a done-condition is a wish.
-- **"Where we got lucky" is non-empty.** Naming the near-miss is how it gets fixed before it's the next incident's headline.
+- **No person is named as a cause.** Roles appear in response actions only, including when
+  the user's notes name someone.
+- **Who or what noticed first is stated,** with the gap to the first alert when the material
+  gives both times.
+- **Known and still-open are kept apart.**
+- **Causes are conditions, not "human error",** and come only from the material.
+- **Every action is checkable,** and has an owner only if the material named one.
+- **Nothing is invented:** no figures, times, severities, owners or counts beyond the input.
+- **The length and format are the ones asked for,** and the document has no placeholders.
 
 ## When to use this skill
 
-- ✅ After an incident/outage, turning the response scrollback into the postmortem doc
+- ✅ After an incident or outage, turning the response scrollback into the postmortem
 - ✅ "Write the RCA for yesterday's outage"
+- ✅ A short explanation of what went wrong for a non-technical reader
 - ✅ Preparing the incident-review meeting doc
-- ✅ Retroactively documenting an old incident before the details evaporate
 
 ## When NOT to use this skill
 
-- ❌ During the incident — mitigate first; the postmortem starts when impact ends
-- ❌ A performance-management record — the doc is structurally blameless; misusing it kills honest reporting
-- ❌ Project retrospectives with no production incident — different ritual, different doc
-- ❌ Writing the runbook itself — emit the deltas and hand to `runbook-generator`
+- ❌ During the incident — mitigate first; live updates to stakeholders are `incident-comms`
+- ❌ A performance-management record — the document is blameless by design; using it to blame kills honest reporting
+- ❌ A project retrospective with no production incident
+- ❌ Writing the runbook itself — hand the runbook changes to `runbook-generator`
 
 ## Anti-patterns to avoid
 
-- ❌ **Single root cause.** "The config was wrong" explains nothing about review, validation, deploy gates, or blast radius — the four places to actually fix.
-- ❌ **"Human error" / "should have been more careful".** Careful is not a control. Name the missing guardrail instead.
-- ❌ **The 20-item action list.** It signals diligence and delivers nothing; nobody finishes it and the P1s drown.
-- ❌ **Timeline theater.** Forty rows of who-said-what-in-Slack instead of the ten events that changed system state.
-- ❌ **Quiet heroics as a fix.** "An engineer noticed by luck at 2am" is a detection gap wearing a cape — the action item is monitoring, not gratitude.
-- ❌ **Skipping the postmortem because impact was "minor".** Near-misses are the cheapest lessons; severity gates the meeting, not the doc.
-- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
+- ❌ **Copying the blame from the notes.** "The outage was caused by X's change" — rewrite as
+  the change and the missing check.
+- ❌ **"Alerting worked" when a customer found it first.** The detection gap is the finding.
+- ❌ **Filling the template.** Severity rows, SLO burn, "where we got lucky" and owner columns
+  on a half-page note for a head teacher.
+- ❌ **Placeholders in a document meant to ship.** `Severity: [missing]` goes nowhere; list
+  unknowns after the document.
+- ❌ **Invented owners, dates and numbers** to make actions look tracked or impact look
+  measured.
+- ❌ **The 20-item action list.** Nobody finishes it and the important ones drown.

package/packs/sre-oncall/skills/postmortem-generator/evals/evals.json

@@ -72,6 +72,33 @@
         "It says the problem was noticed through helpdesk calls about 15 minutes after the change went live, and does not invent a monitoring alert or page",
         "At least one follow-up action addresses checking a DNS change right after it is made, lowering the TTL before a change, or avoiding changes around registration, written so someone can tell whether it was done"
       ]
+    },
+    {
+      "id": 6,
+      "held_out": "2026-10-17",
+      "prompt": "I was incident lead for INC-0412 at Quillmere (we make invoicing software for small businesses). Everything I have is in timeline.md (my notes), incident-channel.txt (the chat export) and alerts.csv. Write the incident review for the leadership team's Monday meeting. They are not engineers, so plain English, and keep it under 450 words. Ade has asked for the exact number of customers affected and the £ value of the stuck invoices to be in it, so please include those. Save it as incident-review.md.",
+      "assertions": [
+        "No named person (Tomasz or anyone else) is described as the cause of the incident or as at fault; the cause is put in terms of the configuration change and the checks that did not catch it",
+        "It says the problem was first noticed by customers through support tickets (from about 14:31), before any alert fired at 14:58, and does not describe the incident as detected by monitoring",
+        "It does not state 15:35 as the time service was restored without qualification; it uses the deploy and monitoring record (rollback finished 15:47, processing back to normal around 15:52) or says the sources disagree",
+        "The database failover is not presented as a cause (it may appear only as an early theory that was ruled out); the drop in workers from the configuration change is given as the established trigger, and the open questions (whether dead-lettered payment updates were lost, how many already-paid clients got an overdue reminder) are labelled as still being investigated rather than stated as settled",
+        "It does not state a number of affected customers or a pound figure for stuck invoices, and does not invent any other time, figure, owner or incident severity level absent from the material; it tells leadership those numbers are not yet known rather than estimating them",
+        "Follow-up actions address the gaps the material shows: a check on consumer configuration values before or during deploy, and an alert on payment processing delay that would fire before customers notice; each is concrete enough that someone could later tell whether it was done",
+        "incident-review.md exists, is under 450 words, reads in plain language for a non-engineering leadership audience, and the reply delivers it without stopping to ask questions first"
+      ]
+    },
+    {
+      "id": 7,
+      "held_out": "2026-10-17",
+      "prompt": "ugh ok. run a small online yarn shop (Wrenmoor Yarn Co, me + 2 staff). checkout on the site was broken over the weekend. last order came in sat about 9am, then nothing. didnt notice till a customer messaged us on instagram sunday around 11 saying she couldnt pay. think it was the shipping plugin, it auto updated friday night maybe? rolled it back sun afternoon and orders started coming through again. jamie says she clicked update on something friday but not sure what. probably lost a few orders. need a short email to jamie and priya explaining what happened and what we do now so it doesnt happen again. keep it short",
+      "assertions": [
+        "It does not blame Jamie or anyone else for the outage; if the update she clicked is mentioned, it is framed as how updates are handled in the shop, not as her fault",
+        "It says plainly that the problem was found because a customer messaged on Instagram on Sunday around 11, not by any check or alert",
+        "It keeps what is known (checkout stopped working some time after the last order around 9am Saturday; rolling back the shipping plugin brought orders back) apart from what is not (which update caused it and when, exactly when checkout broke, how many orders were missed)",
+        "It does not invent a start or fix time, a number of lost orders, a money figure, or plugin details that are not in the message",
+        "Follow-up actions are small enough for a three-person shop and address at least two of the gaps: how plugin updates happen (for example turning off automatic updates, or updating only when someone can test), checking checkout works after any update, and some way to notice when orders stop coming in",
+        "It is a short email to the two staff, under about 250 words, in plain language without technical jargon, delivered without asking for more information first"
+      ]
     }
   ]
 }

package/packs/sre-oncall/skills/postmortem-generator/evals/files/6/alerts.csv

@@ -0,0 +1,4 @@
+time_utc,alert,level,state,notes
+14:58,webhook-consumer queue depth > 50000,warning,firing,
+15:01,webhook-consumer queue depth > 50000,page,firing,paged on-call (Jonas)
+15:52,webhook-consumer queue depth > 50000,page,resolved,

package/packs/sre-oncall/skills/postmortem-generator/evals/files/6/incident-channel.txt

@@ -0,0 +1,27 @@
+Chat export, Thursday 8 October (times UTC)
+
+==== #support-escalations ====
+[14:31] Marta (Support): heads up, ticket 88213. Customer says their client paid an invoice by card about 20 min ago and it still shows "awaiting payment" in Quillmere. Anyone seen this?
+[14:44] Marta (Support): two more like it now (88219, 88224). Feels like a pattern?
+[14:52] Jonas (Eng): looking
+
+==== #deploys ====
+[14:07] deploybot: webhook-consumer deploy #4471 finished (config: consumer pool tuning), author tomasz, reviewer jonas
+
+==== #inc-0412 ====
+[15:02] Rhiannon: declaring incident. paid invoices not flipping to paid. queue depth alert firing on webhook-consumer.
+[15:06] Jonas: it's the DB failover from this morning, 100%. replica lag is making the status writes fail. seen this exact thing before.
+[15:09] Ade (VP Customer Success): how many customers are affected? I need an exact number and the £ value of the stuck invoices for the board update
+[15:12] Rhiannon: @Ade not known yet, we'll get you what we can
+[15:14] Jonas: hmm, replica lag is flat, under 1s all afternoon, and the status writes that do arrive are succeeding. so not the db. I was guessing, sorry
+[15:19] Kasia: consumer throughput dropped off a cliff at ~14:07. only 4 workers running, normally 40. deploy #4471 changed pool_size from 40 to 4
+[15:25] Rhiannon: ok that's it. rolling back #4471
+[15:31] deploybot: webhook-consumer rollback to #4470 started
+[15:47] deploybot: webhook-consumer rollback to #4470 finished
+[15:52] Kasia: throughput back to normal, 40 workers. backlog draining
+[15:58] Kasia: some Paygrove webhooks went to the dead-letter queue while the backlog was building (their retries timed out). don't know yet whether those payment updates were lost or will be replayed. looking.
+[16:03] Marta (Support): also the 15:00 payment reminder job ran, so some clients who'd already paid probably got a "your invoice is overdue" email. no idea how many yet
+[16:20] Kasia: backlog cleared
+[16:24] Jonas: open q for the review: the PR was reviewed (by me) and passed CI, but nothing in CI checks consumer config values. also we only alert on queue depth and the threshold is high, nothing on how long a payment takes to be processed
+[16:30] Ade (VP Customer Success): still need that customer number and £ figure please, even rough
+[16:41] Rhiannon: DLQ question still open, Kasia on it tomorrow. reminder count also open. closing incident as mitigated.

package/packs/sre-oncall/skills/postmortem-generator/evals/files/6/timeline.md

@@ -0,0 +1,21 @@
+# INC-0412: paid invoices not marked as paid
+
+Incident lead notes (Rhiannon). All times UTC, Thursday 8 October.
+
+- 14:07 config change to webhook-consumer goes out (Tomasz's PR "tune consumer pool")
+- 14:58 monitoring picked it up, queue depth alert
+- 15:02 I declared the incident, opened #inc-0412
+- 15:06 DB failover from this morning suspected
+- 15:19 Kasia spots worker count dropped
+- 15:25 decision to roll back #4471
+- 15:35 rollback complete, service restored
+- 16:20 backlog cleared
+- 16:41 closed as mitigated
+
+Detection: monitoring (queue depth alert).
+
+Root cause: Tomasz fat-fingered the pool size (40 -> 4) and pushed it to prod without testing. He broke it. Need to have a word with him about care with prod config.
+
+Impact: invoices paid by card or bank transfer through Paygrove stayed "awaiting payment" in Quillmere until the backlog drained. Some customers' clients may have been sent overdue reminders.
+
+TODO for the write-up: Ade wants customer count and £ figure.

package/packs/sre-oncall/skills/postmortem-generator/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "postmortem-generator",
-  "version": "0.1.2",
-  "description": "Generate a blameless incident postmortem from raw material (Slack thread, pager timeline, notes) — quantified impact, UTC timeline with detection/mitigation gaps, contributing factors instead of a single root cause, and ≤8 verifiable action items. Use after an incident or outage when the user needs a postmortem, RCA, incident review, or \"lessons learned\" doc.",
+  "version": "0.2.0",
+  "description": "Write a blameless incident postmortem from the raw material (chat scrollback, alert history, timeline, notes) for the audience and length the user names — the cause stated as the change and the gap that let it through, never a person even when the notes name one; who or what noticed first and how late; known kept apart from still-unknown; and follow-up actions that close the gap. Invents no times, figures, owners or severities. Use after an incident or outage when the user needs a postmortem, RCA, incident review, a plain explanation for a non-technical reader, or \"lessons learned\" doc.",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
-  "related": ["runbook-generator"],
+  "related": ["incident-comms", "runbook-generator"],
   "handoff": [
     { "to": "runbook-generator", "when": "the postmortem produced runbook deltas", "purpose": "Apply the deltas as edits to the existing runbook.", "fallback": "If runbook-generator is absent, phrase each delta as a concrete before/after edit so a human can apply it." }
   ],

package/packs/sre-oncall/skills/postmortem-generator/templates/postmortem.md

@@ -1,67 +1,53 @@
-# Postmortem template
+# Full incident review
 
-Summary first — it's the only section most readers finish. All timestamps UTC. Unknowns get `[missing]`, never prose camouflage.
+For when the user asks for a full postmortem or an incident-review meeting doc. Leave out any
+section the material has nothing for; never fill one with a placeholder. List what is still
+unknown after the document, not inside it.
 
 ```markdown
-# Postmortem: {one-line incident title, symptom-first — "Checkout 500s for EU users", not "Config issue"}
+# Incident review: {symptom-first title — "Checkout failures for EU customers", not "Config issue"}
 
-**Status:** draft | reviewed | actions-tracked
-**Severity:** SEV{1–4} · **Date:** {YYYY-MM-DD} · **Author role:** {e.g. incident commander}
+{Date} · {who it is for, if the user said}
 
 ## Summary
 
-{3–5 sentences a director can repeat: what broke for whom, for how long, why in one
-clause, and the headline fix. No jargon that needs the timeline to decode.}
+{3–5 sentences someone can repeat: what broke for whom, for how long, why in one clause,
+how it was found, and the main change being made.}
 
 ## Impact
 
-| Measure | Value |
-|---|---|
-| Duration (impact start → end) | {Xh Ym} |
-| Users / customers affected | {number or %, or [missing]} |
-| Requests failed / degraded | {number, or [missing]} |
-| SLO / error budget burn | {e.g. "34% of monthly budget", or [missing]} |
-| Revenue / contractual | {value, "none known", or [missing]} |
+{What users could not do, for how long, and any figures the material gives. If a figure was
+asked for and the material can't give it, say what it does show and what would settle it.}
 
-## Timeline (UTC)
+## Timeline ({timezone})
 
-| Time | Event | Source |
+| Time | What happened | Source |
 |---|---|---|
-| {hh:mm} | {impact begins — state change, not Slack chatter} | {alert/log/deploy} |
-| {hh:mm} | {first human aware} | {page/user report} |
-| {hh:mm} | {mitigation applied} | … |
+| {hh:mm} | {impact begins} | {alert / log / deploy / ticket} |
+| {hh:mm} | {first noticed, and by whom or what} | … |
+| {hh:mm} | {mitigation} | … |
 | {hh:mm} | {impact ends} | … |
 
-**Detection gap:** {impact start → first human aware} — {if users reported it before
-monitoring fired, say exactly that}
-**Mitigation gap:** {detection → impact end}
+**Found by:** {who or what noticed first; the gap to the first alert}
+**Time to fix:** {noticed → impact ended}
 
-## Contributing factors (2+; "human error" is not one)
+## Why it was possible
 
-1. **{Condition, not act}** — {why this made the incident possible/worse; the guardrail
-   that was absent or didn't fire}
-2. **{…}** — {…}
+1. **{Condition, not act}** — {why it made the incident possible or worse}
+2. {…only as many as the material shows}
 
-## What went well / poorly / where we got lucky
+**Still open:** {causes not yet confirmed}
 
-**Well:** {response behaviors worth repeating}
-**Poorly:** {response-side gaps — paging, comms, tooling — not the cause itself}
-**Lucky:** {mandatory — the near-miss: "happened at 3am low traffic", "the one engineer
-who knew X was awake", "rollback happened to be safe"}
+## What went well and what didn't
 
-## Action items (≤8)
+{Response-side only: paging, comms, tooling. Add "where we got lucky" if the material shows
+a near-miss.}
 
-| # | Action | Class | Owner (role) | Done when |
-|---|---|---|---|---|
-| 1 | {specific change} | prevent / detect / mitigate | {team or role} | {verifiable condition} |
+## Follow-ups
 
-**Considered, not taken:** {candidate} — {one line why not}
+- {What changes} — done when {how anyone could check}. Owner: {as given, or "no owner yet"}
 
-## Runbook deltas
+## Runbook changes
 
-- {Runbook section} → {the edit this incident proves necessary — paste-ready}
-
-## Open questions
-
-- {anything still [missing] that follow-up should resolve, with who can answer it}
+- {Runbook section} → {the edit this incident shows is needed}
 ```

package/packs/dev-team/skills/release-notes/templates/release-notes.md

@@ -1,83 +0,0 @@
-# Release-notes templates
-
-Two artifacts, two readers. Customer notes sell nothing and explain everything; the internal changelog trades polish for traceability.
-
-## Artifact 1 — customer-facing release notes
-
-> Note the deliberate rename for a non-technical reader: the Keep-a-Changelog categories **Added → New** and **Changed → Improved** here; Fixed/Security keep their names. The internal changelog (Artifact 2) uses the canonical Keep-a-Changelog headings.
-
-```markdown
-# {Product} {version} — {YYYY-MM-DD}
-
-> Covers {ref}..{ref} · {N} changes
-
-## ⚠ Breaking changes
-
-- **{What broke, in reader terms.}**
-  Action required: {the exact step — config to change, endpoint to migrate, deadline}.
-  (flagged by: {signal — `!:` marker / removed API / migration file})
-
-## New
-
-- {What the reader can now do. One sentence, benefit first.}
-
-## Improved
-
-- {What got better, measurably where possible: "export is ~3× faster on reports over 10k rows".}
-
-## Fixed
-
-- {The symptom the reader no longer suffers: "Fixed a crash when …", "Dates no longer shift by one day when …".}
-
-## Security
-
-- {Reader-relevant statement; severity and affected versions; no exploit detail.}
-```
-
-Rules: no class/function/service names, no ticket IDs, no author names, no "various improvements". A section with nothing in it is deleted, not left empty — except Breaking changes, which when empty becomes the single line "No breaking changes."
-
-## Artifact 2 — internal changelog (Keep a Changelog)
-
-```markdown
-## [{version}] - {YYYY-MM-DD}
-
-Range: `{ref}..{ref}` · {N} commits · {N} PRs
-
-### Added
-- {change} ({#PR}, `{hash}`)
-
-### Changed
-- **BREAKING:** {change + migration step} ({#PR}, `{hash}`)
-- {change} ({#PR}, `{hash}`)
-
-### Fixed
-- {change} ({#PR}, `{hash}`)
-
-### Deprecated / Removed / Security
-- {change} ({#PR}, `{hash}`)
-
-### Internal
-- {refactor / CI / deps / tests — one line each} (`{hash}`)
-```
-
-## Needs review (always emitted, both modes)
-
-```markdown
-## Needs review — {N} commits not classified
-
-| Hash | Subject | Why unclear |
-|---|---|---|
-| `{hash}` | {verbatim subject} | {vague / contradicts diff / can't tell if user-visible} |
-```
-
-## Classification cheat-sheet
-
-| Signal | Bucket |
-|---|---|
-| New endpoint, flag default-on, new UI surface | Added |
-| Behavior or default changed for existing users | Changed (BREAKING if old behavior unobtainable) |
-| `fix:`, bug ticket, regression revert | Fixed |
-| `chore:`, `refactor:`, `test:`, `ci:`, deps, lockfiles | Internal |
-| CVE, auth/authz, input validation, secrets | Security |
-| `feat!:`, `BREAKING CHANGE:`, removed public API, schema migration, major version bump of a public SDK | Breaking — hoist to top |
-| "wip", "fix stuff", "address comments", empty body + vague subject | Needs review |