Draft release notes

Produce public release notes for one Tamanu version, as two files kept in step: the markdown at docs/release-notes/vX-YY.md, and a styled HTML rendering at .workhorse/design/designs/vX-YY-release-notes.html.

The audience is project managers and system administrators, not developers. They read these notes to understand what new capabilities their teams gain, what workflows change, what configuration is required, and what to prepare and test before upgrading. Write to that audience throughout: user-facing capabilities and benefits, not implementation detail.

The canonical format is the published v2.44 notes, kept alongside this skill at example-v2-44.md. Read it first — it is the reference for section order, headings, emoji markers, voice, and how much detail each section carries.

If docs/release-notes/vX-YY.md already exists, that version has been written up — deliver the existing notes rather than redrafting them, unless the user asks for a rewrite. Where the markdown exists but the styled version does not, produce the styled version from it.

Input

The user specifies the version (e.g. v2.45, or 2.45). Normalise it to:

• Release branch release/2.45
• Output files docs/release-notes/v2-45.md and .workhorse/design/designs/v2-45-release-notes.html — both filenames hyphenate the version, so the only dot in each is the extension's
• Linear version label — the label for that version (often v2.45.0); confirm the exact label against the Tamanu team's labels rather than assuming. Version labels also drift, so ground the notes in what code shipped rather than assuming Linear is correct.

Ask for the release date if the user hasn't given it. Format it DD-MM-YYYY in the header. If it's genuinely not known yet, leave Released [RELEASE_DATE_PLACEHOLDER].

Sourcing: two places to look

Work included in a version comes from both of these. The repo is the primary source for what shipped and how it behaves; the trackers supply the human framing. Gather from each, then reconcile.

Cards live in both trackers — Linear for older work, Workhorse for recent cycles — so check both. A single version often draws on each.

1. Issue trackers (Linear — the Tamanu team, and Workhorse — the Tamanu workspace)

In Linear, pull issues on the Tamanu team labelled with the version (e.g. v2.45.0). Filter issues directly by the label string; the label-search tool is unreliable for version labels, so read the labels on a returned issue to confirm the exact spelling rather than trusting a label lookup. Filtering to the Tamanu team already excludes DataTrak, Tupaia, and other non-Tamanu product work — they live on separate teams.

In Workhorse, cards carry no version label, so version membership comes from the release branch instead: collect the card codes from the branch's commit history (commit subjects carry them, e.g. feat(web): F3: …) and read each card. Listing cards in a shipped status — Merged to Main, Release: Regression Ready, Complete: Docs Required, Complete — gives a second list to cross-check that against, catching anything whose commits you missed.

Then, in either tracker:

• Only include work that landed. A version label or a spec branch records intent to ship, not the outcome. Drop anything cancelled, still in progress, or bumped to a later release, and confirm against the branch. Never describe work that didn't ship.
• Exclude internal / non-user-facing work. E2E or test changes, build tooling, dependency bumps, internal readmes and developer docs do not belong in public release notes. Judge by whether a project manager or administrator would notice the change; if not, leave it out.
• A card sitting in "Complete: Docs Required" is explicitly flagged as awaiting release-notes coverage — treat that as a strong signal it belongs in the notes.
• Use the card's title, description, and comments for the human-readable framing of a feature — what it is and why it matters to a user.

2. Specs and code that landed in the release branch

Start with the specs that landed in this release: they describe the behaviour as the product intends it, which is how release notes should read. Then follow the same process across the rest of the repo to ground each claim and fill in missing detail, keeping the specs as the primary framing.

Find the spec delta for the version with git:

git fetch origin release/2.45
git fetch origin release/2.44
git diff --name-status origin/release/2.44...origin/release/2.45 -- specs/

Diff from the merge base (three dots), not between the tips. Tamanu keeps servicing older release branches after a newer one is cut, so a two-dot diff reads the previous version's hotfixes as this version's work.

Read each added or modified spec to understand the behaviour, and use git log on a spec path to recover the card and PR that introduced it.

Notes on refs:

• Derive the previous release line from the branch list, don't assume it's X.(YY-1). List what actually exists and take the highest release branch below the target, so a skipped or unshipped minor can't send you to a branch that was never released:

  git branch -r --list 'origin/release/2.*' --sort=version:refname
  

  Confirm the line shipped by checking it has tags (git tag --list 'v2.44.*'). Compare against that branch so the delta is exactly this version's work, not an accumulation. State which refs you used.

• If release/2.45 hasn't been cut yet, the work is still on main — use origin/release/2.44...origin/main instead, and say so. This is an upper-bound-free view: main may already carry work destined for a later version, so check each spec's introducing commit and drop anything that isn't part of the version being written up.

