Prospect

/flow-next:prospect surfaces candidate ideas before there is a spec to capture.

Optional - never a mandatory stage

Flow-Next runs fully without this. It costs a discovery pass over the repo before any code exists. Reach for it when you need a ranked list of what to do next; when you already know what you are building, capture directly. See Running Lean.

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

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 go to /flow-next:capture (when you already know the shape) or /flow-next:plan (when the idea is solid enough to break down directly). Unsure? /flow-next:guide.

Focus hints

Pass nothing for open-ended ideation, or scope the search with hints:

Hint	Example
Concept	/flow-next:prospect authentication
Path	/flow-next:prospect path:src/billing
Constraint	/flow-next:prospect "no new dependencies"
Volume	/flow-next:prospect count:5

Hints can combine. The skill blends them with the grounding pass against the repo.

Promote to spec

Survivor candidates become specs via flowctl:

flowctl prospect promote <n>

Promoted specs land in .flow/specs/ ready for /flow-next:interview or /flow-next:plan.

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

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

/flow-next:prospect path:src/billing count:3

Grounding: 14 recent files, 2 open specs, 5 memory entries, CHANGELOG, STRATEGY.md
1. 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)
Promote with: /flow-next:capture or /flow-next:plan <candidate>

Every candidate cites its grounding in the repo’s actual state - nothing arrives from generic best-practice lists.

Tips

• Scope with hints (path:, a concept, a constraint like “no new dependencies”) - open-ended ideation is the weakest mode.
• The grounding citations are the review surface: a candidate whose evidence looks thin is a candidate to drop.
• Prospect ranks ideas; it never creates specs - promotion is a deliberate second step through capture or plan.

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

flowctl prospect promote <n>
# 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
/flow-next:interview <spec-id>