Release Notes

Release Notes

Purpose

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

1. 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"

2. 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"

3. 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"

4. 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"

5. 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"

6. 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"

7. 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."

8. 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"

9. Max 2 bullets per section (Problem, Change, Impact). If you need more, you're being too detailed — combine or simplify.

10. 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
• formally, standardized, operationally, implementation
• ad hoc, scope, aligned, resolution
• "it is suitable for", "this reduces the chance of"
• "without X, Y is easier to Z" (rewrite as a direct statement)
• "not explicitly visible in commit history"
• Any phrase longer than 15 words in a single bullet

Writing Test

Before finalizing each feature entry, mentally check:

• Can a PM read this in 10 seconds and know what changed?
• Can a QA person read this and know what to test?
• Would you understand this if you had never seen the code?

If any answer is no, rewrite it simpler.

Supported Generation Modes

1. Date-Based Release Notes (Git History)

Generate release notes from Git commits for a specific date.

Example prompts:

• Generate release notes for 11 March 2026
• Generate release notes for 11 March for all projects
• Generate release notes for PARTNERS-APP on 11 March

Behavior:

1. Read git commit history 2. Filter commits by the requested date 3. Group commits by full project code, app, or module 4. Combine related commits into a single logical improvement summary

2. Session-Based Development Summary

Generate a summary of changes made in the current development session.

Example prompts:

• Summarize what we changed this session
• Create PM update for today's work
• Generate session release notes

Behavior:

1. Review files modified in the session 2. Review developer notes, markdown previews, and code diffs 3. Combine related edits into logical improvements 4. Present them grouped by full project code

3. Feature-Based Summary

Generate release notes for a completed feature or task.

Example prompts:

• Write release notes for the RFID scanning improvements
• Summarize the Stock Take lookup changes
• Create PM update for the asset lookup improvements

Behavior:

1. Identify commits related to the feature 2. Combine commits into a single feature explanation 3. Explain Problem → Change → Impact

Git Data Collection

The skill must NOT run git fetch, git pull, or any command that modifies the local git state. It only reads what is already available locally.

Agent Use

When the runtime supports subagents and the user has allowed them, act as the orchestrator and use read-only Explorer lanes for independent collection and summarization. Use local subagents only — never cloud agents. See the agents-md tool-calling.md reference for the role-to-mechanism map per runtime.

• Run multiple Explorer lanes in parallel for separate repos, date ranges, or clearly independent feature clusters; push long history scans to local background where supported.
• Ask each Explorer to return commit hashes, affected files, visible user-facing changes, likely grouping, and uncertainty — summaries, not raw transcripts.
• Keep the main session responsible for final clustering, plain-language rewriting, QA-step quality, conflict resolution, and file output.
• Do not use Implementer (write) lanes for release notes unless the user explicitly asks for file-writing delegation.

Multi-Repo Workspaces

If the workspace contains multiple repositories (multi-root workspace with several git repos):

1. Find all git roots. Walk the workspace folder tree and identify every directory that contains a .git folder. Each is a separate project repo. 2. Run `git log` in each repo separately. Do not assume the workspace root is the only git repo. 3. Collect commits from all repos, then group by full project code.

Missing a repo means missing an entire project's release notes. Always scan for all git roots.

Git Log Command

Use this command pattern in each repo to get commits for a specific date:

git log --all --after="YYYY-MM-DDT00:00:00" --before="YYYY-MM-DDT23:59:59" --oneline --no-merges

• --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 full project code.

Format

# Stakeholder Summary

Date: DD Month YYYY

PROJECT-CODE-1

- What changed + why it matters in one sentence
- What changed + why it matters in one sentence

PROJECT-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).
• Use full project codes from the Project Matrix (e.g., PARTNERS-APP, PORTFOLIO-WEB, SERVER-REVERSE-PROXY). Never abbreviate or invent shorthand. 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 full project code, 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.

Generating QA Steps

Generate 3–5 practical manual QA steps inline 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:

1. identify the shared problem 2. combine all related commits into one logical summary 3. explain the change in non-technical language 4. describe the resulting improvement 5. avoid commit-by-commit narration unless necessary

Project Discovery

Project names and codes may be found from:

• Project Matrix entries in AGENTS.md
• repository documentation
• workspace metadata
• git repository paths
• folder structure
• user-provided context

