blog-planner

Original source / Raw SKILL.md

---
name: blog-planner
description: >
  Interactive blog post authoring. Produces a draft blog post file
  with structured outline, inline guidance comments, and meta briefs that
  the author proses up in place. Supports pyramid principle, best sales deck,
  and release post formats.
---

# Blog Planner

Plan and outline blog posts for the Electric blog. The output is a draft
markdown file placed directly in `website/blog/posts/` with
`published: false`. The author works through the outline in place, expanding
compressed bullets into prose and swapping in assets.

## Invocation

```
/blog-planner [optional: path to existing draft or reference material]
```

If the user provides a path to existing material (drafts, docs, PRDs, notes),
read it for context and content. Understand what it contains but do not
over-index on its structure — the outline's structure comes from the chosen
format, not the source material.

## Authoring flow

Work through these phases in order. Ask one question at a time. Be clear,
honest, and useful. Don't gamify the questioning or perform — add value
and get out of the author's way.

### Phase 1: Intake

Understand the raw idea.

- What is the post about?
- Who is the author? (Use author keys from the Electric blog: `thruflo`,
  `kyle`, `samwillis`, `icehaunter`, `balegas`, `oleksii`, `purva`)
- Is there existing material to reference? (Drafts, PRDs, RFCs, demos,
  PRs, docs.) If so, read it now.

### Phase 2: Sharpen intent

Nail down why this post deserves to exist. Push until each answer is crisp.

- **What is this post about?** — One sentence.
- **What's interesting about it?** — Why would the reader care? What's the hook?
- **What's the reader takeaway?** — After reading, what does the reader know
  or believe that they didn't before?
- **What are the CTAs / next steps?** — What should the reader do after reading?
- **Why are we / the author the right people to write this?** — What authority
  or experience makes this credible?

These answers form the Intent block in the output file's meta section.

### Phase 3: Choose format

Based on the intent, recommend one of the three formats and confirm with
the author. If the author picks a format, use that format — don't second-guess.

| Format | When to use |
|--------|-------------|
| **Pyramid Principle** | You have a clear point to make and need to build a logical argument. Good for technical explanations, "how we built X", opinion pieces with substance. |
| **Best Sales Deck** | You're introducing a concept or paradigm shift. A narrative flow that names a big change in the world, shows winners and losers, teases the promised land, and introduces the solution. Good for product launches that represent a category shift, thought leadership. |
| **Release Post** | You shipped something. Communicate it clearly. The workhorse format for incremental releases and new features. Always be shipping. |

Once confirmed, load the corresponding reference file from `references/`.

### Phase 4: Draft the outline

Produce the section-level outline per the chosen format.

- Present the outline section by section for feedback
- Bullets are compressed meaning — each should expand to 1-2 sentences
  of prose with minimal rewording
- Include inline HTML comments explaining what each section is doing
  structurally and what tone/content the author should aim for
- Mark where assets will go with `<!-- ASSET: description -->` comments
- For pyramid principle and best sales deck: the TLDR + info box comes
  before the format-specific structure
- Iterate until the author is satisfied with the structure and content

**Writing style for outline bullets:**
- Compressed, direct, specific
- Each bullet carries one clear idea
- Bullets often combine into fresh prose because they are compressed
  expressions of meaning — optimise for this
- Avoid: "robust", "scalable", "flexible", "leverage", "ecosystem",
  "game-changing", "revolutionary" — say what you actually mean
- No LLM tells — no "it's worth noting", "importantly", "in conclusion",
  "let's dive in", "at its core", "in today's landscape"

### Phase 5: Ethos / creative angle

For **pyramid principle** and **best sales deck** formats only.

Draw out the author's personal angle:
- Is there a specific moment, experience, or anecdote that makes this real?
- Is there a creative framing that makes the setup more vivid?

Weave this into the outline bullets for the Situation/Complication (pyramid)
or Big Change (best sales deck) sections. Annotate with comments explaining
how the creative element works structurally. This is done now, not left to
the author to figure out during prose-up.

