Discovery before capture

Some ideas are too big and too unclear to capture as a spec. /flow-next:chart is the optional discovery loop for exactly that case: it resolves one decision at a time until the effort can be captured, and its output is a briefing package rather than a spec.

Optional - never a mandatory stage

Flow-Next runs fully without this. It costs a discovery loop before any code exists, one decision per invocation. Reach for it when you cannot yet state the outcome in a sentence; when you can, capture directly. /flow-next:guide will tell you whether your situation needs it. See What each layer costs.

The unit of work is a decision (D-ID), not a build task. Chart never writes a spec and never sets ready.

When to use it

Use chart when all of these hold:

• You can say what “arrived” looks like - the spec, the decision, or the change this effort is finding its way to. Naming that destination is chart’s first act, because it fixes the scope: everything past it becomes a boundary, everything short of it is either a decision you can state now or an unknown you park.
• One singular effort (not a domain search - that is prospect)
• Too big or too unclear for one capture session
• Several consequential unknowns still block stating intent and boundaries

The shape, in one line: you know the destination, but not the way there. If you cannot name the destination, chart has nothing to orient to - and a direction is not a destination. “Make the CLI more deterministic” or “improve our test story” have no finish line, so nothing can ever be ruled out of scope and the map never closes. Narrow to one effort with an end state, or run prospect to find the candidates first.

"Chart this: multi-tenant billing with unknown pricing and migration risks"
"This is too broad to capture; help me find the first decision worth making."

When to skip it

Starting state	Skip chart because	Go instead
Intent and boundaries already stateable	Signal absent - chart adds no discovery	Capture or author the spec
Tiny local low-risk change	Signal absent - full pipeline is overkill	Direct change + review
Structured brief already resolved	Signal absent - briefing work is done	Capture the brief
Spec exists; judgment gaps remain	Interview owns refinement, not re-discovery	Interview
Spec ready; work understood	Chart is too late	Plan
Looking across a domain for candidates	Prospect first; chart only after selecting a still-unclear idea	Prospect
A theme or direction, not one effort (“make X more Y”)	No nameable destination, so no finish line and no scope boundary	Prospect, or narrow to a single effort

Skipping a command never skips the evidence, consent, or review contract that command would have provided. Distinguish signal absent (the stage’s work is not needed) from despite unresolved risk (you chose a smaller path; contracts still apply later).

Why not plan or prospect

	Chart	Plan	Prospect
Input	Unshaped idea; route not visible	Ready spec	Focus area across a domain
Unit	Decision (D-ID)	Task resolving to a diff	Ranked candidate idea
Done when	Nothing left to decide before someone builds	Every task executed and evidenced	User picks or archives candidates
Output	Briefing package for capture	Tasks with dependencies and waves	Ranked list under .flow/prospects/

Plan decomposes work that is already understood. Chart makes an effort understandable enough to be worth planning. Prospect is plural and upstream; chart is singular after a selection.

Decision types = evidence-first routes

Each decision carries exactly one type. The type is the evidence-first route that settles it - chart is where that doctrine becomes executable.

Type	Attendance	Resolves by
research	unattended	Scout reads docs, primary sources, or knowledge bases; returns a fact
probe	unattended	Measure or reproduce against the real system
eval	unattended	Bake-off or benchmark on real fixtures; winner + why
prototype	attended	Throwaway artefact + human reaction (hard gate)
interview	attended	Conversation, one question at a time (default for product judgment)
task	explicit at create	Manual work that only unblocks a decision (not implementation smuggling)

Attendance is stored and validated by flowctl for five types; task requires --attendance attended|unattended. Cost estimates and unattended gates read the stored field, never prose.

Attended hard gate. An unattended driver (FLOW_RALPH=1, FLOW_AUTONOMOUS, review receipt path, or host loop without a human) that reaches an attended decision writes no answer and terminates NEEDS_HUMAN. Agents do not self-resolve prototypes or interviews.

Grounding Snapshot

Chart kickoff begins with a bounded Grounding Snapshot, which is neither open-ended research nor a world search before you can begin.

Read, in order, only immediately relevant sources:

1. Your prompt and attachments
2. Repository strategy, instructions, and current implementation the idea clearly touches
3. Directly relevant specs and chart history
4. Explicitly connected knowledge sources (memory when enabled; external docs only when you supplied them)

## Grounding Snapshot