When a Project Matrix code exists, use the full code exactly as written in chat output, saved release notes, and any related issue, PR, commit, or code-comment text.

Output Format

Output must follow the exact structure below. Do not reorder sections.

# Stakeholder Summary

Date: <DD Month YYYY>

<PROJECT-CODE>

- <one sentence summary>

---

# Detailed Release Notes

## <PROJECT-CODE>

### <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>

**Change**

- <what changed in product/workflow language>

**Impact**

- <concrete outcome>

**Scope**

- <who is affected and where the change applies>

**Manual QA Steps**

1. <Action> -> <Expected result>

**Commits Included**

- <hash>

For session summaries without a known date, omit only the Date: line.

If there are multiple features under one project, repeat the feature block:

<Feature or Improvement Name>

• Summary
• Problem
• Change
• Impact
• Scope
• Manual QA Steps
• 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 <artifacts-root>/docs/release-notes/. Release notes are on-demand date-based artifacts; they do not share the ADR/prompt NNNN sequence and they do not live beside ADRs. ADRs live in docs/adr/ with NNNN-<slug>.md; feature prompts live in docs/prompts/ with NNNN-<slug>-prompt.md; release notes live separately under docs/release-notes/ with calendar-date filenames like 10-March-2026.md.

Resolving <artifacts-root>

Centralize artifacts when a workspace exists; only fall back to a project repo when there's no workspace. Resolve in this order:

1. VS Code workspace (preferred when present). If a *.code-workspace file is found at or above the cwd, write to the directory containing it. All projects in the workspace share one docs/release-notes/. 2. Multi-context single repo. If no workspace file but a root CONTEXT-MAP.md exists, use the docs/release-notes/ of the context the change belongs to. 3. Single-repo project. Fall back to the repo root.

For multi-repo workspaces _without_ a .code-workspace file, write one file per repo under that repo's own docs/release-notes/.

Path shape

<artifacts-root>/docs/release-notes/<date-slug>.md

• `docs/release-notes/` — relative to <artifacts-root> resolved above.
• `<date-slug>` — D-Month-YYYY, using no leading zero for the day and Title Case English month names. Example: 10-March-2026.
• Do not add NNNN, -release-notes, or a feature slug to the default filename.

Slug per mode

1. Date-based release notes (`Date: <DD Month YYYY>`):

• Path: <artifacts-root>/docs/release-notes/D-Month-YYYY.md
• Example (workspace): <workspace-dir>/docs/release-notes/10-March-2026.md
• Example (single repo): docs/release-notes/10-March-2026.md

2. Feature-based summary:

• Use the release date as the filename, not the feature name. If the user does not provide a release date, ask for one unless they clearly mean today's current session.
• Example (workspace): <workspace-dir>/docs/release-notes/10-March-2026.md
• Example (single repo): docs/release-notes/10-March-2026.md

3. Session summary without explicit feature name:

• If the user says "today" or "current session", use the current local date.
• Example (workspace): <workspace-dir>/docs/release-notes/10-March-2026.md
• Example (single repo): docs/release-notes/10-March-2026.md

4. Date range release notes:

• Path: <artifacts-root>/docs/release-notes/D-Month-YYYY-to-D-Month-YYYY.md
• Example: 10-March-2026-to-12-March-2026.md

Conflict handling

• If <artifacts-root>/docs/release-notes/ does not exist, create it lazily before writing.
• If a release note file already exists for the same date and contains only generated content from this skill, overwrite in place.
• If the existing file contains hand edits, show the diff and ask the user whether to overwrite, append/update the existing date file, or abort.
• Never delete unrelated files in docs/release-notes/.

Section Hierarchy Rule

The hierarchy must be:

1. # Stakeholder Summary 2. Optional Date: DD Month YYYY 3. Full project code with summary bullets 4. --- 5. # Detailed Release Notes 6. Full project code heading 7. Feature name heading 8. Child sections under feature: Summary, Problem, Change, Impact, Scope, Manual QA Steps, Commits Included

Never output child sections directly under the date line, stakeholder summary, detailed notes heading, or project 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, omit that detail and keep the note grounded in what is visible. Do not write "Not explicitly visible in commit history" in the release notes output.

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"
• "refactored useRfidScanner" -> "standardized scanner setup to reduce inconsistent scan starts"
• "added test coverage" -> "reduced regression risk by validating scanner setup behavior"

