Changelog marketing

Changelog Marketing

Purpose

Turns a product changelog from an internal record into a compounding SEO and community asset. Decides whether a release warrants a standalone entry, a batched summary, or a full announcement blog post. Runs a quality gate before publish to catch weak entries that damage changelog credibility.

Built for PMMs and DevRel leads who want to extract ongoing traffic value from release cadence without over-announcing small changes.

---

Inputs

Input	Required?	Description
Release description	Required	What shipped — feature name, change summary, user-facing impact
Release type	Required	Major / minor / patch / internal
Target persona	Required	Who uses this feature
Prior changelog publish date	Optional	When the last entry was published — informs batching decision
SEO context	Optional	Target keywords from content strategy
Visual assets available	Optional	Screenshots, GIFs, or architecture diagrams available for the entry
Brain context	Optional	Prior changelog performance data

Brain read (if connected):

brain/read: changelog_performance_history, seo_keyword_targets

---

Outputs

Output	Format	Description
Publish decision	Markdown decision record	Standalone / batched / blog-post with rationale
Quality gate result	Checklist	Pass / fail per quality criterion
Changelog entry	Markdown	80–150 word entry with SEO title and visual recommendation

Brain write (if connected):

brain/write: changelog_entry_published, seo_title, visual_type

---

Decision Logic

Step 1 — Publish decision

IF release_type = major OR feature_impact = high
  THEN: Standalone entry. Consider full announcement blog post if metrics justify.

IF release_type = minor AND days_since_last_entry < 7
  THEN: Batch. Accumulate until 7-day threshold OR 3+ minor entries, then publish batch.

IF release_type = patch OR change is internal/infrastructure
  THEN: Skip public changelog. Internal record only.

IF release includes a breaking change
  THEN: Standalone entry REQUIRED. Flag for migration guide link.

Batching trigger:

• 7 days have passed since last entry, OR
• 3+ minor changes accumulated

Do not publish a changelog entry solely because something shipped — publish because it creates value for the reader.

Step 2 — Quality gate (run before every publish)

Criterion	Pass	Fail
User benefit	First sentence states user-facing benefit	First sentence names the feature without explaining why it matters
Specificity	Entry is specific to this release — could not apply to any other	Entry is generic ("improved performance," "bug fixes") without specifics
Length	80–150 words	<80 (too thin) or >150 (too long for changelog)
SEO title	Contains version number + capability descriptor, ≤70 chars	No version number OR purely generic title
Visual	Visual recommendation matches change type	Visual type mismatched (e.g., GIF for a config change)

IF quality_gate = FAIL on any criterion
  THEN: Return entry with specific failure reason. Do not publish until fixed.

Step 3 — Visual type selection

Change type	Visual recommendation
UI change	Screenshot
Interactive / motion feature	GIF
API / CLI change	Code snippet
Architecture / data model change	Architecture diagram
Configuration / internal change	None

Enforced constraints:

• Never publish "bug fixes" as a standalone entry without naming the specific bugs fixed
• Never publish a changelog entry that describes an internal refactor with no user-facing impact
• Breaking changes must link to migration guide — do not publish without the link

---

Cross-Review Triggers

Required before FINAL:

• pmm/content-review/ — when changelog entry includes customer-facing claims or benchmark numbers

Conditionally required:

• pmm/positioning-review/ — when entry introduces or changes a key positioning claim

---

Shared-skill consultation

shared-skill: foundations/shared-skills/
signal-direction: growth → pmm
purpose: confirm messaging consistency before publishing entries that touch positioning

---

Example Usage

Example 1: Major feature — standalone entry

Context: B2B SaaS, shipping a new vector search capability. This is a significant differentiated feature with a clear developer audience. Last changelog published 12 days ago.

Input:

• Release type: Major
• Feature: Vector search native support
• Persona: Backend engineers at AI-native startups
• Prior entry: 12 days ago
• Visual: Screenshot of query result UI available

Output:

DECISION: Standalone entry

QUALITY GATE: PASS
- User benefit: ✅ "Query your relational and vector data in a single SQL statement"
- Specificity: ✅ Names the specific capability and the SQL syntax change
- Length: ✅ 120 words
- SEO title: ✅ "Product v2.4 — Native Vector Search for AI Workloads" (52 chars)
- Visual: ✅ Screenshot of query result UI

SEO TITLE: Product v2.4 — Native Vector Search for AI Workloads

