weekly-sentiment-summary

name	weekly-sentiment-summary
description	Weekly sentiment summary of <BRAND>'s social mentions with week-over-week comparison using Octolens. Produces a Slack-ready report with sentiment score, highlights, lowlights, notable patterns, and competitor context. Use when the user asks for a weekly sentiment report, weekly social summary, or "how did mentions look this week".

Weekly Sentiment Summary

Bigger-picture view for growth, product, and devex teams. Typically posted Monday morning covering the prior week.

Uses the Octolens MCP server.

Workflow

Step 1: Determine date ranges

• This week: the most recent completed Mon–Sun (or the user-specified range)
• Prior week: the 7 days immediately before this week

Step 2: Fetch mentions for both weeks

1. Call list_mentions_context to get available keyword IDs and filter syntax.
2. Identify the brand-related keywords (your brand name, your domain, and your GitHub org).
3. For each week, query list_mentions with those keyword IDs, relevance=[0], and the week's date range. Set endDate to the day after Sunday to ensure full coverage.
4. Set includeAll: false and limit: 100.
5. Paginate with cursor until exhausted or 500 mentions per week.

Step 3: Aggregate both weeks

For each week, count:

• pos, neu, neg by sentiment
• total = pos + neu + neg
• Tag distribution (bug_report, user_feedback, competitor_mention, buy_intent, product_question, etc.)

Step 4: Compute sentiment scores

For each week:

sentiment_score = ((pos - neg) / total) * 100

Range: -100 to +100. Round to nearest integer.

Compute deltas:

• Δ volume = this_week_total - prior_week_total
• Δ score = this_week_score - prior_week_score

Use + prefix for positive deltas, - for negative. Show as absolute numbers, not percentages.

Step 5: Identify patterns by sentiment (this week only)

Before analyzing, filter out:

• employee posts (replies from team members to users)
• Spam / reseller posts (e.g. discounted subscription sellers, engagement bait)
• Cross-post duplicates (same content on Twitter and Bluesky — count once, prefer higher-reach version)

For each sentiment category (Positive, Neutral, Negative), identify 3-5 key themes or patterns from this week. Focus on:

• What are users saying? What themes emerge?
• Are there patterns across multiple mentions?
• What's strategically meaningful vs. noise?

Writing style: same as daily skill — lead with pattern/theme, include mention count, provide 1-2 representative links.

For Positive section only: After pattern summaries, include 1-3 direct quotes that work as testimonials. Pick the most specific, enthusiastic quotes that show clear value. Format as:

_"[exact quote]"_ — <url|@username on platform>

Where platform is the source (e.g. "X", "Reddit", "Bluesky", "Hacker News"). This makes it clear the link goes to the post, not the user's profile.

Step 6: Identify notable patterns

Compare this week vs prior week. Look for:

• Recurring themes: topics/features/complaints that appeared multiple times this week
• Trending tags: tags with significant volume changes vs prior week
• New signals: topics that appeared this week but not last week

Max 5 patterns. Each should include a delta or comparison when possible (e.g. " mentions up from 3 → 12 this week").

Step 7: Product feedback patterns

Scan this week's mentions tagged user_feedback, bug_report, product_question for recurring product feedback themes. Focus on specific features, workflows, or pain points mentioned multiple times.

Look for:

• Feature requests that appeared multiple times
• Specific bugs or technical issues with volume
• Pricing/credit feedback patterns
• UI/UX feedback themes

Summarize in 2–4 bullets with mention counts. Example: "Feature requests for on the free plan (5 mentions)" or "UI lag complaints in long sessions (3 mentions)".

Step 8: Format output

Produce a single message in two formats:

A) Slack mrkdwn (for posting to Slack in Step 9): Use Slack's mrkdwn: *bold* (single asterisks), <url|link> for links, • for bullets, _italic_ for italics.

B) Standard Markdown (for saving to repo in Step 10): Use standard Markdown: **bold** (double asterisks), [text](url) for links, - for bullets, *italic* for italics.

Template (shown in standard Markdown):

**Weekly #feed-mentions Summary — <start_date> → <end_date>**
<total> mentions (<Δ> vs last week) | 🟢 <pos> · ⚪ <neu> · 🔴 <neg> | score <score> (<Δ>)

**Positive**
- <pattern summary with count> — [link](url), [link](url)
- <pattern summary with count> — [link](url)
...

*Testimonials:*
*"<exact quote>"* — [@username on platform](url)
*"<exact quote>"* — [@username on platform](url)

**Neutral**
- <pattern summary with count> — [link](url), [link](url)
- <pattern summary with count> — [link](url)
...

**Negative**
- <pattern summary with count> — [link](url), [link](url)
- <pattern summary with count> — [link](url)
...

**Notable Patterns**
- <pattern with week-over-week Δ>
- <pattern with week-over-week Δ>
...

**Product Feedback Patterns**
- <specific product feedback theme with count>
- <specific product feedback theme with count>
...

Omit any section that has no meaningful content.

Step 9: Send to Slack (optional)

Only proceed with this step if the user explicitly asks to "send the report", "send to Slack", "post to Slack", or similar. Do NOT send automatically.

1. Check if BUZZ_SLACK_TOKEN environment variable exists: echo $BUZZ_SLACK_TOKEN
2. If the token exists, send the formatted summary to the channel in $MENTIONS_SUMMARY_CHANNEL_ID using:

curl -X POST https://slack.com/api/chat.postMessage \
  -H "Authorization: Bearer $BUZZ_SLACK_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"channel\": \"$MENTIONS_SUMMARY_CHANNEL_ID\", \"text\": \"<formatted_summary_here>\", \"unfurl_links\": false, \"unfurl_media\": false}"

3. If BUZZ_SLACK_TOKEN is not set, let the user know they need to set it to send Slack notifications

Step 10: Save report to GitHub repo (conditional)

This step runs only if Step 9 was performed (i.e. the Slack message was sent successfully). Do NOT save to the repo if the report was only displayed to the user without sending to Slack.

1. Save the formatted summary as a markdown file at reports/weekly/<YYYY-MM-DD>.md in the buzz repo, where <YYYY-MM-DD> is the end date (Sunday) of the report week. Use the standard Markdown version (format B from Step 8), not the Slack mrkdwn version.
2. Create the reports/weekly/ directory if it doesn't exist.
3. Commit and push directly to main:

REPO_ROOT="$(git rev-parse --show-toplevel)"
mkdir -p "$REPO_ROOT/reports/weekly"
# write the report file
git -C "$REPO_ROOT" add reports/weekly/<YYYY-MM-DD>.md
git -C "$REPO_ROOT" commit -m "Add weekly sentiment summary for <start_date> → <end_date>

Co-Authored-By: <your-agent> <[e-mail]>"
git -C "$REPO_ROOT" push origin main

4. If the push fails (e.g. due to conflicts), pull with rebase and retry once:

git -C "$REPO_ROOT" pull --rebase origin main
git -C "$REPO_ROOT" push origin main

Edge Cases

• Low volume week (<50 mentions): Still produce the report but note the low volume. Reduce highlight/lowlight counts proportionally.
• First run (no prior week data): Skip deltas and comparisons — just report this week's absolute numbers and note that week-over-week comparison will be available next week.
• Non-English mentions: Include if noteworthy, with language/region context in the takeaway.