# Chart Source: https://flow-next.dev/skills/chart/ Decision-map discovery for one oversized or unclear idea before capture - resolve one decision at a time until the effort is briefable. `/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. 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`](https://flow-next.dev/skills/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:flow --explain`](https://flow-next.dev/skills/flow/). How to run a discovery loop, and the doctrine behind it, is [Discovery before capture](https://flow-next.dev/guides/discovery/). This page is the invocation surface. ## 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: ``” | **Re-enter** via local ledger only | ## Work mode ```text "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 ## Verdict grammar Every **work** invocation ends with exactly one greppable line and nothing after it: ```text CHART_VERDICT= chart= decision= reason="" ``` | 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/.md` | Map body - Outcome, Notes, Decisions ledger, Open Questions, Boundaries | | `.flow/charts/.json` | Sidecar - status, decisions metadata, briefings, tracker keys, produced\_specs | | `.flow/charts//.md` | Decision question body | | `.flow/charts//.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 ` 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. ## Invocation Not required vocabulary - conversational equivalents work. | Flag / form | Purpose | | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--status` | Status mode - render only | | `--decision ` | 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 ` | 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: [CLI Reference](https://flow-next.dev/flowctl/cli-reference/#chart). Config: [Configuration](https://flow-next.dev/flowctl/configuration/#chart-pre-capture-discovery). ## Worked examples ### Clear idea: skip chart ```text You: Capture the --json export flag work - intent and boundaries are clear. Flow --explain / chart: no consequential unknowns. CHART_VERDICT=NO_WORK chart=- decision=- reason="no consequential unknowns; capture or direct route" ``` ### Research-led frontier ```text 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 ```text 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](https://flow-next.dev/guides/cookbook/#chart-journeys). ## Dynamic usage * [Flow](https://flow-next.dev/skills/flow/) - `/flow-next:flow --explain` says when chart is or is not the smallest sufficient route * [Prototype-driven specs](https://flow-next.dev/understand/explore-first/) - the doctrine chart makes executable * [Capture](https://flow-next.dev/skills/capture/) - briefing handoff and criterion source tags * [Tracker Sync](https://flow-next.dev/integrations/tracker-sync/#chart-projection-optional) - optional parent/child projection ## Next step ```text /flow-next:chart "the idea that is still too unclear to capture" # ... resolve decisions until briefable ... /flow-next:capture # from the briefing package ```