### Phase 6: Evaluate

Assess whether the outline delivers on the intent from Phase 2.

- Does the structure serve the point of the post?
- Does the logic hold? (Informal — does it hang together, not a PhD defence)
- Are there gaps or weak sections?
- Would the reader reach the intended takeaway by following the outline?
- Is the hook strong enough?

Raise any issues and iterate with the author.

### Phase 7: Fill in the meta

Return to the footer meta section. Draft briefs for:

- **Title brief** — Direction for the final title. Titles use sentence case,
  not Title Case.
- **Description brief** — For SEO. No HTML. What should it convey?
- **Excerpt brief** — For the blog listing card. Max 3 short sentences.
  Match word length of existing post excerpts for consistent listing display.
- **Image prompt** — See image brief guidelines below. If a detailed image
  brief is needed, suggest the author use the `/blog-image-brief` command.
- **Open questions** — Anything unresolved.

### Phase 8: Gather assets

Now that the outline is solid, inventory the assets needed:

- Code samples, diagrams (existing or to-be-created, mermaid or manual),
  demo videos, screenshots, embedded tweets, external blog post links
- Map each asset to its location in the outline
- Note whether each asset exists or needs creating
- Record in the Asset checklist in the meta footer

### Phase 9: Write the file

Save the outline to `website/blog/posts/YYYY-MM-DD-slug.md`.

- Use today's date for the filename prefix
- Derive the slug from the working title (kebab-case)
- Set `published: false` in frontmatter
- Use `...` placeholders for frontmatter fields that need finalising
  (title, description, excerpt) — the briefs in the commented footer
  guide the author on what to write

## Output format

The output is a real blog post file that the author works through in place.

### Frontmatter

```yaml
---
title: '...'
description: >-
  ...
excerpt: >-
  ...
authors: [author-key]
image: /img/blog/slug/header.jpg
tags: [...]
outline: [2, 3]
post: true
published: false
---
```

Use `...` for title, description, and excerpt. These get filled in by the
author using the briefs in the meta footer. Tags can be populated from
the intent discussion.

### Body structure

All formats follow this pattern:

1. **TLDR opener** — 1-2 short paragraphs stating what this is and why it
   matters. Compressed, no setup, no marketing tone. Technical audience
   wants the point immediately. Followed by an info box with key links.
2. **Format-specific body** — Section structure per the chosen format
   reference. Inline HTML comments guide the author on each section's
   purpose and tone.
3. **Next steps** — CTAs, links, what to do now.
4. **`***` separator**
5. **Commented meta footer** — Intent, title brief, description brief,
   excerpt brief, image prompt, asset checklist, open questions.
   Prefixed with instruction to delete before publishing.

### Inline comments

Use HTML comments for:

- **Structural guidance**: What this section is doing in the format's logic
- **Tone direction**: How the author should write this section
- **Asset markers**: `<!-- ASSET: description -->` where assets go
- **Author notes**: Specific instructions for expanding particular bullets

Comments don't render in markdown and the author deletes them as they
prose up each section.

## Typesetting guidelines

Include these as a checklist in the meta footer:

- Use non-breaking spaces (`&nbsp;` in HTML, `\u00A0` in frontmatter)
  and non-breaking hyphens where appropriate to avoid widows and orphans
- Titles MUST use sentence case, not Title Case
- Check title, image, and general post at different screen widths
- Avoid LLM tells: "it's worth noting", "importantly", "in conclusion",
  "let's dive in", "at its core", "in today's landscape"

## Reference blog posts

Existing posts by Electric authors that exemplify good execution. Use these
to calibrate tone, structure, and quality.

**Pyramid principle / narrative:**
- [Durable sessions for collaborative AI](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2026-01-12-durable-sessions-for-collaborative-ai.md) — thruflo
- [Bringing agents back down to earth](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-08-12-bringing-agents-back-down-to-earth.md) — thruflo
- [Building AI apps on sync](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-04-09-building-ai-apps-on-sync.md) — thruflo

