blog-writing

What this skill does

# Blog Writing

## Quickstart

1. Reference braindump.md for research, examples, and outline
2. Hook the reader with an anecdote, problem statement, or rhetorical question
3. Structure with TL;DR bullets, clear H2/H3 headings, short paragraphs
4. Ground abstract concepts in personal examples; cite research from braindump
5. End with practical implications and a question to engage readers

## When to Use This Skill

Use blog-writing when:
- Writing or revising draft.md (the actual blog post)
- User asks to draft a section or the full post
- Refining existing draft content
- User runs `/polish` for quality improvements
- Translating ideas from braindump.md into polished prose

Skip this skill for:
- Brainstorming phase (use **brainstorming** skill)
- Gathering research (use **research-synthesis** skill)
- Technical documentation or API references
- Academic papers requiring formal tone

## Critical: User Control and No Injection

**You assist, you don't inject. The user is in control.**

**NEVER add content to draft.md without explicit approval:**
- Don't make up examples, milestones, or technical details
- Don't invent data, statistics, or research findings
- Don't add sections or points the user hasn't mentioned
- Don't fill in gaps with your own ideas

**ALWAYS ask before adding anything:**
```
User: Draft the intro
AI: I'd suggest opening with [your anecdote from braindump about Company X].
    Should I use that or would you prefer a different hook?
```

**Show, don't inject:**
```
❌ BAD (injecting):
AI: [writes intro with made-up story about OKRs failing]

✓ GOOD (showing and asking):
AI: I see in braindump you mentioned OKRs failing at 3 companies.
    Should I use that as the opening hook? If so, which company
    story would be strongest - the Series B startup or the enterprise?
```

**For technical content (roadmaps, architecture, etc.):**
- NEVER make up milestones, timelines, or technical decisions
- Only use what the user has explicitly stated in braindump
- If something is missing, ASK: "What milestones should I include here?"
- Don't fill gaps with "typical" or "standard" approaches

**For research and data:**
- Only cite real research from braindump.md (sourced via MCP tools)
- NEVER make up statistics, studies, or sources
- If you need data, ask user or use research-synthesis skill
- If uncertain, say "I don't have data for this claim - should I research it?"

**User has final say:**
- Always present drafts for review
- Accept user edits without resistance
- If user says "no," respect it immediately
- Your job is to help express THEIR thoughts, not add yours

## Two-Document Workflow

When working on a blog post, you'll interact with two files:

**braindump.md** - The messy workspace:
- Research findings, citations, sources
- Rough ideas and notes
- Outline iterations
- Examples and anecdotes
- Questions to resolve

**draft.md** - The clean blog post:
- Structured markdown following the template below
- Dhruv's voice and style
- Polished, publishable content
- References research from braindump

**Your role**: Transform ideas from braindump → polished prose in draft

## Core Voice & Tone Principles

**Direct and Conversational**
- Use contractions (don't, isn't, I've) naturally
- Write in first person ("I think," "I've found," "I hope")
- Address the reader directly with rhetorical questions
- Vary sentence length: short punchy lines and longer reflective sentences

**Thoughtful and Analytical**
- Present multiple perspectives on complex issues
- Be slightly skeptical of conventional wisdom and "silver bullet" solutions
- Back up strong opinions with evidence (research, citations, personal data)
- Acknowledge limitations: "I don't really have a silver bullet for this"

**Grounded in Experience**
- Use personal anecdotes to illustrate abstract concepts
- Include self-deprecating humor when appropriate
- Reference Indian context or examples when relevant
- Draw on programming/technical analogies when they clarify concepts

**Engaging and Honest**
- End posts with questions to spark discussion
- Avoid hyperbole and exaggeration in favor of measured statements
- Acknowledge complexity; avoid oversimplification
- Focus on practical implications, not purely theoretical discussions

## Structural Principles

These are the load-bearing principles for how a post holds together. The Core Voice principles above are about *sound*; these are about *shape*. Sources compiled in `references/writing-principles.md`.

**Reader-centric, not writer-centric** (McEnerney)
- Writers use text to think horizontally—a record of their process. Readers consume it vertically—value delivered. Stage-setting must answer the reader's question, not narrate your thinking.
- Test before drafting: what problem does my reader have? What do they value? The intro answers those before the argument begins.

**Progressive Disclosure**
- Never rely on a concept you haven't introduced. If the reader meets a term for the first time mid-argument, you've lost them.
- Introduce concepts at the point of first need—not earlier, not later. Don't front-load a glossary; don't delay the definition until after third use.
- Simplest mental model first; build complexity in layers. Each layer should make sense on its own before the next one depends on it.

**Fight the curse of knowledge** (Pinker; Heath brothers)
- You know the topic too well to judge what's obvious to the reader. Read each draft as a newcomer. What am I using without introducing?
- Smart-general-reader test: would someone outside your immediate circle know this term? If no, prime it at first use.

**Surprise before argument** (Graham)
- Lead with what contradicts reader assumption. Curiosity before case.
- "You probably think X. Actually, Y. Here's why." lands better than "I want to argue Y."

**Outcome before mechanism; concrete before abstract** (Evans, McKenzie)
- State what the reader will understand or be able to do, then explain how.
- Real scenario first, extracted principle second. Not the other way around.

## Structure Template

### Title
Clear, compelling, works as email subject line

### TL;DR
3-4 bullet points summarizing core takeaways. Write bullets for a cold reader: avoid in-group terms you can't prime in one line. If a term is essential, a parenthetical gloss beats a jargon wall. The TL;DR sits above stage-setting—it has to stand on its own.

### Introduction
Hook the reader with one of:
- Personal anecdote that illustrates the problem
- Problem statement that resonates with reader experience
- Rhetorical question that frames the discussion

### Stage-Setting (1–3 short paragraphs after the hook)
Before the argument begins, ground the reader. Use SCQA as a scaffold (Minto, *The Pyramid Principle*):

- **Situation**—the baseline the reader already accepts
- **Complication**—what changed or broke, why it matters *now*
- **Question**—what naturally emerges from the complication
- **Vocabulary**—for any term the post will rely on (e.g. "subagents", "Plan Mode", "skills", "MCP"), give a one-liner on first use. Link to a deeper primer rather than inlining a long definition. Don't front-load a glossary; don't defer the definition until after you've used the term three times.
- **Prior context (for series posts)**—briefly bridge what a new reader needs from earlier posts in 1–2 sentences. Don't assume they've read them.

The Answer (your argument) starts in the Body. Stage-setting is the runway, not the takeoff.

See `references/writing-principles.md` for the sources this beat draws from.

### Body
- Use clear H2/H3 headings that guide the reader
- Keep paragraphs short (1-3 sentences) for readability
- Use bullet lists or numbered steps for clarity
- Integrate quotes, citations, or references to support arguments
- Examine multiple perspectives; critique conventional wisdom
- Use metaphors and analogies to explain complex concepts
- Bold key sentences or phrases for emphasis
- Cite relevant laws/principles (Goodha