Reconciling the two sources

The same piece of work often appears in both places — a spec-driven card usually originates from an issue in a tracker. Match them on the card id carried in the spec's introducing commits.

• Committed specs are authoritative. Where both describe the same work, the spec's description of the behaviour drives the write-up. Use the tracker card only for supporting framing (a readable title, the "why") and for version confirmation.
• Tracker-only work (labelled or staged for the version but with no spec that landed) is included once you've confirmed it actually shipped. The card's status is the first check; confirm it against the release branch by looking for its card id in the history, e.g. git log --oneline origin/release/2.45 --grep TAM-6786. If the work isn't in the branch, leave it out — a label alone is not evidence it shipped.
• Never list the same feature twice. One entry per piece of work, even where the same work appears in both trackers.

Structuring the notes

Classify every included item into one of the six sections. Judge by significance and breadth, exactly as the v2.44 example does.

Let the release set the length. Most releases are quiet, and a quiet release gets a short document. The v2.44 example is a big release and is long because it had that much in it; it sets the shape, not a target size. Never promote smaller work to fill a section, pad an overview to match the example's density, or give an item more space than its significance earns. A release whose largest item is one administrative change should say so plainly in the header and run a few hundred words.

1. Header — Released DD-MM-YYYY, then one short paragraph naming the release's marquee items.
2. 🌟 Major Features and Changes — the items that genuinely warrant it, each with a real overview. Anything that gives users a new capability belongs here, up to about five; a quiet release may have only one or two, and that is the honest answer rather than a gap to fill. Judge scope by what shipped, not by how the card describes itself: a card calling its work "a couple of minor tweaks" sometimes lands a full feature, and a card written up as a feature sometimes lands as an extension of an existing screen, which belongs in Enhancements. Group by surface with ## headings, using only the surfaces that have content: Tamanu Desktop, Tamanu Mobile, Patient Portal, System Administration. Each feature is an ### _Italic title_ with an overview paragraph, a Key features bullet list, and a Supporting documentation list. Add Security considerations or a Keen to implement …? call-to-action block only where the feature warrants it (as the example does for the Patient Portal and integrations).
3. 🔧 System Enhancements — improvements that make existing work better without adding a capability, including a capability extended to a second screen. Lighter than a major feature: a sentence or two each, no Key features list unless one genuinely needs it. Group related items and call out any configuration change.
4. 🐛 Tweaks and Bug Fixes — everything else, summarised at a high level. Group by platform (## Desktop, ## Mobile), with a ## System group for backend, sync, and infrastructure fixes that aren't tied to one client. Within a group, one bullet per area (**Bold label** - what improved), rolling that area's fixes into a themed sentence or two. Do not enumerate individual fixes: a reader wants to know which areas got attention, not to read the commit log. Name a specific fix only where a PM would otherwise be surprised by the change.
5. ⚠️ Critical Upgrade Notes — split Required and Optional, per feature. A checklist for a system administrator: what to review, decide, or set up around the upgrade, at two or three bullets per feature. Describe it in plain language and let the linked configuration guide carry both the settings and the procedure. Say what happens if they don't act, where there is a consequence (a changed default, a feature that stays inert).
6. Upgrade Steps and Recommended Testing — split Required and Optional, closing with a General block. Concrete things a PM can test, and only where the upgrade carries real risk (a migration that could land wrong, a step that lengthens the window) or where a feature needs verifying once adopted. Not every change earns a step: a fix that simply works, or a feature nobody has turned on, needs nothing here. A handful of bullets is usually the whole section.

Give Required and Optional the same heading level as each other in both sections — ### Required and ### Optional. The v2.44 example sets Optional in bold rather than as a heading, which renders it inside the Required section; don't carry that across.

Two more things the example does that a new draft should not. It names settings keys and reference-data values literally (appointments.bookingSlots.startTime, isBookable), which no longer belongs in release notes at all — see the plain-language rule under Voice and conventions. It also opens by calling itself "one of our biggest recent releases", which suited that release and suits few others. Take section order, headings, emoji markers and density from the example; take neither of these.

Separate major sections with --- as the example does. Keep the emoji markers (🌟 🔧 🐛 ⚠️) — they are load-bearing.

Supporting documentation links

You cannot generate real Slab URLs. Wherever the format expects a Supporting documentation link, leave a labelled placeholder for a human to fill:

**Supporting documentation**

- Feature overview - [SLAB_LINK_PLACEHOLDER]
- Configuration guide - [SLAB_LINK_PLACEHOLDER]
- User manual - [SLAB_LINK_PLACEHOLDER]

Keep the descriptive label before each placeholder so the person filling them in knows which document goes where.

Include only the documents that version's feature actually has. Three placeholders is the shape of the example, not a quota — a feature with only a configuration guide gets one line.

The styled version

Every version carries a styled HTML rendering at .workhorse/design/designs/vX-YY-release-notes.html, alongside the markdown. It is what gets shared with a customer, pasted into a published page, or read by someone who is not looking at the repo.

• The markdown is the source of truth for wording. The HTML renders it and says nothing the markdown doesn't. When wording changes, change both in the same turn and then grep to confirm no old phrasing survives in either — a change applied to one file only is the failure mode to watch for.
• Start from the most recent existing styled file. Copy the newest .workhorse/design/designs/v*-release-notes.html, replace its content, and leave its CSS alone. This keeps every release looking like the last one and keeps the styling evolving in a single lineage rather than being reinvented per version.
• It belongs in designs/, never in a card's mockups/ folder. Release notes are read well outside the card that drafted them, and mockups/{card-id}/ is card scratch that gets stripped on merge.
• Structure mirrors the markdown: the same sections in the same order, emoji markers retained, feature entries as cards and the grouped fix lists as plain bullet groups. Carry the release date as the only thing above the title, since the version is already in the title.
• Keep the CSS inline so the file stands alone when sent to someone.
• Where no styled file exists yet to copy from, author one against the design system in .workhorse/design/ — and if that library is absent, the house palette: stone-grey page with white surfaces, burnt orange accent, Inter, 4px spacing grid.

Voice and conventions

• PM/admin audience. Explain what a feature does, why it's useful, and how it fits a workflow. Leave out API specifics, database schemas, and internal architecture.

• No coded language, anywhere in the document. No settings keys, reference-data codes, permission identifiers, environment variables, column names, or file paths. Name the thing in plain words instead: "the modification reason list", not the reference-data type's literal name; "permission to dispense medications", not the permission identifier; "invoicing is off by default", not the setting that turns it on. A reader who needs the exact key follows the configuration guide, which is where keys belong.

• Inverted commas around every feature and interface name, spelled and capitalised as it appears on screen: the 'Send to pharmacy' column, the 'Dispense medication' modal, the 'Emergency patients' board, 'Details' and 'Ordered by', 'Discharge qty' becoming 'Dispensing qty'. The test is whether the reader has to find that exact wording on screen to act on the sentence. Buttons, fields, columns being renamed or made required, tabs, modals, views, menu options and note types all pass it.

  Three things stay as ordinary nouns. Product surfaces: Tamanu Desktop, Tamanu Mobile, the admin panel, Patient Portal. Clinical artefacts: an encounter, a prescription, the medication administration record, a price list. Self-evident values and simple labels, where the words explain themselves and quoting them only adds clutter: last 7 days, the clinician column, the sex column, triage category, the Urgent and Deceased categories. When a simple label sits mid-sentence and reads fine unquoted, leave it unquoted.

• Benefits over mechanics. "The system automatically removes conflicting location assignments" — not how it's implemented.

• Australian/NZ English — finalise, colour, organise, centralise, authorised.

• Concise. Match the example's density: a tight overview paragraph, then scannable bullets. No filler.

Workflow

1. Resolve the version to its release branch, output path, and Linear label. Get the release date, or use the placeholder.
2. Read example-v2-44.md for the target shape.
3. Pull the tracker cards for the version — Linear's Tamanu team by version label, and Workhorse's Tamanu workspace by the card codes in the release branch.
4. [parallel with 3] Fetch the release branches and diff specs/ to get the landed specs; read them; ground and deepen using the code changes as required; recover their cards/PRs from git log.
5. Reconcile the two sets on card id — committed specs win on overlap; tracker-only work is kept once confirmed shipped; dedup.
6. Classify each item into the six sections and draft the notes in the canonical format, leaving [SLAB_LINK_PLACEHOLDER] for every supporting-documentation link.
7. Write docs/release-notes/vX-YY.md (create docs/release-notes/ on the first version).
8. Write the styled version to .workhorse/design/designs/vX-YY-release-notes.html, copying the most recent existing one and replacing its content.
9. Tell the user both paths, and list what still needs a human: the Slab links, the release date if placeholdered, and anything you couldn't confidently classify.

Later turns that revise the notes revise both files, and say so.

Source of truth

The committed specs and the Tamanu commit history are authoritative for what shipped; the trackers supply framing. This skill encodes the method, not a fixed answer — the surfaces, sections, and format can evolve. If the repo or a newer published release disagrees with this skill, the repo wins; update the skill and refresh the canonical example.