**Best sales deck / concept:**
- [Announcing Durable Streams](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-12-09-announcing-durable-streams.md) — kyle, samwillis
- [Super-fast apps on sync with TanStack DB](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-07-29-super-fast-apps-on-sync-with-tanstack-db.md) — thruflo

**Release post:**
- [Electric 1.0 released](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-03-17-electricsql-1.0-released.md) — thruflo
- [Announcing Hosted Durable Streams](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2026-01-22-announcing-hosted-durable-streams.md) — kyle

## Image brief (quick version)

For a quick image direction, note in the meta footer:
- Subject/concept for the image
- Aspect ratio: 16:9 to 16:10 (target ~1536x950px)
- Master as high-quality JPG
- Center-center composition — key content in inner frame
  (responsive cropping will cut edges)
- Brand colors: `#D0BCFF` (purple), `#00d2a0` (green), `#75fbfd` (cyan),
  `#F6F95C` (yellow), `#FF8C3B` (orange)
- Dark theme background
- Site uses OpenSauceOne font

For a detailed image brief with reference image analysis and a full
ChatGPT DALL-E prompt, use the `/blog-image-brief` command separately.

## Review

Once the author has prosed up the outline, use `/blog-review` to review
the draft against the outline, format, and execution guidelines.


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### references/best-sales-deck.md

```markdown
# Best Sales Deck

Based on Andy Raskin's "Greatest Sales Deck I've Ever Seen" framework:
name a big change, show winners and losers, tease the promised land,
deliver magic gifts. Adapted for technical blog posts — the structure
does the persuasion, the tone stays Ronseal straight.

## When to use

You're introducing a concept, pattern, or paradigm shift to a technical
audience. You want to sell an idea — not with marketing language but with
the logic of "the world changed, here's what that means, here's how to
be on the right side of it."

Good for: product launches that represent a category shift, thought
leadership on emerging patterns, "why X matters now" concept pieces.

## Reference examples

- [Announcing Durable Streams](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-12-09-announcing-durable-streams.md) — kyle, samwillis
- [Super-fast apps on sync with TanStack DB](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-07-29-super-fast-apps-on-sync-with-tanstack-db.md) — thruflo

## Structure

The outline names each step of the narrative flow explicitly. The labels
are working structure — in the final prose they dissolve into section
headings that feel natural, not formulaic.

```
[TLDR + info box — standard, see SKILL.md]

The big change:

- Name an undeniable shift that's happening in the world
- This should be observable, not a claim — the reader can verify it
- Keep it factual and concrete, not hyperbolic
- This is NOT your product or company — it's the world changing

Winners and losers:

- This change creates stakes — show who benefits and who doesn't
- Make it concrete: "teams doing X ship in days, teams doing Y are
  still gluing together retry logic"
- The reader should see themselves (or want to see themselves)
  in the winners column

The promised land:

- Paint what life looks like on the right side of this shift
- Don't introduce the solution yet — describe the outcome
- This should feel desirable and specific, not utopian
- The reader should want this before knowing how to get it

The magic gifts:

- Now introduce the thing that gets you there
- Each gift is a specific capability, not a feature list item
- Frame as "this is what makes the promised land reachable"
- These become the ## headings for the body

## Gift a

- What it is, how it works, why it matters
- Evidence: benchmarks, code samples, demos

## Gift b

- ...

## Gift c

- ...

***

Next steps:

