| No written direction - target problem, users, or key metrics are not stated anywhere | $flow-next-strategy | Repeated arguments about what matters; no STRATEGY.md to ground prospect/capture/plan | Skip when STRATEGY.md exists or the effort is small enough that direction is not in question |
| Looking for candidate investments across a domain | $flow-next-prospect | Domain search; need ranked candidates | Skip prospect when the idea is already singular. After selection: chart only if the candidate remains singular + oversized + unclear; otherwise capture |
| One large idea, unclear boundaries, several consequential unknowns | $flow-next-chart then briefing then capture | Singular effort too big for one capture; unknowns block stating intent | Skip chart (signal absent) when intent and boundaries are already stateable - go capture or author the spec directly. Chart is never mandatory |
| A theme or direction rather than one effort ("make X more Y") | $flow-next-prospect, or narrow to a single effort | No nameable end state, so no Outcome and no scope boundary | Chart cannot take this (signal absent for chart): it needs a destination whose route is unknown, not a direction. Narrow first, or prospect when the real ask is which effort to pick |
| One meaningful idea whose intent and boundaries can already be stated | $flow-next-capture or author the spec directly | Clear meaningful idea | Skip chart (signal absent). Do not manufacture a chart for clear work |
| Existing structured brief with resolved business and technical choices | $flow-next-capture the brief | Structured brief / chart briefing package ready | Skip chart. Narrow or skip interview only after capture read-back proves no material gaps - never pre-declare skip interview |
| Tiny, local, low-risk change that fits one implementation context | Direct change + review path appropriate to the repo | One-context fix; low risk | Skip chart and the full spec pipeline (signal absent). Still run the review/consent gates the change would need |
| A valid spec with unresolved judgment questions | $flow-next-interview | Spec exists; judgment gaps remain | Do not reopen discovery as chart unless the questions reveal the effort itself is not yet specifiable - only then route backward to chart |
| A ready zero-task spec whose work is fully known, near-zero risk, one implementation context | $flow-next-work <spec-id> --no-plan (or answer the zero-task fork's ask with "work directly") | Task decomposition would convert no unknown; the fork mints one implicit task and runs the standard pipeline | Prefer $flow-next-plan when independent surfaces could parallelize or design risk remains; autonomous loops keep planning - pilot routes here only for a spec carrying the explicit no_plan field (flowctl spec set-no-plan) |
| A ready spec whose work is understood | $flow-next-plan | Spec ready / work understood enough to task | Chart is too late. Unshaped oversized freeform ideas are not plan input - route those to chart first |
| Planned tasks ready to implement | $flow-next-work, then existing review / QA / ship choices | Tasks exist and are actionable | Stay on work + the repo's review/QA/ship menu. Guide does not invent new ship stages |
| A repo with a drivable user surface whose navigation should compound across QA/drive runs | $flow-next-features | No .flow/features/ yet (seed), or a present map that needs a cadence maintain pass | Skip when there is no drivable surface. Never a pipeline stage; pilot/land/Ralph never dispatch it. QA and drive consume the map when it exists |
| Output too dense - a plan, spec, task, or diff needs reviewing at a glance | $flow-next-visual | Structure has to be reconstructed by serial reading (spec + N task files, an unread diff, a wall of prose) | Skip when the text is already short enough to judge directly. The digest is a lens, not a stage - it never advances the pipeline and never replaces reading the file you drill into |
| A substantial reply, report, or summary needs prose discipline | $flow-next-prose | The output is chat prose - self-applied by the agent at the drafting moment, or invoked with a draft to tighten | Skip for short turns, tool narration, the visual digest, and anything landing in a file, PR, or tracker - those artifact surfaces carry their own pointers to docs/prose.md. Never a pipeline stage |
| Unsure which of these situations applies | This matrix (this skill) | Ambiguous starting state | Ask at most one plain-text numbered prompt when two routes would materially differ; otherwise recommend one route |
