Catch the experience gaps in a spec before build

Specs are written around the thing working. The user clicks, the data loads, the success message appears. But most of the experience lives in the other states — the empty list, the failed request, the half-typed form, the user on a screen reader. When those aren't in the spec, an agent (or a rushing engineer) fills them in with whatever's fastest, and you find out in QA. Reviewing the spec from the design side puts those states on record before a line is written.

The input

A draft IntentSpec with the core flow already authored — objective, outcomes, evidence. The happy path is solid. What's missing is everything around it.

The flow

1. Walk every state, not just success. For each outcome, ask what the user sees when there's nothing yet, when it's loading, when it fails, and when it's their very first time. Each answer that's missing is a gap.

2. Add the missing states as edge cases. Empty state, error state, partial/slow state, first-run state. Write each as an explicit "must handle" item on the spec so it survives the handoff instead of being improvised.

3. Make the experience criteria checkable. "Feels responsive" becomes "skeleton state appears within 100ms; no layout shift on load." "Accessible" becomes a named, testable condition. Vague experience language is how regressions sneak through review.

4. Clear the readiness signals. Pathmode flags outcomes with no verification and edge cases with no evidence. When those are resolved, the spec describes the whole experience — not just the demo.

The output

A spec an agent can build the whole experience from:

• Every state enumerated — empty, loading, error, first-run, not just success
• Experience criteria made testable, so "polish" is a condition, not a vibe
• Accessibility on the record as a requirement, not an afterthought
• Fewer QA surprises, because the gaps were named before code existed

Why this beats catching it in QA

Finding a missing empty state in QA means it's already built, already styled wrong, and already on someone's plate to redo. Finding it in spec review means it's a sentence. Design review of the spec moves the experience decisions to the cheapest possible point — before the agent guesses, not after.

Try it yourself

1. Open a draft spec where the happy path is written but the rest isn't
2. For one outcome, write the empty, loading, and error states as edge cases
3. Turn one vague experience word ("smooth", "clean") into a testable condition
4. Clear the readiness signals and pass it to build

Related

• Use case: Review a spec for implementation risk before it enters the build queue
• Use case: Turn a usability test into a spec the team can build
• Playbook: Verification as an Executable Feedback Loop