- CTAs, links, what to do now
```

## Ethos / creative angle

Same as pyramid principle — the Big Change and Winners/Losers sections
should be enhanced with a specific story or moment drawn from the author.
The logic comes first, then the creative angle makes it land.

The key difference from pyramid: here the anecdote grounds the *change*,
not the *shared reality*. It answers "how do I know this change is real?"
with lived experience rather than assertion.

## Tone guidance

- The structure is a sales deck. The tone is Ronseal
- The TLDR already gave the reader the punchline — the body gives them
  the reasoning to believe it
- No: "revolutionary", "game-changing", "unlock the power of"
- Yes: specific numbers, concrete scenarios, "here's what this looks
  like in practice"
- Technical audience respects being shown, not told
- The persuasion comes from the logic of the narrative arc, not from
  the language used to express it

## Key principles from Raskin's framework

- **Start with change, not pain.** The big change is not "you have a
  problem" — it's "the world shifted." This reframes the conversation
  from selling to informing.
- **The promised land is not your product.** It's the outcome the reader
  wants. The product is how you get there. Keep these separate.
- **Magic gifts earn the promised land.** Each gift should clearly connect
  to the promised land. If a gift doesn't advance the reader toward
  the outcome, cut it.
- **Show proof.** The framework works because each step builds credibility
  for the next. The big change is verifiable. The winners/losers are
  observable. The promised land is desirable. The gifts are demonstrable.

## Evaluation criteria

- Is the big change genuinely undeniable or are we asserting something
  self-serving?
- Do the winners/losers feel real or is it a strawman?
- Does the promised land describe outcomes, not features?
- Do the magic gifts actually deliver the promised land or is there a gap?
- Would a skeptical engineer read this and nod, or roll their eyes?

```

### references/pyramid-principle.md

```markdown
# Pyramid Principle

Based on Barbara Minto's Pyramid Principle: Situation, Complication, Question,
Answer, expanded as a MECE pyramid. Adapted for technical blog posts with a
compressed, no-nonsense tone.

## When to use

You have a clear point to make and need to build a logical argument. The reader
should arrive at your conclusion feeling like they reached it themselves.

Good for: technical explanations, "how we built X", opinion pieces with
substance, "why X matters" arguments.

## Reference examples

- [Durable sessions for collaborative AI](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2026-01-12-durable-sessions-for-collaborative-ai.md) — thruflo
- [Bringing agents back down to earth](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-08-12-bringing-agents-back-down-to-earth.md) — thruflo
- [Building AI apps on sync](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-04-09-building-ai-apps-on-sync.md) — thruflo

## Structure

The outline uses explicit SCQA labels as working structure. The Question is
often edited out or made implicit in the final prose. The Answer bullets
become the `##` headings for the body.

```
[TLDR + info box — standard, see SKILL.md]

Situation:

- Head-nodding statements the reader already believes
- Establish shared reality — no persuasion, just recognition
- 3-5 bullets. If the reader disagrees with any, the post isn't for them
- Every bullet should be so obvious it feels almost boring — that's the point

Complication:

- Introduce tension. Something changed, or something's broken
- The reader should feel "yes, that's my problem"
- This is the hook — if this doesn't land, they stop reading
- Keep it concrete: specific scenarios, not abstractions

Question:

- The question the complication naturally raises
- Stated explicitly in the outline as a working tool
- Often edited to be implicit in the final prose

Answer:

- a — first component of the answer
- b — second component
- c — third component
- These become the ## headings for the body
- Order by importance

## a

- Supporting argument / evidence / detail
- Sub-bullets become ### subsections where needed

### Sub-point of a

- ...

## b

- ...

## c

- ...

***

Next steps:

- CTAs, links, what to do now
```

## Ethos / creative angle

The Situation and Complication should be enhanced with a specific anecdote,
moment, or creative framing drawn from the author during the outline
authoring process. This is not a separate section — it's woven into how
the S and C are expressed.

The logic comes first (establish S and C as bullet points), then the
creative angle refines how they land. The author's personal experience
makes the shared reality vivid and earns the right to make the argument.

Annotate the creative angle inline in the outline:

```
Situation:

- Statement the reader agrees with
- Another shared reality point

<!-- STYLE: Open with [specific anecdote]. This grounds the situation
     in lived experience. The reader should think "this person gets it"
     not "this person is lecturing me." -->

Complication:

- But X is broken / has changed
- The reader recognises this tension
```

