Blog Production

Blog Production

End-to-end workflow for producing a published blog article on the Clarido blog. Takes a topic from ideation through research, writing, voice analysis, illustration, and verification.

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
• Marketing ops (where tools live): ~/dev/clarido-marketing/
  • Voice analyzer: scripts/blog/ai_voice_analyzer.py
  • Illustration generator (reuse pattern): scripts/tiktok/illustrations.py

Workflow with Approval Gates

Phase 1: Topic & Angle (user approves)

The user may invoke this skill in two ways:

• With a topic: User provides a specific concept, keyword, or idea.
• Without a topic: Claude proposes 2-3 options based on the target audience.

1. Dedup check -- Read all files in ~/dev/clarido-landing-page/content/blog/ to avoid repeating topics.
2. Topic selection -- Pick topics at the intersection of:
   • Psychology, neuroscience, or behavioral science (must have real research behind it)
   • Relevance to Clarido's audience: overthinkers, people in transition, people who carry too much in their heads
   • SEO opportunity: topics people actually search for (brain dump, overthinking, journaling, mental clarity, decision fatigue, cognitive load, etc.)
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. Present to user -- Topic, angle, working title, 1-sentence thesis. Wait for approval.

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 (user approves)

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

8. 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
   ---
   

9. Present the draft to the user and wait for approval before proceeding.

Phase 4: Voice Analysis & Polish (automated)

10. Run the voice analyzer:

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

11. Fix flagged issues -- Work through priority fixes. Target: overall score 85+, zero HIGH-severity flagged sentences.

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

13. Re-run analyzer to confirm score meets threshold.

Phase 5: Illustration (automated)

14. 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: Verify & Ship (automated)

15. Build the landing page to verify no errors:

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

16. Start dev server:

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

17. Visual audit with Chrome browser automation. Use mcp__claude-in-chrome__ tools to:

    • Navigate to http://localhost:3000/blog/{slug}
    • Read the page and verify:
      • Article renders with all HTML components (cards, callouts, pull quotes, etc.)
      • Illustration loads correctly
      • Email capture form appears above references section
      • No broken formatting, no raw HTML visible
      • Typography, spacing, and layout look correct
      • Internal links to other articles work
    • Navigate to http://localhost:3000/blog (index page) and verify:
      • New article appears in the list
      • Thumbnail/illustration shows
      • Title, description, tags, and date display correctly

18. SEO & crawler audit. Using Chrome tools, verify:

    • Check http://localhost:3000/robots.txt — blog pages must NOT be disallowed
    • Read the page source/meta tags on the article page:
      • <title> tag contains the article title
      • <meta name="description"> is present and meaningful
      • No <meta name="robots" content="noindex"> blocking crawlers
      • Open Graph tags (og:title, og:description, og:image) are present for social sharing
    • If any crawler-blocking issues are found, fix them in the landing page code and rebuild

19. 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 SEO fixes were made to app/ or lib/ files).

20. Send notification email. Use mcp__google-workspace__send_gmail_message to email abhinav@jabhi.ca and joieta@jabhi.ca 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)

21. 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

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

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:

Don't repeat topics already covered in existing blog posts.

Files