# Prospect

Source: https://flow-next.dev/skills/prospect/

Generate ranked candidate ideas grounded in the repo, upstream of /flow-next:plan.

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

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.

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`](https://flow-next.dev/skills/chart/) only if that candidate remains oversized and unclear; otherwise go to [`/flow-next:capture`](https://flow-next.dev/skills/capture/) (when you already know the shape) or [`/flow-next:plan`](https://flow-next.dev/skills/plan/) (when the idea is solid enough to break down directly). Unsure? Ask [`/flow-next:flow --explain`](https://flow-next.dev/skills/flow/), or hand the survivor to plain `/flow-next:flow` and let it route.

## 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:

```bash
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>`.

```mermaid
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

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

```text
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)
Next 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.

* 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: `flowctl prospect promote <n>`, then `/flow-next:flow <spec-id>`.

## Dynamic usage

Recipes that compose with prospect in the [cookbook](https://flow-next.dev/guides/cookbook/):

* [Prompt into a stage](https://flow-next.dev/guides/cookbook/#prompt-into-a-stage) - constraints in the prompt (“quick wins only”) reshape the candidate list.
* [One-shot chains](https://flow-next.dev/guides/cookbook/#one-shot-chains) - “prospect billing, then plan the top candidate” runs the promotion in the same message.

## Next step

```bash
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
```