authoring-release-docs
Authoring Release Docs
Produces release notes, changelogs, and READMEs — time-sensitive, high-visibility documentation that users and developers rely on to understand what changed and how to respond.
Prerequisite: Load authoring-technical-docs first for the multi-pass workflow, style rules, and quality framework. This skill provides release-specific templates and rules only.
Templates
Follow the asset at ./assets/release_notes_template.md for release notes structure. For changelogs, follow Keep a Changelog conventions unless a project-specific format is already established.
Core rules
Framing
- Lead with user impact, not implementation detail. Write "You can now export dashboards as PDF" — not "Added PDF rendering pipeline."
- Use past tense for all changes: "Added", "Fixed", "Removed", "Deprecated."
- Write for two audiences simultaneously: technical users who need precision, and non-technical stakeholders who need plain-language summaries.
Structure
- Open with a one-paragraph summary of the most significant changes in this release.
- Group changes by type in this order: Breaking Changes → New Features → Improvements → Bug Fixes → Deprecations.
- Within each section, order by impact: most significant change first.
Breaking changes
- Breaking changes must appear in a prominent callout block — they cannot be buried or easy to miss.
- Always include exact migration steps inline, not just a link to external docs.
- Every deprecation must include a target removal date.
Bug fixes
- Be specific. Write "Fixed an issue where CSV exports truncated rows with more than 50 columns" — not "Fixed export bug."
- Include severity where relevant (e.g., data loss, crash, cosmetic).
Traceability
- Every bug fix and feature entry must reference its issue tracker ID (e.g., Jira ticket, GitHub issue).
- Every release must include a release date.
READMEs
- Must work standalone: a developer finding the repo for the first time should be able to install and run the project using only the README, without consulting any other document.
- The quick-start section must be completable in under 30 seconds.
- Include: project description, prerequisites, installation, quick start, configuration, links to further docs.
Generating release docs from raw inputs
When given Jira exports, commit logs, ticket lists, or PR summaries:
- Triage inputs — identify the type of each item: feature, improvement, bug fix, breaking change, deprecation, or internal/non-user-facing (exclude the last category).
- Rewrite for users — commit messages and ticket titles are written for developers; release notes are written for users. Translate accordingly.
- Group and prioritize — apply the section order above; sort by impact within sections.
- Resolve ambiguity conservatively — if a ticket is too vague to describe accurately, flag it for human review rather than guessing. Do not fabricate specifics.
- Verify completeness — cross-check that every input item is either included or explicitly excluded (with a reason), so nothing is silently dropped.
Output locations
| Document | Path |
|---|---|
| Release notes | docs/releases/v[version].md |
| Changelog | CHANGELOG.md (project root) |
| README | README.md (project root) |
More from wizeline/sdlc-agents
editing-pptx-files
Use this action any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions \"deck,\" \"slides,\" \"presentation,\" or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this action.
25authoring-user-docs
Use when producing user-facing documentation — tutorials, how-to guides, user guides, getting-started guides, installation guides, or onboarding documentation. Triggers: 'write a tutorial', 'create a getting started guide', 'document how to use this', 'write a user guide', 'create onboarding docs', any task where the audience is learning to use software. Always load authoring-technical-docs first.
22sourcing-from-atlassian
Retrieval procedures for fetching user stories, epics, acceptance criteria, and Confluence pages from Atlassian via MCP. Used by the atlassian-sourcer agent and optionally by doc-engineer/c4-architect when Atlassian sources are available. Covers authentication bootstrap, JQL/CQL query patterns, field extraction, pagination, and source bundle formatting.
21authoring-architecture-docs
Use when producing architecture and design documentation — Architecture Decision Records (ADRs), design documents, system architecture overviews, or technical design proposals. Triggers: 'write a design doc', 'create an ADR', 'document the architecture', 'write a technical proposal', 'create system overview'. Always load authoring-technical-docs first.
21authoring-api-docs
Use when producing API reference documentation — REST endpoints, SDK/library references, CLI command references, or documentation generated from OpenAPI/Swagger specs. Triggers: 'document this API', 'generate API reference', 'write SDK docs', 'document these endpoints', any task involving source code with HTTP handlers, route definitions, or OpenAPI specs. Always load authoring-technical-docs first.
20authoring-technical-docs
Core documentation engineering action. Provides the quality framework, style rules, and multi-pass workflow (research → draft → review → format) that all documentation must follow. Load this first for any technical documentation task. If no domain action matches the request, this action alone is sufficient.
19