skilldrop-cli 0.16.13 → 0.16.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.13",
+  "version": "0.16.15",
   "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/research/pack.json

@@ -38,7 +38,7 @@
       {
         "skill": "source-synthesis",
         "you_do": "Hand it the sources you collected, as text, with the plan's question.",
-        "you_get": "Findings with every claim cited to a source and page, agreement and disagreement made explicit, a strength rating per finding, the gaps, and a citation check report."
+        "you_get": "What the sources support on the question, each claim traceable to its source, with disagreements and echoes made explicit, the sources' own sums checked, labelled estimates where a figure is needed, and the gaps. Ask for a cited literature review to get page-level citations and strength ratings."
       },
       {
         "skill": "hypothesis-comparison",
@@ -47,6 +47,6 @@
         "decide": "Act on the leading explanation, or run the next observation first."
       }
     ],
-    "you_end_with": "A decision-led plan, a cited synthesis you can check line by line, and, for why-questions, a ranked set of explanations with the next test to run."
+    "you_end_with": "A decision-led plan, a synthesis that keeps what the sources say apart from everything else, and, for why-questions, a ranked set of explanations with the next test to run."
   }
 }

package/packs/research/skills/source-synthesis/SKILL.md

@@ -1,115 +1,112 @@
 ---
 name: source-synthesis
-description: Synthesise a set of supplied sources — papers, articles, reports, interview transcripts — into findings where every claim is cited to a source and a location ([S1:p4]), agreement and disagreement across sources are explicit, each finding carries an evidence-strength rating with the criteria used, and the gaps and what the sources do not say are listed. Never adds outside facts unless tagged as such, and ships a citation checker. Use when the user hands over several sources and asks to "synthesise these", "what do these papers say", "literature review", "pull the findings together", or "where do the sources agree and disagree".
+description: Answer a question from a set of sources the user supplied — papers, reports, articles, interview notes, emails — saying only what the material supports, labelling anything that comes from elsewhere where it appears, counting a source that repeats another once, and giving a labelled estimate when the user needs a figure the sources don't settle. Written in the length and format the user asked for; a full cited literature review only when that is the ask. Use when the user hands over several sources and asks to "synthesise these", "what do these papers say", "pull together what we know", "literature review", or "where do the sources agree and disagree".
 ---
 
 # source-synthesis
 
-You turn a pile of sources the user supplied into findings they can rely on and check. Every
-claim points to a source and a place in it, so a reader can verify it in under a minute.
-Where sources agree, you say how many and which; where they disagree, you show both sides and
-why they might differ. You add nothing from your own knowledge unless it is tagged
-`[outside]`. The synthesis is only as good as its sources, so each finding says how strong its
-evidence is and on what criteria.
+**The rule: say only what the material supports, and mark everything else where it appears.**
+The user handed over sources because they want to know what *those* say. A plausible fact from
+memory, a rule you happen to know about, a price range that sounds right: each one
+reads exactly like a finding, and the user can't tell it apart. The agent's habit is to fill
+gaps helpfully. This skill's job is to keep the line between "the sources say" and "I'm adding"
+visible in every sentence.
 
-What to research and where to look comes first, from `research-plan`. If the findings point to
-several rival explanations, rank them with `hypothesis-comparison`. To turn messy material into
-a brief for another skill rather than findings, use `brief-intake`.
+Two things follow from the rule:
+
+- **A source that repeats another is one source.** An article quoting a survey's figure, an
+  email forwarding a report, three people retelling the same story: trace each figure to where
+  it started and count that origin once. Agreement between echoes is not agreement.
+- **Hearsay and half-memories are reported as what they are.** "A neighbour said it was about half
+  price" is something someone said, not a data point, and an undated clipping is undated.
 
 ## 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:** The reply itself carries the answer: the recommendation, the numbers behind it and the caveats. Saved files are extra. Don't report that your own checks passed.
