Writing a one-page AI feature spec
Write a one-page spec for an AI feature covering the user and job, success metric, quality bar, failure states, cost estimate and the non-AI alternative.
On this page
Why this matters
The cheapest place to discover that a feature is a bad idea is a document nobody has started building yet. A one-page spec forces the decisions that are expensive to change later: who it’s for, what success means, how good is good enough, and what happens when the AI gets it wrong.
AI features need a few sections a normal spec doesn’t. Output quality varies, so you need a quality bar. Failures are visible to users, so you need failure states. Every use costs money, so you need a cost estimate. This article walks through each section and finishes with a complete example you can copy.
Why one page
A one-page limit is a feature, not a constraint:
- It gets read. Reviewers read one page carefully. They skim ten.
- It forces decisions. You can’t hedge every point in one page, so you have to commit to a metric, a bar and a scope.
- It’s cheap to change. When a prototype proves an assumption wrong, updating one page takes minutes.
Detailed designs, technical plans and eval datasets can live in other documents and link from the spec. The spec is the decision record: what we’re building, why, and how we’ll know.
The sections of an AI spec
Show text descriptionHide text description
A stack of 8 layers, listed from top to bottom.
- User and job : Who has the problem and the job statement, with evidence
- Success metric : The one number that should move, plus guardrails
- Proposed solution : What the AI does and what the user does, in a few sentences
- Quality bar : What a good output is, and the eval threshold to launch
- Failure states : What users see when the AI is wrong, unsure, slow or declines
- Cost estimate : Rough cost per successful task, and what that is worth
- Non-AI alternative : What you would build without a model, and why AI beats it
- Open questions : What the prototype must answer next
Here’s what goes in each, and the question a reviewer should be able to answer after reading it.
User and job. Who has the problem, written as a job statement, with the evidence: ticket counts, interview quotes, analytics. Is this a real, frequent problem?
Success metric. One primary metric that should improve, and one or two guardrails that must not get worse. Defining success metrics covers how to choose them. How will we know it worked?
Proposed solution. A few sentences on what the AI does and what the user does. Say whether the AI does the whole job or part of it. Skip implementation detail. Is the user in control where it matters?
Quality bar. What a good output looks like, in concrete terms, and the pass rate on the eval set required to launch. If you can’t describe a good output, you aren’t ready to build. How good is good enough?
Failure states. What users see when the AI is wrong, unsure, slow, cut off or declines. Even one line each is enough at this stage. What happens when it doesn’t work?
Cost estimate. A rough cost per successful task, from expected input and output size and current model pricing, compared with what a success is worth. Order of magnitude is fine. Can this pay for itself?
Non-AI alternative. What you would build without a model: rules, search, templates, better defaults. Explain why AI is better here, or switch to the alternative. Is AI the right tool?
Open questions. The riskiest assumptions, phrased as questions the prototype will answer. What could still prove this wrong?
A worked example
Here’s a complete spec for a support-reply drafting feature. It fits on one page and answers every reviewer question above.
# Spec: AI-drafted replies in the support inbox
## User and job
Support agents handling routine tickets. When a customer asks a question our help center
already answers, agents want to send a correct, friendly reply quickly, so they can spend
their time on hard tickets.
Evidence: about 40% of last month's tickets were tagged "how-to" (support dashboard, March);
agents in 4 of 5 interviews copy-paste from help articles and rewrite by hand.
## Success metric
Primary: median time to first reply on how-to tickets.
Guardrails: customer satisfaction on those tickets doesn't drop; reopen rate doesn't rise.
## Proposed solution
On how-to tickets, the agent sees a draft reply that cites the help articles it used.
The agent edits and sends it. Nothing is sent automatically.
## Quality bar
A good draft answers the question correctly, cites at least one relevant article, and
matches our tone guide. Launch when 85% of drafts pass on a 60-ticket eval set,
graded by two senior agents. Threshold agreed on 2 April, before the first run.
## Failure states
- No relevant article found: no draft; show "No help article matches this question."
- Draft cut off: hide it and offer "Generate a shorter draft."
- Request declined or errored: show the normal inbox; log the event.
- Slow (over 8 s): keep the inbox usable; the draft appears when ready.
## Cost estimate
About 3,000 input tokens (ticket plus articles) and 300 output tokens per draft.
At current prices, a few cents per draft. An accepted draft saves several minutes of
agent time, so the feature pays for itself even if only a minority of drafts are used.
## Non-AI alternative
Saved replies. Agents already have them but rarely use them: 12 replies can't cover the
variety of questions, and searching them takes longer than writing. AI adapts to the question.
## Open questions
1. Do agents trust drafts enough to edit rather than rewrite? (Prototype: 5 agents, 1 day)
2. Is retrieval good enough to find the right article for most how-to tickets?
3. Does the tone match without per-agent customization?Notice what makes it work:
- Evidence is cited. The 40% figure names its source. A spec is a good place to practice the habit of never stating a number without one.
- The threshold has a date. Writing down when the bar was agreed makes it awkward to move it later.
- Failure states are concrete. Each one says what the user sees, not just that errors are “handled.”
- The cost estimate is rough but decisive. You don’t need precision to see that a few cents against several minutes of salary is a good trade.
Reviewing a spec
When you review someone else’s AI spec, or your own after a day away, ask:
- Could two people read the quality bar and agree on whether a given output passes?
- Is the success metric something we can actually measure on launch day?
- Is there a failure state for refusals and truncated answers, not just errors?
- Would the non-AI alternative get us most of the value for much less?
- Which open question, if answered badly, kills the feature? Is the prototype aimed at it?
If any answer is “no” or “not sure,” fix the spec before anyone writes code. The reference template has these sections ready to copy.
Common mistakes
- Writing ten pages. Long specs don’t get read and hide the decisions. Keep the decision record to one page and link to detail.
- A vague quality bar. “High-quality responses” can’t be tested. Describe a good output concretely and set a pass rate.
- No failure states. If the spec doesn’t say what happens when the AI is wrong or declines, the answer in production will be “something confusing.”
- Skipping the non-AI alternative. It’s the quickest way to catch features that don’t need a model.
- Uncited numbers. “Users spend hours on this” isn’t evidence. Name the source of every number, or mark it as an estimate.
Try it
Exercise
About 60 min
Write a one-page spec for your chosen problem
- Take the problem you chose in problem discovery.
- Write a spec with all eight sections, on one page.
- Ask someone else to review it using the five questions above. If you’re working alone, review it yourself the next day.
- Rewrite the weakest section.
Show a hint
If the quality bar is hard to write, try describing three outputs: one clearly good, one clearly bad, and one borderline. The difference between them is your quality bar.
Show a worked solution
There’s no single right answer. A good spec has these properties, which you can check:
- Every number has a source or is marked as an estimate.
- The quality bar would let two people agree on whether a given output passes.
- Failure states cover wrong, unsure, slow, truncated and declined.
- The cost estimate compares cost per success with the value of a success.
- The open questions are ranked, and the first one has a plan to test it within a week.
Check your understanding
Key takeaways
- A one-page spec is the cheapest place to kill a bad idea and the record of why you built a good one.
- AI specs add a quality bar, failure states, a cost estimate and a non-AI alternative.
- Cite every number, and date the quality threshold so it can’t drift.
- The open questions are the real decision: answer the riskiest one before building.
Progress is saved in this browser and lights up the roadmap.
Related articles
- Turning a prototype into a spec Turn what a prototype taught you into a buildable spec, with findings, decisions, the first eval cases and the open risks before engineering starts. Level: Intermediate
- Problem discovery for AI features Find AI feature ideas worth building by starting from frequent, painful user jobs instead of model capabilities, using data you already have. Level: Beginner
- User interviews for engineers Run short, useful user interviews as an engineer, from recruiting to asking about real behavior, avoiding leading questions and turning notes into decisions. Level: Beginner