Do not copy code identifiers directly into PM output unless the user explicitly asks for technical detail.

Quality Check Before Finalizing

Before returning output, verify:

1. A PM can understand it without code context. 2. Each impact bullet describes an observable operational outcome. 3. At least one bullet names affected workflows or teams. 4. Technical identifiers are removed from the main narrative. 5. Commit hashes, if included, appear in a final traceability line only. 6. Output follows Stakeholder Summary -> Detailed Release Notes -> Project -> Feature -> Child sections hierarchy. 7. File is saved in docs/release-notes/ with the D-Month-YYYY.md naming convention, independent of the ADR/prompt number sequence. 8. Change section includes user-visible touchpoints when commit history provides them. 9. Logic changes include one simple sentence understandable by non-technical readers. 10. Final file includes only projects that have confirmed changes. 11. End the response with Suggested next skills (optional) using 1-6 advisory suggestions only (no gating), based on what the user should likely do next.

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.

Stakeholder Summary

Date: <DD Month YYYY>

<PROJECT-CODE-1>

• <What changed + why it matters — combines Summary and Change into one sentence>
• <What changed + why it matters — combines Summary and Change into one sentence>

<PROJECT-CODE-2>

• <What changed + why it matters — combines Summary and Change into one sentence>

---

Detailed Release Notes

<PROJECT-CODE>

<Plain-language name for the change — what the user sees, not how it was built>

Summary

• <One sentence: what is better now, written so a PM understands in 5 seconds>

Problem

• <What the user or team experienced — describe the symptom, not the code>
• <Max 2 bullets>

Change

• <What changed, in words a non-developer understands — name the screen, page, or button>
• <Max 2 bullets. One idea per bullet. No paragraphs.>

Impact

• <What is better now — one short sentence>

Scope

• <Which screen/app/user group is affected>

Manual QA Steps 1. <Do X → Y should happen> 2. <Do X → Y should happen> 3. <Do X → Y should happen>

Commits Included

• <commit-hash-1>, <commit-hash-2>

Stakeholder Summary

<PROJECT-CODE>

• <What changed + why it matters — combines Summary and Change into one sentence>

---

Detailed Release Notes

<PROJECT-CODE>

<Improvement Name>

Summary

• <One sentence: what is better now>

Problem

• <What issue or limitation existed>

Change

• <What was changed in this session>

Impact

• <What improved as a result>

Scope

• <Which screen/app/user group is affected>

Manual QA Steps 1. <Do X → Y should happen> 2. <Do X → Y should happen> 3. <Do X → Y should happen>

Commits Included

• <commit-hash-1>, <commit-hash-2>

release-notes

Generate PM-friendly release notes from git commits, session work, or completed feature work.

Install

npx skills install https://github.com/devarfeen/agent-skills-kit --skill release-notes

Update

npx skills update https://github.com/devarfeen/agent-skills-kit --skill release-notes

Supports

• Date-based release notes (single date or date range)
• All-project or single-project summaries
• Session summaries (current dev session)
• Feature summaries (completed feature/task)
• Automatic commit clustering (related commits → one logical change)
• Stakeholder summary (quick-scan one-liner list at the top)
• Manual QA steps (auto-detected from specs or generated)

Example Requests

• Generate release notes for 11 March 2026
• Generate release notes for PARTNERS-APP on 11 March
• Generate release notes for all projects on 15 April
• Summarize today's development session
• Write release notes for the RFID scanning improvements
• Summarize what we changed this session
• Create PM update for today's work

Output Style

Uses a two-part structure in a single file:

Part 1: Stakeholder Summary (top of file)

Quick-read bullet list structured as: Date → Project Code → Bullet points. Each bullet combines what changed and why it matters into one sentence. Designed for PMs who need to scan everything in 30 seconds.

Part 2: Detailed Release Notes (after --- separator)

Full structured entries per feature:

• Date (date-based mode only)
• Project
• Feature
• Summary
• Problem
• Change
• Impact
• Scope
• Manual QA Steps
• Commits Included

Required section order is strict: Stakeholder Summary -> optional Date -> --- -> Detailed Release Notes -> Project -> Feature -> Child sections.

Only include project sections that have confirmed changes in the selected commit/session scope.

Manual QA Steps

