releases
Read, synthesize, diagnose, clean, author, and publish the releases.db planning ledger (or legacy RELEASES.md where retained) through one routed workflow. Use for /releases; release status or health c
SKILL.mdskills/2-daily/releases/SKILL.md
GitHub/releases — one release-planning router
The release ledger is the Product Release System (PRS; definition).
Treat the release ledger as an optional forward-looking planning aid, never as a second
CHANGELOG.md. Start every invocation by reading and synthesizing the ledger. Route into a mutating
subroutine only when the operator explicitly chooses or requests one.
Routes
/releases read-only synthesis, findings, and relevant route choices
/releases check [window] refresh the evidence-backed health assessment
/releases clean [version|active] preview a spec-aligned cleanup
/releases plan [version] create or explicitly update an upcoming release
/releases anchor <version...> add only the named shipped historical anchors
/releases backfill show eligible historical anchors as an optional menu
/releases publish <version> publish one planned entry to GitHub
Natural-language requests route the same way. Do not make the operator remember the route names.
The DB's second subsystem — the ROADMAP shadow (GH-69)
releases.db also mirrors ROADMAP.md's ledger (roadmap_items, one-way, lossless). This skill
does not own roadmap edits — ROADMAP.md stays the human file — but if a task you are part of
edited that ledger, finish with releases roadmap sync (a no-change sync is a free no-op;
--dry-run previews, roadmap list reads back). Contract: RELEASES-DB-FAQS.md.
Preflight
Resolve the repository root. Require
utils/pdda/pdda.sh; stop if PDDA is absent because there is no fallback release-ledger format.Detect the ledger backend (GH-32 / GH-568). If
releases.dbexists at the repository root, this repo is app-managed: the SQLite database is the sole source of truth (RELEASES.mdis retired per GH-568), and every mutation this skill performs MUST go through thereleasesCLI (utils/py/releases_app.py). Ifreleases.sqlexists at the repository root butreleases.dbis absent, the ledger is in an incomplete state — stop with an error promptingreleases check --rebuild. Only if neither app-managed marker (releases.dbnorreleases.sql) exists is this a legacy-managed repo where legacyRELEASES.mdprocedures apply.Read
PROJECT/PDDA.md's release ledger contract,releases.db(orRELEASES.md), andCHANGELOG.md. A missing, empty, sparse, or apparently old ledger is valid. In an app-managed repo, also runreleases checkand surface any findings before proceeding.In an app-managed repo, read the ledger through the CLI's readers, not raw SQL. All three are read-only, take no lock, and mutate nothing:
releases next [--verbose] the next unshipped release, by target date releases show --version 0.6.0 one full record (or --gid; --full disables elision) releases list [--status ...] one line per release (--all-repos aggregates siblings)There is no generated Markdown mirror of the database to read:
RELEASES-PREVIEW.mdwas removed 2026-08-19. For a whole-ledger view, usereleases list, openreleases.dbin a SQLite viewer, or read the release cardsreleases project sync(GH-39) pushes to GitHub Projects.After any merge that touched the ledger, run
releases checkbefore anything else. The merge procedure resolvesreleases.sqlas text and then requiresreleases check --rebuildto regenerate the DB from it; skipping that leaves a DB that disagrees with the dump, and the DB is what every reader above trusts.test/gh32-releases-artifacts.shgates this on every full-suite run, but it catches the mistake after the fact — checking first is cheaper. Never run--rebuildto make a red check go away without reading what diverged: it is for merge resolution only, never crash recovery. See RELEASES-DB-FAQS.md.Treat GitHub as optional for checks and required for publication. If
ghis unavailable, run the local assessment and state exactly which PR, milestone, issue, or Release conclusions are unavailable. Never convert missing network evidence into a clean verdict.Parse a block from one
Release:line to the nextRelease:line or end of file. Blank lines do not end blocks.
Default route — read and synthesize
Run this route before every other route unless the same invocation already established fresh state.
- Run
utils/pdda/pdda.sh releasesandutils/pdda/pdda.sh releases-current. Preserve their warn-only semantics. - Select the evidence window: use an operator-supplied window, otherwise 21 days. Resolve the
active integration branch from repo policy (
developmentin this repo; otherwise the declared WIP branch, thenmain/master). State the exact dates and branch. - Read reachable non-merge commits plus merged and closed-unmerged PRs targeting that branch during
the window. Use merged PRs as completion evidence. Surface a closed-unmerged PR only when it
contradicts a block's claim that work is in flight or materially changes the cleanup decision.
A push is transport, not evidence; count the commits that reached the branch. Read exact
bracketed versions and dated entries from
CHANGELOG.md. - When GitHub is available, inspect matching releases, milestones, and manifest issues. Verify PR base branches and merge state before using them as evidence.
- Summarize, without dumping the file:
- shipped entries;
- active and upcoming entries, target dates, iteration bands, and milestones;
- strong inconsistencies and advisory drift signals;
- description or manifest discipline warnings;
- evidence that could not be obtained.
- Offer only routes relevant to the findings or the user's stated goal. Make no writes.
Staleness and drift rules
Call something stale only when evidence contradicts a block, not because the ledger is sparse or has not changed recently.
Treat these as strong inconsistencies:
CHANGELOG.mdrecords the exact version as shipped while the block remains unshipped.- A GitHub Release exists but
GH_URL:is empty, points elsewhere, orStatus:contradicts the actual publish state. Target Date:is past whileStatus:is notShipped.- A block says work is open, absent, or unbuilt while a merged PR, reachable commit, or canonical project document proves the opposite.
- Iteration bands overlap or a non-owner release sits inside another block's band.
Treat these as advisory drift signals:
- Recent merged work materially follows a different theme than an active description.
- A manifest contains replaced, duplicated, unrelated, or silently added scope.
- A target date no longer fits explicit dependencies or the observed delivery rate.
Do not infer shipment from a closed-but-unmerged PR, an issue closure alone, a branch push, a commit
on an unmerged branch, or a populated GH_URL: that points to a draft.
Discipline and abuse warnings
Warn, without blocking, when:
Description:exceeds four sentences, becomes multi-paragraph execution history, or duplicatesCHANGELOG.md. Recommend a one-to-four-sentence theme and move history toCHANGELOG.mdand implementation detail to the canonicalPROJECT/**document.Manifest:names more than seven issues. The count triggers review, not condemnation.- A manifest mixes unrelated themes, lacks a fixed denominator, grows without a dated re-scope, crosses several release dependencies, or has no runnable/observable exit criterion.
- A block copies an issue inventory that should be represented by the
Milestone:join key.
Explain which signal fired. Never call a large manifest abusive solely because of its issue count.
Clean subroutine
- Default to active/unshipped blocks. Touch a shipped block only when the operator explicitly names it.
- Propose the smallest cleanup that restores the documented shape: compact descriptions, preserve
theme and dependencies, reduce manifests to a fixed list or milestone pointer, preserve dated
re-scope decisions, and move historical narrative to
CHANGELOG.mdor execution detail to its existing project doc. Never create a new doc merely to shorten the ledger. - App-managed repo: render the cleanup as the exact
releases update --gid <id> ...(andreleases manifest .../ legacy-line disposition) command set, preview those commands, and get one confirmation. On confirmation run them, then finish withreleases check. The CLI's own preimage/lock handling replaces the hash dance below. - Legacy-managed repo: record the file hash before preview. Render the exact patch and get one
confirmation. Immediately before writing, re-read
RELEASES.mdand compare its hash. If it changed, discard the patch, synthesize again, and preview a new patch. Edit only the confirmed blocks. Never reorder unrelated blocks. - Run
utils/pdda/pdda.sh releasesand report every finding.
Plan or update subroutine
- Apply the admission rule. A block earns a place only when it represents a named arc worth
planning toward. A restatement of shipped changes belongs only in
CHANGELOG.md. A version inside another block'sIterations:band is already accounted for. - If no version was supplied, compare the highest bracketed
CHANGELOG.mdversion with the highest ledger version. Propose the next semantic version and explain the patch/minor/major judgment; let the operator override it. - Ask only for unanswered fields:
- status;
- optional iteration band;
- target date or blank/TBD;
- optional codename;
- optional GitHub milestone title;
- a one-to-four-sentence description of the theme;
- optional concise manifest;
- optional executable or observable exit criterion;
- optional QA fields (
Front-door reviewed,Shakedown reviewed,License file).
- Draft the flat block below, omitting blank optional fields except
GH_URL:when publication is expected:
Release: 1.2.0
Iterations: 1.2.0-1.2.4
Status: Draft
Target Date: 2026-12-01
Codename: Example
Description: One coherent release theme in no more than four sentences.
Exit criterion: `command --that-proves-the-release` exits 0.
Manifest: FROZEN YYYY-MM-DD — #101, #102, #103.
GH_URL:
Milestone: Example
Front-door reviewed: No
Shakedown reviewed: No
License file: Yes
- App-managed repo: preview the equivalent
releases add ...(orreleases update --gid ...) command set — including the required tracking issue (a real URL, or aTMP-ref if GitHub is down) — and get one confirmation, then run it. Legacy-managed repo: preview the complete new or replacement block and get one confirmation. Re-check the file hash before writing. Append new blocks after the last block; replace only an explicitly selected existing block. Never silently edit neighboring blocks. - Run
utils/pdda/pdda.sh releasesand report findings.
Anchor and backfill subroutine
Run only when explicitly requested.
- For
anchor, draft exactly the shipped versions the operator named. Trace each one-line summary to its bracketedCHANGELOG.mdsection and setStatus: Shipped. In an app-managed repo the draft is a previewedreleases add ...+releases ship ...command pair, not a file patch. - For
backfill, show bracketedCHANGELOG.mdversions that are not already represented and do not sit inside an existing iteration band. Present them as an optional menu, never as missing work. Draft only the versions the operator selects; drafting none is valid. - Never initiate either route because the ledger looks incomplete.
Publish subroutine
- Require
ghauthentication and a specific existing release block. Stop if it is alreadyShipped. IfGH_URL:exists but status is unshipped, inspect the existing Release and ask how to handle the draft or conflicting object. - Run
utils/pdda/pdda.sh releasesand surface its findings. - Build release notes from the block's
Description:plus concise codename, exit-criterion, and manifest context when useful. Never invent notes. Ask for missing release-facing prose. - Preview together:
- the exact
gh release create <version> --title ... --notes ...action; - the full release body;
- the
GH_URL:andStatus: Shippedwrite-back.
- the exact
- Get one explicit confirmation, publish live, and capture the returned URL. If creation fails, report the error verbatim and make no ledger edit.
- On success only: app-managed repo — write back via
releases update --gid <id> --gh-release-url <url>andreleases ship --gid <id> --evidence ...(never a direct file edit); legacy-managed repo — re-check the file hash, write the returned URL, setStatus: Shipped. Then runutils/pdda/pdda.sh releaseseither way. - Remind the operator that shipped history and lessons belong in
CHANGELOG.md; do not write that entry unless separately asked.
Complementary routing
Offer at most one goal-matched follow-up; do not append generic reminders.
- Offer
/radarwhen the question is whether recent work, recurring defects, and release themes are strategically aligned. State that Radar is broader than this ledger check and owns its own report workflow. Never copy Radar's analysis into this skill or invoke it automatically. - Offer
/finish-linewhen the operator has selected a release checkpoint and wants a frozen, shortest safe path to ship it. State that Finish Line owns the done-list and parking workflow. Never invoke it automatically. - Stay within
/releaseswhen the task is ledger synthesis, cleanup, authoring, or publication.
Guardrails
Schema009 adds nullable exact roadmap_items.status_label (in-progress or NULL).
Only accepted starts establish it; metadata/migration/backfill never infer one
from old markers. NULL is not proof of completion. Use the existing command
roadmap update --gid OWNED_ROW --accepted-start after approved execution admission;
it validates owned URL/native open issue, refuses PRs and preserves repeated starts.
Use --dry-run to preview. Schema migration and remote projection remain opt-in.
An explicitly configured work_connectors.github_labels block with enabled: true
and repos: ["owner/repository"] projects only that exact label. No default network
calls; failures retain replay cursors. Native direct closes require preview-first
roadmap reconcile-state, then --apply. For terminal cleanup drift, use
work reconcile --connector github_labels --reset when witnessed events exist;
for zero-event Completed/Deferred rows, seed work emit --event label_repair --roadmap-gid OWNED_ROW, then reconcile. This qualified repair is labels-only,
not a start/completion claim, and unestablished NULL/open issues are preserved.
Disabling this connector rolls back projection, not the schema; old writers are
unsupported against migrated ledgers because their digests/dumps omit the field.
- Default to read-only synthesis.
- In an app-managed repo (
releases.dbpresent) every mutation goes through thereleasesCLI; never editRELEASES.mddirectly there (RELEASES.mdis retired in this repo per GH-568). Preview the exact command set instead of a patch — the confirmation UX is unchanged, only the write path moves. - Preview every file mutation and public action; obtain one confirmation per atomic write/publication group.
- Re-read before writing and refuse stale patches.
- Never top up the optional ledger, fabricate release notes, or treat absence as failure.
- Keep
CHANGELOG.mdauthoritative for shipped history andPROJECT/**authoritative for execution detail. - Use repo-relative paths in edited documents.
- Never create, edit, install, or synchronize a Codex skill from this workflow.