Spec first

Much of the pain in agentic coding starts with a missing plan. This page shows what a spec is, what yours from today contains, and how to write one for your next project.

What a spec is

A spec is a short written plan: what you build, for whom, and how you know it is done. It is not a long document. Yours from today fits on one screen.

The agent reads it before it works. So does every later chat. Without it, each chat starts by guessing, and each guess is a chance to build the wrong thing.

Your spec from today

The Analyst wrote docs/spec.md in your repo. It has these parts:

• Who: your name and headline.
• For whom: who should visit your site, for example recruiters for frontend jobs.
• What a visitor should do: the one action that matters, for example write you an email.
• Language and Sections: what your site contains.
• Left out on purpose: the kinds of private data that stay off your site.
• Later: what you want to add at home.

Two lines started with "(a guess)": the Analyst did not ask who your site is for. Correct them when they are wrong. A spec is only useful when it is true.

Let the agent interview you

For your next project, do what the Analyst did with you: let the agent ask before it builds. One question at a time works better than a long form, because each answer shapes the next question.

Agent chat

I want to build <your idea in one sentence>. Do not design or write code yet.
Interview me first: one question at a time, at most eight questions,
about who it is for, what it must do, what it must not do,
and how we will know it works.
Then write a short spec to docs/spec.md and read it back to me.

A spec template

Ask the agent to fill in this shape, or fill it in yourself:

A file in your repo, such as docs/spec.md

# Spec: <name>

## Problem
Who has it, and why it matters now.

## Solution
The approach, in plain words.

## Out of scope
What we do not build this time.

## Done when
- [ ] <something you can see or test>
- [ ] <something you can see or test>

## Open questions
What we still have to decide.

From spec to small tasks

A spec says what; small tasks say how, one piece at a time. Each task has a clear "done when", and each gets a fresh chat. Today's Roles worked exactly like this: six small tasks, each with one outcome, each in its own chat.

This order follows the flow Matt Pocock describes in his skills for coding agents: get interviewed, write the spec, split it into tickets, give each ticket a fresh context, build, review. His skills automate the flow for bigger projects, with the tickets as GitHub issues.

Each part prevents a typical pain

• The spec prevents "we built the wrong thing".
• Small tasks prevent "this took three times as long as planned".
• A review against the spec prevents "it works on my laptop, but not for the visitor".