Abhi5415/blog-production

Blog Production (Autonomous)

Fully autonomous end-to-end workflow for producing a published blog article on the Clarido blog. Auto-selects the best topic, researches, writes, voice-analyzes with a retry loop, generates illustration, builds, pushes to production, and sends notification email. No human approval gates.

Invoked by the user with /blog-production or when asked to write/create a new blog post.

Repos

• Landing page (where blog lives): ~/dev/clarido-landing-page/
  • Articles: ~/dev/clarido-landing-page/content/blog/{slug}.md
  • Illustrations: ~/dev/clarido-landing-page/public/blog/{slug}.png
  • Blog engine: ~/dev/clarido-landing-page/lib/blog.ts
  • Blog post page: ~/dev/clarido-landing-page/app/blog/[slug]/page.tsx
  • Blog index: ~/dev/clarido-landing-page/app/blog/page.tsx
  • Sitemap: ~/dev/clarido-landing-page/app/sitemap.ts (auto-discovers all posts via listPostSlugs())
• Marketing ops (where tools live): ~/dev/clarido-marketing/
  • Voice analyzer: scripts/blog/ai_voice_analyzer.py
  • Illustration generator (reuse pattern): scripts/tiktok/illustrations.py

Autonomous Workflow

All phases run without user intervention. The voice analyzer retry loop is the critical quality gate.

Phase 1: Topic & Angle (auto-selected)

The user may invoke this skill in two ways:

• With a topic: User provides a specific concept, keyword, or idea. Skip auto-selection and use it.
• Without a topic: Claude auto-selects the best topic from the bank below.

1. Dedup check -- Read all files in ~/dev/clarido-landing-page/content/blog/ to identify already-covered topics.
2. Auto-select topic -- From the uncovered topics in the bank below, pick the one that:
   • Best complements the existing published articles (covers a different angle/keyword cluster)
   • Has the strongest search opportunity (higher volume keywords, less competition)
   • Has a natural angle that will produce a compelling essay (not just informational)
   • Log the reasoning: "Selected [topic] because [rationale]. Rejected alternatives: [brief notes on top 2-3 runners-up]."
3. Define the angle -- Not just "what" but "why it's interesting." Every article needs a core insight that makes the reader think differently. Not a listicle, not a how-to guide. An essay that builds an argument.
4. Log the decision -- Output the selected topic, angle, working title, and 1-sentence thesis to the conversation. Do NOT wait for approval. Proceed immediately.

Phase 2: Research (automated)

