Agile Add Release Notes

When closing a sprint — i.e. assembling release notes for the sprint's PRs, tagging main, and opening a draft GitHub release.

The whole pipeline runs through compass release-notes (projects/ores.compass/src/compass_release_notes.py) — five verbs, run in order, from a task branch off main.

1. Confirm the sprint to close. It is always the previous (already-closed) sprint, not the one currently in flight — ask the user if there is any ambiguity.

2. Create: collect PR data since the last release tag and render the release notes org file.

   ./compass.sh release-notes create --sprint <N>
   

   Pass --since-tag v0.0.<N-1> explicitly if a tag for the sprint being closed already exists (e.g. created ahead of time) — otherwise PR collection will pick up its own tag as "latest" and undercount merged PRs.

   Output: doc/agile/versions/v0/sprint_N/release_notes.org — a standard org-mode document with a proper UUID, frontmatter, and two summary blurb placeholders (opening paragraph, "Next sprint" line) that must be filled in.

3. Fill in the blurbs. Open release_notes.org and replace both (( ... )) placeholders. Source material: sprint mission (sprint.org * Mission), retrospective (sprint.org * Retrospective), and health reviews. Keep the opening paragraph to 4–6 sentences.

4. Charts: render the sprint's gnuplot health charts so the org file's chart images resolve to real files.

   ./compass.sh release-notes charts --sprint <N>
   

5. Export: batch-export release_notes.org to GitHub-flavoured Markdown.

   ./compass.sh release-notes export --sprint <N>
   

   Output: release_notes.md — this is the file that ships verbatim as the GitHub release body.

6. Commit: stage, commit, and push release_notes.org=/.md= and the four chart PNGs on the current branch. There is no separate "upload images" step — the markdown embeds them via raw.githubusercontent.com/.../main/... URLs, so they only render correctly once these files are merged to main.

   ./compass.sh release-notes commit --sprint <N>
   

   Open and merge the PR the normal way (compass pr create / compass pr merge) before the next step, so the images resolve.

7. Draft: tag main and open a draft GitHub release. A codename is invented per release (house convention: v0.0.20, "Capopolo") — --codename is required.

   ./compass.sh release-notes draft --sprint <N> --codename <Codename>
   

   Idempotent: safe to re-run if the tag or release already exists (e.g. tagged ahead of time, or fixing the title/body after the fact) — reuses/updates in place rather than erroring or losing work.

8. Hand off to a human. The release is always created in draft so a maintainer can review, attach binaries/screenshots, and publish.

The release is the upward signal that work landed (see Release in the glossary). Cutting it is a Sprint closure task — System 3 owns it at sprint level.

• How do I generate release notes? — the end-to-end procedure.
• PR Manager — for the notes PR itself.

• The compass release-notes pipeline — why it's five verbs, the image-resolution mechanism, tag/release idempotency, the title convention.
• Sprint closure phase — where this skill is invoked.
• Release (glossary).
• Agile recipes — sibling recipes for the agile cycle.