Interview

/flow-next:interview is a deep Q&A pass against an existing spec. It extracts the requirements a conversation glossed over, then writes them back as new acceptance criteria on the same artifact.

A sharpening tool, not intake

The highest-leverage way to use interview: not as “interview me on this ticket” - that’s capture’s job (capture the ticket first; it proposes the spec count and tags every line with its provenance). Interview shines after the spec exists, pointed at what’s actually soft:

Burn down the guesses. Capture tags every line [user], [paraphrase], or [inferred] - so aim the interview at exactly the inferred ones: “do a business interview with me on this spec regarding anything that has been inferred”. Every question then lands on a line the agent guessed, not on things you already stated.
Pressure-test one requirement. “In-depth technical interview regarding R9” - the whole question machinery (recommendation-led questions, codebase investigation before asking, edge-case discovery) concentrates on the single criterion that worries you instead of re-walking the spec.
Let it find what you didn’t think about. A scoped technical pass surfaces edge cases and constraints the original material never mentioned - that’s the discovery half, and it works precisely because the settled parts are already tagged as settled.

Capture marks the guesses; interview burns them down.

The options are support, not the answer

A pattern we see in the field: teams treat each question’s proposed options as a multiple-choice test and blindly pick one - usually the recommended one. That inverts the tool. The AI proposes answers to help you think about the question; it should not be making these judgment calls for you. The recommendation is a starting position with a stated confidence, not a verdict.

When none of the options fit, that is not friction - it is the interview working. Use the Other option, and remember it is fully agentic, not just a text field for a fourth answer:

“None of these - here’s what actually matters: …” - answer in your own words; the spec records your words, tagged [user].
“Go do more research on the codebase before asking me this” - the interview investigates and comes back with a better-grounded question.
“This question isn’t the right one - focus on the migration risk instead” - redirect the whole line of questioning.
“Not decidable yet, park it” - it lands in ## Open Questions instead of forcing a fake decision.

An interview where you picked the recommended option every time didn’t sharpen anything - it laundered the AI’s guesses into requirements with your name on them. The questions where you push back are the ones paying for the session.

Do not reopen discovery as chart just because a valid spec has judgment gaps - interview owns those. Route backward to chart only when the questions reveal the effort itself is not yet specifiable. Chart also has an attended interview decision type that uses the same question machinery on a chart rather than a spec; that path never writes .flow/specs/.

Two question banks (business and technical) are selectable via --scope=business|technical|both. From 2.9.0, omitting the flag no longer silently runs the technical bank — the interview asks up front which pass to run (business / technical / both), recommending one based on the spec’s current state. A PM refining a fresh spec is steered toward the business pass instead of an architecture interrogation.

The symmetric interview

Both passes write to the same spec file. R-IDs are append-only across passes, so a business pass followed by a technical pass produces one continuous chain.

Pass	Asks about
Business	Problem framing, target user, success metrics, MVP scope, what NOT to build, prioritization rationale, business risks, UX expectations.
Technical	Architecture, API contracts, data model, edge cases, performance, security boundaries, test strategy.

/flow-next:interview fn-1 --scope=business
/flow-next:interview fn-1 --scope=technical --strategy --docs

Teams should keep the passes distinct so product ownership and engineering ownership are both visible in the artifact. Solo developers can collapse them with --scope=both.

Question rounds

The interview maps the spec as a design tree - every decision branches into the decisions that hang off it - and asks in rounds over the tree’s frontier: the questions whose prerequisites are already settled, askable now without guessing at answers not yet heard.

Each round asks the whole frontier, split across question calls of up to 4 questions each, grouped by topic and announced as one round (“Round 2 - part 1/2”).
A question is never asked alongside its own prerequisite. Anything that depends on an answer still open in the current round waits for a later round.
A frontier slot is earned. Every genuinely open decision joins the round - NFR probes (failure modes, concurrency, scale, portability, testing) always qualify, however thin the spec - but pure-cosmetic polish (message wording, label spelling) never gets its own question: it folds into a related question’s options or a stated default the user can veto at write-back.
The frontier is recomputed between rounds. Answers reshape the tree: settled decisions unblock their dependents, pruned branches are announced at the next round’s opener (“Skipping persistence questions - you said no DB”), and the interview is done when the frontier is empty.

Standalone checkpoints - scope selection, the code-mismatch question, write-back consent, the mark-ready offer - sit outside rounds and are never counted against them.

While the user answers a round, the interviewer may dispatch a read-only fact-scout to resolve in the background the codebase lookups gating the next round’s questions - investigation latency hides inside answer time instead of stalling the interview between rounds.

No time-budget questions

From Flow-Next 1.1.5 the business interview no longer asks about deadlines, sprint cadence, or “ship before X”. Two reasons:

