DAY 03 · Refine
Refine — Turn Intent Into Specs AI Can't Misread
"Add password reset. Email the user a link." The AI shipped it — links that never expire, tokens in the logs, resets for accounts that don't exist. The AI didn't fail. It did exactly what the spec said. The spec just didn't say much.
The spec failed. Not the AI.
A human engineer reads "Add password reset. Email the user a link" and silently fills in the missing half: links expire, unknown emails get a neutral response, tokens never touch a log. Ten years of judgment, applied without being asked.
AI has no silent half. It reads the words, and only the words. Everything you didn't specify becomes a decision it makes for you — invisibly, confidently, and at machine speed across every file it touches.
This is the mechanic underneath every "the AI wrote bad code" complaint: AI turns specifications into code faithfully — including faithfully reproducing the gaps in a vague one. The output is a mirror of the input. When the output is wrong, the spec was wrong first.
Which changes where the work lives. For thirty years we treated the spec as the annoying paperwork before the real work of coding. That's inverted now. "Specs are the new code" — Sean Grove, OpenAI, AI Engineer 2025. The spec is the artifact you author. The code is what gets generated from it.
Refine is the CRAFT Method practice for authoring that artifact: turning intent into a specification precise enough that AI can't misread it — before generation begins.
The instrument: the PRP
You don't refine a spec by writing a longer paragraph. Paragraphs are the problem — AI interprets prose differently every run.
The instrument is the PRP — the Product Requirement Prompt. Not a wish, not a ticket, but a structured document that carries everything AI needs to implement correctly the first time: the goal, the constraints, the acceptance criteria, the edge cases, the code examples and schema fragments, and the validation gates that prove it's done. Refine breaks into five sub-practices — read them as a checklist for what a real spec contains.
The cost-of-fix curve
The reason Refine comes before AI touches the keyboard is economics, not tidiness. A defect caught in the spec costs one edited sentence. The same defect caught downstream multiplies at every stage.
Vague ticket vs refined spec
The uncomfortable truth
The median AI PR written without structured requirements runs 150% larger with 9% more bugs (2025 PR-size analysis). And roughly 70% of AI suggestions get rejected — a 30% acceptance rate — the majority for ambiguity: the AI answered a question the spec asked badly (developer surveys, 2025).
Sit with the 150% number. When you skip the spec to "save time," AI doesn't do less work. It does more — it generates a PR half again as large, carrying more bugs, that your reviewers then reject seven times out of ten. The vague ticket didn't save the ten minutes of spec-writing. It spent them, with interest, three stages downstream.
Most teams don't feel this as a spec problem. They feel it as "AI is unreliable" or "our reviewers are swamped." It's neither. It's an under-specified input producing an over-sized, under-correct output — exactly as designed.
Mostly A's puts you at The Vibe Coders — requirements live in chat messages, every session reinvents the wheel, edge cases surface in production. Mostly B's is The Ticket Followers — specs exist but are loose. Real specs on major features but inconsistent adoption is The Emerging Specifiers; a standard format most work starts from is The Structured Specifiers; full specification-driven development is The Spec-Driven Org. Most teams honestly land in the first two — the expected starting point, not a verdict.
Refine closes the gap the same way for every archetype: it moves the decision from after generation, where it's expensive and invisible, to before generation, where it's one edited sentence. You stop generating from two-line tickets and start generating from specs AI can't misread — and the 150%-larger, 9%-buggier, 70%-rejected PR stops being your default output.
- A - There's no spec. A developer opens the tool and prompts until something works.
- B - There's a ticket with a description. Some are good; most aren't. No shared standard.
- C - Every non-trivial task starts from a validated spec that passed a completeness check before any code was generated.
- A - In conversation, or in the developer's head. Nothing an AI could parse.
- B - As prose bullet points — readable, but not testable, and interpreted differently each run.
- C - As predicates — IF condition THEN outcome — that AI parses the same way every time, with anti-patterns stated explicitly.
- A - No. Nobody checks whether the output matches what was asked.
- B - Manual spot-checks by whoever's reviewing. Inconsistent.
- C - Every change traces to a requirement, and a validation gate confirms compliance before merge.
The Free CRAFT Scorecard does precisely what you've just done by feel — 25 questions, 5 minutes, your archetype before your next standup ends. Take it at craftmethod.co/scorecard/free. — Luis