Prospect
/flow-next:prospect surfaces candidate ideas before there is a spec to capture.
Each candidate is scored against the repo’s actual state: recent files, open specs, .flow/memory/ entries, CHANGELOG.md, and STRATEGY.md. Nothing is invented from generic advice.
When to use it
Section titled “When to use it”When you have a focus area but no specific idea yet.
- “What should we do about authentication this quarter?”
- “Ideate inside
src/billing/.” - “Three improvements to onboarding.”
Prospect is plural and upstream of selection. After you pick a candidate: use optional /flow-next:chart only if that candidate remains oversized and unclear; otherwise promote it and hand it to /flow-next:flow, which picks the next stage, or go to /flow-next:capture when you already know the shape and want to write the spec yourself. Flow splits a spec into tasks only when you ask for a plan. Unsure? Ask /flow-next:flow --explain.
Focus hints
Section titled “Focus hints”Pass nothing for open-ended ideation, or one hint to scope the search. Prospect reads the whole hint as one kind:
| Kind | Recognised when | Example |
|---|---|---|
| Path | It contains /, has no spaces, and resolves inside the repo | /flow-next:prospect src/billing |
| Volume | It is top N, N ideas or raise the bar | /flow-next:prospect top 5 |
| Concept | Anything else, including a constraint | /flow-next:prospect authentication, /flow-next:prospect "no new dependencies" |
Without a volume hint, prospect generates 15 to 25 candidates and keeps 5 to 8 survivors. top N generates enough candidates for at least N to survive the critique, N ideas generates at least N, and raise the bar generates 25 to 30 and rejects more of them. A path that does not exist on disk stops for a question: continue open-ended, enter another hint, or abort.
Prospect needs a person at the terminal. Under mode:autonomous, FLOW_AUTONOMOUS=1 or AUTONOMOUS=1 it exits with status 2 before it reads the repo, because deciding what a repo tackles next is your call.
Promote to spec
Section titled “Promote to spec”Survivor candidates become specs via flowctl:
flowctl prospect promote <n>Promoted specs land in .flow/specs/, and promote prints Next: /flow-next:flow <spec-id> so the router picks the next stage; it sends the spec to refine only when a named product or authority decision is open. Each survivor in the prospect artifact carries the same pointer: **Next step:** promote, then /flow-next:flow <spec-id>.
flowchart LR Focus["Focus hint"] --> Ground["Ground in repo state"] Ground --> Rank["Rank candidates"] Rank --> Review["User reviews list"] Review -->|promote| Spec[".flow/specs/<id>.md"] Review -->|archive| Drop["Discard"]
Artifacts
Section titled “Artifacts”Ideas live under .flow/prospects/ until promoted or archived. Default retention is 30 days; older candidates are pruned so the directory stays small enough to scan.
Worked example
Section titled “Worked example”/flow-next:prospect src/billingGrounding: 14 recent files, 2 open specs, 5 memory entries, CHANGELOG, STRATEGY.md1. Idempotent retry for webhook ingestion (grounded: bug/integration memory entry + TODO at src/billing/webhooks.ts:112)2. Invoice-line rounding audit (grounded: CHANGELOG regression note, 2.3.1)3. Usage-metering backfill job (grounded: STRATEGY.md metering track, no spec covers it)... 3 more survivors in .flow/prospects/billing-2026-11-15.mdNext step: promote, then /flow-next:flow <spec-id>Every candidate cites its grounding in the repo’s actual state - nothing arrives from generic best-practice lists.
Dynamic usage
Section titled “Dynamic usage”Recipes that compose with prospect in the cookbook:
- Prompt into a stage - constraints in the prompt (“quick wins only”) reshape the candidate list.
- One-shot chains - “prospect billing, then plan the top candidate” runs the promotion in the same message.
Next step
Section titled “Next step”flowctl prospect promote <n>/flow-next:flow <spec-id> # the router picks the next stage# if the selected candidate is still too unclear:/flow-next:chart "the selected candidate - settle the unknowns before capture"# if intent is already stateable:/flow-next:capture