Explore first, then capture

Write the spec at the moment you know the most, which is after you have explored, not before. Prototype the awkward screen, reproduce the bug, run the eval, read the code, and then capture what you learned as acceptance criteria a reviewer and an agent can both hold you to.

That ordering is the whole practice, and it is also the answer to the objection this page gets asked more than any other: “spec first means decide everything up front, so this is waterfall with a new coat of paint.” It comes from the most experienced person in the room, usually within ten minutes, and it deserves a real answer.

What waterfall actually is

Waterfall is not “thinking before building.” Three properties make it waterfall:

Phases you cannot return to. Requirements close, then design closes, then build starts. Going back is an exception with a change-control form attached.
A plan frozen before contact with reality. Commitments are made at the moment of least knowledge and defended afterwards.
Lossy handovers. Each phase discards what the next one learns. What the builders found out never travels back to the document.

Flow-Next has none of the three, and the reason is structural rather than cultural.

Stages are re-enterable. Re-interview a spec after planning exposed a hole. Re-plan after a task shows the approach was wrong. Amend a spec mid-flight. The pipeline is a composable pipeline, and that applies backwards as well as forwards.
The spec is written at the moment of most knowledge, not least. That is the entire point of capture: you explore first, and the spec records what the exploration settled. A spec you wrote before looking at anything is a bad spec, and the interview exists to find that out.
The handover is not lossy - it is the product. Evidence, review verdicts, and QA results are written back into the spec as work proceeds. The spec at merge is not the spec at capture. A waterfall document is authored once and defended; a spec accumulates.

The honest concession, because dodging it costs you the room: yes, this requires more thought earlier than a loose ticket does. That is real. What it does not require is more commitment earlier. The distinction is the whole doctrine.

The spec is a ratchet, not a gate. A gate decides what you are allowed to do next. A ratchet just stops you sliding back. You do not need the spec’s permission to read code, prototype, or research - the spec exists so that what you learned cannot be silently lost by the next stage, the next person, or the next agent.

What you are actually comparing against

The waterfall objection almost always compares Flow-Next against an idealized agile process nobody is running. Compare against what the team does today, one week after the AI coding tool was switched on:

A vague ticket goes into the agent. The agent produces something. Someone looks at it, does not like it, prompts again. Looks again, fixes by hand, prompts again. Round and round until it looks close enough to ship.

That loop is not agility. It is rework with no artifact - the requirement is being discovered, one prompt at a time, and then thrown away. Two things follow:

Nothing accumulates. The next person to touch that code inherits a diff and a dead chat scrollback. Every insight paid for in that loop is gone.
It forecloses autonomy permanently. You cannot automate a process whose only record is a conversation. The pilot build loop and the land ship loop both work by advancing a spec one stage per tick and reporting a machine-greppable verdict - that is what lets your host’s /loop or /goal drive them unattended, and what makes autonomous bug-fixing possible later (the defect traces back to a feature, its spec, and its evidence). The prompt-look-fix circle produces no such object, so a team stuck in it can never climb the autonomy dial, no matter how good the models get.

Flow-Next pulls the knowledge dump from the POs, PMs, and lead devs slightly forward in the process, and writes it down. That is the change. It is a smaller change than it sounds like, and a larger one than it looks.

What capture actually takes as input

The stubborn assumption underneath the waterfall fear is that “spec-driven” means somebody sits down and writes a requirements document. Nothing in Flow-Next asks for that. Capture takes whatever carries the intent: a conversation, a refinement session, a half-formed briefing package, a business requirements doc, a working prototype, a generated interface image, an eval result, or a spike you are about to throw away.

The pattern underneath all of them is one move: let something real answer the question, then capture the answer. The routes for doing that, and the rule for how much fidelity a question actually needs, are in From prototype to spec.

The ideation edge stays open on purpose

Everything from capture onwards is heavily exercised and deliberately opinionated. The stage before capture - ideation, product shaping, customer requirements - is intentionally left composable, because it is the most company-specific part of any delivery process and the part where human decision matters most.

So bring your own front door. A prototype, a BRD skill that talks to customers in business language, a discovery questionnaire, an intake form: build it to fit your organization, have it emit a briefing artifact, and start the pipeline from there. The composable pipeline principle applies at the front of the pipeline exactly as it does inside it.

One caveat learned the expensive way: keep the customer-facing business document distinct from the technical execution detail. Collapsing product language, technical language, and contractual language into a single artifact serves none of the three audiences.

What holds on every route

None of this flexibility is bought by loosening the guarantees. Whether the spec came from a two-hour refinement session, a prototype captured in ten minutes, or an overnight eval run, the execution, evidence, and review contracts are identical - the three of them are stated once, in Skipping and composing stages. Evidence-seeded specs get no discount for having done their homework early: a prototype does not vouch for the code that replaces it, and a green eval does not vouch for the diff that adopts it.

The spec is what makes verifiability, accuracy, and evidence possible at all: it is the thing acceptance criteria attach to, the thing review checks against, the thing a defect can later be traced back to. Take it away and there is nothing to verify against except somebody’s memory of what was wanted.

That is why the spec earns its place. It was never there to tell you what you are allowed to explore.

Skipping and composing stages - the flexibility doctrine this page is the second half of
From prototype to spec - the technique: routes, fidelity, and what happens to prototype code
Writing Specs - what belongs in a spec and what does not
FAQ - spec sizing, the spec-library misconception, and the rest of the field objections