changelog-social-swarm

name	changelog-social-swarm
description	Weekly skill that scans merged PRs in your internal repo for CHANGELOG entries, categorizes them into topic buckets, drafts tweet suggestions, and posts a structured summary to #social-swarm on Slack for the team to pick up. Use when asked to "generate the social swarm post", "what's tweet-worthy this week", or "run the changelog bot".

Changelog → Social Swarm

Weekly content plan for #social-swarm. Scans merged PRs in your-org/your-repo-internal, extracts changelog entries, buckets them by topic, drafts tweet suggestions, and posts a structured Slack message for the team to pick up.

Inputs

Optional:

• Lookback window — days to scan (default: 7)
• Release version — specific stable tag to anchor around (default: latest)

Workflow

Step 1: Fetch merged PRs with changelog entries

Use gh to pull recent merged PRs:

gh api "repos/your-org/your-repo-internal/pulls?state=closed&sort=updated&direction=desc&per_page=100" --paginate

For each PR:

• Skip if merged_at is null or older than the lookback window.
• Parse the body for CHANGELOG-* entries:

  CHANGELOG-(NEW-FEATURE|IMPROVEMENT|BUG-FIX|HIGHLIGHT|IMAGE):\s*(.+)
  

• Discard entries containing {{ (unfilled template placeholders).
• Collect: PR number, title, author login, merged_at, HTML URL, parsed entries.

If zero changelog entries found, post a short "quiet week" message to Slack and stop.

Step 2: Categorize into buckets

Assign each entry to exactly one bucket. Customize these buckets, owners, and keyword hints for your product. Example:

• Performance () — perf, memory, startup, latency, speed, faster
• Platform () — platform support, OS-specific fixes, cross-platform
• <FEATURE_A> () — keywords for one of your product areas
• <FEATURE_B> () — keywords for another product area
• General (team) — catch-all

Rules:

1. A typed entry (e.g. CHANGELOG-<TYPE>) maps to its matching bucket regardless of text.
2. Keyword match against entry text + PR title (case-insensitive). Single match → that bucket.
3. Multiple or zero matches → use judgment, default to General.

Update the owner names and Slack member IDs here as team assignments change. When posting, tag owners with <@SLACK_MEMBER_ID> if the ID is filled in; otherwise use the name as plain text.

Step 3: Rate tweet-worthiness

Rate each entry:

• 🟢 Tweet-worthy — user-visible, interesting to devs, good for social
• 🟡 Maybe — could work with the right angle or asset
• 🔴 Skip — too minor, internal, or uninteresting externally

Heuristic:

• NEW-FEATURE → almost always 🟢
• HIGHLIGHT → usually 🟢 (entries in your key product narrative)
• IMPROVEMENT → 🟢 if it solves a common pain point, otherwise 🟡
• BUG-FIX → 🟢 only if widely reported, otherwise 🔴
• IMAGE → skip (changelog images, not social content)

Step 4: Draft tweet suggestions

For each 🟢 or 🟡 item, draft a 1-2 sentence tweet.

Read .agents/skills/draft-brand-tweet/style-notes.md for voice. Key points:

• Product-first and direct
• Human, not corporate
• No hashtags, one emoji max
• Phrases like "You can now...", "We just added...", "Fixed the ... issue."
• Avoid banned phrases and AI writing tells from the style notes

For each item, also recommend an asset type:

• 🎬 GIF demo (5-10s) — new UI features
• 📸 Screenshot — visual changes
• 📊 Chart — performance improvements
• 📝 Text-only — minor improvements or fixes

Step 5: Build posting schedule

Spread 🟢 items across the week:

• ~2 posts per weekday (Mon–Fri)
• Strongest items Monday/Tuesday
• Lighter items Thursday/Friday
• Group related items that could be a single post

Step 6: Post to Slack

Post a single message to #social-swarm using the Slack blocks API. Use $BUZZ_SLACK_TOKEN via os.environ and read the channel ID from $SOCIAL_SWARM_CHANNEL_ID. Never echo, log, or hardcode the token.

Message format (mrkdwn):

📋 *Social Swarm — Week of <DATE>*
<COUNT> tweet-worthy items from <PR_COUNT> merged PRs

---

*Performance* — <@OWNER>
🟢 *<changelog entry>*
> <suggested tweet copy>
🎬 Asset: GIF demo | 📅 Post: Tuesday
<PR_URL|PR #NNN>

*<FEATURE_A>* — <@OWNER>
🟢 *<changelog entry>*
> <suggested tweet copy>
📝 Asset: Text-only | 📅 Post: Wednesday
<PR_URL|PR #NNN>

---
🔴 *Skipped* (N items): <brief comma-separated list>

Use Python with urllib.request and json to build the payload and post via chat.postMessage. Set unfurl_links: false and unfurl_media: false.

Edge Cases

• Zero entries: Post a short "quiet week — nothing tweet-worthy" message and stop.
• Missing env vars: BUZZ_SLACK_TOKEN or SOCIAL_SWARM_CHANNEL_ID not set → log error, do not attempt to post.
• gh auth failure: Log error and stop.
• Very few items (<3): Still post, but note the light week.

Constraints

• Do NOT fabricate changelog entries, PR numbers, or metrics.
• Do NOT post multiple messages — one structured Slack message.
• Do NOT include the Slack token in any output, log, or file.
• Keep tweet suggestions grounded in the actual changelog text.
• Follow draft-brand-tweet/style-notes.md voice for all copy.