Build spec

Build Spec

Most AI-built automations break in week two, not week one. They work in the demo because the demo is the happy path. Then a field comes back null, an API rate-limits, the agent runs twice on the same record, and nobody decided what should happen because nobody wrote it down.

This skill writes that down first. You answer a short interview, it produces a build spec you can read in two minutes and hand to Claude (or a human) to build against. The spec is the review surface. Vibe-coding the prototype is fine. Vibe-coding the spec is how you get slop.

Twelve sections, in order. Fill them as you go. Do not skip ahead to writing code.

Inputs (ask for whatever is missing)

• The one-line ask (required): "a thing that ___". The outcome, in plain English.
• Who runs it and where (the stack: Trigger.dev / cron / a server / a serverless function), and what it touches (which APIs, DBs, tools).
• Optional, makes it sharper: an example of a real input record, the worst input you can imagine, and how often it runs.

The 12 sections

1. Job to be done. One sentence: the outcome, not the mechanism. "Every morning, surface companies in our niche that started hiring this week." If you can't say it in one sentence, the scope is wrong — split it.

2. Trigger. What starts a run: a cron schedule (state it), a webhook, an event, a manual call. Note what happens if a run is still going when the next trigger fires (skip, queue, or overlap).

3. Inputs and sources. Every piece of data in, where it comes from, and how it authenticates. For each source: what happens when it's slow, empty, or down.

4. Outputs and destinations. What the run produces and where it lands (a row, a Slack message, an email, a file). The exact shape. Who or what consumes it next.

5. The happy path. The steps of one successful run, in order, plainly. This is the part the demo proves. Keep it to the steps, not the code.

6. State and idempotency. What the run remembers between runs. How you dedupe so the same item isn't processed twice. Whether re-running it is safe (it should be). What the unique key is.

7. Failure modes. The list nobody writes. For each external call and each assumption: what can go wrong, and what should happen when it does — retry (how many, what backoff), skip and log, fall back, or stop and alert. A null field is a failure mode. A 429 is a failure mode. A model refusing is a failure mode.

8. External dependencies and limits. Every third-party it leans on, their rate limits and quotas, and the cost per call. What degrades gracefully vs what takes the whole run down.

9. Observability. What gets logged per run, what a healthy run looks like, and the one or two things that should page you. If you can't tell whether last night's run worked without opening the database, the spec isn't done.

10. Cost and guardrails. The token / API budget per run, a hard spend ceiling, and a kill switch. What stops it looping forever or burning the month's budget at 3am.

11. Acceptance criteria. How you know it works, as checks you can run: "given this input, produces this output", "given a 429, retries twice then logs", "running it twice produces one record, not two." These become the tests.

12. Out of scope. What it deliberately will not do, this version. The single most useful section for stopping an agent from gold-plating. Write the "not yet" list explicitly.

Output

Produce the filled spec as a single markdown document under these twelve headings, with a one-line Open questions list at the top for anything the user still needs to decide. Then stop.

Do not write the implementation. The spec is the deliverable. Building to it — yours, or your agent's — is the next step, and now it has something to build against.