@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/skills/next/SKILL.md

@@ -1,18 +1,23 @@
 ---
 name: next
-description: "Decide what to do next from a project's real state, or from the current conversation: loose work in the tree, commits since the last tag, unreleased changelog entries, roadmap or plan items still open, and the project's check command. Returns a short ranked list with the evidence for each item and the command that starts it; read-only, it never edits, commits, or begins the work. Use when asked what to do next, where to pick up, what is left, or what to work on now."
+description: "Decide what to do next from the current conversation when it has work in it, or from the project's real state when it is empty: loose work, commits since the last tag, unreleased changelog entries, roadmap or plan items still open, and the project's check command. Returns a short list of suggested next todos in priority order, with the evidence for each and the command that starts it; read-only, it never edits, commits, or begins the work. Use when asked what to do next, where to pick up, what is left, or what to work on now."
 ---
 
-# Decide what to do next
+# Suggest the next todos, by priority
 
-This is a triage, not a work session. The deliverable is a short ranked list with
-evidence; do not edit, commit, tag, or start the top item. The skill is
-model-invoked when a request matches the description; `/skill:next` is the
-explicit fallback. Read the project's own instructions first; where they disagree
-with this skill, the project wins.
+This is a triage, not a work session. The deliverable is a short list of
+suggested next todos in priority order, each with the evidence for it; do not
+edit, commit, tag, or start the first one. The skill is model-invoked when a
+request matches the description; `/skill:next` is the explicit fallback. Read the
+project's own instructions first; where they disagree with this skill, the
+project wins.
 
-Two sibling skills own a narrower question: an audit of *where to refactor* is
-`refactor`, and *what the last tag owes the changelog* is `changelog`. When the
+The conversation decides where the candidates come from (section 3); the request
+decides only what to ask and where to look.
+
+Two sibling skills, where they are installed, own a narrower question: an audit
+of *where to refactor* is `refactor`, and *whether a document still tells the
+truth* — the changelog, the roadmap, the front door — is `project-docs`. When the
 request is already scoped to one of those, name the skill that answers it and
 hand over, instead of returning a generic list.
 
@@ -24,15 +29,12 @@ its list survives the conversation that produced it.
 
 The host appends the text after the command to these instructions as the request.
 It is `<prompt>` in `/skill:next <prompt>`, it comes before any reading, and it
-carries up to three parts:
+carries up to two parts:
 
 ```text
-/skill:next [session] [what you want] [@path ...]
+/skill:next [what you want] [@path ...]
 ```
 
-- **`session`, first word** — session mode (section 3). The rest of the prompt
-  keeps its own meaning: `/skill:next session what is left?` is session mode with
-  a filter, not a filter of `session`.
 - **What you want** — a question, a goal, or a topic: "what is left before
   0.17?", "plan file outline". It chooses what the shortlist is about and keeps
   only the sources that can answer it; say which ones you kept. A named release,
@@ -48,7 +50,9 @@ carries up to three parts:
 - **An imperative** — "fix the failing test" names one piece of work, and the
   prompt is not approval for it. Answer with that item alone — evidence, starting
   command, effort — and ask before starting, instead of producing a list.
-- **No prompt** — triage of the current project.
+- **No prompt** — the source rule in section 3 still decides: an empty
+  conversation is triaged from the project, and one that has done work is read
+  for what it left open.
 - **Anything unreadable** — triage anyway, and say in one clause how you read the
   prompt, so a misreading is visible in the report rather than silently narrowing
   the list.
@@ -66,40 +70,56 @@ With the request read, find:
 - the release path: what a tag, a version bump, or an unreleased entry owes;
 - the VCS, its branch model, and the last tag if there is one.
 
-State the profile in one or two lines. Do not invent a source the project does
-not have; a project with no roadmap is triaged from git and the check alone.
+Do not invent a source the project does not have; a project with no roadmap is
+triaged from version control and the check alone. These profile facts decide
+which evidence rows apply, and section 7's report states them.
+
+## 3. Choose the source
+
+There are two sources, and the conversation picks one:
+
+- **This conversation** — the source once it has done work. Read its own record:
+  the todo list, the goal, the approved plan and its ticked steps, what subagents
+  and jobs returned, the paths it recorded, and the diff it produced. The
+  candidates are the loose ends it left: uncommitted files, an unapproved plan, a
+  check that was never run, a documented behavior that changed without a doc or
+  changelog edit.
+- **The project's real state** — only when the conversation is empty. Read git,
+  the changelog, the roadmap or issues, and the plans directory; the candidates
+  are the project's loose work, broken promises, and unfinished ones.
 
