Pipeline Variations

The Pipeline is the canonical walk; Menu, Not a Rail is the doctrine that says you may deviate from it. This page is the bridge between the two: five worked routes through the same stages, from a full epic down to a docs chore, and the reasoning that selects between them.

Read the variants as worked examples, not tiers to pick from a list. They illustrate what the smallest-sufficient rule produces for five common shapes of work. Your change composes its own route out of the same primitives; the examples exist so you can reproduce the reasoning, not memorize the table.

The selector is risk and unknowns, not size

Size and complexity correlate with ceremony, but neither is the criterion. The question each stage answers is: what don’t we know yet, and what does it cost to be wrong?

A five-line change to auth handling deserves more ceremony than a five-hundred-line refactor of well-understood code. Every stage in the pipeline exists either to convert an unknown into a known — interview burns down requirement unknowns, plan-review burns down design risk, QA burns down runtime-behavior risk — or to bound the cost of being wrong, which is what the gates, receipts, and reviews of the verification spine do. A stage with no unknown left to convert and no risk left to bound is ceremony, and ceremony is what the smallest-sufficient rule tells you to drop.

Three questions pick the route:

1. What’s unknown? Requirements unclear → capture + interview. Design contested → plan-review. Runtime behavior unproven → QA. Nothing unknown → straight to work.
2. What breaks if we’re wrong? High blast radius — auth, data, money, a public API — justifies review stages even on a tiny diff. Low blast radius on a large diff may need nothing beyond the standard review contract.
3. Who else needs the record? A team consuming handover files, a tracker audience, or an autonomous loop that must re-anchor from files all pull toward the fuller spec surface. Solo, present, at the keyboard pulls lean.

Before the pipeline: discovery is upstream, and often already done

/flow-next:prospect (ranked candidate ideas) and /flow-next:chart (decision-map discovery for one oversized, unclear idea) sit upstream of every variant — they are not stages of any of them. In most organizations their work has already happened under another name: a roadmap, a product brief, a groomed backlog item is prospect/chart output. Reach for them only when no shaped intent exists yet — when you cannot state the outcome in a sentence.

The pipeline proper starts where shaped intent exists: at capture (turn the intent into a spec) or directly at plan (when the intent is already sharp enough to decompose).

flowchart LR
  subgraph DISCOVERY["Upstream discovery - often external"]
    direction LR
    P["/flow-next:prospect"] -.-> Ch["/flow-next:chart"]
  end
  DISCOVERY -.->|"only when no shaped\nintent exists yet"| Entry["Shaped intent\n(brief, ticket, roadmap item,\nconversation, prototype)"]
  Entry --> Pipeline["The pipeline proper\ncapture or plan onward"]

The variants

Variant	Driving signal	Route
Epic	Many requirement unknowns, high blast radius, multi-task scope	capture → interview → plan → plan-review → work → qa → make-pr → land
Feature, requirements known	Design risk remains; requirements already clear	plan → plan-review → work → make-pr
Small task	Low risk, one implementation context, no real unknowns	plan → work (or work "idea text")
Bug or defect	The unknown is the cause; the risk is regression	work + regression test as the R-ID
Docs or chore	Near-zero risk, fully known	direct change → triage-skip receipt → PR

Epic

Signal: a large intent with many requirement unknowns and real blast radius — the kind of work several people will touch and an autonomous loop may finish.

flowchart LR
  E([Epic intent]) --> C["/flow-next:capture\nthe whole epic"] --> I["/flow-next:interview\nsharpen what's soft"] --> P["/flow-next:plan"] --> PR["/flow-next:plan-review"] --> W["/flow-next:work"] --> Q["/flow-next:qa"] --> M["/flow-next:make-pr"] --> L["land"]

The pattern that works in practice: capture the entire epic, then let the machinery scope it. Capture proposes whether the input is one spec or a dependency-sorted set, and source-tags every criterion [user], [paraphrase], or [inferred]. Then interview sharpens exactly what is soft — “interview me on everything [inferred]” burns down the lines the agent guessed instead of re-litigating the whole spec. Plan decomposes into a context-fit task graph, plan-review burns down design risk before any code exists, work executes in fresh re-anchored workers, QA drives the live app when there is one, and land babysits the PRs to merged.

