Create Changelog
Requirements
Version number, release date, list of changes. Audience (end users, developers, internal teams).
3
Gather context from the user. A good changelog needs:
Release basics
- Version number (following semver or their scheme)
- Release date
- Release name or theme (optional)
The changes
- New features or capabilities
- Improvements to existing features
- Bug fixes
- Breaking changes or deprecations
- Security updates (note: keep details vague)
Audience
- End users → Focus on benefits, plain language
- Developers → Include API changes, migration guides
- Internal teams → Add talk tracks, known limitations
Format preferences
- Markdown, HTML, or plain text?
- Detailed or concise?
- Any existing changelog style to match?
Check Product Context Profile for product context and tone guidance.
Ask for the list of changes if not provided.
4
Draft the changelog using the template from the guide:
- Group changes by type (New, Improved, Fixed, Changed)
- Lead each item with the benefit or capability
- Be specific about what changed and why it matters
- For bug fixes, describe what was wrong, not just "fixed bug"
- Note breaking changes prominently with migration guidance
- Use the appropriate tone for the audience
Writing patterns:
Good: "Find emails faster with natural language search—just type what you're looking for"
Bad: "Added NLP-based search functionality"
Good: "Fixed an issue where notifications weren't delivered in background on iOS 17"
Bad: "Fixed notification bug"
Output the complete changelog in the requested format.
5
After presenting the changelog:
- Ask if any items need more detail or different emphasis
- Offer to create audience-specific variations (user vs developer vs internal)
- Ask if they have additional changes to add
- If the changelog surfaced new product capabilities or positioning worth
preserving (e.g., new features that define the product direction),
offer to updateProduct Context Profile: "This release introduces
some significant capabilities—want me to add them to your product
profile for future reference?"
To run this task you must have the following required information:
> Version number, release date, list of changes. Audience (end users, developers, internal teams).
If you don't have all of this information, exit here and respond asking for any extra information you require, and instructions to run this task again with ALL required information.
---
You MUST use a todo list to complete these steps in order. Never move on to one step if you haven't completed the previous step. If you have multiple read steps in a row, read them all at once (in parallel).
Add all steps to your todo list now and begin executing.
## Steps
1. [Read Changelog Writing Guide]: Read the documentation in: `./skills/sauna/[skill_id]/references/product.changelog.guide.md` (Get the changelog template and style guidelines)
2. [Read Human-Style Prose]: Read the documentation in: `./skills/sauna/[skill_id]/references/shared.prose.style.md` (Reference for clear writing)
3. Gather context from the user. A good changelog needs:
1. **Release basics**
- Version number (following semver or their scheme)
- Release date
- Release name or theme (optional)
2. **The changes**
- New features or capabilities
- Improvements to existing features
- Bug fixes
- Breaking changes or deprecations
- Security updates (note: keep details vague)
3. **Audience**
- End users → Focus on benefits, plain language
- Developers → Include API changes, migration guides
- Internal teams → Add talk tracks, known limitations
4. **Format preferences**
- Markdown, HTML, or plain text?
- Detailed or concise?
- Any existing changelog style to match?
Check `./documents/product/profile.yaml` for product context and tone guidance.
Ask for the list of changes if not provided.
4. Draft the changelog using the template from the guide:
1. Group changes by type (New, Improved, Fixed, Changed)
2. Lead each item with the benefit or capability
3. Be specific about what changed and why it matters
4. For bug fixes, describe what was wrong, not just "fixed bug"
5. Note breaking changes prominently with migration guidance
6. Use the appropriate tone for the audience
Writing patterns:
- Good: "Find emails faster with natural language search—just type what you're looking for"
- Bad: "Added NLP-based search functionality"
- Good: "Fixed an issue where notifications weren't delivered in background on iOS 17"
- Bad: "Fixed notification bug"
Output the complete changelog in the requested format.
5. After presenting the changelog:
- Ask if any items need more detail or different emphasis
- Offer to create audience-specific variations (user vs developer vs internal)
- Ask if they have additional changes to add
- If the changelog surfaced new product capabilities or positioning worth
preserving (e.g., new features that define the product direction),
offer to update `./documents/product/profile.yaml`: "This release introduces
some significant capabilities—want me to add them to your product
profile for future reference?"