-## 3. Choose the mode
+Empty means the conversation has done no work yet, not that it has no messages:
+there is no todo list, no goal, no approved plan or ticked step, no subagent or
+job result, no path it recorded, and no edit or commit from this session. The
+request itself never counts, or `/skill:next` could never reach the tree.
 
-- **Triage** — what the tree says. Use git, the changelog, the roadmap or issues,
-  and the plans directory. This is the default.
-- **Session** — what this conversation left open. Read the conversation's own
-  record: the todo list, the goal, the approved plan and its ticked steps, what
-  subagents and jobs returned, and the diff this session produced. Then list the
-  loose ends it left: uncommitted files, an unapproved plan, a claim that was
-  never run, a documented behavior that changed without a doc or changelog edit.
-- When both apply, run triage and read the session for context; the tree wins,
-  because it is where the work actually is.
+The tree is evidence in both sources. Verify every candidate against the code
+before recommending it, and read the tree's status, the session's diff, the
+changelog's unreleased section where the project has one, and the last check
+result whichever source chose the candidates. A conversation that ended cleanly
+has an empty list; do not fall back to the tree to fill it.
 
-Mode and scope are independent: session mode still honours a path, and triage
-with a path reads the whole tree's evidence before narrowing. State the mode, the
-scope, and the prompt as read, at the top of the report.
+Scope is independent of the source: a path narrows either one, and a topic keeps
+only the sources that can answer it. State the source, the scope, and the prompt
+as read, at the top of the report.
 
 ## 4. Gather evidence
 
 Read only; nothing in this stage writes. Follow the project's own tool
-discipline, and say what you could not read.
+discipline, and say what you could not read. The commands below are git's — use
+the project's VCS for a project that is not on git — and read the rows its
+profile says exist.
 
 | Source | What it proves |
 |---|---|
 | `git status --short`, `git diff --stat` | Work in flight, and whose it is |
-| `git log --oneline <last-tag>..HEAD` | What has landed unreleased |
+| `git log --oneline <last-tag>..HEAD` | What has landed unreleased, if the project tags |
 | `git worktree list`, `git branch --no-merged` | An isolated tree left behind, a branch never merged |
-| The changelog's `[Unreleased]` | Whether a landed change is recorded, and whether the window is empty |
+| The changelog's unreleased section (`[Unreleased]` under Keep a Changelog) | Whether a landed change is recorded, and whether the window is empty |
 | The roadmap, issue tracker, or `TODO` docs | The project's stated priorities, and which are already done |
