# Release Notes Roles: - Writer - Reviewer When a milestone build is ready, the account lead names the milestone — a tag, or a commit range — and this playbook writes the client-facing release notes, has them reviewed against the commits, and commits them only once the account lead approves. The account lead is Boss; the request naming the milestone is the caller input. No step before the approval writes a file or commits: every draft travels as text in the Writer's reply, and only the final Writer step writes RELEASE-NOTES.md and makes the one commit. There are at most two review rounds. When the account lead names the milestone, Captain shall prompt Writer with the following instruction: ```markdown Write the client-facing release notes for the milestone named in the request below; this step drafts them only. Determine the commits the milestone covers: if the request gives a commit range, read exactly that range; otherwise read the commits since the last tag before the milestone — up to the milestone tag when it already exists, or up to the current HEAD when it does not. If you cannot resolve which commits the milestone covers, ask the account lead before drafting. Read every commit in that range, together with the spec items and decision records the commits cite. Draft RELEASE-NOTES.md as one Markdown document with: - a title giving the milestone name and today's date; - a "What's new" list in which every entry names one user-visible change in plain words a client understands; - a "Known limitations" list, drawn from the commits, spec items, and decision records, reading "None known." if they record none; - a "For your testers" section naming the three most important flows to try. Claim no change the commits do not contain, and leave out internal changes a client cannot see. Do not edit any file or commit; give the complete document in one fenced markdown block in your reply. Report the draft. ``` Captain shall append the account lead's request in quotes (`>`): > Milestone request: Results: - `drafted`: The Writer gave a complete draft of the release notes in its reply and left the repository unchanged. Output shall include `writerDraft: `. When the Writer has drafted the notes, at the first review round, Captain shall prompt Reviewer with the following instruction: ```markdown Review the draft release notes below for the milestone named in the request; the notes go to a client, so every entry must be true and plain. Determine the commits the milestone covers: if the request gives a commit range, read exactly that range; otherwise read the commits since the last tag before the milestone — up to the milestone tag when it already exists, or up to the current HEAD when it does not. Check every entry against those commits and the spec items and decision records they cite, and return numbered findings, one problem each: - a claim that no commit supports; - a commit with a user-visible change that no entry covers; - jargon or internal terms a client would not understand; - a missing title with the milestone name and date, a missing "What's new", "Known limitations", or "For your testers" section, or a testers section that does not name exactly three flows. Flag only real problems, not style preferences. Do not edit files or commit; report findings only. Report your numbered findings, or state that the notes have no findings. ``` Captain shall append the round's context in quotes (`>`): > Milestone request: > Draft: Results: - `hasFindings`: The Reviewer raised one or more numbered findings against the draft. Output shall include `reviewerOutput: `. - `noFindings`: The Reviewer affirmatively stated that the notes have no findings; a progress report or a promise of a later review supports neither outcome. After the Writer revises the notes in the first review round, the second review round begins. After the Writer revises the notes in the second review round, no further review follows and the notes go to the account lead for approval. When the Reviewer raises findings, in either review round, Captain shall prompt Writer with the following instruction: ```markdown The Reviewer checked your draft release notes and returned the numbered findings below. Fix every finding in the notes; if a finding is wrong against the commits, spec items, or decision records, leave that part unchanged and say why. Claim no change the commits do not contain, and keep the title with the milestone name and date, the "What's new", "Known limitations", and "For your testers" sections, and exactly three tester flows. Do not edit any file or commit; give the complete revised document in one fenced markdown block in your reply, followed by your disposition of each finding by number. Report the revised draft. ``` Captain shall append the round's context in quotes (`>`): > Milestone request: > Current draft: > Reviewer findings: Results: - `revised`: The Writer gave the complete revised notes and its disposition of each finding in its reply and left the repository unchanged. Output shall include `writerDraft: `. When the Writer has revised the notes after the first review round, at the second review round, Captain shall prompt Reviewer with the following instruction: ```markdown This is the second review round of the release notes for the milestone named in the request. The Writer revised the notes after your earlier findings; the revised notes, the Writer's disposition of each finding, and your earlier findings are below. Check that each earlier finding is fixed, or rejected with a reason the commits, spec items, or decision records support. Determine the commits the milestone covers: if the request gives a commit range, read exactly that range; otherwise read the commits since the last tag before the milestone — up to the milestone tag when it already exists, or up to the current HEAD when it does not. Check every entry of the revised notes against those commits and the spec items and decision records they cite, and return numbered findings, continuing your earlier numbering, one problem each: - a claim that no commit supports; - a commit with a user-visible change that no entry covers; - jargon or internal terms a client would not understand; - a missing title with the milestone name and date, a missing "What's new", "Known limitations", or "For your testers" section, or a testers section that does not name exactly three flows. Flag only real problems, not style preferences. Do not edit files or commit; report findings only. Report your numbered findings, or state that the notes have no findings. ``` Captain shall append the round's context in quotes (`>`): > Milestone request: > Revised draft and the Writer's dispositions: > Your earlier findings: Results: - `hasFindings`: The Reviewer raised or kept one or more numbered findings against the revised notes. Output shall include `reviewerOutput: `. - `noFindings`: The Reviewer affirmatively stated that the revised notes have no findings; a progress report or a promise of a later review supports neither outcome. The account lead's answer resumes this same Writer step. On `committed`, the playbook ends and returns the new commit's hash. On `rejected`, the playbook ends and returns the Writer's report, which carries the account lead's reason. When the Reviewer reports no findings in either review round, or the Writer has revised the notes after the second review round, Captain shall prompt Writer with the following instruction: ```markdown The release notes below have finished review and need the account lead's approval before anything is committed. Until the account lead has answered, write no file and make no commit: show the account lead the complete notes, then ask exactly one question, "Send these notes to the client?", and end your reply with it. Once the account lead has answered, treat only a clear yes as approval; any other answer is a rejection, and its words are the reason. On approval, write exactly the release-notes document from the draft below — without dispositions or any other commentary — to RELEASE-NOTES.md at the repository root, replacing any earlier content. Commit RELEASE-NOTES.md alone in one new commit on the current branch, with a message naming the milestone; do not create a branch or tag, amend a commit, or push. Report the new commit's hash. On rejection, write no file, make no commit, and report the reason the account lead gave. ``` Captain shall append the approved draft's context in quotes (`>`): > Milestone request: > Draft: Results: - `committed`: The account lead clearly approved, and the Writer committed RELEASE-NOTES.md in one new commit on the current branch; asking the question supports neither outcome. Output shall include `latestCommit: `. - `rejected`: The account lead's answer was not a clear yes, and the Writer wrote no file, made no commit, and reported the reason the account lead gave; asking the question supports neither outcome. Output shall include `writerOutput: `.