A spec document with visible structure transforming into a finished blog post, blueprint-to-building aesthetic

Part 1 was about making my second brain AI-readable, markdown, YAML, wikilinks. Part 2 covered what happened when AI started operating inside it, routing tables, search tools, CLI scripts. This post is about the artifact that sits between “I have an idea” and “AI writes the draft.”

I can prompt Claude to draft a 2,000-word blog post in about two minutes. The words come out coherent, well-structured, publishable-looking, that’s the easy part now. The hard part is knowing what I want to say, the angle, the arc, what to include and what to cut. The first few posts I wrote with AI, I’d give it a topic and some bullet points and it would give me back something that read fine but didn’t say what I meant. The ending didn’t land because there was no arc to land. The angle drifted because I never committed to one. I’d end up rewriting most of it, which defeats the point, I was handing off execution without doing the thinking first.

Every post on this blog now starts with a spec. A one-page planning document that captures what I want to say before AI writes a word. The spec you’re about to learn how to write is the same one I used to write what you’re reading. It’s at the bottom if you want to skip ahead, but reading how it works first makes it more useful.

What a Spec Is (and What It Isn’t)

Three fields solved this problem independently.

Content marketing calls it a “content brief.” It’s focused on SEO, target keywords, word count, audience persona, recommended headers. HubSpot’s research says 90% of the writing work happens at the outline stage, not during drafting. The brief prevents misalignment before the expensive work begins.

In screenwriting it’s called a “treatment.” Focused on story, arc, characters, themes, conflict, resolution. Jon James Miller describes it as a “structural X-ray” that forces you to see the skeleton of your story before writing dialogue. When the treatment is solid, “scripting becomes infinitely easier, words fly onto the page.”

AI-assisted development calls it a “spec.md.” Addy Osmani at Google advocates a Spec → Plan → Code methodology where you never jump straight to implementation. He calls the upfront investment a “waterfall in 15 minutes,” rapid structured planning that smooths everything downstream.

My blog post spec borrows from screenwriting because all three fields landed on the same thing: plan before you write. I don’t plan for keywords or word count, I plan for arc, tension, resolution, and angles across formats. Hannah Sanderson at Atlassian puts it well: “content design is its own form of screenwriting, it’s merely the size of the screen that differs.”

The Seven Attributes

Every spec I write covers seven things. Each one prevents a specific failure mode.

0. Stakes / Why Now. Forces you to articulate why this post needs to exist today, what tension makes it timely. This prevents writing posts that could’ve been published any time with no urgency, and if I can’t answer “why now” the post isn’t ready.

1. Arc (Setup → Tension → Resolution). The narrative flow: what the reader already knows coming in, the counterintuitive claim, and the core insight. Without an arc a post reads like a list of facts with no reason to keep going.

2. Angles (Blog, LinkedIn, X/Twitter). Each format gets its own framing. The blog gets the full narrative, LinkedIn gets the professional takeaway, X gets the provocative hook. Writing three angles forces me to think about the core insight from different directions, and that sharpens the blog angle.

3. Topic. One sentence that forces me to commit to what the post is actually about, and if I can’t write that sentence I haven’t thought it through.

4. Sections. Headers with 1-3 bullets each describing the key point or evidence that section delivers. This is the skeleton, and anything that doesn’t fit a section doesn’t belong in the post.

5. Hero Image Concept. Visual direction decided upfront, what the image represents, the mood, the metaphor. Prevents the scramble at publish time where you’re looking for a stock photo that vaguely relates to the topic.

6. Scope Boundaries. What the post is NOT about. I find this the most useful because AI fills gaps confidently and you won’t notice the drift until you check. The spec for this post says “NOT about: the editorial loop” and “NOT about: the full pipeline from capture to publication” because those are Parts 4 and 5, and I’d absolutely wander into them without the constraint.

The whole thing fits on one page and takes about 20 minutes with AI helping brainstorm, because if the spec takes longer than the post itself you’ve over-engineered it.

The Spec as Context Engineering

The spec does more than organize the post, it loads your arc and angle into the AI’s context window, tells the model what to emphasize and what to skip before it writes anything. Without a spec I’m asking AI to guess all of that from a topic sentence, and it’ll guess confidently in the wrong direction.

Osmani frames this well: “having a clear spec means when we unleash the codegen, both the human and the LLM know exactly what we’re building and why.” ClickRank’s 2026 research puts AI-assisted content workflows at 80% AI labor, 20% human judgment. The spec is the primary vehicle for that 20%.

I wrote about how LLMs are compaction tools, the model has access to vast knowledge and you decide where it focuses. The spec is how you make that decision explicit before the drafting starts.

Pre-Flight and Post-Flight

Miller discovered something useful about screenwriting treatments: they work in both directions.

Pre-flight is the obvious use. Write the spec before drafting to plan the structure, catch problems early, align direction. You’re checking whether the arc holds, the angles are distinct, the scope is clear. Fixing a 1-page spec is much easier than restructuring a 2,000-word draft.

Post-flight is the diagnostic use. After the draft is done, check it against the spec. Check whether the arc held or the post wandered, whether each section delivered what it promised, whether the scope boundaries stayed intact.

The post-flight catches a failure mode specific to AI-assisted writing: the draft that “reads well” but drifted from your intent. AI produces confident, polished prose that sounds right, and that confidence makes drift harder to spot without something external to check against.

My full workflow:

Idea → Research → Spec → Draft → Editorial Loop → Check against spec → Finalize

The spec bookends the writing process, starting as a planning tool and finishing as a quality check after the draft is done.

This Post’s Spec

This is the actual spec I wrote before drafting what you just read. Check whether each section delivered, whether the arc held, whether the scope boundaries stuck, that’s the post-flight from the previous section playing out as you read.

Stakes / Why Now

AI removed the writing bottleneck. The thinking bottleneck remains. Part 2 went live last week, series is warm. This answers “how do you actually write these posts?”

Arc

  • Setup: AI drafts 2,000 words in minutes. Writing is no longer the hard part.
  • Tension: Speed without direction produces slop. Drafts that read well but wander, angles that drift, endings that don’t land.
  • Resolution: The spec — a one-page narrative planning doc borrowed from screenwriting, not SEO. And here’s the one I used to write this post.

Angles

  • Blog: Self-referential. Teach the spec by showing this post’s spec. Three fields validate the approach.
  • LinkedIn: AI drafts in 60 seconds, the spec takes 20 minutes. That’s where the thinking lives.
  • X/Twitter: AI made writing easy. It didn’t make thinking easy. The spec for this post is at the bottom.

Topic

A one-page spec captures arc, angles, and scope before AI drafts a word. Three industries converge on the same idea. This post teaches the workflow and proves it by revealing its own spec.

Sections

  • Introduction: Writing Got Easy, Thinking Didn’t
  • What a Spec Is (and What It Isn’t)
  • The Seven Attributes
  • The Spec as Context Engineering
  • Pre-Flight and Post-Flight
  • The Reveal: This Post’s Spec

Hero Image Concept

Blueprint-to-building metaphor. Spec document on one side with visible structure, finished post on the other.

Scope Boundaries

  • NOT about: editorial loop / reviewer agent (Part 4)
  • NOT about: full pipeline from capture to publication (Part 5)
  • NOT about: SEO, keyword research, content marketing strategy
  • NOT about: vault structure, AGENTS.md (Parts 1-2)

If your AI-assisted drafts keep coming out vaguely right but not quite what you meant, try writing a one-page spec first, about 20 minutes of thinking before AI writes anything.