The-Notorious-Avengers changelog-release-notes Weapon
You are the playbook for changelog-release-notes-guardian. Every invocation should leave the team with one concrete artifact: either a ready-to-publish changelog entry, a tool setup, an audit report, or a distribution plan. The research in research/ backs every claim in these guides.
When this weapon applies
Load this weapon for any of:
- Writing a single changelog entry for a shipped release.
- Choosing and setting up a changelog tool for the first time.
- Auditing an existing changelog for quality, cadence, or tone.
- Planning a multi-channel announcement for a significant release.
- Advising on the right format (in-app widget vs dedicated page vs markdown file vs email).
Do NOT load for:
- Engineering deployments or CI/CD — that is
devops-guardian. - Marketing landing pages or launch campaigns — that is
website-guardian. - Internal sprint retrospectives — that is a product management workflow, not a changelog.
First action when this weapon is loaded
- Read
guides/00-principles.md— the non-negotiables that govern every output. - Match the user's request to one of the four triage intents in Step 1 of the Angel's ACTION.
- Open the relevant guide(s) for the matched intent before producing any output.
Folder layout
changelog-release-notes-weapon/
+- SKILL.md (this file)
+- README.md (one-page human overview)
+- guides/
| +- 00-principles.md (core doctrine: user-centric, honest, distributed)
| +- 01-tool-selection.md (decision matrix: Headway vs FeatureBase vs Productlane vs Beamer vs markdown)
| +- 02-tool-setup.md (integration patterns per platform)
| +- 03-copy-craft.md (writing playbook: impact-first, user-centric verbs, honest scope)
| +- 04-distribution-channels.md (when to use each channel, sequencing, tailoring)
| +- 05-audit-playbook.md (scoring framework for existing changelogs)
+- examples/
| +- saas-minor-release.md (SaaS product minor release entry with distribution checklist)
| +- api-breaking-change.md (developer-facing API changelog with migration guide reference)
| +- audit-report-example.md (filled-in audit report for a fictional product)
+- templates/
| +- changelog-entry.md (standard entry skeleton)
| +- audit-report.md (audit scoring sheet)
+- reports/
| +- README.md (describes how past audit reports accumulate here)
+- research/
+- research-plan.md
+- research-summary.md
+- index.md
+- internal/command-brief-notes.md
+- external/keep-a-changelog.md
+- external/headway-app.md
+- external/featurebase.md
+- external/productlane.md
+- external/beamer.md
+- external/changelog-copy-craft.md
Critical directives (from Command Brief)
These apply on every invocation. Full justifications in guides/00-principles.md.
- Never paste raw commit logs into a changelog entry. Raw commit messages are written for engineers; re-frame for user impact.
- Always name the user-visible behavior, not the implementation. "Fixed a bug where signing in on multiple tabs sometimes logged you out" beats "Fixed a race condition in the token refresh handler."
- Include honest scope. When users might expect something that did NOT ship, say so. One sentence is enough.
- Respect the team's existing tone. Read two or three recent entries before writing; match their register.
- Never recommend a paid tool without confirming budget / tier fit. Default to markdown (Keep a Changelog) when unsure; it is always migratable.
- Surface the distribution plan every time. Writing and not distributing is the most common failure mode.
Triage decision tree
User request → Triage intent
"write this entry" / "here's what we shipped" → guides/03-copy-craft.md
"set up a changelog" / "which tool?" / "compare X and Y" → guides/01-tool-selection.md
"audit our changelog" / "review our release notes" → guides/05-audit-playbook.md
"plan our announcement" / "how to distribute this?" → guides/04-distribution-channels.md
First time setup + writing + distribution → 01 → 02 → 03 → 04 in sequence