# Capture Source: https://flow-next.dev/skills/capture/ Synthesize a conversation into a flow-next spec with source-tagged R-IDs, then review the saved file. `/flow-next:capture` turns a recent design conversation into a durable spec without losing the source of each requirement. The host agent extracts user turns, drafts a structured spec at `.flow/specs/.md`, tags every acceptance criterion with its origin, saves the spec, and offers to open the saved file in your editor. ## When to use it Capture is the pipeline’s **intake valve**: it doesn’t want a requirements document, it wants whatever carries the intent. All of these are first-class inputs - pipe one in and say “capture the initial spec”: * an idea you just talked through with the agent * a briefing packet from a kickoff * an already-well-described ticket * research the agent just ran (“research competitor pricing, then capture a spec for a tiered pricing page”) * a prototype (“capture a spec from this prototype - ignore the code quality, I want the intent and the requirements it demonstrates”) * a [chart](https://flow-next.dev/skills/chart/) briefing package Capture is upstream of `/flow-next:plan` and `/flow-next:work`. What it hands downstream is more than a document. The [spec-count proposal](https://flow-next.dev/skills/capture/#spec-count-proposal-epic-shaped-inputs) settles “one spec or several?” at intake, and the source tags mark exactly which lines are the agent’s guesses - which is what makes [refine](https://flow-next.dev/skills/refine/) targetable afterward. Capture the material first, then sharpen; “refine this ticket” skips the step that makes the question pass precise. Use it when: * The conversation already contains the requirement, or a chart briefing is ready. * Intent and boundaries are stateable (if they are not, chart first - do not force capture). * You want the spec to credit user statements vs. agent inferences. * A teammate will pick up the work and never saw the chat. If the conversation left a product or authority decision open that would change what gets built, run `/flow-next:refine` afterwards to settle it. Under [`/flow-next:flow`](https://flow-next.dev/skills/flow/), capture is invoked with the token `from:flow`; the flow page describes what changes on that path. Chart decision evidence (D-IDs, assets, supersession) is cited as briefing provenance - it does **not** become acceptance-criterion source tags. Capture (and refine) own trailing tags on criteria they newly write. ## Source tags Capture tags only what it authored, so reviewers can see where each line came from. Your own words stay untagged: * untagged: your verbatim requirement (trimmed is fine, reworded is not) * `[paraphrase]`: your requirement restated in spec language * `[inferred]`: agent filled the gap * `[strategy:]`: derived from `STRATEGY.md` The summary surfaces the `[inferred]` count so you can inspect assumptions in the saved spec; your words count under `[user]` in its tally. Capture asks only on duplicates and its must-ask cases (an ambiguous title, an untestable criterion, a scope conflict); other inferred content surfaces in the summary instead of as a question. ## The evidence block An untagged criterion is a claim that you said it, so capture collects your verbatim turns first and checks every untagged line against them before it saves. A close rewording is tagged `[paraphrase]`. An option you picked from one of capture’s questions counts as your input, recorded as the option label exactly as shown. With the bundled scaffold those quotes are also written into the spec as a `## Conversation Evidence` section, so a reviewer can look up the quote behind a tag. No tool reads that section. If your team finds it is 15 to 20 lines nobody acts on, [leave it out of your `SPEC.md`](https://flow-next.dev/guides/spec-scaffold/#leaving-a-section-out). The check still runs during capture, and the quotes stay out of the committed file. ## Review the saved spec Asking for capture authorizes saving the spec. Capture writes the file, reports its title, criteria and source tally, and offers `open in editor` or `continue`. Edits target that saved file; after an editor round, capture re-reads it, validates the result, and reports the changes. The full spec prints on request. Substantive questions still happen before a decision is recorded. Saving a spec does not mark it ready, authorize implementation, or grant merge permission. Refine and plan retain their own approval contracts; scripted `mode:autofix` still requires `--yes`. ## Spec-count proposal (epic-shaped inputs) Since 3.16.2, capturing an epic, briefing package, or large feature answers the question “is this one spec or several?” for you. At 8+ counted requirements - business and technical only; standing criteria and process items like “tests must be green” never count - or when the requirements clearly serve more than one independently shippable outcome, capture presents a concrete proposal: per-spec titles, which requirements go to which spec, and the dependency edges between them. Choosing `split-as-proposed` authorizes saving the proposed linked set, followed by the editor offer. This dissolves the perennial “how big should a spec be?” debate at intake: capture the **entire epic**, let the proposal scope it into specs whose dependencies are already sorted, then improve each spec where it’s soft - steering prose or a targeted [refine](https://flow-next.dev/skills/refine/) - instead of hand-carving one oversized document. The judgment is independence, not size - a large-but-cohesive spec is recommended to stay one spec, and small captures see nothing new. Nothing splits without your say-so; autonomous runs record the proposal inside the spec’s Decision Context instead of acting on it. ## Mark-ready offer When `tracker.readyState` is **not** configured, a new capture in a repo that has adopted [readiness](https://flow-next.dev/guides/writing-specs/#the-ready-flag) (≥1 spec already ready) gets one optional consent question after saving. A rewrite gets that question only when the target itself was ready before rewriting - an unrelated ready spec no longer interrupts a draft rewrite. The question explains that `mark-ready` makes the spec eligible for `flow --auto` or another autonomous driver; default is **keep-draft**. Tracker-connected repos set readiness on the board instead, because the next sync would overwrite a local toggle. `--rewrite` still resets a previously-ready target to draft before optionally restoring it with explicit consent, and announces the reset only when the flag actually changed. Autofix never writes readiness. **The `--no-plan` opt-in** is the sibling flag for the [no-plan route](https://flow-next.dev/choosing-your-route/#no-plan-route). Pass `/flow-next:capture … --no-plan` (exact token) and, after the spec write, capture sets the spec-level `no_plan` field so `flow --auto` and work take the direct route once the spec is ready. User-invoked capture treats it as explicit consent only - it never sets the field from the conversation or the draft, in interactive and autofix mode alike - and it is flow-local (the tracker-authoritative carve-out above applies to readiness, not to `no_plan`). Under `/flow-next:flow` (the `from:flow` token) capture applies the plan-versus-no-plan rule itself, sets `no_plan` when the rule resolves to direct, and writes no placeholder requirement-coverage table on that route; capture saves the spec before offering the editor. A request to capture only still stops before implementation. A fresh capture has no tasks yet, so the set always lands; only a `--rewrite` of an already-planned spec gets the one-line refusal notice. ```mermaid flowchart LR Chat["Conversation"] --> Extract["Extract user turns"] Extract --> Draft["Draft spec"] Draft --> Tag["Tag what capture authored"] Tag --> Write["Save spec"] Write --> Review["Open in editor or continue"] Review --> Check["Re-read and validate edits"] ``` ## Invocation | Flag | Use | | --------------------- | --------------------------------------------------------------------------------------------------------- | | `mode:autofix` | Scripted use; runs without questions and requires `--yes` to write. | | `--rewrite ` | Re-synthesize over an existing spec instead of refusing. | | `--from-compacted-ok` | Override the compaction-detection refusal for compressed transcripts. | | `--override-strategy` | Proceed when the draft contradicts an active `STRATEGY.md` track; prompts to log a decision-record entry. | ## Worked example After a long design conversation has settled the approach: ```plaintext /flow-next:capture ``` ```text Synthesizing spec from this conversation... Saved: .flow/specs/fn-7-rate-limit-alerts.md Title: Rate-limit alerts Criteria: 5 (R1-R5) Source tags: [user] x7, [inferred] x2 Recommended next: /flow-next:work fn-7 --no-plan - ready cohesive spec; no positive plan signal open in editor / continue (or type a change) ``` The summary is mandatory. It shows what was stated versus inferred in the saved spec, and the full spec is one request away. * Capture while the conversation is still rich. Historical compaction is only a warning when the relevant feature evidence remains fully visible; Capture stops when requirements needed for this spec are missing, truncated, summary-only, or depend on unavailable results. * The `[inferred]` tags in the summary are where to look hardest; a wrong inference caught here costs seconds, caught at review it costs a cycle. * Use `--rewrite ` when the conversation continued past an earlier capture - it overwrites deliberately instead of forking a second spec. ## Dynamic usage Recipes that compose with capture in the [cookbook](https://flow-next.dev/guides/cookbook/): * [One-shot chains](https://flow-next.dev/guides/cookbook/#one-shot-chains) - “capture this, then build it” is a supported single message. * [Team patterns](https://flow-next.dev/guides/cookbook/#team-patterns) - capture + Spec-as-PR turns a design discussion into a reviewable artifact the same day. ## Next step The closer prints the plan-versus-no-plan rule’s result for the captured spec: `Recommended next: /flow-next:work --no-plan - ready cohesive spec; no positive plan signal`, or `/flow-next:plan - `. Direct execution is the default for a ready spec. Plan is chosen only on a positive signal: you asked for a plan, separate human owners will implement, or delivery is staged across several PRs. Risk, size, and file count never trigger plan on their own. Design risk routes to plan-review, which reviews a spec with zero tasks; unresolved product or authority choices route to refine, and the closer recommends it only when it can name the open decision: `Recommended next: /flow-next:refine - `. Inferred criteria alone are not a reason to refine, and neither are technical detail, performance, or edge cases that implementation, review, and QA will surface ([when to refine](https://flow-next.dev/skills/refine/#when-to-refine)). The recommendation never grants readiness or no-plan consent by itself. ```bash /flow-next:work --no-plan ``` Or, when a named decision is still open (or to read the docs of a library the repo does not already use with `--scope=research`): ```bash /flow-next:refine ```