Agents can’t reliably estimate their own work, so any answer is a guess that anchors the rest of the interview.
Time-pressure framing collapsed interviews into brutal-prioritization debates instead of surfacing requirements.

MVP-scope cuts are still asked, but reframed by feature value instead of clock. The budget envelope question is scoped to infrastructure, vendor, and licensing cost.

Doc-aware behaviors

The interview integrates with the repo’s existing documents:

Resolves vocabulary against GLOSSARY.md.
Surfaces foreign-file references when answers cite paths.
Flags contradictions with active STRATEGY.md tracks.
Writes a decision-record entry when a strategy track is intentionally overridden.

Doc-aware meta-questions carry a per-round budget: at most one glossary question, one strategy-conflict question, and three doc-aware questions combined per round. A meta-question deferred by the budget is held for a later round, not dropped - the one sanctioned hold-back in the rounds protocol.

Source tags on the criteria it writes

Every acceptance criterion the interview newly writes carries a trailing provenance tag, the same vocabulary /flow-next:capture uses: [user] for the human’s words, [paraphrase] for their meaning tightened, [inferred] for the agent’s own fill-in, [strategy:<track>] when it traces to a STRATEGY.md track. Under a business pass [user] means the PO; under a technical pass, the tech lead.

That makes “which of these did I actually say?” a grep rather than a re-read - see the tally recipe. Three rules to rely on:

A pass tags only what it authors and never retags an existing bullet, so provenance is frozen exactly like the R-ID number. On a spec that went through both passes, each tag reflects the pass that wrote it.
Untagged means unknown provenance, never [user]. Criteria written by hand, or before this shipped, carry no tag.
The read-back will not recommend approve while unverified [inferred] items remain - narrowed here to inferred criteria that no question covered, since an answered question has already done the verifying.

Tags apply to a spec’s ## Acceptance Criteria bullets. Task acceptance is a plain checklist and carries none, and an interview over a loose markdown file leaves that file’s shape alone.

Spec-count check

Since 3.16.2, when refinement pushes a spec past 8 counted requirements (business and technical only - standing criteria and process items never count) or an answer reveals a second independently shippable outcome, interview proposes a split before writing back: proposed titles, requirement allocation, and dependency edges, with keep-single as the default. Criteria a review cycle has already judged are never moved or renumbered - for those the proposal is recorded in the spec’s Decision Context instead. Autonomous runs never split.

Mark-ready offer

After the write-back, when readiness is adopted in the repo (≥1 spec already marked ready) and tracker.readyState is not configured, the interview offers once to mark the refined spec ready for execution. Default is keep-draft — re-read the refined spec on disk before blessing it. The offer applies to flow-spec inputs only (task ids and file paths carry no spec readiness), and refinement never auto-resets a previously-blessed spec — only /flow-next:capture --rewrite does. Non-adopters see no question anywhere; tracker-connected repos set readiness on the board.

Question discipline

Each question leads with the recommended option and a confidence tier:

[high] — the agent is confident in the recommendation.
[judgment-call] — reasonable people disagree; the user should weigh in.
[your-call] — the agent has no view; the user owns the decision.

Questions arrive in rounds - up to 4 topically grouped questions per call, the whole frontier per round.

Skips are not answers (2.9.0). Only an explicit answer or an explicit “you decide” delegation resolves a question — the agent’s recommendation never silently becomes spec content. Every skipped, declined, or “I don’t know” question parks under ## Open Questions with an owner hint and the agent’s unconfirmed leaning. When at least one question was skipped, a consent checkpoint runs before the spec is written back:

park-open (default) — skipped items land under Open Questions only; nothing skipped becomes a decision.
fill-assumptions — the agent’s recommendations are written into the spec, each marked inline *(assumed — unconfirmed)*, with an Open Questions pointer for later ratification.
re-ask — walk the skipped questions once more.

Worked example

/flow-next:interview fn-14-rate-limits

Reading spec fn-14-rate-limits... 3 gaps found: limit scope (per-user? per-key?),
burst behavior, and the 429 response contract.
Round 1: 4 questions (multiple choice + free text)...
Round 2: 2 follow-ups on the sliding-window choice...
Spec updated: Boundaries sharpened, R3 rewritten, R6 added, 0 open questions remain.

The interview extracts decisions you already half-made and pins them into the spec before any code exists.

Dynamic usage

Recipes that compose with interview in the cookbook:

Prompt into a stage - “interview me only about the error-handling section” scopes the rounds.
Team patterns - interview + Spec-as-PR is the async replacement for a refinement meeting.

Next step

/flow-next:plan <spec-id>

If the interview reveals fundamental ambiguity, return to /flow-next:capture --rewrite or /flow-next:strategy before planning.