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.

1. Confirm the sprint to close. The most recently-completed sprint folder under doc/agile/versions/v0/ is the target; ask the user if there is any ambiguity.

2. Collect PR data since the last release tag:

   python3 build/scripts/collect_release_pr_data.py
   

   Output lands in tmp/release_pr_data/. If already collected this sprint, skip.

3. Generate the release notes org file. The script reads sprint.org and all story.org files, extracts story descriptions into the Key Improvements section, derives Highlights from the retrospective, and renders doc_release_notes.org.mustache via pystache:

   python3 build/scripts/generate_release_notes.py
   

   Output: doc/agile/versions/v0/sprint_N/release_notes.org — a standard org-mode document with a proper UUID, frontmatter, and a summary blurb placeholder that must be filled in.

4. Fill in the blurb. Open release_notes.org and replace the (( Summary blurb ... )) placeholder with one paragraph summarising the sprint's focus and key outcomes. Source material: sprint mission (sprint.org * Mission) and retrospective (sprint.org * Retrospective). Keep it to 4–6 sentences.

5. Export to Markdown inside Emacs:

   ;; C-c C-e m m  (org-export-dispatch → Markdown → to file)
   

   The exported release_notes.md is what GitHub Releases uses.

6. Open the PR via PR Manager. Merge once green.

7. Tag main and open a draft GitHub release (see the * Tag and release section in How do I generate release notes?):

   git checkout main && git pull --ff-only origin main
   git tag -s v0.0.<N> -m "Sprint <N>"
   git push origin v0.0.<N>
   gh release create v0.0.<N> \
     --draft \
     --title "Sprint <N>" \
     --notes-file doc/agile/versions/v0/sprint_<N>/release_notes.md
   

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.

The release notes pipeline separates three concerns:

• Mechanical collection — collect_release_pr_data.py gathers all PR metadata; generate_release_notes.py parses sprint/story org files and extracts story descriptions.
• Template rendering — the script renders projects/ores.codegen/library/templates/doc_release_notes.org.mustache via pystache (same infrastructure as all other documents). Story descriptions are the first sentence of each story's * Goal section; Highlights come from the * Retrospective ** What went well bullets.
• Editorial judgement — the summary blurb is intentionally left as a placeholder. It requires reading the sprint's mission, retrospective, and PR list to synthesise a coherent narrative. Claude fills it in; the human reviews.

The output is an org-mode source file. The human exports it to Markdown in Emacs (C-c C-e m m) for the GitHub release.

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

• Sprint closure phase — where this skill is invoked.
• Release (glossary).
• Agile recipes — sibling recipes for the agile cycle.