Flow Next Refine

Flow refine

Refine a spec, task, or spec file: settle the decisions that would change what gets built and that only the person can make, then write the answers back. Everything else you resolve by investigation, record, or leave to implementation. --scope=research is a separate pass that asks nothing and writes the spec's external-library unknowns back from official docs.

All task state is read and written through flowctl; .flow/ is the only tracker (no markdown TODOs, plan files or TodoWrite).

Refine clarifies a spec that can already be specified. Route back to /flow-next:chart only when the answers show the effort itself is not yet specifiable; unsure of the hop, use flow-next:flow-next-flow --explain.

Read working-rules.md first unless you already have this run; it holds for every step of this skill.

Preamble

flowctl is bundled, not installed globally (which flowctl fails). Define once; later blocks use $FLOWCTL:

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"

Input

Full request: $ARGUMENTS

A Flow spec id, a Flow task id, a tracker handle linked to one, or a file path. Examples:

• /flow-next:refine fn-1-add-oauth (legacy fn-1, fn-1-xxx and task ids like fn-1-add-oauth.3 work too)
• /flow-next:refine docs/oauth-spec.md
• /flow-next:refine fn-1-add-oauth --scope=qa (the same interview, focused on what QA decides)
• /flow-next:refine fn-1-add-oauth --scope=research (external-docs pass; no interview, one write-back approval)

Empty: ask "What should I refine? Give me a Flow ID (e.g. fn-1-add-oauth) or a file path (e.g. docs/spec.md)."

Setup

Scope lens. --scope=<value> is an optional free-text lens: business, technical, qa, security, or any other audience; --biz means --scope=business and --tech means --scope=technical. Take these tokens out of the arguments before detecting the input; several values combine into one lens. There is one interview whatever the lens: interpret the lens from its words and let it focus which open decisions you look for (a QA lens looks for what counts as done, which failures matter, what must be testable). No lens means no filter. Never ask which scope to run.

Research pass. With --scope=research, skip the doc-aware gate and the interview: detect the input, then read references/research-scope.md and follow it. The interview never reads that file.

Doc flags. When the arguments carry any of --docs, --no-docs, --strategy, --no-strategy, read references/doc-flags.md § Flag parsing before detecting the input; it strips them and sets the two force values used below.

Doc-aware gate. Doc-aware mode adds glossary, decision-record and strategy behaviours to the interview. It turns on when the repo has a glossary term, a decision entry, or a filled strategy section (counts, not file presence); the doc flags override. Run once per interview:

REFINE_PREFLIGHT="${TMPDIR:-/tmp}/flow-refine-preflight-<suffix>.json"   # literal path; reused after the write-back
# One preflight bundle per interview. A failed, missing or empty probe counts as signal (fail open).
"$FLOWCTL" preflight --json > "$REFINE_PREFLIGHT" 2>/dev/null || printf '{}' > "$REFINE_PREFLIGHT"
# DOC_AWARE_FORCE / STRATEGY_AWARE_FORCE keep the "on" / "off" that doc-flags.md § Flag parsing set; unset = autodetect.
GATES="$(jq -er '
  def v(p): if p.status == "ok" then p.value else null end;
  [ (if v(.probes.glossary) == null or v(.probes.decisions) == null
        or (v(.probes.glossary).total_terms // 0) > 0 or (v(.probes.decisions).entry_count // 0) > 0 then 1 else 0 end),
    (if v(.probes.strategy) == null or (v(.probes.strategy).sections_filled // 0) >= 1 then 1 else 0 end)
  ] | join(" ")' "$REFINE_PREFLIGHT" 2>/dev/null)" || GATES="1 1"
DOC_AWARE="${GATES% *}"; STRATEGY_AWARE="${GATES#* }"
case "${DOC_AWARE_FORCE:-}" in on) DOC_AWARE=1 ;; off) DOC_AWARE=0 ;; esac
case "${STRATEGY_AWARE_FORCE:-}" in on) STRATEGY_AWARE=1 ;; off) STRATEGY_AWARE=0 ;; esac
if [ "$DOC_AWARE$STRATEGY_AWARE" != "00" ]; then
  echo "DOC-AWARE GATE ACTIVE (DOC_AWARE=$DOC_AWARE STRATEGY_AWARE=$STRATEGY_AWARE) — STOP. Read references/doc-aware.md before drafting the first question."
fi

When the sentinel prints, read references/doc-aware.md and apply the behaviours its gates enable. Otherwise do not read it.

Detect the input

Route every single-token argument that is not an .md path through $FLOWCTL show <arg> --json before calling it a file: flowctl resolves spec ids, task ids, and tracker keys linked to them (wor-17 / wor-17.3). Use the canonical id from the JSON.

• Spec (fn-12, fn-1-add-oauth, or a handle that resolves to one): read it with $FLOWCTL cat <id>.
• Task (fn-1-add-oauth.3, or a handle with a .): $FLOWCTL cat <id>, plus the parent spec with $FLOWCTL cat <spec-id>.
• File path (does not resolve): read the file; if it does not exist, ask for a valid path.

Keep the text you read: the write-back compares against it.

Interview

Ask through the question tool

