flow-next-chart

# Chart - decision-map discovery (pre-capture)

**Read [workflow.md](workflow.md) for routing and the mode dispatch table.** It routes to exactly one mode reference per invocation (chart / work / briefing-reopen / re-entry); status mode and the safety recap stay inline there. Native prompts, adaptive traces, and the full flag tables: [references/examples.md](references/examples.md).

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. Unit of work is a **decision** (D-ID), not a build task. Chart never writes a spec and never sets `ready`; output is a briefing handed to `/flow-next:capture`.

**Role**: discovery coordinator (inline skill - keep blocking questions reachable). Host agent owns grounding, interpretation, frontier judgment, evidence-route dispatch, prototype presentation, attended consent, re-charting, and the terminal verdict. flowctl owns atomic create/claim/resolve/scope/briefing/store mutations.

## Preamble

**CRITICAL: flowctl is BUNDLED - NOT installed globally.** `which flowctl` will fail (expected). Define once; subsequent blocks (here and in `workflow.md`) use `$FLOWCTL`:

```bash
FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"
```

**Inline skill (no `context: fork`)** - keeps `AskUserQuestion` available for read-back consent and attended routes. Subagents cannot call blocking question tools. For read-only scouts use `Task` with `subagent_type: Explore` (or the host's generic read-only dispatch with Edit/Write disallowed when Explore is unavailable). On portable hosts without `AskUserQuestion`, fall back to a plain-text numbered prompt with a final `Other - type your own answer` option. (sync-codex.sh rewrites AskUserQuestion to a plain-text numbered prompt in the Codex mirror.)

## Prompt-first contract

Natural language is the primary control surface. Free-form steering of outcome, known facts, next move, skips, reversals, prototype reactions, and briefing intent reaches the same guarded flowctl operations. Flags and exact subcommands are documented for automation, scripting, and debugging - they are **never required vocabulary** for humans.

On every invocation:

1. Infer the intended **mode** and operation from `$ARGUMENTS` + conversation.
2. Ask a blocking question **only** when two interpretations would materially change the chart, cost, or consent boundary.
3. Read back any state-changing interpretation before persisting.
4. Never edit chart Markdown or decision sidecars by hand - always `$FLOWCTL chart ...`.

## Modes (disambiguate by argument)

| Invocation shape | Mode | Behavior |
|---|---|---|
| free-form idea / "chart out ..." | **chart** | Bounded Grounding Snapshot -> name Outcome + visible frontier + parked unknowns + cost -> consent read-back -> `chart create --initial-map-file` (resolve nothing) |
| `<chart-id>` or "work the next decision on ..." | **work** | Re-anchor Outcome + Notes -> `chart frontier` sole selection input -> claim one D-ID -> evidence route -> resolve/scope/release -> re-chart |
| `<chart-id> --decision <n>` / explicit D-ID | **work** (pinned) | Same as work; human selects the decision if it is still open/unblocked/unclaimed |
| `<chart-id> --status` / "what's left to decide" | **status** | Render map + frontier + remaining attended cost; **resolve nothing** |
| stored tracker URL / locator | **re-enter** | Probe `chart locate` (local ledger only); degrade if unavailable - see workflow |

Plain-language equivalents reach the same modes (R17).

## Verdict grammar (exact)

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` | Stored `attendance:attended` decision reached by an unattended driver - **no answer write** |
| `COMPLETE` | Chart briefable (no open decisions, no parked questions) after this tick, or briefing emitted |
| `NO_WORK` | Empty frontier, skip-chart (no consequential unknowns), 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).

**Unattended driver signals** (any one): `FLOW_RALPH=1`, non-empty `REVIEW_RECEIPT_PATH`, non-empty `FLOW_AUTONOMOUS`, or the host is driving without a human present. Interactive terminal sessions are attended.

## Decision types = evidence routes

| Type | Attendance | Resolves by |
|---|---|---|
| `research` | unattended | Scout reads docs / primary sources / knowledge bases; returns a fact |
| `probe` | unattended | Measure or reproduce against the real system |
| `eval` | unattended | Bake-off / 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.

## Invariants (hard)

- **One invocation = one D-ID = one claim = one verdict.** Independent una