Chart

/flow-next:chart takes one unshaped idea that is too big for a single capture session and wrapped in unknowns, and finds the route by resolving one decision at a time until the effort can be captured as one or more specs.

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 Running Lean.

The unit of work is a decision (D-ID), not a build task. Chart never writes a spec and never sets ready. Its output is a briefing package (B-IDs) handed to /flow-next:capture.

Chart is an optional high-uncertainty route - not a new mandatory pipeline stage. When intent and boundaries are already stateable, skip it and capture or author the spec directly. Unsure which path fits? Use /flow-next:guide.

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.

Prompt-first contract

Natural language is the primary control surface. Flags and exact subcommands are for automation, scripting, and debugging - never required vocabulary for humans.

On every invocation the skill:

1. Infers the intended mode from what you said
2. Asks a blocking question only when two interpretations would materially change cost or consent
3. Reads back any state-changing interpretation before persisting
4. Never hand-edits chart Markdown or sidecars - always flowctl chart ...

You say	Mode
”Chart out multi-tenant migration”	Chart - ground, propose frontier, create (resolve nothing)
“Work the next decision on fn-140”	Work - claim one frontier D-ID, evidence route, re-chart
”Continue from the tenancy prototype decision”	Work (pinned)
“What’s left to decide on fn-140?”	Status - render only
”Continue from this tracker link: <url>”	Re-enter via local ledger only

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 - not open-ended research and not 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).

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.

Work mode

"Work the next decision on the billing chart"
/flow-next:chart fn-140
/flow-next:chart fn-140 --decision 3

1. Re-anchor Outcome + Notes (flowctl chart show)
2. flowctl chart frontier is the sole selection input (human pin must still appear on that frontier)
3. Claim before any work
4. Load full decision body only for the claimed D-ID
5. Attended gate if needed
6. Evidence route by type
7. Resolve / out-of-scope / release-claim
8. Optional sharpen in the same resolve transaction
9. Recompute frontier; propose the next smallest uncertainty - do not execute it in this invocation
10. Print exactly one CHART_VERDICT=... line

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

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.

Verdict grammar

Every work invocation ends with exactly one greppable line and nothing after it:

CHART_VERDICT=<RESOLVED|BLOCKED|NEEDS_HUMAN|COMPLETE|NO_WORK> chart=<id> decision=<D> reason="<one line>"

Verdict	When
RESOLVED	One D-ID closed via resolve or out-of-scope; frontier recomputed
BLOCKED	Claim conflict, graph/store refusal, or no actionable path without human repair
NEEDS_HUMAN	Attended decision reached by an unattended driver - no answer write
COMPLETE	Chart briefable after this tick, or briefing emitted
NO_WORK	Empty frontier, skip-chart, status-only, or chart mode finished without resolving

Chart mode and status mode also print one terminal line so host /loop / /goal drivers can parse uniformly (decision=- when no D-ID was claimed).

Artifacts

Path	Role
.flow/charts/<chart-id>.md	Map body - Outcome, Notes, Decisions ledger, Open Questions, Boundaries
.flow/charts/<chart-id>.json	Sidecar - status, decisions metadata, briefings, tracker keys, produced_specs
.flow/charts/<chart-id>/<n>.md	Decision question body
.flow/charts/<chart-id>/<n>.json	Decision sidecar - type, attendance, status, edges, assets, answer

Chart ids share the repo prefix and allocator with specs (fn-N) but carry a distinct kind. D-IDs are chart-local (fn-140.D3), append-only, never renumbered or reused.

Tracker projection + URL re-entry

Optional projection when the tracker bridge is active and tracker.charts is the literal on:

• Parent issue for the chart; child issues for decisions
• Local chart mutations always commit first; remote projection never blocks them
• Projection carries type, attendance, status, blocking, and safe evidence summaries
• Parent rollups: counts, latest resolution, frontier, chart status - projection-only, never canonical
• Provider degradation is explicit; reconcile receipts stay local-first and revisioned

URL re-entry is local ledger only. flowctl chart locate <selector> resolves a chart/D-ID, stored tracker identifier, or stored tracker URL through the local provenance ledger - no network, no title matching, no create-on-miss.

Selector	Behavior
Parent chart URL	Re-anchor on local chart status + frontier
Open decision URL	Pin that exact open D-ID
Resolved / superseded / historical URL	Show history + frontier options - never silent reassignment
Unsupported / unlinked / missing	Fail visibly; offer local chart-id path; mutate nothing

Always read back canonical local ID, title, and record link before claim/work.

Flags reference (automation)

Not required vocabulary - conversational equivalents work.

Flag / form	Purpose
--status	Status mode - render only
--decision <n>	Pin a D-ID for work mode
--json on every flowctl chart subcommand	Machine envelope {success, schema_version:1, command, result|error}
create --initial-map-file / --force-size --reason	Atomic chart + ceiling override (audited)
resolve --answer-file / --sharpen-file / --supersedes / --keep-dependents	Close + optional sharpen/cascade. Sharpen notes_append corrects a disproved grounding note (dated, append-only, travels into the briefing); an unknown sharpen key is an error, not a silent no-op
attach-asset --asset-file	Safe artefact while open
briefing --proposal-file / --force	Confirmed split proposal; force is draft-only
claim / release-claim [--break-stale --reason]	Claims; no silent expiry (chart.claimStaleAfter, default 24h)
locate <selector>	Local ledger re-entry
link-spec --briefing --spec --decisions	Record successful capture handoff

Error classes: not_found | conflict | invalid_state | invalid_graph | stale_claim | validation | io.

Full CLI surface: Commands and CLI Reference. Config: Configuration.

Worked examples

Clear idea - skip chart

You: Capture the --json export flag work - intent and boundaries are clear.
Guide/chart: no consequential unknowns.
CHART_VERDICT=NO_WORK chart=- decision=- reason="no consequential unknowns; capture or direct route"

Research-led frontier

You: Chart multi-tenant rate isolation - we don't know provider limits or billing split.
# Grounding cites STRATEGY.md + existing auth modules; parks billing; opens research frontier
CHART_VERDICT=NO_WORK chart=fn-140 decision=- reason="chart created; research frontier offered for parallel work"

You: Work the next decision on fn-140
# Claims D1 research, scout returns cited limits, sharpen turns parked billing into interview
CHART_VERDICT=RESOLVED chart=fn-140 decision=fn-140.D1 reason="provider limits cited; parked billing sharpened"

Prototype reversal

You: The prototype changed direction. Preserve the old assumption and redraw.
# Asset already attached; human reaction recorded; resolve --supersedes prior D-ID
CHART_VERDICT=RESOLVED chart=fn-140 decision=fn-140.D3 reason="prototype reversed D2 assumption; cascade reported"

More journeys (skip, research fan-out, multi-spec briefing, tracker re-entry): Cookbook - Chart journeys.

Dynamic usage

• Guide - when chart is or is not the smallest sufficient route
• Prototype-driven specs - the doctrine chart makes executable
• Capture - briefing handoff and criterion source tags
• Tracker Sync - optional parent/child projection

Next step

/flow-next:chart "the idea that is still too unclear to capture"
# ... resolve decisions until briefable ...
/flow-next:capture   # from the briefing package