-
-1. **Ask once for what's missing.** You need the **sources** themselves (text, files or
-   excerpts, not titles) and the **question** the synthesis answers. If the user has a
-   research plan, take the question and sub-questions from it. Ask for both in one message.
-   If the user sends only titles or links you can't open, ask for the text. Don't summarise a
-   paper from memory.
-
-2. **Register the sources.** Give each one an id (`S1`, `S2`, …) and one line: author or owner,
-   title, date, type (peer-reviewed study, survey, internal report, news article, interview,
-   opinion piece), and for studies the method and sample size if the source states them. Note
-   how location works in each: page numbers, section numbers, or timestamps for transcripts.
-   Mark sources that aren't independent (two articles reporting the same survey count as one
-   line of evidence).
-
-3. **Extract claims before you synthesise.** For each source, list the claims that bear on the
-   question, each with its location, in the source's own terms. Keep the source's hedges:
-   "associated with" stays "associated with", not "causes". Quote the key sentence when the
-   wording matters.
-
-4. **Group claims into findings, one per sub-question or theme.** For each finding:
-   - **State it in one sentence,** worded no stronger than its weakest supporting source.
-   - **Cite every source that supports it,** with locations: `[S1:p4; S3:§2.1]`.
-   - **Show agreement and disagreement:** "S1, S3 and S4 agree; S2 disagrees", and give the
-     likely reason for the disagreement when the sources show one (different population,
-     period, definition or method). Don't average conflicting results into a middle answer.
-   - **Rate the evidence strength** (strong / moderate / limited / conflicting) and say which
-     criteria drove it: independent sources, source type, method, sample size, recency,
-     directness. Criteria are in [`reference.md`](reference.md).
-
-5. **List the gaps and what the sources don't say.** Sub-questions no source answers;
-   populations, periods or regions no source covers; claims everyone repeats but nobody tests;
-   and the question the user is likely to ask next that these sources can't answer. Write
-   these as statements: ✅ *"None of the sources measures effects beyond 12 months."*
-
-6. **Tag anything from outside.** If context the sources don't give is genuinely needed (a
-   definition, a well-known date), add it with `[outside]` so the reader knows to check it.
-   Keep it rare. Never use `[outside]` to fill a gap in the findings; list the gap instead.
-
-7. **Write it up with [`templates/synthesis.md`](templates/synthesis.md):** the question, the
-   source register, the bottom line in three sentences or fewer, findings with citations and
-   strength, the agreement and disagreement table, gaps, what the sources do not say, and the
-   `[outside]` list.
-
-8. **Check every citation.** Save the draft and run:
-
-   ```bash
-   # Claude Code
-   python3 "${CLAUDE_SKILL_DIR}/scripts/citations.py" synthesis.md -o citation-check.md
-   # Other IDEs (from the skill folder)
-   python3 scripts/citations.py synthesis.md -o citation-check.md
-   ```
-
-   It reads the `## Sources` section of the draft (or a separate file with `--sources`), and
-   reports citations that don't resolve, malformed citations, paragraphs and table rows with no
-   citation, citations with no location, sources never cited, and every `[outside]` claim. Fix
-   every error, and either fix or explain each warning. A source never cited is a question:
-   did it say nothing relevant, or did you miss it? Say which in the source register.
-
-**Non-interactive runs** (subagent, CI, headless): with no source text, emit
-`BLOCKED: need the sources' text, not titles or links`. A missing question becomes
-`[assumption] The question is: …`, inferred from the sources and stated at the top.
-
-## Useful references in this skill
-
-- [`reference.md`](reference.md) — citation format, evidence-strength criteria, how to handle disagreement, independence, and common distortions
-- [`templates/synthesis.md`](templates/synthesis.md) — the synthesis skeleton
-- [`scripts/citations.py`](scripts/citations.py) — checks that every citation resolves and every claim is cited (stdlib only)
-- [`examples/four-day-week.md`](examples/four-day-week.md) — worked example: four sources on a four-day-week pilot, the synthesis, and the checker's real output on a first draft and the fixed draft
+1. **Answer the question first, in the user's terms.** The opening lines say what the material
+   supports on the question they asked, organised around the decision in front of them (the
+   options on the table, the yes/no, the number they need). Not source by source.
+
+2. **Fit the size and format they asked for.** "Half a page", "a few bullets for the meeting",
+   "two pages for the board pack", a chat answer: that is the format. Name sources in plain
+   words where a claim comes from them ("the pilot report", "the team lead's interview",
+   "the manager survey"), so a reader can check it. Use bracketed citations with locations, a source
+   register or strength ratings only when the user asked for a literature review or an
+   evidence summary with citations (see **A cited literature review** below).
+
+3. **Check the sources before you trust them.**
+   - Add up every total, percentage and per-unit figure a source gives from its own parts, and
+     say plainly when one doesn't match ("the report says 60 staff took part; its team table adds
+     to 54").
+   - Where sources disagree on a number, show both, and give the reason they might differ when
+     the sources show one: a different population, period, size or definition. Say which one
+     fits the user's situation better and why. Don't average them.
+   - Keep each source's hedges. "Associated with" stays "associated with"; "about a third"
+     stays approximate, and a change that happened alongside another change is not put down to
+     either one.
+
+4. **When they need a figure the sources don't settle, estimate it and label it.** A cost, a
+   break-even point, a likely uptake: work it out from what the sources give, show the
+   sum, and give the range the uncertain inputs produce. If an input has to come from outside
+   the material, write it into the sentence as yours ("assuming 21 working days a month,
+   which none of the sources gives"), never as a finding. End with the one or
+   two facts that would settle it. "The sources can't say" on its own is not an answer.
+
+5. **Say what the material doesn't cover, once, briefly.** The gaps that matter for the
+   decision, as plain statements at the end: ✅ *"None of the sources measures effects beyond
+   six months."* Not a list of everything a perfect study
+   would have measured.
+
+6. **Deliver from what you have.** If you have the sources' text and the question, write the
+   answer, stating in one line any assumption about what they want. Ask first only when there
+   is nothing to work from: titles or links you can't open, or no sources at all. Then ask for
+   the text in one or two plain sentences. Don't summarise a paper from its title or from
+   memory.
+
+7. **Keep the machinery out of the reply.** No skill names, no paths or scripts, no "checks
+   passed", no notes about how the run was set up. The reply carries the answer. A file is
+   saved only when the user asked for one, and it is the answer itself, nothing beside it.
+
+## A cited literature review
+
+When the user asks for a literature review, an evidence summary with citations, or findings
+"every claim cited", produce the full form: a source register, findings grouped by theme with
+`[S1:p4]` citations to a location, agreement and disagreement named source by source, an
+evidence-strength rating with its criteria, and the gaps. Citation format, strength criteria
+and how to handle disagreement are in [`reference.md`](reference.md); the skeleton is
+[`templates/synthesis.md`](templates/synthesis.md); a worked example is
+[`examples/four-day-week.md`](examples/four-day-week.md).
+
+Before you hand it over, run the citation checker on the saved draft and fix what it reports:
+
+```bash
+# Claude Code
+python3 "${CLAUDE_SKILL_DIR}/scripts/citations.py" synthesis.md
+# Other IDEs (from the skill folder)
+python3 scripts/citations.py synthesis.md
+```
+
+It reports citations that don't resolve, claims with no citation, citations with no location
+and sources never cited. It is your check, not part of the deliverable: don't save its report
+for the user or mention that it passed.
 
 ## Quality bar
 
-- **Every claim is cited to a source and a location.** The checker reports no errors; any warning left is explained.
-- **Nothing comes from outside the sources** unless it is tagged `[outside]`, and gaps are never filled from memory.
-- **Agreement and disagreement are explicit,** with the sources named on each side and a likely reason for the split where the sources show one.
-- **Each finding has a strength rating and the criteria behind it.** A finding from one survey never reads like one from three independent studies.
-- **Findings are no stronger than their sources.** Hedges survive; correlation stays correlation.
-- **Gaps and what the sources do not say are listed** as specific statements.
-- **Sources that aren't independent are counted once.**
+- **Nothing reads as coming from the sources that doesn't.** Every outside input is marked as
+  outside in the sentence where it appears; no gap is filled from memory.
+- **Echoes are counted once.** A figure repeated by a second source is traced to its origin.
+- **The sources' own sums are checked,** and any that don't add up are named.
+- **The answer opens the reply and fits the requested size and format.**
+- **A needed figure gets a worked, labelled estimate** with its range and what would settle it,
+  not a refusal.
+- **Findings are no stronger than their sources.** Hedges, approximations and confounds
+  survive; hearsay stays hearsay.
 
 ## When to use this skill
 
+- ✅ "Here's everything I've collected — what do we actually know?"
 - ✅ "Synthesise these six papers / reports / articles on X"
-- ✅ Turning a set of interview transcripts into cited themes
+- ✅ Turning interview notes or transcripts into what they show, with the disagreements kept
 - ✅ A literature review or evidence summary for a decision
-- ✅ Checking where a set of analyst reports agree and where they don't
 
 ## When NOT to use this skill
 
@@ -122,10 +119,16 @@ a brief for another skill rather than findings, use `brief-intake`.
 
 ## Anti-patterns to avoid
 
-- ❌ **Source-by-source summaries.** "S1 says…, S2 says…" is an annotated list, not a synthesis. Organise by finding.
-- ❌ **A citation with no location.** `[S2]` on a 60-page report can't be checked.
-- ❌ **Smoothing over conflict.** "Results were mixed" hides which sources disagree and why.
+- ❌ **The helpful outside fact.** A regulation's threshold, a typical salary, an industry
+  norm, written as if a source said it. Label it in the sentence, or leave it out.
+- ❌ **Counting echoes.** "Two sources agree on 63%" when the second one is quoting the first.
+- ❌ **Stopping at "the sources can't say".** The user asked a practical question; show the
+  sum with labelled assumptions and what would settle it.
+- ❌ **A research report for a meeting note.** Source registers, strength tables and
+  bracketed citations on a request for five bullets.
+- ❌ **Source-by-source summaries.** "S1 says…, S2 says…" is a list, not an answer. Organise by
+  the decision.
+- ❌ **Taking a source's total on trust.** Add it up.
 - ❌ **Promoting hedges.** "May be associated with" becomes "drives" by the second paragraph.
-- ❌ **Counting echoes.** Three news stories about one study are one source.
-- ❌ **Filling gaps from memory.** A plausible fact with no source is the error this skill exists to prevent.
-- ❌ **Citing a title you haven't read.** If you only have the abstract, say so in the register and rate accordingly.
+- ❌ **Machinery in the reply.** "Citations all pass", file names of working drafts, the
+  skill's own vocabulary.

package/packs/research/skills/source-synthesis/evals/evals.json

@@ -74,6 +74,34 @@
         "It gives the up-front gap as about £10,100 (£14,200 against about £4,100)",
         "It does not add energy prices, grant scheme rules or typical heat pump costs from outside the notes, unless clearly labelled as not coming from the notes"
       ]
