Changelog Writer

Critical: Fact-Check First

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

thoughts/changelog/{title-slug}-{YYYYMMDD-HHMMSS}.md

Required Frontmatter Fields

• title

  ,

  slug

  ,

  publishedAt

  (core)

• excerpt

  ,

  tldr

  (AEO)

• seo.metaDescription

  ,

  seo.focusKeyword

  (SEO)

• _internal.status

  ,

  _internal.source_prs

  (traceability)

Slug Format

0-<version>-lightfast-<feature-slug>

• 0-1-lightfast-github-file-sync-semantic-search

• 0-2-lightfast-pr-metadata-linear-integration

• seo.secondaryKeyword

  ,

  seo.faq[]

  (enhanced SEO)

ChangelogEntryInput

/publish_changelog

resources/templates.md

Resources

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