BODY:
[Publish-ready 120-word entry]

VISUAL: Screenshot — show a side-by-side SQL query with relational JOIN and vector similarity
search in a single statement, with result latency displayed.

Reviews triggered: pmm/content-review

---

Example 2: Minor improvements — batching decision

Context: Developer tool, shipped 3 minor improvements in 5 days: improved error messages, faster CLI startup, and a new config flag. Last changelog published 4 days ago.

Input:

• Release type: 3x minor
• Features: Error messages, CLI startup time, config flag
• Prior entry: 4 days ago

Output:

DECISION: Batch — 3 minor changes accumulated; publish as single "improvements" entry.
Next review in 3 days or when major feature ships, whichever is first.

QUALITY GATE: PASS (conditional — error message improvement needs specificity)
- "Improved error messages" FAILS specificity: name the specific errors that changed.
  Revision required: "Error messages for failed authentication now include the exact
  missing scope, reducing debug time from minutes to seconds."

SEO TITLE: Product CLI — Faster startup, clearer auth errors, new --watch flag (v1.8.2–1.8.4)

BODY:
[Publish-ready batched entry after specificity fix]

Reviews triggered: None (no customer-facing claims)

---

Example 3: Breaking change — mandatory standalone

Context: API-first tool, shipping a breaking change to the authentication endpoint. Migration guide exists in docs.

Input:

• Release type: Major (breaking)
• Change: Auth endpoint path changed from /v1/auth to /v2/auth
• Migration guide URL: [provided]
• Visual: Code snippet showing old vs. new endpoint

Output:

DECISION: Standalone entry — MANDATORY (breaking change).

QUALITY GATE: PASS
- Breaking change flag: ✅ "Action required" in first sentence
- Migration guide link: ✅ Included
- Visual: ✅ Code snippet (old endpoint → new endpoint, side by side)

SEO TITLE: Product v3.0 — Auth Endpoint Migration Required (/v1 → /v2)

BODY:
Action required: The authentication endpoint has moved from /v1/auth to /v2/auth in v3.0.
The /v1 endpoint will be deprecated on [date]. [Migration guide link] covers the 3-step
update: update your base URL, rotate your API key, verify your token expiry settings.
New v2 tokens also support scoped permissions — see the permissions docs for details.

VISUAL: Code snippet — show old /v1/auth call and new /v2/auth call side by side with
diff highlighting.

Reviews triggered: pmm/content-review

---

Validation Criteria

Output passes if:

• Publish decision (standalone / batched / skip) is documented with rationale
• Quality gate is run and result is shown per criterion
• Entry is 80–150 words
• SEO title ≤70 characters and includes version or date reference
• Visual recommendation matches the change type
• Breaking changes include migration guide link
• Sources are declared and Tier-1 frameworks are cited
• Review triggers are listed with current status
• Output carries: Confidence: [0-100] and Review Trace: [list of reviews passed]

Output fails if:

• Entry published without quality gate
• "Bug fixes" entry without naming specific bugs
• Breaking change published without migration guide link
• Entry >150 words (too long for changelog format)

---

Benchmarks

Metric	Benchmark	Source
Changelog SEO compounding	Linear reports changelog as a top-3 SEO traffic source within 12 months of consistent publishing	Linear (public, 2023)
Publish cadence	Weekly or bi-weekly standalone entries; daily batching accumulation	Reforge Growth Series, 2023
Entry length	80–150 words optimal for skim-reading and SEO density	aether-launch-copilot knowledge base, 2026

---

References & Sources

Tier-1 frameworks used:

• Linear changelog methodology — Linear (public) — 2022–2024 — Standalone vs. batch decision logic; SEO compounding mechanism

Tier-2 operator repos referenced:

• aether-growth/campaign/knowledge/tactics/changelog-marketing.md — cadence + quality gate — internal

Tier-3 supplemental context:

• Reforge Growth Series — Reforge — 2023 — Used for: publish cadence benchmarks

---

Output metadata (append to every FINAL output):

---
Skill: changelog-marketing v0.1.0
Role: growth
Confidence: [0-100]
Review Trace: [list of reviews passed, or "DRAFT — pending: [list]"]
Bridge Signals: none
Brain Context: [connected / not connected]
Sources: Linear changelog methodology 2022–2024; Reforge Growth Series 2023
Generated: [date]
---