+    },
+    {
+      "id": 6,
+      "held_out": "2026-10-17",
+      "prompt": "I'm the practice manager at Brackenmoor Veterinary Practice. We have three vets. The partners decide on Thursday whether to start opening on Saturday mornings, and they've asked me one question: would a Saturday morning clinic cover its own staffing cost in its first year? I've put five things in this folder: client-survey-summary.md, wcapa-benchmarking-extract.md, practice-ledger-article.md, fenwick-lane-call-notes.txt and finance-email.txt. Go by what these say. The partners want a straight answer and a number they can argue about, not a literature review, so keep it to one page at most. I'm in theatre all day and can't answer questions, so just write it up.",
+      "assertions": [
+        "It answers the question directly: on the evidence in the files, a Saturday clinic probably would not cover its staffing cost across the first year, because the 14-a-session benchmark clears the break-even but the closer comparison (Fenwick Lane, 4 vets) ran at 8 to 9 a session for six months and only reached about 12 by month ten",
+        "It works out a break-even of roughly 11 to 12 appointments a session from the finance email (£640 to £680 a session divided by £58 contribution per appointment), or an equivalent comparison of contribution against cost",
+        "It treats the Practice Ledger's 14-a-session figure as a repeat of the WCAPA report, not as a second source confirming it",
+        "It points out that the WCAPA figure and Fenwick Lane's figures disagree and gives a reason to weigh them differently, such as the WCAPA practices being larger (median 7 vets, with larger practices reporting higher numbers) than Brackenmoor",
+        "It flags that the finance email's £680 a session does not match its own line items, which add up to £640, rather than silently using one of the two",
+        "Any first-year figure the files do not give directly is labelled as an estimate, and it says what would settle the question, such as finding out whether Saturday bookings would be new visits or moved from weekdays, which neither the survey nor Fenwick Lane measured",
+        "It does not invent figures that are not in the files, such as a share of Saturday visits moved from weekdays, a ratio of survey intent to actual bookings, or Saturday pay rates, and it fits on about one page without stopping to ask questions"
+      ]
+    },
+    {
+      "id": 7,
+      "held_out": "2026-10-17",
+      "prompt": "I'm secretary of the Hollins Green Amateur Dramatic Society, which is a fancy name for twenty-odd of us who put on a panto every January. The committee wants to know if we should move it from St Aldric's church hall to the primary school hall, because someone thinks we'd sell more tickets. I'm not a numbers person and this is all I've got, scribbled down:\n\n1. Bev from the Oakhurst Players told me at the summer fete they moved to their school hall and \"sold out every night\". I think she said 180 seats? Might have been 150.\n\n2. A clipping from the Linden Vale Gazette, no date on it, Mum cut it out ages ago: \"Linden Vale Players' panto raises £2,300 for hall roof fund ... an audience of nearly 600 across four nights.\"\n\n3. Chatted to Mr Pruett, the school caretaker. He said the hall seats 220 \"with the stage in\" but the fire officer's limit might be lower, he wasn't sure. Hire is £45 an hour. Or was it £45 a session? I didn't write it down properly.\n\n4. Our own panto last January at St Aldric's: three nights, roughly 110 a night I think, tickets £8. I'm fairly sure we turned people away on the Saturday.\n\nCould you give me a few bullet points I can read out at Tuesday's committee meeting? Five or six at most, please, nothing long.",
+      "assertions": [
+        "It does not give a firm yes: it says the notes cannot show whether moving would sell more tickets, and that the best evidence for extra demand is the society's own report of turning people away on the Saturday",
+        "It names the things to check before deciding, including the school hall's actual permitted capacity (220 or the possibly lower fire limit) and whether the £45 is per hour or per session",
+        "It treats Bev's \"sold out every night\" and the 150-or-180 seat figure as second-hand and uncertain, not as established fact",
+        "It does not use the undated Linden Vale clipping as evidence that moving venue raises sales, since the clipping says nothing about a venue change or when it happened",
+        "Any figure it gives for extra tickets, takings or hire cost is clearly labelled as a rough estimate and, for hire cost, shows that it depends on whether the £45 is per hour or per session",
+        "It does not invent facts that are not in the notes, such as fire regulations, typical panto audiences, or details about the Oakhurst or Linden Vale groups beyond what is written",
+        "It stays within six bullet points, short enough to read out, and delivers them without stopping to ask questions first"
+      ]
     }
   ]
 }

