/flow-next-refine

name: flow-next-refine
description: Refine a spec, task, or spec file before building - one question pass for the decisions that would change what gets built, optionally focused by a free-text --scope lens (business, technical, qa, ...), or a read-only research pass (--scope=research) that resolves library versions, changed APIs, and gotchas from external docs into the spec. Use when a named product, authority, or costly-to-reverse technical decision is open, or when the spec names a library or API the repo does not already use. Triggers on /flow-next:refine with Flow IDs (fn-1-add-oauth, fn-1-add-oauth.2, or legacy fn-1, fn-1.2, fn-1-xxx, fn-1-xxx.2) or file paths.
user-invocable: false

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](../../references/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. Under a non-technical lens, speak to the person in their words throughout, not only in questions: round openers, the read-back and the completion summary say what was recorded and what is left for engineering, and gloss or leave out source tags, criterion ids, section names and command names.

**Research pass.** With `--scope=research`, skip the doc-aware gate and the interview: detect the input, then read [references/research-scope.md](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](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](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