candidate_outcome: <1-2 lines>
known_facts:
  - <fact> [ref: <path|commit|https> rev:<optional>]
conflicts_or_staleness:
  - <uncertainty - missing, conflicting, stale, inaccessible>
smallest_visible_frontier:
  - <proposed title> (type: research|probe|eval|prototype|interview|task)
parked_unknowns:
  - <in-scope but not yet sharp enough>
attended_unattended_cost:
  - <N decisions: U unattended, A attended; estimated sessions with you>

Rules:

• Missing, inaccessible, conflicting, or stale evidence stays uncertainty - never becomes a fact by inference
• Imported background lands under ## Notes with citations - no imported fact becomes a D-ID
• Chart facts do not receive acceptance-criterion trailing tags ([user] / [paraphrase] / [inferred] / [strategy:*])
• No verified/inferred fact grammar on chart decisions (that experimental path did not land)
• Chart creation resolves nothing - map + open decision records + cost only

If grounding finds no consequential unknowns, chart creates nothing and recommends capture or the smaller direct route.

Cost read-back

Before any write, the skill presents Outcome, cited known facts, frontier (title + type + attendance), parked unknowns, and a cost line:

9 decisions: 5 unattended (parallel, ~1 session), 4 attended (~4 sessions).
Estimated 4-5 working sessions with you.

You approve, edit, or abort. Abort creates nothing.

Size ceiling. chart.maxDecisions defaults to 12. Past that, chart refuses and offers narrow Outcome or split. Only after explicit warning + consent: --force-size --reason (audited).

Prototype lifecycle (attended)

1. Create or import one scoped throwaway artefact sized to the question
2. flowctl chart attach-asset while the decision stays open (stable reference + optional revision)
3. Present the exact safe reference to the human
4. Record the reaction (approve / reject / redirect)
5. Resolve or supersede with the reaction - never infer approval
6. Interruption leaves asset + open D-ID resumable - never rebuild

Prototype code is evidence, not silent implementation under plan/work.

Supersession

When a later answer invalidates an earlier one:

• Prior answer stays immutable; ledger line is struck-through, never deleted
• resolve --supersedes D3 after read-back of cascade
• Open dependents on the premise lose claims; resolved dependents get replacement D-IDs unless --keep-dependents
• Briefing retains the wrong turns

Adaptive discovery loop

Chart is intentionally not a complete discovery plan written up front:

1. Re-anchor on Outcome and ## Notes
2. Choose the next frontier uncertainty (smallest answer that most reduces risk or unlocks others)
3. Take the cheapest evidence route for that decision
4. Record resolve, supersede, park, or out-of-scope with evidence
5. Re-chart from the new state - add only what the answer made visible; prune dead branches
6. Stop when nothing material remains to decide - emit a briefing

One invocation = one D-ID = one claim = one verdict. Independent unattended frontier decisions fan out only as separate invocations - never batch-claimed in one tick.

Briefing + capture handoff

A chart is briefable only when it has no open decisions (including blocked or claimed) and no parked Open Questions.

Default is one cluster. Propose a multi-spec split only when clusters are genuinely disjoint. Shared multi-cluster decisions are named once as shared_context, not duplicated requirements.

"Show whether this should become one spec or two; do not build yet."

After confirmation:

flowctl chart briefing fn-140 --proposal-file proposal.json --json

• Ordinary briefing refuses while open/parked remain
• --force emits an explicitly draft briefing - chart stays open, never capture-ready
• First final briefing sets chart done
• Capture owns source tags on criteria it newly authors; chart evidence stays as D-ID / B-ID / cluster links
• After successful capture, flowctl chart link-spec records the handoff in produced_specs[]

Chart never bypasses capture: its output is evidence for a spec, not a spec.

Worked journeys

Six possible traces, not phases: a real chart re-draws after every answer. The unit is a decision (D-ID) and the output is a briefing for capture, never a spec.

1. Skip chart: signal absent

Field	Trace
Prompt	"Add a --json flag to export; intent and boundaries are clear - don't chart this."
Grounding	Repo already has the export command; no consequential unknowns; nothing worth parking
Chart state	No chart created
Next decision	None - recommend capture or direct plan/work
Evidence / consent	Charting resolves nothing; skip is signal absent, not a silent drop of review contracts
Re-chart	N/A
Handoff	/flow-next:capture or /flow-next:plan for the clear change
Verdict	CHART_VERDICT=NO_WORK chart=- decision=- reason="no consequential unknowns; capture or direct route"

