release-comms: release note, docs, announcement and marketing pipeline
Lane: full. It mutates external state (Slack posts, docs PR, wiki pages), so every post and PR is drafted first and gated on the user's explicit approval. See the closed-loop skill.
Configuration
Fill these in once (kit.toml, .env or arguments). Placeholders below are examples.
| Setting | Meaning | Example |
|---|---|---|
PRODUCT_REPO | Repo that holds the release milestone | your-org/your-product |
MILESTONE_PATTERN | Milestone naming | Release YYYY-MM-DD |
TEAM_LABEL | Label that filters the milestone to your team | team:platform |
RUNSHEET_SOURCE | Where the deployment runsheet lives | a wiki page, a doc, or a Slack thread |
RELEASE_DIR | Working folder per release | comms/release-notes/<date>/ |
DOCS_REPO | Local path of the docs repo | ../your-docs |
RELEASE_NOTES_FILE | Running release-notes page in the docs repo | docs/release-notes.md |
ANNOUNCE_CHANNEL | Slack channel for the internal announcement | #product-releases |
MARKETING_CHANNEL | Slack channel for the marketing package | #marketing |
FLAG_SYSTEM | Feature-flag tool named in the runsheet | any |
Source-of-truth chain (walk it in order)
- Deployment runsheet. Gives release scope, the milestone link, the PR list per service, feature flags being enabled, the deploy window, and trailing items (merged to QA but not staged). Exclude trailing items from "available now".
- GitHub milestone. The milestone filtered by
TEAM_LABELis the release manifest. Issues may still be open, so closed does not equal shipped. - Issue bodies and comments. This is the media source. Dev-test comments ("Dev test: passed on prod") and QA comments ("Verified PASSED on staging") carry screenshots and demo videos as GitHub attachment URLs. For a private repo these need auth to resolve:
curl -sL -H "Authorization: Bearer $(gh auth token)" -o <file> <url>Check the Content-Type withcurl -sIfor the right extension. GitHub videos are usually QuickTime.mov. Treat a comment-level "Verified PASSED" as the ship signal, because issues often stay open until a later close step. - Feature flags. Anything behind a flag in the runsheet gets honest gating language ("rolling out", "enabled per organization").
Pipeline
1. Collect (parallel workers, staging files)
Use one worker per headline cluster plus one sweep worker over the remaining milestone issues. Each worker extracts user-visible changes with verbatim quotes and links, classifies each as user-facing feature, user-facing fix or internal, downloads media into assets/ with descriptive kebab-case names, writes to RELEASE_DIR/staging/<cluster>.md, and returns only a status line. Never paste one worker's output into another's prompt.
2. Release note (lead writes, single file)
Write RELEASE_DIR/release-note-<date>.md: frontmatter (version, date, milestones, labels), a one-paragraph narrative summary, Highlights (bold, benefit-first bullets with issue links), per-feature sections (What's new, Why this matters, What you can do now, Shipped in this capability), Enhancements, Fixes, and an appendix table of shipped issues. See the generate-release-notes skill for the base format.
Voice rules:
- Do not write a feature list. Every item says what the user can now do and what pain it removes. Lead with the before/after story where one exists.
- Embed the downloaded screenshots and videos inline next to the feature they prove.
- Disclose known issues plainly with a fix timeline.
- Flag to the user anything user-benefiting found in the sweep that they did not list.
- Frame the release around the opportunity it opens, and sanity-check every number.
- Naming: avoid "v1" or "first version" in customer copy. Call gated first releases "early access". Call UI refreshes "a new look", not "redesign". Describe capabilities as what is now supported, and say when one serves both humans and agents.
- The internal post is the deep dive: same naming, plus issue links, flag names, architecture notes, verification status and known-issue numbers. Marketing copy stays light.
3. Docs updates (branch off main, never touch in-flight branches)
Use a git worktree so work in the main checkout is never disturbed:
git worktree add ../docs-release-<date> -b release-comms/<date> origin/main (run inside DOCS_REPO). Check what exists on origin/main before planning edits, because drafts in the checkout may not be merged. Two motions:
- New or changed feature docs. Use the
feature-docskill for any new article or real screenshot refresh. - Retrofit sweep. Grep the docs for surfaces this release changed: stale screenshots, stale flow text, stale limitations. Always add the release entry to
RELEASE_NOTES_FILE(heading per date, "What's new" and "Why this matters" for features, enhancements and fixes in collapsible blocks). If unmerged drafts cover the same surface, do not edit them. Flag the needed change to the user for that branch. The docs PR is a ship gate: the user approves before it opens. To publish the note to a wiki, see thepublish-to-confluenceskill.
4. Slack announcement draft (ANNOUNCE_CHANNEL)
Format: an announcement line (:mega: *Product Release Announcement* | <release note link> | Available now), a channel-wide greeting, then emoji-prefixed bold-name bullets with one benefit sentence each, a known-issue heads-up, and a link to the full release note. Keep it terse. Draft only: the user posts or approves posting.
5. Marketing package (MARKETING_CHANNEL)
Use a lightweight changelog-thread format, not positioning essays:
- Lead post: "This week's release:" plus a numbered list (
1/ ...), one line per shipped feature, and one short closing line. No media required. - One detail post per feature: a hook line (the pain or the punch), 2 to 4 short lines on what it does, the benefit and a use case, an honest caveat if any, and a specific demo video, GIF or screenshot from
assets/(name the file and note any trim or convert work). Each post reuses cleanly as an X or LinkedIn thread, a Slack lead with thread replies, or a newsletter section. - Media manifest: each asset marked near-ready, needs trim, or missing (record fresh). The
release-video,social-media-kitandyoutube-video-kitskills cover producing media. - Suggested channel message for the people who compile and review the newsletter. Draft only: gate on the user.
5b. Demo videos back to the tickets (optional)
Once demo videos are published somewhere the team can open, write each video link into a "Demo" field on every shipped issue it covers (for example a GitHub Project text field, set through gh api graphql with updateProjectV2ItemFieldValue). One link per issue. Check an existing value before overwriting it. Verify by re-reading the field.
6. Verify (closed loop)
- A fresh-context verifier re-checks release-note claims against the issue links and tags each Verified, Weakened or Falsified. Drop or demote accordingly.
- Media check: every embedded asset exists locally and renders (size above zero, correct extension).
- After any approved Slack post or docs PR, re-fetch the artifact and confirm it matches intent.
Cockpit
Keep a session-review.md in RELEASE_DIR (the review-cockpit pattern): progress, one card per deliverable, the user's approvals logged. Delete staging files after consolidation.
