Generate clear, structured release notes or session summaries for Project Managers based on development activity.
The skill can produce summaries from:
Git commits
Current development session
Completed feature work
Outputs must explain what changed, why it changed, and the improvement delivered, using simple language suitable for non-technical stakeholders.
Default audience is Project Managers and operations stakeholders, not engineers.
Writing Style Rules
The #1 priority of this skill is clarity for non-technical readers. Every sentence must pass this test: "Would a PM or QA person understand this without asking a developer?"
Absolute Rules
Use plain, everyday words. No jargon. No corporate-speak. No 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"
Verwandte Skills
Say what the user sees or does. Name the screen, button, field, or page.
BAD: "Concrete touchpoints called out in the workstream docs include the signin page"
GOOD: "Affects the Login page, Sign Up page, and Reset Password page"
One idea per bullet. Each bullet = one short sentence. Never a paragraph.
BAD: "Two implementation workstreams were documented and broken down for execution covering username lowercasing and consistent password show/hide behavior across login, signup, reset, invite, and user-management screens."
GOOD:
"Usernames will be saved as lowercase so 'John' and 'john' are treated the same"
"All password fields now have a show/hide toggle"
Feature names must describe what changed, not how it was done.
BAD: "Auth Hardening Workstreams Prepared"
GOOD: "Login and Password Improvements Planned"
BAD: "Workspace Process Rules Clarified"
GOOD: "Updated Internal Team Workflow Guide"
No filler phrases. Remove words that add no meaning.
Remove: "formally prepared", "in a clear scope", "as a result of", "in order to"
Remove: "it should be noted that", "this ensures that", "with a clear"
Avoid abstract language. Be specific about what happened.
BAD: "reduces the risk of one screen being fixed while another screen keeps the same login or password-typing problem"
GOOD: "All login screens now behave the same way"
Problem section = what the user experienced. Not what the code lacked.
BAD: "Without a written design and task breakdown, this type of security-sensitive work is easier to implement inconsistently"
GOOD: "Some login pages let you toggle password visibility, others didn't. Usernames 'John' and 'john' were treated as different accounts."
Impact section = what is better now. One short sentence per bullet. Concrete outcome.
BAD: "Engineering now has approved-ready implementation notes for sensitive auth work instead of relying on ad hoc fixes"
GOOD: "Login will work the same way across all apps"
Max 2 bullets per section (Problem, Change, Impact). If you need more, you're being too detailed — combine or simplify.
Write like you're telling a coworker what you did today over a coffee. Not like you're writing a formal document.
Banned Words and Phrases
Never use these in release notes output:
workstream, artifact, canonical, process drift, touchpoint
--all includes commits from all local branches (catches work merged into any branch).
--no-merges skips merge commit noise like "Merge pull request #123".
For richer detail, use --format="%H %s" instead of --oneline.
Finding Repos Automatically
find <workspace-root> -name ".git" -type d -maxdepth 3 | sed 's/\/.git$//'
Then loop through each path and run git log inside it.
Important
If a user mentions a specific project/repo and the skill finds no commits, report that explicitly. Do not silently omit projects — say "No commits found for <Project> on <date>. The local branch may not be up to date — try running git pull in that repo."
Automatic Commit Clustering
When generating release notes from Git history, do not summarize each commit separately unless the commits clearly represent unrelated work.
Instead, automatically cluster related commits into one logical change so the output reads like PM-facing release notes rather than raw engineering history.
Goal
Convert multiple implementation commits into one stakeholder-friendly summary using:
Problem → Change → Impact
Cluster Commits Together When They Share
the same product, app, or module
the same feature or workflow
the same bug or user problem
the same file area or code path
the same implementation objective across several commits
Keep Commits Separate When They Represent Different
products
workflows
features
bugs with unrelated causes
independent user-facing changes
Stakeholder Summary Section
Every release notes file must start with a Stakeholder Summary section at the top, before the detailed notes.
This section is the quick-read version for PMs and stakeholders. It combines the Summary and Change from each feature entry into short bullet points grouped by date and project code.
Format
# Stakeholder Summary
Date: DD Month YYYY
PRODUCT-CODE-1
- What changed + why it matters in one sentence
- What changed + why it matters in one sentence
PRODUCT-CODE-2
- What changed + why it matters in one sentence
Rules
Start with Date: DD Month YYYY (omit for session summaries that have no date).
Product codes in ALL CAPS (e.g., PARTNERS-APP, PORTFOLIO-WEB, SERVER-REVERSE-PROXY). No markdown heading syntax — plain text on its own line.
Each change is a markdown bullet (- ). One bullet per feature.
Each bullet combines Summary + Change into one sentence that answers: "What changed and what does that mean for the user?"
Write bullets so a PM can scan the entire list in under 30 seconds.
Group by product/app, same grouping as the detailed section below.
Separate the Stakeholder Summary from the Detailed Release Notes with a horizontal rule (---).
The detailed section follows under a # Detailed Release Notes heading.
Manual QA Steps Section
Every feature entry in the detailed release notes must include a Manual QA Steps subsection.
Finding Existing QA Steps
Before generating QA steps, search for an existing 5-manual-qa-steps.md file:
Look in the feature's specs folder (e.g., specs/5-manual-qa-steps.md, specs/<feature-name>/5-manual-qa-steps.md, or any **/specs/5-manual-qa-steps.md path relative to the feature's code).
If found, link to it: See [Manual QA Steps](relative/path/to/specs/5-manual-qa-steps.md)
Also include the key steps from that file inline so the release note is self-contained.
Generating QA Steps
If no 5-manual-qa-steps.md file exists, generate 3–5 practical manual QA steps based on the change:
Each step must be: Action → Expected Result
Steps should cover the primary happy path and one edge case.
Write steps a manual tester can follow without reading the code.
Keep language simple and specific (name the screen, button, or field).
Clustering Heuristics
Infer that commits belong together when several commits:
touch the same files or folders
use similar wording in commit messages
refer to the same screen, flow, or process
appear to be iterative work on one feature
are clearly part of one bugfix sequence
Summarization Rules
For each cluster:
identify the shared problem
combine all related commits into one logical summary
explain the change in non-technical language
describe the resulting improvement
avoid commit-by-commit narration unless necessary
Project Discovery
Project names and codes may be found from:
repository documentation
workspace metadata
git repository paths
folder structure
user-provided context
Output Format
Output must follow the exact structure below. Do not reorder sections.
For date-based release notes, include a date line at the top.
Date: <DD Month YYYY>
<Product / App Name>
<Feature or Improvement Name>
Summary
One sentence: what is now better in day-to-day operations.
Problem
What users or operations teams were experiencing before this change
Include the business consequence (delays, rework, missed scans, confusion, etc.)
Change
Explain the solution in product/workflow language
Name affected workflows or screens in plain language
Include 1 to 3 concrete user-visible touchpoints when available: setting, view/page, component/screen section, URL/route, or visible UI element
If logic changed, add one simple sentence in plain language for a 5th grader
Do not include file paths, class names, package names, or internal module names
Impact
State concrete outcomes, not generic claims
Prefer specific statements such as "fewer failed scans during stock take" over "improved reliability"
Scope
Who is affected (teams, roles, or flows) and where the change applies
Commits Included
List commit hashes only at the end for traceability
If there are multiple features under one project, repeat the feature block:
<Feature or Improvement Name>
Summary
Problem
Change
Impact
Scope
Commits Included
Do not place feature sections above the project header.
Project Inclusion Rule
Include a project section only if that project has at least one confirmed change in the selected commits/session scope.
Do not include unchanged projects in the final generated file.
File Output Rules
Always save the generated markdown under the root changelog/ folder.
Date-based summary or release notes:
Path: changelog/DD-Month-YYYY.md
Example: changelog/12-March-2026.md
Feature-based summary:
Path: changelog/Feature-Name.md
Use Title-Case words joined with hyphens
Example: changelog/RFID-Scanner-Reliability.md
Session summary without explicit feature name:
Path: changelog/DD-Month-YYYY.md
If changelog/ does not exist, create it before writing output.
Section Hierarchy Rule
The hierarchy must be:
Date line (date-based only)
Project Name
Feature Name
Child sections under feature: Summary, Problem, Change, Impact, Scope, Commits Included
Never output child sections directly under the date line or without a feature heading.
Writing Guidelines
Write for non-technical stakeholders
Translate implementation details into user-facing outcomes
Avoid unnecessary engineering terminology
Focus on what improved and how it affects operations
Prefer short bullet points
Avoid vague wording such as "enhanced", "optimized", or "improved" without saying what changed in behavior
If exact metrics are unavailable, use directional impact grounded in observed behavior
Git Detail Extraction Rules
When generating from git commits/diffs, explicitly extract and summarize user-visible change locations when present.
Look for and report in plain language:
Main setting changed (for example scanner power, timeout, toggle defaults)
View/page/screen affected
Component or visible screen section affected
URL or route changed (if available and user-visible)
Visible element changed (button label, status text, warning, banner, modal, etc.)
Prefer naming what users see over code object names.
If details are not available in commits/diffs, say "Not explicitly visible in commit history" instead of guessing.
Simple Logic Explanation Rule
If a feature includes programming logic changes, add a plain-language explanation inside the Change section.
Format:
Simple logic explanation: <one sentence a 5th grader can understand>
Example:
Simple logic explanation: Raised scanner power from 20 to 30 and made the app switch it on every time before scanning.
Translation Rules
When source input contains engineering details, rewrite them as operational meaning.
Examples:
"added API classes/interfaces" -> "connected scanner capabilities so app screens use the same scan process"
File is saved in changelog/ with correct naming convention.
Change section includes user-visible touchpoints when commit history provides them.
Logic changes include one simple sentence understandable by non-technical readers.
Final file includes only projects that have confirmed changes.
Fallback
If clustering is uncertain, keep commits separate rather than merging unrelated work.
Do not speculate about changes not present in the workspace, git history, or provided context.