package/packs/research/skills/source-synthesis/evals/files/6/client-survey-summary.md

@@ -0,0 +1,15 @@
+# Brackenmoor Veterinary Practice: client survey on opening hours
+
+Run by reception, March 2026. Emailed to 2,950 active clients; 412 replied (14%).
+
+**Question: "If we offered appointments on Saturday mornings (9am to 1pm), would you use them?"**
+
+| Answer | Share of replies |
+|---|---|
+| Definitely | 38% |
+| Probably | 27% |
+| Unlikely or no | 35% |
+
+Free-text comments mostly mentioned work hours ("I can never get there before 6") and vaccination boosters.
+
+Note from reception: we did not ask whether people would use a Saturday slot instead of a weekday visit or as well as one, or how often they would come. The survey went to clients with an email address on file, so older clients are probably under-represented.

package/packs/research/skills/source-synthesis/evals/files/6/fenwick-lane-call-notes.txt

@@ -0,0 +1,10 @@
+Call with Tom Ashdown, practice manager, Fenwick Lane Vets (4 vets, edge of town, about 20 min from us)
+My notes, 9 Oct 2026
+
+- They started Saturday mornings 9-1 about eleven months ago.
+- First six months were slow: "eight or nine appointments a session, some weeks fewer".
+- Picked up after that. By month ten they were at about twelve a session. Now month eleven, similar.
+- Staffing cost per Saturday about £740. That includes paying a locum vet at a premium, because their own vets would not cover weekends at first.
+- He thinks it will pay for itself in year two but "not this year, honestly".
+- Most Saturday bookings are vaccinations and minor stuff, not surgery.
+- He said he hasn't looked at whether Saturday clients are new or people who'd have come in on a weekday anyway.