## MECE expansion

The Answer bullets expand into the body of the post as a loosely MECE
(mutually exclusive, collectively exhaustive) pyramid:

- Each Answer bullet becomes a `##` section
- Sub-arguments become `###` subsections where warranted
- Each section should stand alone — a reader who skips to one section
  should still get value
- Assess the logic informally: does the expansion hang together and feel
  complete? Are there overlapping sections or obvious gaps?
- This is a blog post, not a PhD thesis — the logic should be sound
  but don't nitpick mutual exclusivity

## Tone guidance

- Situation bullets should be matter-of-fact, confident, no persuasion yet
- Complication should make the reader lean in — emotional, not just logical
- Answer should be direct and clear — state the thesis, don't hedge
- Expansion sections: show, don't tell. Code, examples, evidence
- Bullets are compressed meaning — expand each into 1-2 sentences with
  minimal rewording. The compression often produces fresh prose naturally

## Evaluation criteria

- Does the situation establish genuine shared reality or is it hand-waving?
- Does the complication create real tension or is it manufactured?
- Does the answer actually resolve the complication?
- Do the expansion sections follow logically from the answer bullets?
- Would the reader reach the same conclusion if they followed the logic?
- Is the ethos / creative angle woven in or missing?

```

### references/release-post.md

```markdown
# Release Post

Ship often, communicate clearly, don't overthink it. The workhorse format
for incremental releases, new features, and point releases.

## When to use

You shipped something and want to tell people about it. This is the
keep-it-simple format for ticking-along releases. Bigger launches that
represent a category shift should use the Best Sales Deck format instead.

## Reference examples

- [Electric 1.0 released](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-03-17-electricsql-1.0-released.md) — thruflo
- [Announcing Hosted Durable Streams](https://github.com/electric-sql/electric/blob/main/website/blog/posts/2026-01-22-announcing-hosted-durable-streams.md) — kyle

## Structure

No narrative arc needed. Lead with what shipped and why it matters.
The TLDR *is* the what and why — no separate setup section.

```
[TLDR — this IS the what and why. 1-2 paras: what shipped,
 why it matters, key benefit. Info box with key links.]

## Context

- Brief orientation for readers not already tracking this
- 2-3 bullets max. If it needs more, link to a previous post
- Not a backstory — just enough to make the rest make sense

## What's shipping

- Concrete capabilities, numbers, facts
- Lead with benefits, follow with specifics
- Each bullet is a thing the reader can now do that they couldn't before

<!-- SOCIAL PROOF: embed positive tweets, quotes from users/community
     about the need for this or reactions to it. -->

<!-- ASSET: demo video with poster frame, or screenshot,
     or external blog post image tiles -->

## Get started

- Code samples, commands, steps
- Show don't tell — the reader should be able to try it

## Coming next

- Brief roadmap tease. 2-3 bullets
- Keeps momentum, shows we're not stopping

***

Next steps:

- CTAs: docs, cloud signup, discord
```

## Tone guidance

- Factual and brisk. This is a shipping cadence post, not an essay
- Dry is fine — let the content do the work
- Liven it up with: a good header image, video with poster frame,
  embedded tweets, external blog post image tiles
- No preamble, no throat-clearing. The TLDR opens the post and
  that's the pitch
- Celebrate shipping without overselling what shipped

## Visual elements

Release posts benefit from visual variety to break up what can
otherwise be a dry feature list:

- Demo video with a poster frame
- Screenshots of new UI or output
- Embedded tweets showing community need or positive reactions
- External blog post tiles linking to deeper dives
- Code samples showing the new thing in action

## Evaluation criteria

- Can the reader understand what shipped and why they should care
  in the first 30 seconds?
- Are benefits concrete or vague?
- Is there a visual element breaking up the text?
- Can the reader get started immediately from this post?
- Is the context section brief enough or is it becoming a backstory?

```