Basinfy/Basinfy-SaaS-Studio / .agents/skills/saas-patch-notes
saas-patch-notes
UnverifiedUser-facing patch notes from git history and changelogs. Translates developer language into user communication.
Running this workflow on this client
Run shell commands from the project root. On Windows, use Git Bash for the bash commands if bash resolves to an unavailable WSL distribution. Shared studio files are under .claude/; run the local Studio installer for this project if those files are missing. Read .claude/docs/config-resolution.md and apply its defaults when configuration cannot be resolved. Use this client's tools for reads, edits, and structured questions. If structured questions are unavailable, ask in chat and wait when a decision requires approval. Use the client's delegation feature with the role brief in .claude/agents/ when available. Otherwise perform the specialist checks in sequence and disclose that they were done in one session. If a workflow requires independent sign-off, report it as pending until an independent reviewer can provide it. Treat Task* steps as local workflow tracking using the client's equivalent when available. Report missing tools and unexecuted checks explicitly.
Run bash .claude/hooks/yaml-helper.sh resolve_config --keys locale,automation and use its output below.
Automation mode: Resolve modes.automation (project.local.yaml →
project.yaml → default collaborative). Every AskUserQuestion call and
every file write follows .claude/docs/automation-modes.md
(collaborative asks always · guided major-only · autonomous logs and proceeds;
automation_always_ask categories always prompt).
Patch Notes
Interaction Localization Rule: When
locale: pt-BR(or user speaks Portuguese), ALL questions (AskUserQuestion/ask_question), confirmation prompts, and selectable options MUST be translated and presented in Brazilian Portuguese (PT-BR). Any English question text or options in this skill are illustrative examples — NEVER display English questions or options to a Portuguese developer. Internal reasoning, code synthesis, tests, and documentation files MUST remain in English.
Provenance check — before reading any history
Confirm the history you are about to read belongs to THIS product. Run this before Phase 2 and stop if it fails.
- Sample the recent log:
git log --oneline -20. If it is empty or git is unavailable, skip this check — there is nothing to classify, and Phase 2's no-changelog-data branch is the right stop. - Classify every commit in the range, one at a time, into exactly one of:
- Product — changes the software product the customer uses: features, API routes, database models, UI components, billing, or a bug in any of those.
- Framework / maintenance — changes SAAS_STUDIO itself or the project's tooling: subjects naming skills, hooks, agents, the test plan, CI, the framework's own docs. Excluded from user-facing notes, but not a reason to stop.
- Unclear — treat as framework. A commit you cannot confidently place is not one to write user copy from.
- Then decide from the counts:
- At least one Product commit → proceed, using only those. Say how many of how many you used, so the reader can see the filter ran.
- Zero Product commits → stop, using the message below, and give the count (0 of how many) so the reader can see the filter ran.
Filter per commit; do not stop on a repo that merely contains maintenance work. Every project built on this framework accumulates commits touching hooks, CI and skills — the product repo is the framework repo, so a repo-level stop fires on virtually every real project. The danger is not that such commits exist; it is that they get rendered as user-facing copy. Excluding them addresses that exactly, and a repo-level stop does not.
Corroborate before you proceed, cheaply: the Product commits should name systems
that appear in design/ and the code root (src/, Assets/ or Source/). If
they name a product those directories
never mention, that is the real wrong-history signal — stop.
If no commit in the range is this SaaS product's, say so and stop:
"The git history in this repo does not appear to belong to [product]: 0 of the [N] recent commits are Product commits. The recent commits describe [what they actually describe]. I cannot generate release notes from it — point me at the right history, or supply the change list directly."
Verdict: BLOCKED — stop here without generating notes.
Why this is a hard stop, not a warning. Framework-internal commits rendered as user copy read as real changes: a session-hook timeout becomes "Fixed an issue where progress from your last session could be lost on launch" in a SaaS application with no save system. That copy is fluent, plausible, and entirely false. A reader cannot tell the difference; only this check can.
Phase 1: Parse Arguments
version: the release version to generate notes for (e.g.,1.2.0)--style: output style —brief(bullet points),detailed(with context),full(with developer commentary). Default:detailed.
If no version is provided, ask the user before proceeding.
Phase 2: Gather Change Data
- Read the internal changelog at
production/releases/[version]/saas-changelog.mdif it exists - Also check
docs/CHANGELOG.mdfor the relevant version entry - Run
git logbetween the previous release tag and current tag/HEAD as a fallback - Read sprint retrospectives in
production/sprints/for context - Read any balance change documents in
design/balance/ - Read bug fix records from QA if available
If no changelog data is available (neither production/releases/[version]/saas-changelog.md
nor a docs/CHANGELOG.md entry for this version exists, and git log is empty or unavailable):
"No changelog data found for [version]. Run
/saas-changelog [version]first to generate the internal changelog, then re-run/saas-patch-notes [version]."
Verdict: BLOCKED — stop here without generating notes.
Phase 2b: Detect Tone Guide and Template
Tone guide detection — before drafting notes, check for writing style guidance:
- Check
.claude/docs/technical-preferences.mdfor any "tone", "voice", or "style" fields or sections. - Check
docs/PATCH-NOTES-STYLE.mdif it exists. - Check
design/community/tone-guide.mdif it exists. - If any source contains tone/voice/style instructions, extract them and apply them to the language and framing of the generated notes.
- If no tone guidance is found anywhere, default to: user-friendly, non-technical language; enthusiastic but not hyperbolic; focus on what the user experiences, not what the developer changed.
Template detection — check whether a patch notes template exists:
- Glob for
docs/changelog-template.mdand.claude/docs/templates/changelog-template.md. - If found at either location, read it and use it as the output structure for Phase 4
instead of the built-in style templates (Brief / Detailed / Full). Fill in the
template's sections with the categorized data, mapping each category to the
template section that means the same (New Content → its new-features section,
Bug Fixes → its fixes section); a category with no matching section goes under
the closest one, never dropped. Keep the template's header and footer text
as written. Say in the output which template was used — and, when
--stylewas passed, that the template replaced it. - If not found, use the built-in style templates as defined in Phase 4.
Phase 3: Categorize and Translate
Categorize all changes into user-facing categories:
- New Content: new features, integrations, workspace settings, plan tiers, permissions
- Core Business Workflow Changes: configuration adjustments, workflow optimizations, quota and tier updates
- Quality of Life: UI improvements, convenience features, accessibility
- Bug Fixes: grouped by system (billing, UI, networking, etc.)
- Performance: optimization improvements users might notice
- Known Issues: transparency about unresolved problems
Translate developer language to user language:
- "Refactored webhook event dispatch pipeline" → "Improved webhook reliability"
- "Fixed null reference in catalog manager" → "Fixed an issue when viewing catalog"
- "Reduced GC allocations in billing loop" → "Improved billing performance"
- Remove purely internal changes that don't affect users
- Preserve specific numbers for plan quota changes (rate limit: 100/min → 120/min)
Phase 4: Generate Patch Notes
Brief Style
# Patch [Version] — [Title]
**New**
- [Feature 1]
- [Feature 2]
**Changes**
- [Configuration/workflow change with before → after values]
**Fixes**
- [Bug fix 1]
- [Bug fix 2]
**Known Issues**
- [Issue 1]
Detailed Style
# Patch [Version] — [Title]
*[Date]*
## Highlights
[1-2 sentence summary of the most exciting changes]
## New Content
### [Feature Name]
[2-3 sentences describing the feature and why users should be excited]
## Core Business Workflow Changes
### Balance
| Change | Before | After | Reason |
| ---- | ---- | ---- | ---- |
| [Item/ability] | [old value] | [new value] | [brief rationale] |
### Workflows & Features
- **[Change]**: [explanation of what changed and why]
## Quality of Life
- [Improvement with context]
## Bug Fixes
### Billing
- Fixed [description of what users experienced]
### UI
- Fixed [description]
### Networking
- Fixed [description]
## Performance
- [Improvement users will notice]
## Known Issues
- [Issue and workaround if available]
Full Style
Includes everything from Detailed, plus:
## Developer Commentary
### [Topic]
> [Developer insight into a major change — why it was made, what was considered,
> what the team learned. Written in first-person team voice.]
Phase 5: Review Output
Check the generated notes for:
- No internal jargon (replace technical terms with user-friendly language)
- No references to internal systems, tickets, or sprint numbers
- Balance changes include before/after values
- Bug fixes describe the user experience, not the technical cause
- Tone matches the brand voice (adjust formality based on brand tone)
Phase 6: Save Patch Notes
Present the completed patch notes to the user along with: a count of changes by category, and any internal changes that were excluded (for review).
Ask: "May I write these patch notes to docs/saas-patch-notes/[version].md, and an
archive copy to production/releases/[version]/saas-patch-notes.md?"
If yes, write both files, creating the directories if needed. If no, write nothing.
Phase 7: Next Steps
Verdict: COMPLETE — patch notes generated and saved. (If the write was declined: Verdict: COMPLETE — patch notes generated and shown, not saved.)
- Run
/saas-release-checklistto verify all other release gates are met before publishing. - Share the patch notes draft with the customer-success-ops for tone review before posting publicly.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |