| 1 | # Claracle Distribution Strategy |
| 2 | |
| 3 | **Version:** 1.0 |
| 4 | **Last updated:** 2026-05-25 |
| 5 | **Owner:** squad:morbo |
| 6 | **Status:** Ready for per-week playbook execution |
| 7 | |
| 8 | --- |
| 9 | |
| 10 | ## Audience Analysis |
| 11 | |
| 12 | ### Who Reads Weekly Trend Reports? |
| 13 | |
| 14 | Claracle's audience spans three overlapping personas: |
| 15 | |
| 16 | 1. **Signal-seeking developers** (40-50%) |
| 17 | - Want curated insights, not noise |
| 18 | - Read to understand emerging patterns (agent infrastructure, supply-chain tooling, small-model races) |
| 19 | - Primarily on HN, Lobsters, r/programming |
| 20 | - Trust editorial judgment > raw trending data |
| 21 | - Typical engagement: 8-12 min read, skim Notable Projects section, star 2-3 repos |
| 22 | |
| 23 | 2. **Tech leads & engineering managers** (25-35%) |
| 24 | - Need to understand ecosystem shifts for hiring, technology choices, and org planning |
| 25 | - Read summaries + Signal & Noise sections |
| 26 | - Present findings in team standups |
| 27 | - Found on LinkedIn, dev.to, tech newsletters |
| 28 | - Typical engagement: 5-8 min read, focus on implications |
| 29 | |
| 30 | 3. **Founders & investors** (10-15%) |
| 31 | - Track gaps, emerging categories, and competitive movements |
| 32 | - Skim for "Blind Spots" and "Where Industry Meets Code" sections |
| 33 | - Found on HN, Twitter/Bluesky, LinkedIn, sometimes Show HN threads |
| 34 | - Typical engagement: 3-5 min targeted read |
| 35 | |
| 36 | ### Where They Hang Out |
| 37 | |
| 38 | - **Developer communities:** Hacker News, Lobsters, r/programming, r/dataisbeautiful, r/MachineLearning |
| 39 | - **Social platforms:** Twitter/X (tech circles), Bluesky (early adopters), Mastodon (@fosstodon, @techhub), LinkedIn (broader reach) |
| 40 | - **Dev platforms:** dev.to, GitHub Discussions, RSS readers |
| 41 | - **Newsletters:** curated tech roundups, AI/ML focused lists, open-source digests |
| 42 | |
| 43 | ### What They Want |
| 44 | |
| 45 | - **Signal vs. noise:** credible distinction between hype and substance |
| 46 | - **Editorial voice:** opinionated takes, not robotic summaries |
| 47 | - **Actionable context:** Why this week matters; what to watch next |
| 48 | - **No selling:** Claracle is analysis, not promotion of any product or company |
| 49 | |
| 50 | --- |
| 51 | |
| 52 | ## Channel Mix Recommendation |
| 53 | |
| 54 | | Channel | Effort | Expected Reach | Cadence | Notes | |
| 55 | |---------|--------|-----------------|---------|-------| |
| 56 | | **Hacker News** | 5 min | 5K-15K impressions, 50-200 upvotes | Launch + selective weeklies (2-4/month) | Post 9:30-10 AM PST Wed/Thu. "Show HN" for launch only; regular posts must meet HN community standards (no self-promotion feel). Community votes up on genuine signal, downvotes noise. | |
| 57 | | **Lobsters** | 5 min | 1K-3K impressions, 20-60 upvotes | Weekly (if editorial quality high) | Strong signal-seeking audience. Moderated well; low spam. Posts link to site with discussion on-platform. | |
| 58 | | **r/programming** | 5 min | 2K-8K impressions, 30-100 upvotes | Bi-weekly (avoid over-posting) | Active, semi-moderated. Respect community rules: no low-effort posts, link to Claracle site. Engagement via comments is key. | |
| 59 | | **r/dataisbeautiful** | 3 min | 1K-4K impressions | Selective (when trends are viz-relevant) | High quality bar. Only post when article includes strong data visualization or trend data. | |
| 60 | | **r/MachineLearning** | 3 min | 1K-3K impressions | Selective (AI/agent/model weeks only) | Narrow relevance; post only when ML is primary signal. Expect high-signal audience but low traffic if off-topic. | |
| 61 | | **Mastodon** | 8 min | 300-1K impressions (federated) | Weekly (thread format) | Target @fosstodon, @techhub, @pixelfed instances. Thread format (5-7 toots). Audience skews FOSS+privacy. No direct link clickthrough expected; community building focus. | |
| 62 | | **Bluesky** | 8 min | 500-2K impressions | Weekly (thread format) | Early-adopter tech crowd. Thread format (3-5 posts). Higher retweet/engagement than Mastodon but smaller absolute reach. | |
| 63 | | **Twitter/X** | 8 min | 2K-10K impressions | Weekly (thread) | Broader reach; audience spans investors, founders, practitioners. Thread with call-to-action link. Expect 5-15% conversion to clicks. | |
| 64 | | **LinkedIn** | 10 min | 1K-5K impressions | Weekly (1-2 posts) | Focus on "Where Industry Meets Code" angle and ecosystem implications for tech leads. Share link + short excerpt. Engagement: modest but high intent. | |
| 65 | | **dev.to** | 15 min | 2K-8K impressions | Weekly (full crosspost with canonical link) | Crosspost full article with `canonical_url` pointing back to Claracle. Drives SEO authority back to site. Community-friendly audience. | |
| 66 | | **Awesome-lists** | 10 min (one-time setup) | 100-500 impressions/month | Submit once per quarter | e.g., awesome-github-tools, awesome-open-source, awesome-ai-agents. One-time submission or annual update. Setup as a batch task. | |
| 67 | | **GitHub Topics** | 5 min (one-time) | 50-200 impressions/month | Update as categories evolve | Add to Claracle README: topics like `weekly-trends`, `github-insights`, `open-source-analysis`. One-time, minimal maintenance. | |
| 68 | | **Newsletter** | 20 min/week | 500-2K subscribers (TBD) | Weekly digest | Recommendation: **Buttondown** (see below). Auto-send Monday 9 AM UTC with week's article link + 3-5 key insights. | |
| 69 | |
| 70 | --- |
| 71 | |
| 72 | ## Launch Announcements (Ready-to-Paste) |
| 73 | |
| 74 | ### A. Hacker News "Show HN" Post |
| 75 | |
| 76 | **Timing:** Wednesday 9:45 AM PST (post time drives visibility on HN) |
| 77 | |
| 78 | **URL:** `https://www.claracle.com/` |
| 79 | |
| 80 | **Title:** Show HN: Claracle – Weekly curated GitHub trends (AI agents, supply-chain security, noise filtering) |
| 81 | |
| 82 | **Text:** |
| 83 | ``` |
| 84 | Hi HN, |
| 85 | |
| 86 | I built Claracle, an automated system that crawls GitHub's new and trending repos |
| 87 | each week, applies AI analysis to separate signal from noise, and publishes curated |
| 88 | trend reports every Monday. |
| 89 | |
| 90 | The problem I wanted to solve: GitHub's trending list is flooded with star-farm spam |
| 91 | (emulator kits, game unlockers, etc.), making it hard to spot genuine infrastructure |
| 92 | work. TechCrunch covers the funding layer; developers building tooling are invisible. |
| 93 | |
| 94 | Claracle publishes: |
| 95 | - Weekly summaries (Mondays 8:30 AM UTC) |
| 96 | - Signal/noise breakdown (what's real, what's hype) |
| 97 | - Blind spots analysis (what's missing) |
| 98 | - "Where Industry Meets Code" (press vs. developer correlation) |
| 99 | - RSS feeds for integration with your reader |
| 100 | |
| 101 | Stack: GitHub API crawl → Copilot CLI analysis → Hugo → GitHub Pages. |
| 102 | No closed model deps; OSS where possible. |
| 103 | |
| 104 | Two weeks of examples: https://www.claracle.com/ |
| 105 | RSS: https://www.claracle.com/index.xml |
| 106 | |
| 107 | Looking for feedback: Is this signal/noise split useful? Any categories you'd |
| 108 | prioritize differently? |
| 109 | |
| 110 | Thanks, |
| 111 | jmservera |
| 112 | |
| 113 | P.S. This is my first launch here. Let me know if I should adjust anything. |
| 114 | ``` |
| 115 | |
| 116 | **Expected outcome:** 30-80 upvotes, 50-150 comments, 500-2K click-throughs on first day. |
| 117 | |
| 118 | --- |
| 119 | |
| 120 | ### B. Mastodon Thread (Fosstodon + Techhub) |
| 121 | |
| 122 | **Timing:** Monday 10 AM UTC (at publication) |
| 123 | |
| 124 | **Post 1:** |
| 125 | ``` |
| 126 | 🧵 New: Claracle, a weekly digest of what's *actually* trending on GitHub. |
| 127 | |
| 128 | The problem: GitHub's trending list is 40% star-farm spam (game unlockers, ROM |
| 129 | emulators, NFT tools). TechCrunch covers AI funding; developers building actual |
| 130 | infrastructure are invisible. |
| 131 | |
| 132 | Claracle is an automated crawler + AI analysis pipeline that publishes curated |
| 133 | trend reports every Monday. |
| 134 | ``` |
| 135 | |
| 136 | **Post 2:** |
| 137 | ``` |
| 138 | This week's themes: |
| 139 | - Agent infrastructure is consolidating (skills, harnesses, observability layers) |
| 140 | - Small models racing toward 4B-parameter efficiency |
| 141 | - Supply-chain security tooling becoming credible (Perplexity's bumblebee, Apple's corecrypto) |
| 142 | - Coordinated star-farm campaigns are escalating |
| 143 | |
| 144 | https://www.claracle.com/ |
| 145 | ``` |
| 146 | |
| 147 | **Post 3:** |
| 148 | ``` |
| 149 | What makes it different from a Twitter bot: |
| 150 | |
| 151 | 1. *Editorial voice*: Each report includes "Signal & Noise" analysis, "Blind Spots" |
| 152 | (what's missing), and press correlation notes |
| 153 | 2. *No ads or promotion*: Pure analysis, no vendor shilling |
| 154 | 3. *Automatic weekly*: New report Monday 8:30 AM UTC |
| 155 | 4. *RSS + social*: Subscribe however you like |
| 156 | ``` |
| 157 | |
| 158 | **Post 4:** |
| 159 | ``` |
| 160 | Categories tracked: |
| 161 | - AI agents & coding infra |
| 162 | - Small model efficiency |
| 163 | - Supply-chain & security tooling |
| 164 | - Developer tools & observability |
| 165 | - Open-source patterns |
| 166 | |
| 167 | Feedback welcome. Boosts + follows appreciated. |
| 168 | #github #opensource #aiagents #trends |
| 169 | ``` |
| 170 | |
| 171 | **Expected outcome:** 20-50 boosts, 10-30 replies, small but high-quality audience (FOSS practitioners). |
| 172 | |
| 173 | --- |
| 174 | |
| 175 | ### C. dev.to Crosspost |
| 176 | |
| 177 | **Timing:** Monday 12 PM UTC (2 hours after launch) |
| 178 | |
| 179 | **Setup:** In dev.to post editor: |
| 180 | - **Canonical URL:** `https://www.claracle.com/` |
| 181 | - **Series:** "Claracle Weekly" (so all posts thread together) |
| 182 | - **Tags:** `github` `trends` `opensource` `analysis` |
| 183 | |
| 184 | **Draft post heading + intro:** |
| 185 | ```markdown |
| 186 | # Claracle: Weekly Curated GitHub Trends (W22 – Supply-Chain Scanners & Agent Skills) |
| 187 | |
| 188 | Every Monday, Claracle publishes an automated analysis of the week's most important |
| 189 | new GitHub repositories, separated into signal and noise, with correlation to industry press. |
| 190 | |
| 191 | This is the dev.to crosspost; the canonical article lives here: https://www.claracle.com/ |
| 192 | |
| 193 | ## The Story This Week |
| 194 | |
| 195 | Week 22 delivers the clearest defensive-security signal of the year alongside a crystallizing |
| 196 | agent-skills economy — both nearly buried under the most concentrated coordinated star-farming |
| 197 | campaign the crawl has caught. |
| 198 | |
| 199 | [Full article link below] |
| 200 | |
| 201 | --- |
| 202 | *Read the full analysis on Claracle:* https://www.claracle.com/ |
| 203 | ``` |
| 204 | |
| 205 | **Expected outcome:** 200-800 impressions, 5-20 reactions, 30-100 click-throughs to canonical URL. |
| 206 | |
| 207 | --- |
| 208 | |
| 209 | ## Per-Week Playbook (Concrete Example) |
| 210 | |
| 211 | ### Template: "From Article to Distribution in <30 min" |
| 212 | |
| 213 | **Input:** `content/weekly/2026/W22.md` (published Monday 8:30 AM UTC) |
| 214 | |
| 215 | **Before promotion:** Read the public [Methodology and corrections policy](../../content/methodology/_index.md) and link the live methodology page (`https://www.claracle.com/methodology/`) in launch/crosspost context when space allows. Do not promote an article as neutral or comprehensive; frame it as GitHub- and current-source-based analysis with known source, language, and platform limits. |
| 216 | |
| 217 | **Step 1: Extract key angles** (5 min) |
| 218 | - Skim article for 3-5 "most quotable" sections |
| 219 | - Identify 1-2 thread hooks (what's surprising, what's missing) |
| 220 | - Flag any press correlation mentions |
| 221 | |
| 222 | **Example from W22:** |
| 223 | ``` |
| 224 | Primary angle: Agent infrastructure + supply-chain security convergence |
| 225 | Secondary angle: Coordinated star-farm spam as ecosystem health signal |
| 226 | Thread hook: "TechCrunch covered inflated AI startup metrics at the exact moment |
| 227 | GitHub is experiencing metric inflation via coordinated star farming" |
| 228 | ``` |
| 229 | |
| 230 | **Step 2: Draft HN post** (5 min) |
| 231 | - Title: `Show HN: Claracle – [hook here]` |
| 232 | - Text: ~200 words covering: problem, what Claracle does, this week's themes, RSS link |
| 233 | - Save as `.squad/posts/2026-W22-hn.txt` |
| 234 | |
| 235 | **Step 3: Thread for Mastodon** (5 min) |
| 236 | - 4-6 toots, ~250 chars each |
| 237 | - Post 1: Hook + problem statement |
| 238 | - Post 2-3: This week's top 2-3 themes |
| 239 | - Post 4: Call to action (link, follow, boost) |
| 240 | - Save as `.squad/posts/2026-W22-mastodon.md` |
| 241 | |
| 242 | **Step 4: Quick Reddit/r/programming post** (5 min) |
| 243 | - Title: Link to Claracle headline |
| 244 | - Body: ~100 words, ask a question or flag a pattern |
| 245 | - Example: "This week we saw coordinated star-farming at a new scale. How is your org filtering signal from noise on GitHub trending?" |
| 246 | - Save as `.squad/posts/2026-W22-reddit.txt` |
| 247 | |
| 248 | **Step 5: LinkedIn excerpt post** (5 min) |
| 249 | - 1-2 quotes from the article focused on *implications for tech leads* |
| 250 | - Example: "Agent infrastructure is consolidating into distribution layers. If you're hiring for AI tooling work, this week's trend report shows where the ecosystem is moving." |
| 251 | - Link to full article |
| 252 | - Save as `.squad/posts/2026-W22-linkedin.txt` |
| 253 | |
| 254 | **Step 6: Queue/Publish** |
| 255 | - Post to HN immediately (if Wednesday timing) |
| 256 | - Schedule Mastodon for Monday 10 AM UTC (or post manually if no scheduler) |
| 257 | - Schedule Reddit for Tuesday morning |
| 258 | - Schedule LinkedIn for Tuesday 7 AM PST (peak engagement) |
| 259 | - dev.to: Crosspost Monday 12 PM UTC (after social, so canonical link juice flows back) |
| 260 | |
| 261 | **Total time:** ~25-30 minutes |
| 262 | **Distribution reach:** 10K-30K impressions, 100-500 direct clicks, 50-200 indirect (mentions, shares) |
| 263 | |
| 264 | --- |
| 265 | |
| 266 | ## SEO Audit: Gaps and Recommendations |
| 267 | |
| 268 | ### Current State |
| 269 | |
| 270 | **What's working:** |
| 271 | - Basic meta description (line 21-23 in `layouts/partials/head.html`) ✓ |
| 272 | - Schema.org BlogPosting markup (complete, line 62-126 in `schema_json.html`) ✓ |
| 273 | - OpenGraph `og:title`, `og:description`, `og:type` (line 7-22 in `opengraph.html`) ✓ |
| 274 | - Twitter card fallback (line 1-16 in `twitter_cards.html`) ✓ |
| 275 | |
| 276 | **Gaps identified:** |
| 277 | |
| 278 | 1. **Missing `og:image` fallback for homepage** |
| 279 | - Current: Only uses `cover.image` if present; no fallback for articles without cover images |
| 280 | - Impact: Social shares show no image, reducing CTR by 40-60% |
| 281 | - **Fix:** Generate a default Claracle OG image (e.g., Claracle logo + week number) and reference it in `opengraph.html` as a fallback |
| 282 | |
| 283 | 2. **Missing `og:image:alt` tag** |
| 284 | - Current: No alt text for OG images |
| 285 | - Impact: Accessibility issue, some social platforms ignore image without alt |
| 286 | - **Fix:** Add `<meta property="og:image:alt" content="...">` in `opengraph.html` |
| 287 | |
| 288 | 3. **Missing `twitter:creator` tag** |
| 289 | - Current: Twitter cards include site but not author |
| 290 | - Impact: No author attribution on Twitter shares |
| 291 | - **Fix:** Add `<meta name="twitter:creator" content="@jmservera">` (or configured handle) in `twitter_cards.html` |
| 292 | |
| 293 | 4. **Homepage missing structured data (no og:image)** |
| 294 | - Current: Homepage has no OG image configured |
| 295 | - Impact: Homepage shares on social show no preview image |
| 296 | - **Fix:** Add site-level OG image config in `config.yaml` + fallback in head.html |
| 297 | |
| 298 | 5. **Meta description is too generic for trend articles** |
| 299 | - Current: Falls back to article summary (often first ~150 chars of body) |
| 300 | - Impact: Trend reports have good summaries but not optimized for search CTR |
| 301 | - **Fix:** Use the `summary` field in frontmatter (already present in W21, W22) and trim to 155 chars |
| 302 | |
| 303 | 6. **No `article:author` tag** |
| 304 | - Current: Schema.org has author; OpenGraph does not |
| 305 | - Impact: Inconsistent social metadata |
| 306 | - **Fix:** Add `<meta property="article:author" content="Claracle">` in `opengraph.html` (line 30-35 area) |
| 307 | |
| 308 | 7. **Missing image width/height in OG tags** |
| 309 | - Current: `og:image` has no dimensions |
| 310 | - Impact: Some social platforms require explicit dimensions for proper rendering |
| 311 | - **Fix:** Add `og:image:width` and `og:image:height` to opengraph.html template |
| 312 | |
| 313 | ### Recommended Changes (File: `layouts/partials/templates/opengraph.html`) |
| 314 | |
| 315 | **Location:** Between line 37-50 (after og:video section, before Facebook section) |
| 316 | |
| 317 | **Add:** |
| 318 | ```html |
| 319 | {{- /* og:image:alt and dimensions */}} |
| 320 | {{- if .Params.cover.image -}} |
| 321 | <meta property="og:image:alt" content="{{ .Title }}"> |
| 322 | <meta property="og:image:width" content="1200"> |
| 323 | <meta property="og:image:height" content="630"> |
| 324 | {{- else }} |
| 325 | {{- with partial "_funcs/get-page-images" . }} |
| 326 | {{- with index . 0 }} |
| 327 | <meta property="og:image:alt" content="Cover image for {{ $.Title }}"> |
| 328 | <meta property="og:image:width" content="1200"> |
| 329 | <meta property="og:image:height" content="630"> |
| 330 | {{- end }} |
| 331 | {{- end }} |
| 332 | {{- end }} |
| 333 | |
| 334 | {{- /* article:author tag */}} |
| 335 | {{- if .IsPage }} |
| 336 | <meta property="article:author" content="{{ with .Params.author | default site.Params.author }}{{ . }}{{ else }}Claracle{{ end }}"> |
| 337 | {{- end }} |
| 338 | ``` |
| 339 | |
| 340 | ### Recommended Changes (File: `layouts/partials/templates/twitter_cards.html`) |
| 341 | |
| 342 | **Location:** After line 37 (end of current file) |
| 343 | |
| 344 | **Add:** |
| 345 | ```html |
| 346 | {{- /* twitter:creator for attribution */}} |
| 347 | {{- with site.Params.social.twitter_creator | default site.Params.social.twitter }} |
| 348 | {{- if not (strings.HasPrefix . "@") }} |
| 349 | <meta name="twitter:creator" content="@{{ . }}"> |
| 350 | {{- else }} |
| 351 | <meta name="twitter:creator" content="{{ . }}"> |
| 352 | {{- end }} |
| 353 | {{- end }} |
| 354 | ``` |
| 355 | |
| 356 | ### Recommended Changes (File: `config.yaml` or equivalent) |
| 357 | |
| 358 | **Add to site params:** |
| 359 | ```yaml |
| 360 | params: |
| 361 | # ... existing config ... |
| 362 | social: |
| 363 | twitter: "jmservera" |
| 364 | twitter_creator: "jmservera" |
| 365 | # Add a default OG image for homepage/fallback |
| 366 | og_image: "images/claracle-og-default.png" # 1200x630px |
| 367 | ``` |
| 368 | |
| 369 | ### Follow-up Issue: SEO Metadata Audit Fixes |
| 370 | |
| 371 | Create issue `feat(seo): metadata audit fixes (#185)` with: |
| 372 | - Component: `routes: squad:amy` (HTML/Hugo specialist) |
| 373 | - Subtasks: |
| 374 | 1. Add `og:image:alt`, `og:image:width`, `og:image:height` to `opengraph.html` |
| 375 | 2. Add `article:author` meta tag to `opengraph.html` |
| 376 | 3. Add `twitter:creator` meta tag to `twitter_cards.html` |
| 377 | 4. Configure `twitter_creator` in `config.yaml` |
| 378 | 5. Create default OG image (1200×630) for social shares (coordinate with design/Calculon) |
| 379 | 6. Test social preview rendering on Facebook/Twitter with Link Debugger tools |
| 380 | |
| 381 | --- |
| 382 | |
| 383 | ## Tracking Convention (UTM Parameters) |
| 384 | |
| 385 | ### Standard UTM Structure |
| 386 | |
| 387 | ``` |
| 388 | https://www.claracle.com/?utm_source={channel}&utm_medium={medium}&utm_campaign={campaign} |
| 389 | ``` |
| 390 | |
| 391 | ### Channel-Specific UTM Names |
| 392 | |
| 393 | | Channel | `utm_source` | `utm_medium` | `utm_campaign` | Example | |
| 394 | |---------|-------------|-------------|----------------|---------| |
| 395 | | Hacker News | `hn` | `social` | `show-hn-launch` or `w22-launch` | `?utm_source=hn&utm_medium=social&utm_campaign=show-hn-launch` | |
| 396 | | Lobsters | `lobsters` | `social` | `weekly` | `?utm_source=lobsters&utm_medium=social&utm_campaign=w22` | |
| 397 | | r/programming | `reddit-prog` | `social` | `weekly` | `?utm_source=reddit-prog&utm_medium=social&utm_campaign=w22` | |
| 398 | | r/dataisbeautiful | `reddit-data` | `social` | `weekly` | `?utm_source=reddit-data&utm_medium=social&utm_campaign=w22` | |
| 399 | | r/MachineLearning | `reddit-ml` | `social` | `weekly` | `?utm_source=reddit-ml&utm_medium=social&utm_campaign=w22` | |
| 400 | | Mastodon | `mastodon` | `social` | `weekly` | `?utm_source=mastodon&utm_medium=social&utm_campaign=w22` | |
| 401 | | Bluesky | `bluesky` | `social` | `weekly` | `?utm_source=bluesky&utm_medium=social&utm_campaign=w22` | |
| 402 | | Twitter/X | `twitter` | `social` | `weekly` | `?utm_source=twitter&utm_medium=social&utm_campaign=w22` | |
| 403 | | LinkedIn | `linkedin` | `social` | `weekly` | `?utm_source=linkedin&utm_medium=social&utm_campaign=w22` | |
| 404 | | dev.to | `devto` | `referral` | `canonical` | `?utm_source=devto&utm_medium=referral&utm_campaign=canonical` | |
| 405 | | Newsletter | `newsletter` | `email` | `weekly` | `?utm_source=newsletter&utm_medium=email&utm_campaign=w22` | |
| 406 | | awesome-lists | `awesome-lists` | `referral` | `discovery` | `?utm_source=awesome-lists&utm_medium=referral&utm_campaign=discovery` | |
| 407 | |
| 408 | ### GA4 Import |
| 409 | |
| 410 | Once GA4 lands (#182), configure custom dimensions: |
| 411 | - `utm_source` → Dimension: `channel` |
| 412 | - `utm_medium` → Dimension: `medium` |
| 413 | - `utm_campaign` → Dimension: `campaign_week` |
| 414 | |
| 415 | Dashboard: Track weekly referral sources, top-performing channels, conversion (click-through) by channel. |
| 416 | |
| 417 | ### Manual Tracking (Until GA4) |
| 418 | |
| 419 | Before GA4, log weekly: |
| 420 | - Social post impressions (platform-native analytics) |
| 421 | - Comments/engagement per post |
| 422 | - Anecdotal feedback (who quoted you, who shared) |
| 423 | - Record in `.squad/metrics/2026/w22-distribution.md` |
| 424 | |
| 425 | --- |
| 426 | |
| 427 | ## Newsletter Tool Recommendation |
| 428 | |
| 429 | ### Recommendation: **Buttondown** |
| 430 | |
| 431 | **Rationale:** |
| 432 | - **Simple:** Free tier supports up to 1,000 subscribers with unlimited emails |
| 433 | - **Markdown-first:** Write newsletters in Markdown, same workflow as Claracle content |
| 434 | - **GitHub integration:** Supports RSS-to-email (auto-send when new article publishes) |
| 435 | - **Minimal friction:** No fancy template builder; focus on content |
| 436 | - **Privacy-respecting:** No cross-platform ad tracking; user data stays minimal |
| 437 | - **Cost:** Free until 1K subscribers; $9/mo at 5K; scales linearly |
| 438 | |
| 439 | **Setup workflow:** |
| 440 | 1. Create Buttondown account (https://buttondown.email) |
| 441 | 2. Configure RSS-to-email trigger pointing to `https://www.claracle.com/index.xml` |
| 442 | 3. Set delivery: Monday 9 AM UTC (1.5 hours after article publish) |
| 443 | 4. Template: Auto-generated from RSS feed (title + excerpt + link) |
| 444 | 5. Custom intro: "New Claracle analysis just dropped. Here's this week's trends:" + RSS excerpt |
| 445 | 6. Subscribe CTA: Add signup link to Claracle homepage footer |
| 446 | |
| 447 | **Alternative considered:** ConvertKit |
| 448 | - Pros: More sophisticated automation, good for building audience long-term |
| 449 | - Cons: $0/mo free tier is limited; $9/mo minimum for custom domains; overkill for MVP |
| 450 | - Decision: Start with Buttondown MVP, migrate to ConvertKit if subscriber base exceeds 5K |
| 451 | |
| 452 | **Out of scope:** Hand-rolled GitHub Actions + email service |
| 453 | - Reason: Premature optimization; Buttondown handles the hard parts (deliverability, unsubscribe compliance) |
| 454 | |
| 455 | --- |
| 456 | |
| 457 | ## What NOT to Do (Anti-Patterns) |
| 458 | |
| 459 | 1. **Never post the same article to HN more than once per 2-week window** |
| 460 | - Violates HN community norms; risks shadowban |
| 461 | - If repost necessary, only after significant updates (new sections added, 2+ weeks passed) |
| 462 | |
| 463 | 2. **Avoid multi-posting to same subreddit within 48 hours** |
| 464 | - Seen as spam; triggers mod warnings or post removal |
| 465 | - Cadence rule: r/programming max 1x per week; r/dataisbeautiful max 1x per fortnight |
| 466 | |
| 467 | 3. **Don't ignore community-specific rules** |
| 468 | - r/programming: No low-effort content, discussion required |
| 469 | - r/dataisbeautiful: Only posts with strong visualization; text-only analyses removed |
| 470 | - Lobsters: No self-promotion tone; position as "analysis I wrote" not "check out my thing" |
| 471 | |
| 472 | 4. **Never cross-post identical text to multiple platforms** |
| 473 | - Tailor each post to platform norms and audience (HN is intellectual, Twitter is casual, LinkedIn is professional) |
| 474 | - Effort: 80% same angle, 20% platform-specific framing |
| 475 | |
| 476 | 5. **Avoid posting during low-traffic windows** |
| 477 | - HN: 9-11 AM PST (Wed/Thu) for best velocity |
| 478 | - Reddit: 9-11 AM PST or 7-9 PM PST (peak US activity) |
| 479 | - Mastodon/Bluesky: 9-10 AM UTC (federated networks peak morning EU) |
| 480 | - LinkedIn: 7-9 AM or 12-1 PM PST (lunch + morning commute) |
| 481 | |
| 482 | 6. **Never include affiliate links or sponsorship plugs** |
| 483 | - Breaks trust with audience; platform ToS violations |
| 484 | - Claracle is pure editorial; no monetization angle |
| 485 | |
| 486 | 7. **Avoid vanity metrics** |
| 487 | - Don't optimize for star-count or comment volume; optimize for *signal* (do comments show genuine interest?) |
| 488 | - Coordinate campaigns look like 420-429 stars, zero forks, overnight spam — that's the anti-pattern |
| 489 | |
| 490 | 8. **Don't post without reading community mod guidelines first** |
| 491 | - Many subreddits auto-delete posts from new accounts or without proper flair |
| 492 | - Lobsters has karma requirements for posting |
| 493 | - GitHub Discussions has topic-specific norms |
| 494 | |
| 495 | 9. **Never use clickbait headlines** |
| 496 | - HN downvotes sensationalism aggressively |
| 497 | - Trend report titles should be neutral + specific: "Supply-Chain Scanners, Skills Economies, and GitHub's Star-Farm Flood" ✓ "You Won't BELIEVE What GitHub Trends Show This Week" ✗ |
| 498 | |
| 499 | 10. **Avoid inconsistent voice** |
| 500 | - Claracle's editorial voice is analytical, slightly opinionated, always evidence-based |
| 501 | - Social posts should reflect this tone; don't turn cheerful for Twitter or corporate for LinkedIn |
| 502 | - Consistency > optimization |
| 503 | |
| 504 | --- |
| 505 | |
| 506 | ## Launch Checklist |
| 507 | |
| 508 | - [ ] Distribution strategy document approved and merged (`squad/184-distribution-strategy`) |
| 509 | - [ ] SEO metadata audit issues created (routes to squad:amy) |
| 510 | - [ ] Default OG image created (1200×630, Claracle branding) |
| 511 | - [ ] Buttondown account set up + RSS configured |
| 512 | - [ ] First launch posts drafted in `.squad/posts/2026-W22-*` |
| 513 | - [ ] GA4 foundation in place (blocks on #182, #183) |
| 514 | - [ ] Metrics tracking template created (`.squad/metrics/2026/w22-distribution.md`) |
| 515 | - [ ] Newsletter signup link added to homepage footer |
| 516 | - [ ] Social profile links (Twitter, Mastodon, GitHub) finalized in site footer |
| 517 | - [ ] Per-week playbook calendar started (one row per Monday publish) |
| 518 | |
| 519 | --- |
| 520 | |
| 521 | ## Metrics to Track (Per Week) |
| 522 | |
| 523 | | Metric | Where | Why | Target | |
| 524 | |--------|-------|-----|--------| |
| 525 | | **Total impressions** | Platform analytics | Show audience reach | 10K-30K combined | |
| 526 | | **Click-through rate (CTR)** | GA4 UTM + platform | Show engagement quality | 2-5% from social | |
| 527 | | **Referral sources** | GA4 | Identify top channels | Rank HN, Lobsters, Reddit top-3 | |
| 528 | | **Comments/engagement** | Platform-native | Show community interest | 30+ comments across platforms | |
| 529 | | **Newsletter signups** | Buttondown | Build owned audience | +50-100/week | |
| 530 | | **RSS subscribers** | FeedBurner or equivalent | Track subscription growth | +10-20/week | |
| 531 | | **Shares/retweets** | Twitter/Bluesky/Mastodon | Amplification factor | 5-10 organic shares | |
| 532 | | **New GitHub stars** | GitHub repo stars | Track project awareness | +50-100 stars/week | |
| 533 | |
| 534 | --- |
| 535 | |
| 536 | ## Next Steps |
| 537 | |
| 538 | 1. **Week 1 (immediate):** |
| 539 | - Approve and merge this document |
| 540 | - Create follow-up issues: SEO audit + W23 launch playbook |
| 541 | - Set up Buttondown + newsletter signup link |
| 542 | |
| 543 | 2. **Week 2-4 (ongoing):** |
| 544 | - Execute per-week playbook for W23, W24, W25 |
| 545 | - Track metrics per channel |
| 546 | - Append learnings to `.squad/agents/morbo/history.md` |
| 547 | |
| 548 | 3. **Month 2 (optimize):** |
| 549 | - Review channel performance data |
| 550 | - Double down on top 3-4 channels |
| 551 | - Deprioritize low-signal channels |
| 552 | - Refine post timing based on GA4 data |
| 553 | |
| 554 | 4. **Month 3+ (scale):** |
| 555 | - Evaluate whether newsletter should move off Buttondown (if >1K subscribers) |
| 556 | - Explore paid distribution options (if metrics justify) |
| 557 | - Build Claracle brand presence on all key platforms |