v13.1 release notes: skill-driven, memory-mined, multi-iteration

Problem scope

Release notes at this project's bar are a narrated release, not a changelog dump — and the v13.1 window is large: 663 merged PRs / 748 closed issues ticketed (cutoff 2026-06-12, v13.0.0 @ 92eb323fb), project board 13 carrying 160 items (19 todo / 2 in progress / 139 done), and an estimated 300–500 changes not yet filed as tickets at all — the ticket record lags the shipped reality, so no single enumeration source tells the story. (Operator direction, 2026-07-02: do NOT downplay a release of this magnitude; whether to mention the unfiled mass is an editorial call inside the iterations.)

Three structural gaps make this an epic rather than a ticket:

1. No reusable protocol exists. v13.0's notes reached their quality bar through an unformalized iteration cluster — #12695 (author) refined across #12700, #12716, #12729, #12811, #12815, #12924 over roughly a month. The process worked and was lost: nothing captured how to derive scope, how to ground chapters in Memory Core evidence, or what the quality bar mechanically requires. Every release re-derives it.
2. Single-pass drafts fail the bar in a measured way. The first v13.1 draft (kept as iteration 1, per operator) carried exactly the failure classes a protocol must catch: a War-Story environment error (the #13999 incident was a LOCAL Agent OS incident; self-healing is MOSTLY for cloud environments but not fully limited to them), one-lens narration (a single epic's view of a multi-arc window), and scope framing that downplayed the release. Multiple iterations ARE needed — by design, not as failure.
3. The release pipeline's own staging state is currently untestable-illegal. publish.mjs REQUIRES resources/content/release-notes/v{version}.md at the flat root pre-flight (:83-87), appends the atomic-hash line to it, creates the GitHub Release from it, and removes it itself post-release (:223-226). A unit guard added in the #13273/#13276 orphan cleanup asserts the flat root is ALWAYS empty — outlawing the mandatory pre-cut staging state and blocking any notes PR from green CI.

Intended solution shape

• A new agent skill (.agents/skills/) codifying release-notes authoring as a repeatable protocol: scope derivation (analyzeClosedSinceRelease.mjs + board views + epic closures + the unfiled-work reality), heavy Memory Core mining per narrative arc (the grounding method — sessions and summaries, not just ticket titles), a per-claim V-B-A discipline (every factual claim carries a source anchor; environment/scope claims verified against primary sources), the quality-bar contract distilled from the v13.0 notes (hero chapters, "in 2 minutes" section, honest bounds, upgrade-path framing), the publish-flow mechanics (flat-root staging lifecycle, frontmatter/H1 parse contract, atomic-hash line), and the iteration cadence (draft → mined refinements → cut-readiness).
• Iteration-1 draft merges early with an explicit multiple-iterations-needed marker — the draft is a living staging document on dev (the v13.0 lineage precedent, formalized), refined by mining-driven iteration leaves until the cut bar is met.
• The staging flow unblocked — the orphan guard refined to its actual defect class (a flat file lingering alongside its chunk-N mirror post-publish) so the designed pre-cut state is representable; the release-index interplay (buildScripts/docs/index/release.mjs scans flat files recursively) recorded as an observation for the leaf that fixes the guard.
• Cut mechanics stay a leaf (version bump validation, operator publish handoff — publish.mjs execution remains human-only per the critical gates).

Subs link via the relationship graph and are added incrementally as iterations clarify; the graph, not this body, is the sub registry.

Out of scope

• publish.mjs execution and the dev→main release line (operator-only).
• v13.2 roadmap scoping (/update-roadmap, post-release beat).
• Retro-filing the estimated 300–500 unfiled tickets (the notes narrate reality; they do not backfill the tracker).

Avoided traps

• Changelog-dump notes — the bar is narrative (v13.0 precedent); grouped appendices support, never replace, the story.
• Single-pass authoring — empirically produces V-B-A misses and downplaying; iterations are the design.
• One-lens narration — a multi-arc window narrated through one epic's view under-tells the release.
• Board-Done ≡ shipped-scope-complete — the ticket record lags reality (harness is EARLY; the board looks mostly done because tickets for the remaining work were not filed yet); scope derivation must not treat any single tracker view as the window's truth.
• Weakening the orphan guard wholesale — the guard's post-publish purpose is real; the fix is narrowing it to its defect class, not deleting it.
• Relocating the notes out of the pipeline's contract (attempted in-window, reverted): the flat root IS the designed authoring/staging surface; fixes go to the guard, not the flow.

Related

Related: #14039 (the v13.1 scope epic this release ships), #12695 (v13.0 notes lineage anchor), #13273 (orphan-cleanup origin of the guard), #10321 (release-cut sibling process)

Origin Session ID: 8cf234b7-e698-47ca-99e2-bf865196b6aa

Retrieval Hint: v13.1 release notes epic skill memory-mining iterations quality bar flat-root staging orphan guard