Every stage earns its place here because every stage has an unknown to convert or a risk to bound. This is the route The Pipeline walks in full.

Feature, requirements known

Signal: requirements are already clear — a good brief or ticket exists, or the team already argued this out — but design risk remains.

flowchart LR
  B([Brief / ticket]) --> P["/flow-next:plan"] --> PR["/flow-next:plan-review"] --> W["/flow-next:work"] --> M["/flow-next:make-pr"]
  C["capture / interview"] -.->|"unknown already\nconverted - skipped"| P

Capture and interview are skipped because their unknown is already converted: the requirements exist. Plan turns the brief into R-IDs and tasks; plan-review stays because the design is where the remaining risk lives. What still holds: R-IDs, gates, review, receipts — the full evidence chain from plan onward.

Small task

Signal: low risk, fits one implementation context, nothing genuinely unknown.

flowchart LR
  T([One-liner]) --> P["/flow-next:plan"] --> W["/flow-next:work"]

Tiny fix? Plan + work, nothing else.

/flow-next:plan "rename the config key" && /flow-next:work fn-N ⧉

✓ Fewer stages, same contracts: done still demands evidence JSON, the green receipt still gates completion.

All skip recipes →

Or skip the explicit plan call entirely: /flow-next:work "rename the config key" accepts idea text and mints the minimal spec + task itself, and /flow-next:work fn-N.M runs a single task of an existing spec without looping onward. Spec-less is a UX affordance, not a data model — a spec always exists underneath, which is exactly why the contracts still hold on the fastest route.

Bug or defect

Signal: the unknown is not the requirements — it’s the cause. The risk is regression.

flowchart LR
  R([Bug report]) --> Repro["Reproduce as a\nfailing test"] --> W["/flow-next:work"] --> Rev["/flow-next:impl-review"]
  I["interview"] -.->|"wrong instrument\nfor a defect"| Repro

The sharpening tool for a defect is reproduction, not conversation — an interview is usually the wrong instrument here. Reproduce the bug as a failing test and make that test the R-ID: the requirement is “this no longer happens, provably.” Enter with /flow-next:work "fix: <report>" for a direct fix, or capture when the diagnosis conversation itself carries decisions worth locking down — a root-cause discussion that ruled out three approaches is spec material. What still holds: the regression test, review, receipts. The deeper pattern — let something real answer the question, then capture the answer — is Prototype-Driven Specs.

Docs or chore

Signal: near-zero risk, fully known — lockfile bumps, docs-only edits, release chores, regenerated files.

flowchart LR
  D([Direct change]) --> TS["flowctl triage-skip\ndeterministic verdict"] --> PR([PR])

The change is made directly; flowctl triage-skip --base <ref> deterministically verdicts qualifying diffs (docs-only, lockfile-only, release-chore, generated-only) and writes a receipt with mode: triage_skip. That receipt is the whole point: the review pass is skipped, and the skip is recorded, never silent.

What holds on every route

Skipping a stage never skips the evidence, consent, or review contract that stage would have provided — the contract is satisfied by a cheaper mechanism, or the skip is recorded as a deliberate decision:

• Evidence — flowctl done requires evidence JSON (commits, test commands) on every variant. There is no route where a task closes on narration.
• Gates and receipts — green receipts, review receipts, and QA verdict receipts gate the same transitions regardless of how much ceremony preceded them.
• Recorded skips — every orchestrated stage records ran, skipped(reason), or failed(reason) in the receipts it already writes; read it back with flowctl usage --stages <spec-id>. A stage you deliberately left off is an explicit entry with your reason attached, not a silent absence.
• Review — the review path scales with the risk (a cross-model backend, an in-host pass, or a triage-skip receipt), but some review artifact exists on every route.

That set — gates, receipts, evidence, review — is the verification spine. The variants differ in which unknowns they pay to convert; none of them touches the spine.

Where to go next

• Menu, Not a Rail — the doctrine these variants instantiate, and the full catalog of composition moves.
• Guide — /flow-next:guide, the live router: one situation in, the smallest sufficient route out.
• Running Lean — the adjacent axis: which layers (subsystems) to switch on at all, priced.
• Cookbook — Skip & lighten — copy-paste recipes for the lightweight routes.
• The Pipeline — the full walk the epic variant runs.