Changelog Writer

Changelog Writer

Create clear, accurate changelog entries that help developers understand what's new in Lightfast releases.

Critical: Fact-Check First

Before writing anything, verify against docs/architecture/implementation-status/README.md:

1. Check implementation status to verify:

   • What's actually completed vs planned
   • Current limitations and known gaps
   • Technical accuracy of claims

2. Never oversell:

   • Use specific names: "GitHub File Sync (File Contents)" not "GitHub Integration"
   • Disclose limitations: "Currently supports X; Y coming in vZ"
   • Be honest about conditionals: "when 3+ customers request"

3. Verify every claim:

   • If you cite a number, confirm it's in implementation docs
   • If you mention a feature, confirm it exists in production
   • When uncertain, ask for clarification

Writing Guidelines

1. Concise & scannable: 1-3 sentences per feature (Cursor-style brevity)
2. Lead with benefit: Start with what users can do, then how
3. Be transparent: Mention beta status, rollout timelines, limitations
4. User-focused but technical: Balance benefits with specifics developers need
5. Active voice: "You can now..." not "Users are able to..."
6. No emoji: Professional tone
7. Specific examples: Include config snippets, API calls
8. SEO-conscious: Use target keywords naturally
9. AEO-conscious: Write tldr for AI citation engines, excerpt for listings
10. FAQ quality: Questions must match real search queries, answers must be complete

Workflow

1. Gather input: PR numbers, URLs, or manual change list
2. Read implementation status for fact-checking
3. Draft following templates
4. Cross-check claims against implementation reality
5. Add SEO elements per seo-requirements
6. Review with checklist

Quick Reference

Do

• "GitHub File Sync (File Contents)" with limitations disclosed
• "When 3+ customers request: Linear integration"
• Include code examples for every major feature
• Link to 3-5 related docs

Don't

• "GitHub Integration" (vague - what does it cover?)
• "Coming soon: Linear, Notion, Slack!" (when at 0%)
• Long paragraphs (keep to 1-3 sentences per feature)
• Claims without verification

Output

Save drafts to: thoughts/changelog/{title-slug}-{YYYYMMDD-HHMMSS}.md

Required Frontmatter Fields

Every draft MUST include:

• title, slug, publishedAt (core)
• excerpt, tldr (AEO)
• seo.metaDescription, seo.focusKeyword (SEO)
• _internal.status, _internal.source_prs (traceability)

Slug Format

Always use: 0-<version>-lightfast-<feature-slug>

Examples:

• 0-1-lightfast-github-file-sync-semantic-search
• 0-2-lightfast-pr-metadata-linear-integration

Recommended:

• seo.secondaryKeyword, seo.faq[] (enhanced SEO)

The frontmatter structure maps directly to ChangelogEntryInput type. Use /publish_changelog to publish drafts to BaseHub.

See resources/templates.md for complete frontmatter template.

Resources

• Document Templates
• SEO Requirements
• Examples
• Pre-Publish Checklist