Every question goes through AskUserQuestion (load it with ToolSearch select:AskUserQuestion when its schema is not loaded); fall back to numbered plain-text options only when the tool is unreachable. Never print questions as narration ("Question 1: ... Options: a) b) c)").

The one test

Ask a question only when all three hold: a wrong guess would build the wrong thing or ship behaviour the person would reject; the code, the docs, a quick experiment, or implementation cannot settle it; and it is the answerer's call. A topic on the list below is not a reason to ask.

Check the spec for these, and ask about one only when the spec leaves it unclear and it passes the test: who it is for; what done looks like; what is explicitly out; a constraint the domain implies (a regulation, a contract, a partner commitment); an irreversible data or contract change (a data model, a migration, a public contract); an external interface; a security boundary. A lens adds its audience's open decisions. Technical detail, performance, failure modes, concurrency, scale and edge cases qualify only when they pass the test; implementation, review and QA surface the rest. Cosmetic polish (message wording, flag spelling, formatting) never gets its own question: fold it into a related question's options or state it as a default the person can veto at write-back. Refine never asks for success metrics or latency budgets unless the spec is about them.

Stop when no question that passes the test remains. Asking nothing is a good outcome: report "Nothing worth asking; the spec is clear enough to build." and skip the write-back unless investigation resolved something worth recording.

Investigate before asking

Before the first round, read STRATEGY.md and search the other project docs for what the spec touches rather than reading them end to end: README.md, CHANGELOG.md, GLOSSARY.md, the decisions track ($FLOWCTL memory list --track knowledge --category decisions --json), the titles of open specs ($FLOWCTL specs --json), and docs/ when present. Then sort each candidate question:

• The code answers it (what exists, how it is wired, which conventions hold): read and search; log it under ## Resolved via Codebase with file:line evidence.
• The project docs answer it (what the strategy says, what shipped, what was decided): log it under ## Resolved via Project Docs with path:line evidence.
• Running something settles it (behaviour, timing, layout, output, whether an eval separates two options): run a throwaway experiment in .flow/tmp/experiments/ and log the question, what ran, what you observed and the decision under ## Resolved via Experiment. The working rules' limit on experiments decides which run without asking. An inconclusive result (noise larger than the difference) is logged as inconclusive and goes to the person with the data. The experiment is evidence, never product code.
• It is a judgment (what should exist, which trade-off, what priority): ask it.

Answering a "should" question by grep is the bug; so is asking something the docs already answer. Use multi-select for options that are not exclusive, and probe answers that contradict each other.

While the person answers a round you may dispatch one read-only fact scout for lookups that gate the next round; before dispatching one, read references/fact-scouts.md. Investigating inline needs nothing from it.

Rounds over the decision tree

Treat the open decisions as a tree: each decision opens the ones that hang off it. The frontier is every question whose prerequisites are settled. Work in rounds:

1. Each round asks the whole current frontier. A question whose answer depends on another question still open belongs to a later round; never ask a question alongside its own prerequisite.
2. Split the round across AskUserQuestion calls of up to 4 questions, closest-related together, announced as one round ("Round 2, part 1/2"). Never pad a call to 4 and never hold a frontier question back to smooth pacing.
3. Recompute the frontier from the answers; deeper rounds are discovered, not pre-scripted.
4. When an answer prunes a branch, say so at the next round's opener ("Skipping persistence questions; you said no database.").
5. Go at most 4 rounds down any one branch.
6. If part of a round was never asked (tool error, interruption), ask it before moving on.

Standalone checkpoints (the code-mismatch question, the skipped-items checkpoint, the mark-ready offer, doc-aware prompts that have their own per-round budget in doc-aware.md) sit outside rounds, are never labelled "Round N" and never count against round depth. A doc-aware prompt deferred by that budget is pending for a later round, not dropped.

The interview is done when every decision the tree opened is answered, delegated, parked under ## Open Questions, or pruned with its branch named.

Question shape

Write each question so the person can read it once and answer it confidently.

• Body: one sentence of stakes (what this decides, in the audience's words), then the recommendation with a one-sentence rationale, then one confidence tier: <stakes>. Recommended: <X> — <why>. Confidence: [high | judgment-call | your-call].
• Options: neutral labels, no "(recommended)" marker. Each description says what choosing it means ("Choose this if…", "This means…").
• Plain words. Prefer the common word; a term of art you genuinely need gets a short gloss at first use ("counter-metrics — things we'd hate to make worse"). No unexplained acronyms or repo shorthand. A product question, or any question under a non-technical lens, carries no implementation vocabulary (schemas, endpoints, config keys). A cited criterion gets a short gist: "R3 (the audit line's required fields)", never a bare "R3".
• Length: never drop the stakes, recommendation, tier, gloss or option consequences. Trim repetition, background and hedging first; a body of about 40-60 words is usually right.

Tiers: [high] when the code or a convention gives strong signal and the person can usually accept; [judgment-call] when you lean one way but reasonable people disagree; [your-call] when you have no basis. Use [your-call] whenever that is true and say so ("I found no convention to copy; this depends on what your callers expect"). Always recommending trains people to defer.

Example: "This decides how long the rate limiter remembers a result before checking again. Recommended: 60 seconds — short enough that stale answers stay rare, long enough to be worth caching. Confidence: [judgment-call]." Options 30s, 60s, 300s, no cache, each with its plain consequence.