package/packs/research/skills/source-synthesis/evals/files/6/finance-email.txt

@@ -0,0 +1,21 @@
+From: Dana Whitcombe (Finance Lead, Brackenmoor Veterinary Practice)
+To: Practice Manager
+Subject: Re: Saturday numbers
+Date: 13 Oct 2026
+
+Hi,
+
+Quick numbers for the Saturday question.
+
+Average contribution per appointment, after drugs and consumables, comes out at £58 on last year's figures. That's across all appointment types.
+
+Saturday staffing at our own rates, if we cover it ourselves with no locum:
+- Vet: £360
+- Nurse: £170
+- Receptionist: £110
+
+So £680 a session.
+
+Call it 50 Saturdays a year once you take out the bank holiday weekends.
+
+Dana

package/packs/research/skills/source-synthesis/evals/files/6/practice-ledger-article.md

@@ -0,0 +1,13 @@
+# The Practice Ledger, May 2026
+
+## Is it time to open on Saturdays?
+
+*By our staff writer*
+
+Clients' working lives have changed, and more practices are asking whether a Saturday morning clinic would pay its way.
+
+Practices that open on Saturday mornings see an average of 14 appointments per session in their first year, according to the WCAPA 2025 Benchmarking Report. That is encouraging news for any practice weighing up the move.
+
+Saturday opening is quickly becoming something clients expect rather than a bonus, and practices that hold back risk losing younger pet owners to competitors who open at weekends.
+
+For practices thinking about it, the advice is to start with a trial and to talk to the team early about rotas.