5. Find 4-6 real academic studies that support the article's argument. Requirements:

   • Real authors, real journals, real years
   • Use WebSearch to verify each citation exists
   • Prefer landmark/foundational studies (they're more interesting to read about)
   • Include: author(s), year, paper title, journal name, volume/issue/pages if available
   • Mix of classic studies (establishes credibility) and recent ones (shows the field is active)

6. Build a research brief -- For each study, write 1-2 sentences summarizing the key finding that's relevant to the article. This becomes the raw material for weaving research into the prose.

Phase 3: Writing (automated, no approval gate)

7. Read the reference article before writing: ~/dev/clarido-landing-page/content/blog/brain-dumping-article.md This is the gold standard for style, structure, and quality (scores 95/100 on the voice analyzer).

8. Write the article following the style guide below. Target 1,500-2,200 words (7-10 min read).

9. Save to ~/dev/clarido-landing-page/content/blog/{slug}.md with proper frontmatter:

   ---
   title: "Full Title Here"
   description: "1-2 sentence hook for SEO/social. Should make someone want to click."
   date: YYYY-MM-DD  # today's date
   author: Clarido Team
   tags: [primary-topic, secondary-topic, ...]  # 3-5 tags for SEO
   illustration: /blog/{slug}.png
   ---
   

10. Proceed immediately to voice analysis. Do NOT present the draft or wait for feedback.

Phase 4: Voice Analysis & Polish (automated with retry loop)

This is the critical quality gate replacing human review. Up to 3 attempts to pass.

11. Attempt loop (max 3 iterations):

    For each attempt:

    a. Em dash sweep -- Search for any --- (em dashes) and replace with periods, commas, colons, or parentheses. Em dashes are a strong AI tell.

    b. Run the voice analyzer:

    pipenv run python3 scripts/blog/ai_voice_analyzer.py ~/dev/clarido-landing-page/content/blog/{slug}.md
    

    c. Check results against quality gates:

    • Overall score >= 85
    • Zero HIGH-severity flagged sentences
    • Zero em dashes
    • Zero hedge phrases
    • Zero AI signal words
    • Readability grade 6-10
    • Questions >= 5% of sentences
    • Word count 1,500-2,200

    d. If all gates pass: Break out of loop, proceed to Phase 5.

    e. If any gate fails: Fix all flagged issues:

    • Rewrite every HIGH-severity sentence
    • Delete all hedge phrases
    • Replace all AI signal words
    • Simplify vocabulary / shorten sentences if readability is off
    • Add rhetorical questions if question ratio is low
    • Expand thin sections or cut bloat if word count is off
    • Loop back to step (a) for the next attempt.

    f. After 3 failed attempts: STOP. Do not publish. Report failure to the user with:

    • Final voice analyzer score
    • Remaining HIGH-severity sentences
    • Remaining issues
    • The saved draft path so the user can review manually

Phase 5: Illustration (automated)

12. Generate a blog hero illustration using OpenAI gpt-image-1.5. Use the Clarido brand illustration style:

    • Simple white character with black outlines, gray watercolor shading
    • Yellow (#FFD60A) as the only color accent
    • Clean, minimal, conceptual (not literal)
    • Soft gray wash texture, hand-drawn look
    • Reference images: assets/illustrations/overwhelmed-filing-cabinet.png, floating-yellow-balloon.png, planting-yellow-seedling.png

    Use the same approach as scripts/tiktok/illustrations.py: pass reference images via images.edit(), prepend the STYLE_PREFIX, use quality="high".

    Save to: ~/dev/clarido-landing-page/public/blog/{slug}.png Dimensions: 1536x1024 (3:2 landscape). Unlike TikTok (portrait 1024x1536), blog illustrations are landscape.

Phase 6: Build, Verify & Ship (automated)

13. Build the landing page to verify no errors:

    cd ~/dev/clarido-landing-page && pnpm build
    

14. Verify the new article appears in the build output:

    • Check that the route /blog/{slug} appears in the build output (Next.js logs generated routes)
    • The sitemap at app/sitemap.ts auto-discovers all posts via listPostSlugs(), so if the build includes the route, the sitemap is correct
    • If the build fails, fix the issue and rebuild

15. Push to production. In the landing page repo (~/dev/clarido-landing-page):

    cd ~/dev/clarido-landing-page
    git add content/blog/{slug}.md public/blog/{slug}.png
    git commit -m "Publish blog: {article title}"
    git push origin main
    

    Include any other modified files (e.g., if fixes were made to app/ or lib/ files).

16. Verify the live page after deployment (wait ~30 seconds for Vercel to deploy):

    curl -s -o /dev/null -w "%{http_code}" https://clarido.app/blog/{slug}
    

    Expect HTTP 200. If not, wait another 30 seconds and retry once. If still failing, report to the user.

17. Send notification email. Use mcp__google-workspace__send_gmail_message to email [email protected] and [email protected] with:

    • Subject: New blog published: {article title}
    • Body (keep it concise):
      • 2-sentence brief summarizing the article and its angle
      • Link to the live article: https://clarido.app/blog/{slug}
      • Target keywords: list the 5-8 SEO keywords this article targets (from the tags + content strategy)
      • Internal links: list any other Clarido blog articles linked to from within this article (title + URL for each)
      • Voice analyzer score: final score out of 100

18. Report to user -- Share the live URL, final voice analyzer score, word count, and confirmation that the email was sent.

Writing Style Guide

The voice is Paul Graham meets quality journalism. Intellectual rigor in conversational prose, with modern visual formatting for scanability.

Prose Rules

| Rule | Do | Don't | |------|-----|-------| | Tone | Conversational, curious, direct | Academic, coaching, marketing | | Perspective | "you" to engage, "I" for opinions | Impersonal third-person throughout | | Contractions | "don't", "it's", "you're", "can't" | "do not", "it is", "you are" | | Sentences | Wild variation: 4-word fragments mixed with 30-word explorations | Every sentence 15-20 words | | Paragraphs | One-liners mixed with longer blocks | Uniform paragraph sizes | | Openers | Questions, fragments, "But", "And", prepositional phrases | "The", "This", "It is" repeatedly | | Research | Woven into narrative: "In the 1920s, a psychologist named Bluma Zeigarnik noticed..." | Announced: "Research shows that..." or "According to a study..." | | Analogies | Concrete, visual: "Think of it as a desk with room for four things" | Abstract: "This can be compared to a multifaceted system" | | Em dashes | Never. Use periods, commas, colons, parentheses instead. | "The answer is simple --- just write it down" | | Hedge phrases | Never. See the analyzer's HEDGE_PHRASES list. | "It's important to note", "In today's world" | | Questions | 5-10% of sentences. Rhetorical questions that make the reader feel seen. | Zero questions (pure declaration) | | Endings | End with quiet resonance, not a CTA. The last paragraph should land. | "So what are you waiting for? Try it today!" |

Structure Pattern

Don't follow a rigid template, but most good articles have this shape:

1. Opening hook -- Start with something specific and interesting. A feeling, a paradox, a question. Not "In today's fast-paced world." Not a definition. Drop the reader into the middle of something.
2. The problem/phenomenon -- What's actually going on? Build understanding through concrete details and analogies.
3. The research -- Weave in 3-4 studies naturally. Name the researchers, tell the story of the finding, make the reader care about the science.
4. The mechanism -- Why does this work? Go one level deeper than the surface explanation.
5. The practical -- What can the reader do? But frame it as insight, not instruction. "The people who benefit most are the ones who..." not "Step 1: Do this."
6. The close -- Tie back to the opening. Leave the reader thinking.

HTML Components

Use these sparingly to aid comprehension. They should feel earned, not decorative. The article should read well as pure text; components enhance, they don't carry.

Key Stat -- For one striking number that anchors the argument:

<div class="key-stat">
<span class="stat-number">4-7</span>
<span class="stat-label">items your working memory can hold at once. Recent research suggests the real number is closer to four.</span>
</div>

Pull Quote -- For a sentence that deserves emphasis. Use 1-2 per article max:

<blockquote class="pull-quote">
Your brain evolved to think, analyze, and solve problems. Not to be a filing cabinet.
</blockquote>

Card Grid -- For parallel concepts (2-4 items). Use when items are genuinely parallel:

<div class="card-grid">
<div class="card">
<h4>Title</h4>
<p>Description</p>
</div>
<!-- more cards -->
</div>

For 3 columns: add cols-3 class to the card-grid div. Cards can optionally include <div class="card-example"> for italic examples.

Callout -- For a parenthetical tip or insight that doesn't fit the main flow:

<div class="callout">
<strong>Label (optional)</strong>
Content here.
</div>

Add insight class for insight-style callouts: <div class="callout insight">.

Comparison -- For before/after or contrasting approaches:

<div class="compare">
<div class="compare-bad">
<span class="compare-label">Label A</span>
"The bad example"
</div>
<div class="compare-good">
<span class="compare-label">Label B</span>
"The good example"
</div>
</div>

References Section

Every article ends with a references section. Format:

---

### References

- Author, A.B. (Year). "Paper Title." *Journal Name*, Volume(Issue), Pages.
- ...

---

*Clarido is a quiet log for a loud mind. Speak or type what's on your mind. Clarido holds it for you so you can return when you have space. [Join the beta](https://clarido.app)*

The references section gets automatically split from the main content by the blog engine. An email capture form appears between the article body and references.

Quality Gates

| Gate | Threshold | Action if failed | |------|-----------|-----------------| | Voice analyzer overall score | 85+ | Fix flagged issues, re-run (up to 3 attempts) | | HIGH-severity flagged sentences | 0 | Rewrite each flagged sentence | | Em dashes | 0 | Replace with periods/commas/colons/parens | | Hedge phrases detected | 0 | Delete every one | | AI signal words detected | 0 | Replace or cut | | Readability grade | 6-10 | Simplify vocabulary, shorten sentences | | Questions asked | 5%+ of sentences | Add rhetorical questions | | Word count | 1,500-2,200 | Expand thin sections or cut bloat | | Voice analyzer attempts | Max 3 | STOP and report failure if score < 85 after 3 attempts | | Build | Must succeed | Fix errors and rebuild | | Live page HTTP status | 200 | Retry once after 30s, then report failure |

Reference Article

The brain-dumping article is the gold standard for style, structure, and quality: ~/dev/clarido-landing-page/content/blog/brain-dumping-article.md

Read it before writing any new article. It scores 95/100 on the voice analyzer.

Topic Bank

Psychology and neuroscience concepts relevant to Clarido's audience. Each maps to search keywords people actually type. Claude auto-selects the best uncovered topic based on SEO opportunity and complement to existing content.

| # | Concept | Search Keywords | Angle | |---|---------|----------------|-------| | 1 | Zeigarnik Effect | overthinking at night, can't stop thinking | Why unfinished tasks haunt you | | 2 | Decision Fatigue | decision fatigue, too many choices | Why you can't decide anything by 8pm | | 3 | Cognitive Offloading | brain dump, write things down | Your brain isn't meant to store things | | 4 | Affect Labeling | name your emotions, journaling anxiety | Why naming the feeling makes it smaller | | 5 | Implementation Intentions | how to follow through, procrastination | The planning trick that bypasses willpower | | 6 | Attention Residue | can't focus, distracted, task switching | Why you're still thinking about the last thing | | 7 | Peak-End Rule | bad days, why do I feel bad | You're judging your day by two moments | | 8 | Expressive Writing | journaling benefits, writing therapy | Why writing about pain actually heals | | 9 | Spotlight Effect | social anxiety, self-conscious, overthinking social | Nobody is thinking about you as much as you think | | 10 | Ego Depletion (controversy) | willpower, self-control, mental energy | The willpower myth that won't die | | 11 | Paradox of Choice | overwhelmed by options, too many choices | More options make you less happy | | 12 | Bedtime Worry Journaling | can't sleep, racing thoughts at night | The 5-minute trick that fixes 3am anxiety | | 13 | Cognitive Load Theory | mental overload, too much to remember | Why your brain crashes like a browser with 47 tabs | | 14 | Default Mode Network | mind wandering, daydreaming, can't be present | Your brain's background app that won't close | | 15 | Rumination vs Reflection | stuck in a loop, same thoughts over and over | The difference between thinking and spiraling | | 16 | Self-Distancing (Kross) | can't think clearly, emotional decisions | Why talking to yourself in third person actually works | | 17 | Goal Gradient Effect | losing motivation halfway, almost gave up | Why you speed up near the finish line (and stall everywhere else) | | 18 | Psychological Safety (Edmondson) | afraid to speak up, walking on eggshells | Why the best teams feel safe enough to be wrong | | 19 | Negativity Bias | always thinking the worst, can't see the good | Your brain has a built-in bad news filter | | 20 | Planning Fallacy | always late, underestimate time, bad at planning | Why everything takes longer than you think | | 21 | Mere Exposure Effect | growing on me, familiar feels safe | Why your brain confuses familiarity with preference | | 22 | Emotional Granularity (Barrett) | can't describe how I feel, emotional vocabulary | "Fine" is not a feeling (and your brain knows it) | | 23 | Flow State (Csikszentmihalyi) | in the zone, deep focus, flow state tips | What actually happens when everything clicks | | 24 | Anchoring Bias | first impression, stuck on initial number | Why the first thing you hear hijacks everything after | | 25 | Self-Determination Theory | unmotivated, no drive, lost sense of purpose | The three things every human needs to feel alive | | 26 | Dunning-Kruger Effect | imposter syndrome, feel like a fraud, overconfident | Why the people who worry about being bad are usually good | | 27 | Sunk Cost Fallacy | can't let go, wasted too much time, should I quit | Why you stay in things you should have left a year ago | | 28 | Temporal Discounting | can't plan ahead, instant gratification, procrastination | Your brain thinks future-you is a stranger | | 29 | Sleep and Memory Consolidation | learning while sleeping, why sleep matters, memory | Your brain's night shift: what happens while you sleep | | 30 | Identity-Based Habits (Clear) | building habits, identity change, becoming | You don't rise to your goals, you fall to your identity |

Topics already published (do not select): check ~/dev/clarido-landing-page/content/blog/ at runtime.

Files

| File | Repo | Purpose | |------|------|---------| | content/blog/{slug}.md | landing-page | Article markdown with frontmatter | | public/blog/{slug}.png | landing-page | Hero illustration (1536x1024) | | lib/blog.ts | landing-page | Blog engine (splits references, calculates reading time) | | app/blog/[slug]/page.tsx | landing-page | Blog post page template | | app/blog/[slug]/email-capture.tsx | landing-page | Email capture component (auto-inserted above references) | | app/blog/page.tsx | landing-page | Blog index page | | app/sitemap.ts | landing-page | Sitemap (auto-discovers all posts via listPostSlugs()) | | app/globals.css | landing-page | Blog component CSS (callout, card-grid, key-stat, pull-quote, compare) | | scripts/blog/ai_voice_analyzer.py | marketing | Voice analyzer script (19 dimensions) | | scripts/tiktok/illustrations.py | marketing | OpenAI gpt-image-1.5 illustration generator (reuse the pattern) | | assets/illustrations/ | marketing | Brand illustration style references (passed to OpenAI as style refs) |