Each feature entry includes a Manual QA Steps section:

• 3–5 practical QA steps are generated inline (Action → Expected Result format).
• Steps cover the primary happy path and one edge case, written so a manual tester can follow them without reading the code.

Detail Level

• For git-based outputs, include concrete "what changed where" details when available:

setting, page/view, component section, URL/route, or visible UI element.

• If programming logic changed, include one plain-language sentence understandable by a 5th grader.
• If a detail is not present in commit history, state that clearly instead of guessing.

Output File Location

• Save all generated notes under <artifacts-root>/docs/release-notes/. Release notes are on-demand date files and do not share the ADR/prompt NNNN sequence. Feature prompts (-prompt) live in the sibling <artifacts-root>/docs/prompts/ folder.
• Resolve <artifacts-root> in this order: (1) directory containing a *.code-workspace file if one exists, (2) per-context root in a multi-context repo (CONTEXT-MAP.md at root), (3) the single repo root. Workspace mode is preferred — it keeps artifacts out of individual project repos.
• Date-based, feature, or session summary: <artifacts-root>/docs/release-notes/D-Month-YYYY.md (workspace example: <workspace-dir>/docs/release-notes/10-March-2026.md; single repo: docs/release-notes/10-March-2026.md)
• Date range summary: <artifacts-root>/docs/release-notes/D-Month-YYYY-to-D-Month-YYYY.md (example: 10-March-2026-to-12-March-2026.md)
• Date filenames use no leading zero for the day and Title Case English month names.

The output is designed for Project Managers and other non-technical stakeholders.

File Structure

skills/release-notes/
├── SKILL.md                            # Core skill instructions (required)
├── README.md                           # This file
├── references/
│   ├── examples.md                     # Full input/output examples
│   └── triggers.md                     # Trigger phrases
└── assets/
    ├── release-notes-template.md       # Date/feature release notes template
    └── session-summary-template.md     # Session summary template

This follows the Agent Skills spec folder conventions: references/ for on-demand documentation, assets/ for static templates.

Examples

Example 1: Date-Based Release Notes

User Request

Generate release notes for 11 March 2026

Example Input

• fix: RFID power initialization
• fix: retry RFID reader setup
• fix: prevent scan before reader ready
• feat: verify scanner power before lookup
• feat: add activity tracking for field support
• fix: filter component asset list in Collection Package
• feat: verification warnings for QR/RFID data mismatches
• fix: Android app startup crash
• fix: photo selection crash on Android

Example Output

Stakeholder Summary

Date: 11 March 2026

PARTNERS-APP

• App now checks the scanner is ready before starting a scan, so first-try scans no longer fail
• New Activity Log in Field Support screen lets support see what a partner did on their device
• Collection Package screen now filters out unrelated assets so the list is cleaner
• Warning shown when a QR code and RFID tag don't match on the same asset
• Fixed crash on Android when opening the app or selecting photos

---

Detailed Release Notes

PARTNERS-APP

Scanner Now Checks Readiness Before Scanning

Summary

• The app waits for the scanner to be ready before starting a scan, so scans don't fail on the first try.

Problem

• Scans sometimes failed when the scanner wasn't ready yet, forcing staff to retry.

Change

• The app now shows a "Ready" status before allowing scans on the Stock Lookup screen.
• If the scanner isn't responding, the app retries automatically instead of failing.

Impact

• Fewer failed scans and retries during busy shifts.

Scope

• Stock Lookup screen in PARTNERS-APP.

Manual QA Steps 1. Open Stock Lookup and start a scan → "Ready" status should appear before the scan begins. 2. Start a scan right after opening the app → Scan should wait for the scanner, not fail. 3. Unplug the scanner briefly, then try again → App should retry and recover on its own.

Commits Included

• abc1234, def5678, ghi9012, jkl3456

Support Teams Can View Partner Activity Logs

Summary

• Field support can now see a log of what a partner did on their device, making troubleshooting faster.

Problem

• Support had no way to see what happened on a partner's device and had to call them to ask.

Change

• New Activity Log section in the Field Support screen shows recent partner actions with timestamps.

Impact

• Support can troubleshoot without calling the partner.

Scope

• Field Support screen in PARTNERS-APP.