package/packs/research/skills/source-synthesis/evals/files/6/wcapa-benchmarking-extract.md

@@ -0,0 +1,12 @@
+# Westbourne Companion Animal Practice Association (WCAPA)
+## Benchmarking Report 2025, extract: Section 4, Extended hours
+
+Sample: 41 member practices that returned the extended-hours questionnaire. Median practice size 7 full-time-equivalent vets (range 3 to 16).
+
+Of these, 17 practices introduced Saturday morning opening between 2022 and 2024.
+
+Practices that open on Saturday mornings see an average of 14 appointments per session in their first year. The range across practices was 6 to 23 appointments per session. Larger practices and those in town centres reported the higher figures.
+
+Average staffing cost per Saturday morning session, as reported by practices: £610.
+
+Figures are self-reported by practices and have not been audited.

package/packs/research/skills/source-synthesis/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "source-synthesis",
-  "version": "0.1.1",
-  "description": "Synthesise a set of supplied sources — papers, articles, reports, interview transcripts — into findings where every claim is cited to a source and a location ([S1:p4]), agreement and disagreement across sources are explicit, each finding carries an evidence-strength rating with the criteria used, and the gaps and what the sources do not say are listed. Never adds outside facts unless tagged as such, and ships a citation checker. Use when the user hands over several sources and asks to \"synthesise these\", \"what do these papers say\", \"literature review\", \"pull the findings together\", or \"where do the sources agree and disagree\".",
+  "version": "0.2.0",
+  "description": "Answer a question from a set of sources the user supplied — papers, reports, articles, interview notes, emails — saying only what the material supports, labelling anything that comes from elsewhere where it appears, counting a source that repeats another once, and giving a labelled estimate when the user needs a figure the sources don't settle. Written in the length and format the user asked for; a full cited literature review only when that is the ask. Use when the user hands over several sources and asks to \"synthesise these\", \"what do these papers say\", \"pull together what we know\", \"literature review\", or \"where do the sources agree and disagree\".",
   "entrypoint": "SKILL.md",
   "deps": {
     "npm": [],
@@ -37,6 +37,6 @@
   "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "standard",
-    "rationale": "Bounded synthesis over supplied text with a fixed citation format and strength criteria; the citation checker catches the mechanical failures, so mid-tier judgment is enough."
+    "rationale": "Bounded synthesis over supplied text. The hard part is keeping outside knowledge out and checking the sources' own sums, which a mid-tier model does when told to."
   }
 }

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 |