-| The plans directory (`.pi/plans` or the project's equivalent) | An approved plan whose steps remain |
+| The plan files the host's plan tool records (`~/.pi/agent/plans/<repo-key>` here) | An approved plan whose steps remain |
 | The todo list, the goal, job and subagent results | What the session promised and did not finish |
-| The check command | Whether the tree is green — cite the last known result, and make running it the item's starting command rather than running it here |
+| The check command | Whether the tree is green — cite the session's last result, and make running it the item's starting command rather than running it here |
 
 A roadmap, a changelog, and a plan all lag the tree. Verify a candidate against
 the code before recommending it, and drop one that is already done.
@@ -116,12 +136,14 @@ cannot point at it, drop it.
 - Prefer the candidate with a fast verification command.
 - Never invent work to fill the list. An empty list is a valid answer.
 
-## 6. Rank by cost of loss
+## 6. Rank by priority
 
-Order by what it would cost to lose, cheapest loss first:
+Priority is what it would cost to lose the work, cheapest loss first, so the
+order is the suggestion: the first item is the one to start, and a later item is
+not an alternative to an earlier one. Order by that cost:
 
 - **Loose work** — a dirty tree, an unapproved plan, a check that has not been
-  run, an unmerged branch, a worktree left behind, a stopped job.
+  run, an unmerged branch, a scratch tree or branch left behind, a stopped job.
 - **A broken promise** — a README, roadmap, or doc claim the code no longer
   meets, a released behavior with no test.
 - **An unfinished promise** — a stated roadmap item, the remaining steps of an
@@ -130,8 +152,8 @@ Order by what it would cost to lose, cheapest loss first:
 - **New reach** — a capability nobody has asked for comes last, and only when the
   three above are empty.
 
-Label each item with the ceremony it needs. The label is not a second ordering:
-cost of loss decides the order, and the label says how much work the item takes.
+Label each item with the ceremony it needs. The label says how much work the item
+takes, not where it ranks: the priority ladder decides the order.
 
 - **Do next** — cheap, safe, and unblocks the rest.
 - **Worth planning** — high value, but it spans files, changes a public surface,
@@ -139,17 +161,20 @@ cost of loss decides the order, and the label says how much work the item takes.
 - **Later** — real, but not now.
 
 Cap the list at three to five items, and let a tier be empty. A roadmap restated
-as ten suggestions is not a triage. Do not invent a numeric score; the reason
-must be readable.
+as ten suggestions is not a triage. Number the items: the number is the priority.
+Do not invent a score beyond that; the reason must be readable.
 
 ## 7. Report
 
-- **State** — one paragraph: the mode, the scope and how the prompt was read,
-  the branch or worktree, what is dirty, what is unreleased, and whether the
-  check passes. Name anything you could not read.
-- **The shortlist** — each item with its label, the action, the evidence at
-  `path:line` or the command output that proves it, the command that starts it,
-  and effort (S/M/L). Link the file the item lives in.
+- **State** — one paragraph: the source and why it was chosen (a conversation
+  with work in it, or an empty one), the scope and how the prompt was read, the
+  branch or tree, what is dirty, what is unreleased, whether the check passes,
+  and the profile facts the list rests on — VCS, check command, and where work
+  is tracked. Name anything you could not read.
+- **The list** — the suggested next todos, numbered in priority order, each with
+  its label, the action, the evidence at `path:line` or the command output that
+  proves it, the command that starts it, and effort (S/M/L). Link the file the
+  item lives in.
 - **Rejected or stale** — one line each, with the reason the roadmap, changelog,
   or plan entry no longer applies.
 - **Next step** — ask which item to start. Do not start it, and do not open with
@@ -174,11 +199,12 @@ When the user picks an item, the audit is over:
 - Nothing worth doing: say so, with what was checked, instead of inventing work.
 - The tree is mid-rebase, mid-merge, mid-bisect, or has a conflict: reconciling it
   is the only next item; nothing else is safe to suggest.
-- The project has no work tracking: say the list is derived from git and the check
-  only, and suggest recording the plan or roadmap the project is missing.
+- The project has no work tracking: say the list is derived from version control
+  and the check only, and suggest recording the plan or roadmap the project is
+  missing.
 - A candidate needs a destructive command (a branch delete, a worktree prune, a
   history rewrite) to start: name it as a decision for the user, not as a step.
 
-The triage is done when the mode is stated, every item has evidence and a
+The triage is done when the source is stated, every item has evidence and a
 starting command, the list is capped, rejected candidates are explained, and no
 file was modified.

package/skills/project-docs/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: project-docs
+description: "Keep a project's documents true to its tree: a read-only audit of the front door, the roadmap, the contributor path, and the changelog against the code and against each other, then one mode per act that writes — record a changelog bullet in the same commit as the change, curate a release section from the project's own rules, delete a shipped roadmap item and renumber, and sync the README front door. Use when a doc claim looks stale, before a release, or when a change lands owing an entry; prioritisation stays with `next` and structure with `refactor`."
+compatibility: "Bun for scripts/state.ts; git for the roadmap and the audit."
+---
+
+# Keep the docs true to the tree
+
+Goal: the documents a reader trusts — the front door, the plan of record, the record
+of what shipped, and the contributor path — so a claim the tree no longer meets is
+found, and each act that needs writing has one owner. This is a procedure, not a
+second policy: the project's instructions and release document win, and where they
+are silent this file says ask.
+
+A bare `/skill:project-docs` reads and reports. Nothing is written until a mode is
+named.
+
+## Pick the mode
+
+| The words after `/skill:project-docs` | Mode | Owns | Writes | Follow |
+|---|---|---|---|---|
+| nothing | audit | every document, read-only | no | [`references/audit.md`](./references/audit.md) |
+| `changelog` | changelog | the unreleased window of the changelog | yes | [`references/changelog.md`](./references/changelog.md) |
+| `release <version>` | release | one version's section and link refs | yes | [`references/release.md`](./references/release.md) |
+| `roadmap` | roadmap | items, ids, and buckets | yes | [`references/roadmap.md`](./references/roadmap.md) |
+| `readme` | readme | the front door and its mirror | yes | [`references/readme.md`](./references/readme.md) |
+| anything else | refuse, and name the five | — | no | — |
+
+Audit is the default because the skill spans four documents: a bare invocation that
+writes would edit a document nobody asked about.
+
+## Start here
+
+Read [`references/discovery.md`](./references/discovery.md) first, in every mode. It
+finds the project's documents, the version's single source, the changelog's local
+conventions, the roadmap's rules, the check command, and the guards by name. State
+that profile in one paragraph before writing anything; it is how a misread is caught
+in a line instead of in a diff.
+
+For the changelog's mechanical half, run the state script, resolved against this
+skill's own directory:
+
+```bash
+bun <skill>/scripts/state.ts <project-root>
+```
+
+It prints the changelog file it found, the last tag and the commits since it, the
+`[Unreleased]` categories with counts and line numbers, the empty and duplicate
+headings, the scope prefixes in use, and the link refs. That is the state; read the
+diffs for judgement, not for counting. When it finds no changelog, no repository, or no
+Bun to run it with, say so and fall back to discovery by hand. The git commands these
+references give are git's; use the project's VCS where it differs.
+
+## Non-negotiables
+
+1. **Discover, don't impose.** The project's document set, category spelling, scope
+   prefix, bullet shape, item ids, bucket caps, and release procedure are the rules.
+   State the profile in one paragraph, and ask when two sources disagree.
+2. **One bullet per user-visible outcome**, in the same commit as the change. A
+   feature and the bug it fixed before release are one bullet; two observable
+   changes are two.
+3. **A shipped item is deleted here, with its reason, never ticked.** A roadmap that
+   keeps what already landed describes a tree that no longer exists.
+4. **One id per thing, across every document.** A README row, a roadmap item, and a
+   changelog entry that name the same feature use the same name. A mismatch is
+   reported, never renamed.
+5. **A judgement is not a finding.** Positioning, priority, dates, non-goals, and
+   contribution policy are the maintainer's: list them and ask.
+6. **One owner per artefact.** The changelog belongs here; what to do next belongs to
+   the `next` skill; structure belongs to `refactor`.
+
+## Modes
+
+- **Audit** — read-only, five faces: the tree against the docs, the docs against each
+  other, the changelog's commit window, the roadmap's own ids and caps, and the front
+  door's examples. Every finding names the mode that fixes it.
+- **Changelog** — one bullet under the project's category for one user-visible
+  outcome, re-reading the file first. It never decides whether something has already
+  shipped.
+- **Release** — only for a version the user named, and only after the project's
+  release document has been read; everything after moving the entries follows it.
+- **Roadmap** — re-derived from the commits since the last tag rather than from the
+  last tag: shipped items deleted, ids renumbered, every citation and link fixed.
+- **Readme** — the front door's catalog rows, counts, examples, and mirror, kept equal
+  to the tree; deep detail stays in the project's own guides.
+
+## Handover
+
+- **A changelog entry, an audit, or a release** is this skill: do not look for
+  another one.
+- **What to do next** is `next`, where it is installed: it triages loose work and
+  broken promises across the project, and its candidates are not a doc audit's findings.
+- **A structural change to the docs or the code** is `refactor`, where it is installed.
+- **Who may contribute, and how** is a decision for the maintainer: ask, and edit
+  nothing until it is answered.
+
+## Report
+
+Open with the profile in one paragraph, then:
+
+- **Stale** — the claim, `path:line`, the evidence in the tree, and the mode that
+  fixes it.
+- **Missing** — a document, a row, an entry, or an item the project's own rules call
+  for and the tree does not have.
+- **Suggested edit** — the diff or the exact replacement, for the mechanical items
+  only, and never applied until the user says so.
+- **Needs a decision** — one line each: the question, and what it changes.
+
+Nothing found is a valid result, and the whole report may be empty. Say what was
+checked and stop; an audit that invents four entries to look thorough is worse than
+one that finds nothing.
+
+## Quality gate
+
+- The project's own check passes, including any guard on the release window, the
+  documentation's parity, or the roadmap's ids.
+- Every edit names the document and the line, and every bullet names a scope in the
+  project's spelling and a user outcome.
+- No judgement is smuggled into a diff, and the changelog entry is in the change's
+  own commit.
+
+## Stop conditions
+
+- The project has only a README, no roadmap, and no changelog: say so. Whether to
+  adopt one is the maintainer's decision, not an edit.
+- The changelog is generated — by `semantic-release`, `changesets`, `git-cliff`, or a
+  step in the release workflow: the entry lands upstream, in the commit message, a
+  changeset fragment, or the generator's config. Never hand-edit the file.
+- Two sources disagree — two changelogs, a version in two places, a roadmap item the
+  changelog contradicts: ask instead of averaging them.
+- The change would reverse a documented non-goal: it is a decision, and the item is
+  listed rather than written.
+- The request is really triage or a refactor: name the sibling skill and stop.

package/skills/project-docs/references/audit.md

@@ -0,0 +1,131 @@
+# Audit
+
+Read-only. The audit answers one question per claim: is this still true, and if not,
+which mode fixes it? It never edits — not even a typo, not even "while we are here".
+If the user asks for the fixes, finish the report first, then enter the mode it names.
+
+Read [`discovery.md`](./discovery.md) first and open the report with the profile. The
+five faces below are a reading order, not a checklist: a face with no evidence
+produces no findings.
+
+## 1. The tree against the docs
+
+The claims a reader acts on: a catalog row, a limit stated in a package README, a
+default in a configuration table, a roadmap item, a non-goal, a "supported format"
+list. For each, find the code that does it — the registration, the branch, the config
+default — and name where it disagrees.
+
+| Where the claim lives | What falsifies it |
+|---|---|
+| A catalog row or feature bullet | The tool, command, flag, or route no longer registers |
+| A limitations section | The gap was closed, or widened, and the text did not move |
+| A configuration default | The loader's default differs from the table |
+| A roadmap item | The tree already does it (see face 4) |
+| A non-goal | The changelog records the thing being shipped anyway |
+
+## 2. The docs against each other
+
+- **Counts** — a number a doc states about the code (modules, tools, extensions,
+  screens) belongs to the tree. A project that derives it in a test has the count; one
+  that does not is a finding, and the fix is a guard, not a number.
+- **Catalog rows** — every row names a thing that exists; every existing thing the
+  catalog claims to cover has a row. Both directions.
+- **Cross-reference ids** — the same feature named in a front-door row, a roadmap item,
+  and a changelog entry. Report a mismatch; never rename one side to match.
+- **The version** — the source of truth, the newest dated changelog heading, the tag,
+  and any badge, badge-adjacent prose, or install instruction that repeats it.
+- **The mirror** — a translated README carries the original's sections, table rows, and
+  links. A row that exists in one and not the other is a finding even when the prose is
+  deliberately translated.
+- **The contributor path** — the commands `CONTRIBUTING.md` tells a newcomer to run,
+  against the manifest's `scripts` and the CI workflow's steps. A command the docs promise
+  and the manifest does not define is the one stale claim a new contributor hits first,
+  and a step CI runs that the docs never mention is the one they skip.
+
+## 3. The changelog's commit window
+
+Run `scripts/state.ts` (see the skill's *Start here*). It gives the file, the last tag,
+the commits since it, the `[Unreleased]` categories, and the scopes in use.
+
+When discovery says a tool generates the file, the window's entries live in that tool's
+input — the changeset queue, the commit-message convention — so audit those, and report
+a missing fragment rather than a missing bullet.
+
+Read every commit it lists: `git show <sha>` for the diff, or the pull request when the
+repository squashes. A subject line is not enough — `fix bug` and `wip` hide
+user-visible changes, and `feat: rewrite the config loader` is often invisible to users.
+For each commit, decide whether a user can observe it, which bullet covers it, whether
+that bullet's scope is right, and whether a reader of the bullet alone would know what
+changed for them.
+
+| Commit | User-visible | Evidence | Existing entry | Action |
+|---|---|---|---|---|
+| `3f19a02` | yes | `src/load.ts:42` now rejects an unknown key | — | add |
+| `b81c4de` | no | test-only | — | leave |
+| `0ad9f12` | yes | retry limit 3 → 5 | `Changed`: "`api`: retries are now bounded" | update: the bullet never names the limit |
+| `77e0a1e` | unclear | touches the public `--json` shape | — | ask |
+
+`Action` is one of **add** (user-visible, no bullet), **update** (a bullet exists and is
+wrong, unscopeable, or too vague to act on), **leave** (covered, internal, or recorded
+under an older release), or **ask** (the outcome depends on intent the diff cannot show).
+
+Report separately:
+
+- Duplicate `##` or `###` headings — some tools render the second as its own section,
+  and a reader sees half the entries.
+- An empty category heading, or a heading a release guard rejects.
+- An `[Unreleased]` section that is missing or empty while the window contains
+  user-visible changes.
+- An entry for something already shipped under a dated heading: the same outcome twice,
+  which reads as a second change.
+- A stale link reference pointing at an older tag than the newest dated heading — where
+  the file uses link references at all. A generated or non-Keep-a-Changelog file may have
+  none, and the state script reports that absence as a missing reference without it being
+  a defect.
+
+## 4. The roadmap's own ids and caps
+
+Re-derive the window before judging an item: `git log --oneline <last-tag>..HEAD` plus
+the changelog's newest dated heading. A roadmap describes the tree, so work that landed
+but has not shipped is already part of what it should describe.
+
+- An item the tree already does is a deletion, with its reason recorded where the item
+  was.
+- An id used twice, skipped in a sequence, or cited from nowhere the file defines.
+- A bucket over the cap the file states; a bucket that keeps growing stops being a
+  priority.
+- A ledger row whose items all closed, or an open item with no ledger row.
+- A relative link or a `path:line` citation that no longer resolves.
+
+## 5. The front door's examples
+
+- The quickstart command, run as written. A command that no longer exists is a stale
+  promise, and it is the most expensive one because it is the reader's first step.
+- An example that imports, configures, or calls something the code no longer accepts.
+- A screenshot or a recording that shows a surface that has since changed.
+- A link to a guide that moved, a section anchor that was renamed, or a badge whose
+  target is gone.
+
+## Report
+
+Open with the profile, then the four sections from the skill: **Stale**, **Missing**,
+**Suggested edit**, **Needs a decision**. Every stale finding carries the document,
+`path:line`, the evidence in the tree, and the mode that fixes it. Group by the mode
+when there are more than a handful, so the user can act one mode at a time.
+
+Nothing found is a valid result for the whole audit or for any face. Say what was
+checked — the files read, the commands run, the commits examined — and stop. An audit
+that invents findings to look thorough is worse than one that reports none.
+
+## What the audit cannot see
+
+Name these in a closing line instead of guessing:
+
+- Whether a change is user-visible to someone the diff does not show — a default that
+  only matters on one platform, a behavior the docs promised and the tests never
+  covered.
+- Whether a commit message describes what the code does; only the diff does.
+- Whether an item shipped: a merged change to a document is not a release, and only the
+  maintainer knows whether the front door's promise is meant to hold today or next
+  version.
+- Whether a roadmap priority is still right, and whether a non-goal still stands.

package/skills/project-docs/references/changelog.md

@@ -0,0 +1,105 @@
+# Record one bullet
+
+This mode writes one thing: a bullet in the changelog for a change that just landed.
+It does not decide whether something shipped, and it does not curate a release — that
+is the `release` mode, and only for a version the user named.
+
+Read [`discovery.md`](./discovery.md) first for the file, the categories, their order,
+the scope spelling, and whether the entry ships with the change. Where a tool owns the
+file — `semantic-release`, `changesets`, `git-cliff`, or a step in the release workflow —
+this mode does not write it: the entry belongs upstream, in the commit message's
+convention, a changeset fragment, or the generator's config.
+
+## Where the bullet goes
+
+- Re-read the changelog before editing: another session, another contributor, or the
+  user may have written since the state script ran.
+- Under `[Unreleased]`, in the category the project uses for this kind of change, in
+  the file's own order and spelling. Never create a second heading for a category that
+  already exists in the section.
+- When the file keeps no `[Unreleased]` section, ask where the change is recorded — the
+  preamble decides, and a project that writes entries only at release has a different
+  procedure.
+- Insert without disturbing any other bullet, keep the file's wrap column, and write it
+  in the same commit as the change it describes.
+
+## Does it qualify
+
+It qualifies when a user can observe it: behavior, a CLI or tool or command surface, a
+config default, packaging and dependencies a user installs, security, or a documented
+promise that is now true or false.
+
+It does not qualify when only the implementation moved: an internal refactor, a rename
+with no behavior change, a test, formatting, a comment, a dependency bump with no
+behavior change, or a typo fixed in the changelog itself.
+
+When a change is both — a refactor that also fixes a rounding bug — the bullet is the
+rounding bug, and the refactor is not mentioned.
+
+## One outcome, one bullet
+
+- A feature and the bug it fixed before release are one bullet: users never saw the
+  broken version.
+- Two observable changes are two bullets, even in one commit.
+- Two commits that produce one outcome are one bullet, written where the outcome became
+  true.
+- A breaking change is its own bullet with the required action; do not bury it in a
+  feature's sentence.
+
+When the outcome is unclear, ask. Reading the diff tells you what changed; only the
+author knows what a user will notice.
+
+## The shape
+
+Follow the file's newest released section. Where the project states nothing, the shape
+is one bullet that leads with the scope in backticks, a colon, then what the user can
+now do:
+
+```text
+- `billing`: invoices show tax as a separate line. Amounts that used to be bundled
+  into `total` are summed on the printed total, so an invoice stored by an older
+  release still reconciles.
+- `cli`: `--legacy-auth` is no longer read; run `mytool migrate auth` first.
+```
+
+- **Scope**: the area a user would name — an extension, package, module, or subsystem,
+  in the project's own spelling. Never a file path, a function, or a ticket number. A
+  bullet with no scope is a defect where the project uses scopes, and noise where it
+  does not.
+- **Outcome first**: what is different for the user, then the mechanism if it matters,
+  then any action they must take.
+- **Length**: a bullet may run to several sentences when the outcome needs them — what
+  the user sees, what it replaced, what to do about it. Brevity is not the goal;
+  vagueness is the defect.
+- **Voice**: match the file. Most changelogs are present tense and third person; do not
+  switch to marketing, and do not add praise for the change.
+- **Wrap**: match the file's column, usually near 80, and let one bullet be one
+  paragraph.
+
+## What does not belong
+
+File names and paths, internal helper names, test counts and coverage, commit hashes
+and pull-request numbers as the subject (a link at the end is fine where the file does
+it), and empty words such as "various", "improvements", "cleanup", "refactor", "misc".
+A reader who cannot tell from the bullet whether the change affects them has been told
+nothing.
+
+## The two failure modes
+
+```text
+- `billing`: refactored invoice rendering and added tests.
+- `misc`: improvements.
+```
+
+The first names no outcome and reports the implementation. The second names no scope,
+no outcome, and would fit any release.
+
+```text
+- `api`: `POST /v2/charge` now refuses an amount with more than two decimals
+  instead of truncating it, so a client that relied on the old rounding sees a
+  `422` with `code: "amount_precision"`. Truncation moved to `POST /v2/charge/draft`,
+  which is what the old behavior should have been.
+```
+
+Three sentences, one outcome, one scope, and the migration named. Long is fine when
+each sentence tells the reader something they must know.