Manual QA Steps 1. Log in as field support and open a partner's Activity Log → Recent actions should appear with timestamps. 2. Do a few actions as a partner (scan, lookup, submit), then check the log → All actions should be listed. 3. Filter the log by date → Only matching entries should show.

Commits Included

• mno7890

Example 2: Single Project on a Date

User Request

Generate release notes for PARTNERS-APP on 11 March

Example Output

Stakeholder Summary

Date: 11 March 2026

PARTNERS-APP

• App now checks the scanner is ready before starting a scan, so first-try scans no longer fail

---

Detailed Release Notes

PARTNERS-APP

Scanner Now Checks Readiness Before Scanning

Summary

• The app waits until the scanner is ready before starting, so scans don't fail on the first try.

Problem

• Scans sometimes failed when started before the scanner was ready.

Change

• Stock Lookup screen now shows a "Ready" indicator before scans can begin.
• App retries automatically if the scanner is slow to connect.

Impact

• Fewer failed scans during stock checks.

Scope

• Stock Lookup screen in PARTNERS-APP.

Manual QA Steps 1. Open Stock Lookup and start a scan → "Ready" indicator should appear first. 2. Switch between screens and scan again → Each scan should wait for readiness. 3. Start a scan with a slow connection → App should show "waiting" then proceed.

Commits Included

• abc1234, def5678

Example 3: Session Summary

User Request

Summarize today's development session

Example Output

Stakeholder Summary

PARTNERS-APP

• All scanner screens now use the same setup process, so scanning works reliably everywhere

---

Detailed Release Notes

PARTNERS-APP

Consistent Scanner Setup Across All Screens

Summary

• All screens that use the scanner now prepare it the same way, so scanning works reliably everywhere.

Problem

• Some screens prepared the scanner differently, causing scans to sometimes fail on certain pages.

Change

• All scanner screens now use the same setup process and show a retry message if the scanner isn't ready.

Impact

• Scanning works the same way no matter which screen you're on.

Scope

• All scanner-enabled screens in PARTNERS-APP.

Manual QA Steps 1. Open any scanner screen and start a scan → Scanner should finish setup before scan begins. 2. Try scanning on 3 different screens → All should behave the same way. 3. Turn Bluetooth off and on, then scan → App should show a retry message and recover.

Example 4: Bad vs Good (Writing Style Reference)

This example shows the same work described in bad (verbose/corporate) style vs good (clear/simple) style.

Bad Output (DO NOT generate like this)

### Auth Hardening Workstreams Prepared

**Summary**
- The next round of login and password-handling improvements for the Partners and Portfolio platforms was formally prepared so implementation can move with a clear scope and QA target.

**Problem**
- Follow-up work was still needed around username casing, password visibility, and stronger password rules across multiple auth flows.
- Without a written design and task breakdown, this type of security-sensitive work is easier to implement inconsistently across products.

**Change**
- Two implementation workstreams were documented and broken down for execution:
- Partners portal follow-up work covering username lowercasing and consistent password show/hide behavior across login, signup, reset, invite, and user-management screens.
- Portfolio auth hardening covering username lowercasing, stronger password requirements when setting a password, and password show/hide coverage in staff and gallery user-management flows.
- Concrete touchpoints called out in the workstream docs include the signin page, signup flow, reset and force-change password pages, invite flow, staff password screens, and gallery user forms.

**Impact**
- Engineering now has approved-ready implementation notes for sensitive auth work instead of relying on ad hoc fixes.
- This reduces the risk of one screen being fixed while another screen keeps the same login or password-typing problem.

Good Output (Generate like this)

### Login and Password Improvements Planned

**Summary**
- Planned fixes for how usernames and passwords work across Partners and Portfolio apps.

**Problem**
- "John" and "john" were treated as different accounts. Some password fields had a show/hide toggle, others didn't.

**Change**
- Wrote the plan for: making usernames always lowercase, adding show/hide to all password fields, and requiring stronger passwords.
- Covers: Login, Sign Up, Reset Password, Invite, and User Management pages in both apps.

**Impact**
- Once built, all login pages will work the same way across both apps.

What makes the good version better

• Feature name says what changed ("Login and Password Improvements") not how ("Auth Hardening Workstreams")
• Problem describes what the user experienced, not what the code lacked
• Each bullet is one short sentence
• No jargon: no "workstreams", "touchpoints", "ad hoc", "formally prepared"
• A PM can read it in 10 seconds and know exactly what's happening