2. Research-led with parallel unattended fan-out

Field	Trace
Prompt	"Chart multi-tenant rate isolation - we don't know provider limits or how billing splits."
Grounding	Bounded snapshot cites STRATEGY.md multi-tenant track + src/auth/ modules; parks billing split; does not invent resolved D-IDs from background
Chart state	fn-140 open; frontier: D1 research provider limits (unattended), D2 research isolation knobs (unattended, independent); parked: billing split
Next decision	Two separate work invocations claim D1 and D2 in parallel - one D-ID per invocation
Evidence / consent	Unattended research may fan out; chart mode itself resolved nothing; citations under Notes, not fabricated ledger lines
Re-chart	D1 resolve + sharpen turns parked billing into D3 interview (attended); frontier redraws
Handoff	Continue work mode until briefable; then briefing → capture
Verdicts	NO_WORK (create) → RESOLVED per research D-ID → later NEEDS_HUMAN if an unattended driver hits D3

3. Prototype reversal with supersession

Field	Trace
Prompt	"The tenant-switcher prototype is the wrong direction - preserve the old assumption and redraw."
Chart state	D2 product assumption resolved earlier; D3 prototype open with throwaway mock attached (attach-asset while open, stable path + revision)
Next decision	Present exact asset ref; record human reaction; resolve D3 with --supersedes D2 after read-back
Evidence / consent	Asset persisted before reaction; attended hard gate - no self-approval; prior answer stays struck-through on the ledger
Re-chart	Open dependents on D2 lose claims; newly visible interview/probe decisions via sharpen; frontier redraws
Handoff	Briefing retains artefact reference and superseded gist; capture cites D-IDs, does not retag chart facts as [user]
Verdict	CHART_VERDICT=RESOLVED chart=fn-140 decision=fn-140.D3 reason="prototype reversed D2 assumption; cascade reported"

4. Multi-spec briefing with shared context

Field	Trace
Prompt	"Show whether this should become one spec or two; do not build yet."
Chart state	Briefable - no open decisions, no parked questions; resolved decisions span two disjoint surfaces
Next decision	None to resolve; propose N=2 clusters + one auth decision in shared_context
Evidence / consent	User confirms merge/split before briefing --proposal-file; chart never writes .flow/specs/
Re-chart	N/A after final briefing (done)
Handoff	Two capture runs (one per cluster); chart link-spec per successful spec; shared context named once
Verdict	CHART_VERDICT=COMPLETE chart=fn-140 decision=- reason="multi-spec briefing B1 confirmed; shared_context preserved"

5. Tracker URL re-entry (including a failing / historical URL)

Field	Trace
Prompt	"Continue this chart from this decision link: https://linear.app/.../D3-tenancy-prototype"
Happy path	flowctl chart locate (local ledger only) → read back canonical fn-140.D3 + title + record link → pin and work that open D-ID
Parent URL	Locates chart; re-anchors on local status + frontier - no remote search
Historical / resolved URL	Shows history + frontier options; never silently reassigns work
Unsupported / unlinked URL	Locator fails visibly; offer local chart-id path; mutate nothing
Evidence / consent	Local ledger is sole identity source; failures create nothing
Verdicts	Work: normal one-decision verdict. History-only: NO_WORK ... reason="historical decision; no new work selected". Failure: BLOCKED chart=- ... reason="locator failed local ledger; no mutation"

6. Chart refuses: a direction, not a destination

Field	Trace
Prompt	"Make flow-next more deterministic - chart it."
Grounding	Not reached. The refusal lands before grounding spend: “more deterministic” names a direction with no end state, so no Outcome can be stated and nothing can ever be ruled out of scope
Chart state	No chart created
Next decision	None. Offer exactly two routes: narrow to one effort whose arrival is nameable, or prospect when the real ask is which determinism effort to pick
Evidence / consent	Chart never silently charts a guessed narrowing - the user picks the effort. A --force-size override is the wrong tool here: the ceiling is not the problem, the missing destination is
Re-chart	Same idea narrowed to “make flowctl list output byte-identical across machines” is chartable - destination nameable, route genuinely unknown
Handoff	None until narrowed
Verdict	CHART_VERDICT=NO_WORK chart=- decision=- reason="direction not destination; narrow to one effort or run prospect"

Invocation, flags, the verdict grammar, artifacts, and tracker re-entry are on the chart skill reference.