# Writing a spec that doesn't backfire

The AI obeys perfectly. That means *your specification is the bug*. Before you
hand it a task, run it past this list — most failures are caught right here, for
free, before a single line is written.

## The pre-flight checklist

- [ ] **No hidden contradictions.** Did I ask for things that fight each other?
      (e.g. "be brief", "be thorough", and "be certain" at once — mathematically
      no answer can satisfy all three, so you get nothing usable.)
- [ ] **Goal, not proxy.** Did I describe what I actually want, or a metric that's
      easy to game? "Pass the tests" is a proxy; "be correct" is the goal. It will
      optimise whichever one you wrote down.
- [ ] **Acceptance criteria are concrete.** Could someone tell, unambiguously,
      whether the result is right? If you can phrase it as a test, do — *the spec
      becomes the test suite.*
- [ ] **Edge cases named.** Empty input, zero, negatives, duplicates, "what if it's
      missing?" If you don't say, it will guess — confidently.
- [ ] **Constraints stated.** Performance, security, money handling, what it must
      NOT touch. Unstated constraints get violated.
- [ ] **Examples included.** One good input→output example removes more ambiguity
      than a paragraph of prose.

## A good prompt shape

```
Goal:           <the outcome you actually want, in one sentence>
Context:        <where this lives, what it must fit with>
Constraints:    <must / must-not — perf, security, style, don't-touch>
Acceptance:     <how we'll know it's right — ideally as tests>
Edge cases:     <empty / zero / negative / missing / duplicate>
```

## Risk-stratify the request before you send it

Not every task carries the same blast radius. Match the rigour of the spec — and
the human review after it — to what the work touches:

| Data / impact class | Spec rigour | After the build |
|---------------------|-------------|-----------------|
| **Public / low-stakes** (drafts, internal tooling) | Goal + one example | Spot-check |
| **Internal / business** (reports, non-customer logic) | Full checklist above | Verify with data |
| **Sensitive / PII** (customer data, accounts) | Add explicit handling: what may be read, logged, retained; scrub rules | Independent review + audit trail |
| **Regulated / irreversible** (money movement, decisions of record) | Acceptance as executable tests; named edge cases; human sign-off gate | Frontier-model or human verification; nothing ships on a green check alone |

State the class in the brief. "This handles customer PII" or "this moves money"
changes how the AI should behave — and unstated, it will default to the
convenient path.

## The BA/PO superpower

Your role didn't shrink — it became more valuable. Point the AI at an ambiguous
requirement and ask: **"Where is this contradictory or unclear?"** Finding the
contradiction *before* the build is now worth more than the build itself.