User Request

Write release notes for the RFID scanning improvements

Example Output

PARTNERS-APP

RFID Scanning Improvements

Summary

• RFID workflows now follow a more consistent scan startup process.

Problem

• Scan attempts could fail when startup steps were incomplete in certain flows.

Change

• Standardized scanner setup before scan actions.
• Added readiness checks and controlled retry handling.
• What changed where: RFID scan pages and scan action controls used by front-line teams.
• Simple logic explanation: The app turns the scanner setup steps into the same repeatable checklist every time.

Impact

• Fewer startup-related scan failures.
• Reduced operational interruptions in RFID workflows.
• More reliable scan behavior for front-line users.

Scope

• Applies to RFID scanning flows covered by this feature.

Example 5: Omit Unchanged Projects

User Request

Generate release notes for 12 March 2026 across all projects

Example Input

• PARTNERS-APP commits found for 12 March 2026
• WAREHOUSE-ADMIN commits found for 12 March 2026
• No commits found for CUSTOMER-PORTAL on 12 March 2026

Example Output Rule

• Include PARTNERS-APP and WAREHOUSE-ADMIN sections.
• Do not include CUSTOMER-PORTAL because it has no confirmed changes.

Example Output

Stakeholder Summary

Date: 12 March 2026

PARTNERS-APP

• Scanner startup is more consistent, so teams see fewer failed first scans

WAREHOUSE-ADMIN

• Intake warnings are clearer, so users can fix missing fields before submitting

---

Detailed Release Notes

PARTNERS-APP

RFID Scanner Reliability

Summary

• Scanner startup became more consistent in daily operations.

Problem

• Teams faced failed first scans in some operational flows.

Change

• Standardized scanner startup behavior across updated flows.
• What changed where: scan setup setting and scan status indicator.

Impact

• Fewer failed first-scan attempts.

Scope

• RFID-enabled operational flows in PARTNERS-APP.

Manual QA Steps 1. Open an RFID scan screen -> Scan status should be visible before scanning. 2. Start a scan -> The first scan should complete without a startup failure. 3. Leave and return to the scan screen -> Scanner setup should still behave the same way.

Commits Included

• 148cfb8f, f626e8fa

WAREHOUSE-ADMIN

Intake Validation Clarity

Summary

• Intake warnings are clearer before submission.

Problem

• Users missed required fields during intake.

Change

• Added clearer required-field guidance in intake screens.
• What changed where: intake page warning banner and submit-state message.

Impact

• Fewer intake retries due to missing fields.

Scope

• Intake flow for warehouse supervisors.

Manual QA Steps 1. Open the intake page with a missing required field -> A clear warning should appear. 2. Fill the missing field -> The warning should clear. 3. Submit a complete intake form -> The form should submit normally.

Commits Included

• a1b2c3d4

Example 6: Output File Naming

Release notes live in <artifacts-root>/docs/release-notes/. They are on-demand date files and do not use the ADR/prompt NNNN sequence. Feature prompts (-prompt) live in the sibling <artifacts-root>/docs/prompts/ folder.

<artifacts-root> resolves to (1) the directory containing the *.code-workspace file when a VS Code workspace is present, (2) the per-context root in a multi-context repo (CONTEXT-MAP.md at root), or (3) the repo root for single-repo projects. Workspace mode is preferred — it keeps artifacts out of individual project repos.

User Request

Generate release notes for 12 March 2026

Expected Output File

• Workspace mode: <workspace-dir>/docs/release-notes/12-March-2026.md
• Single repo: docs/release-notes/12-March-2026.md

User Request

Write release notes for RFID Scanner Reliability for 12 March 2026

Expected Output File

• Workspace mode: <workspace-dir>/docs/release-notes/12-March-2026.md
• Single repo: docs/release-notes/12-March-2026.md

Triggers

Use this skill when the user asks to:

• generate release notes
• create a changelog
• summarize today's development work
• write a PM update
• summarize git commits
• generate release notes for a date
• generate release notes for a project
• summarize a completed feature
• summarize the current session
• explain what changed in simple language

Example trigger phrases:

• Generate release notes for 11 March 2026
• Create changelog for today
• Summarize this development session
• Write PM notes for this feature
• Turn these commits into release notes
• Summarize changes for non-technical stakeholders