Release Notes

release-notes

Turn development activity into release notes a Project Manager can scan in 30 seconds: every entry tells PMs, QA, and operations what changed, why, and what is better now. It only summarizes work that already happened — never plans, files issues, or reviews code (those are /feature-prompt, /qa, and /code-review).

Writing rules

Every sentence must pass: "Would a PM or QA person understand this without asking a developer?"

1. Plain, everyday words. No jargon, corporate-speak, or engineering terms.

• BAD: "Standardized how scanning is prepared before each RFID lookup"
• GOOD: "The app now checks the scanner is ready before starting a scan"

1. Say what the user sees or does. Name the screen, button, field, or page.
2. One idea per bullet, one short sentence each. Never a paragraph. Max 2

content bullets per Problem/Change/Impact section — the labeled What changed where: and Simple logic explanation: lines don't count; needing more means too much detail.

1. Feature names describe what changed, not how ("Login and Password

Improvements Planned", not "Auth Hardening Workstreams Prepared").

1. Problem = what the user experienced (the symptom, not what the code

lacked). Impact = what is concretely better now.

1. No filler or abstraction. Remove "formally", "in order to", "it should

be noted that", "this ensures that", and risk-reduction prose.

1. Translate engineering into operational meaning. Rewrite code-level

detail as its user-visible effect ("refactored useRfidScanner" → "the app now sets up the scanner the same way before every scan"); keep code identifiers out of the narrative unless the user asks for technical detail.

1. Banned words/phrases: workstream, artifact, canonical, process drift,

touchpoint, formally, standardized, operationally, implementation, ad hoc, scope (as jargon — the structural Scope section header is exempt), aligned, resolution, "it is suitable for", "this reduces the chance of", "without X, Y is easier to Z", "not explicitly visible in commit history", any bullet phrase over 15 words.

1. If logic changed, add one sentence a 5th grader could understand inside

the Change section: Simple logic explanation: .

1. Write like telling a coworker what you did today — not a formal document.

Avoid vague verbs ("enhanced", "optimized", "improved") without saying what changed in behavior. Without exact metrics, use directional impact grounded in observed behavior. Never state anything not supported by the workspace, git history, or context the user provided.

Generation modes

• Date-based (a date or range) — filter local git history by date, group by project, cluster commits.
• Session summary — combine session-modified files, notes, and diffs into logical improvements.
• Feature summary — the feature's commits explained as one Problem → Change → Impact story.

Git data collection

Never run git fetch, git pull, or anything that modifies local git state. Read only what is already available locally.

Multi-repo workspaces

1. Find every git root in the workspace:

``bash find -maxdepth 3 -name ".git" | sed 's/\/.git$//' ` No -type d — in worktrees and submodules .git` is a file; filtering to directories silently drops those projects.

1. Run the log in each repo, never only the workspace root:

``bash git log --all --after="YYYY-MM-DDT00:00:00" --before="YYYY-MM-DDT23:59:59" --oneline --no-merges ` Before presenting a cluster, verify it reached the default branch (git branch --contains ); work that hasn't is labeled "in progress on `" in its Summary, never mixed silently into shipped notes.

1. If the user names a project and no commits are found, say so explicitly:

"No commits found for on . The local branch may not be up to date — try running git pull in that repo." Never silently omit a project.

Project discovery

Map commits to projects via the AGENTS.md Project Matrix, repo docs, paths, or user context. Name the full PROJECT-CODE from the Project Matrix everywhere; never mix one project's conventions, tokens, or components into another.

Agent use

Sub-agents: dispatch local lanes automatically for independent work — never cloud agents; announce the lane count at dispatch and report each lane as it completes. Split lanes by repo, date range, or feature cluster; lanes return summaries — commit hashes, affected files, user-visible changes, likely grouping, uncertainty — never transcripts; the main session owns clustering, plain-language rewriting, QA-step quality, and file output.

Emit Stage / Found / Next / Needs user at each phase transition — one line per field.

Commit clustering

Never narrate commit-by-commit — cluster related commits into one PM-facing Problem → Change → Impact change. Commits sharing a product, feature or workflow, bug, file area, or one objective cluster together (iterative and bugfix sequences included); when uncertain, keep them separate.

Output format

One markdown file, filled from the mode's asset skeleton — the skeletons are the single format source:

• Date-based / date-range / feature mode →

[assets/release-notes-template.md](assets/release-notes-template.md)

• Session summary →

[assets/session-summary-template.md](assets/session-summary-template.md)

Worked examples live in [references/examples.md](references/examples.md); load when unsure how an entry should read.

Filling rules:

• Stakeholder Summary is the 30-second scan: each PROJECT-CODE as plain

text on its own line (no heading syntax), one bullet per feature combining Summary + Change into a single sentence; Date: line omitted for undated session summaries.

• Repeat the feature block for multiple features under one project;

feature sections sit under their project heading.

• Manual QA Steps: 3–5 practical steps per feature, each

Action -> Expected Result, covering the primary happy path and one edge case, written so a manual tester needs no code knowledge.

• Include only projects with at least one confirmed change in the selected

scope.

• User-visible detail goes on the optional What changed where: line

under Change — the setting, page/screen, element, or route, only when commits/diffs reveal it; otherwise omit the line (rule 8 bans disclaimer wording).

• Commit hashes appear only under Commits Included, one per bullet (the

session skeleton's (uncommitted session work) fallback covers no-commit sessions).

File output

Save under /specs/release-notes/.

Release notes are a generated document: keep all co-author, AI, and tool attribution out of both the saved file and the chat response.

Resolve `: the *.code-workspace directory if one exists, else the per-context root (CONTEXT-MAP.md at repo root), else the repo root. Multi-repo workspaces *without* a .code-workspace file get one file per repo, under each repo's own specs/release-notes/`.

Filenames — D-Month-YYYY, no leading zero, Title Case English month: 10-March-2026.md; date ranges 10-March-2026-to-12-March-2026.md.

• Feature summaries use the release date, not the feature name; if no date

is given and the user doesn't clearly mean the current session, ask — or, if the user is away, use the current local date and note the assumption up top.

• "Today" / "current session" → the current local date.
• Do not add NNNN, -release-notes, or a feature slug to the filename —

release notes do not share the ADR/prompt NNNN sequence.

Conflict handling: overwrite a same-date file only if it contains purely generated content from this skill; if it has hand edits, show the diff and ask (overwrite, append/update, or abort) — and if the user is away, write a (2)-suffixed sibling file instead and say so; never overwrite hand edits unconfirmed. Never delete unrelated files.

Completion criteria

• [ ] The saved file contains zero rule-8 banned words in narrative text

(Scope header exempt), no bullet over 15 words, no Problem/Change/Impact section over 2 content bullets.

• [ ] Each file exists at specs/release-notes/.md under the

resolved root and re-opens matching the loaded skeleton's structure, with only changed projects present.

• [ ] Every cluster presented as shipped passed git branch --contains or

carries its "in progress on ``" label.

• [ ] At least one bullet names an affected workflow or team.
• [ ] Every Manual QA step is Action -> Expected Result naming a screen,

button, or field; every Impact bullet states a behavior change.

• [ ] The reply states each saved file path and ends with

Suggested next skills (optional) — 1–3 advisory suggestions, never gating.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: devarfeen
• Source: devarfeen/agent-skills-kit
• License: MIT

Install and usage instructions live in the source repository linked above.