flow-next-interview
In-depth Q&A to refine a spec, task, or spec file before building. Use when asked to flesh out, refine, or interrogate requirements.
gmickel · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add gmickel/flow-next --skill flow-next-interviewAbout this skill
name: flow-next-interview description: In-depth Q&A to refine a spec, task, or spec file before building. Use when asked to flesh out, refine, or interrogate requirements. user-invocable: false
Flow interview
Conduct an extremely thorough interview about a task/spec and write refined details back.
.flow/ is the only task tracker. A run that recorded task state in a markdown TODO, a plan file, TodoWrite, or any other tracker has broken this — all task state is read and written via flowctl.
Chart boundary (fn-135)
Existing-spec clarification stays primary. Interview refines a valid spec with unresolved judgment questions. Do not reopen discovery as /flow-next:chart unless the answers reveal that the effort itself is not yet specifiable - only then route backward to chart. Clear work that never needed a chart stays out of chart. Unsure of the hop: /flow-next:guide.
Preamble
CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Define once; subsequent blocks use $FLOWCTL:
FLOWCTL="${CODEX_HOME:-$HOME/.codex}/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"
Role: technical interviewer, spec refiner Goal: extract complete implementation details through deep questioning (40+ questions typical)
Input
Full request: $ARGUMENTS
Accepts a Flow spec ID, a Flow task ID, a resolvable tracker handle, a file path, or nothing — recognition rules and the fetch command per type are in "Detect Input Type" below (single copy; the write-back command per type is in references/write-back.md).
Examples:
/flow-next:interview fn-1-add-oauth/flow-next:interview fn-1-add-oauth.3/flow-next:interview fn-1(legacy formats fn-1, fn-1-xxx still supported)/flow-next:interview docs/oauth-spec.md
If empty, ask: "What should I interview you about? Give me a Flow ID (e.g., fn-1-add-oauth) or file path (e.g., docs/spec.md)"
Setup
Parse --scope=business|technical|both (fn-44.1 plumbing)
Token-safe parsing for --scope / --biz / --tech lives in flowctl scope resolve — never re-implement inline. The subcommand strips scope tokens, preserves every other token in order (Flow IDs, paths, --docs, --strategy, ...), and emits the resolved scope plus a defaulted flag. The resolver's fallback when no scope flag is passed is technical (1.0.2 backward-compat) — but the skill does NOT silently run it: when defaulted == true, ask the user which pass to run after Detect Input Type (see "Scope selection when no flag passed" below). technical applies only when that question cannot be asked.
# Run BEFORE the --docs / --strategy strip block. Conflict / invalid value
# → non-zero exit; SKILL propagates.
#
# `--raw "$ARGUMENTS"` tokenizes via shlex INSIDE flowctl — preserves quoted
# paths with spaces (e.g., `/flow-next:interview --biz "docs/my spec.md"`).
# Unquoted `$ARGUMENTS` would word-split into broken tokens.
RESOLVED_JSON=$("$FLOWCTL" scope resolve --json --raw "$ARGUMENTS")
SCOPE=$(printf '%s' "$RESOLVED_JSON" | jq -r '.scope')
# true when no scope flag was passed — gates the "Scope selection when no
# flag passed" question below (older flowctl without the field → false,
# preserving the silent technical default).
SCOPE_DEFAULTED=$(printf '%s' "$RESOLVED_JSON" | jq -r '.defaulted // false')
# `remaining_args` is a JSON array of strings. Re-join with single spaces
# for downstream consumption; downstream code MUST re-tokenize via the
# same safe path (shlex) if it might re-encounter quoted paths.
ARGUMENTS=$(printf '%s' "$RESOLVED_JSON" | jq -r '.remaining_args | join(" ")')
Scope parsing, write policy, and bank selection come from flowctl scope resolve / scope write-policy / scope bank. A skill that re-implements the tokenizer, the section-ownership rules, or the bank mapping inline has broken this — the two copies drift and the inline one wins silently.
Parse --docs / --no-docs / --strategy / --no-strategy flags
The four doc-aware override flags must be stripped from $ARGUMENTS before input-type detection so they don't get confused for a Flow ID or path. Two force variables carry the result — "" = autodetect, "on" = forced on, "off" = forced off:
RAW_ARGS="$ARGUMENTS"
DOC_AWARE_FORCE="" # controls glossary + decisions
STRATEGY_AWARE_FORCE="" # controls strategy independently
When the invocation carried ANY of --docs / --no-docs / --strategy / --no-strategy, STOP and read references/doc-aware.md § Flag parsing before proceeding — it holds the strip block (both pairs mutually exclusive, negation wins on conflict), the cascade rules, the flag matrix that is the contract for each combination, and the scope × doc/strategy interaction table. A bare invocation skips it: no flag token is present, so RAW_ARGS is $ARGUMENTS unchanged (whitespace-normalized) and both force variables stay empty (autodetect).
Doc-aware autodetect
Decide whether doc-aware mode activates. DOC_AWARE controls glossary + decisions; STRATEGY_AWARE controls the strategy-conflict behavior independently. Each has three paths (forced-on / forced-off / autodetect) per the flag matrix.
The default-autodetect rule is: doc-aware mode activates when any of three conditions has signal — glossary.total_terms > 0 (a) OR a decision entry exists (b) OR strategy.sections_filled >= 1 (c). The two flag pairs override (a)+(b) and (c) independently. Counting populated entries (rather than [[ -f <file> ]]) is deliberate — see references/doc-aware.md § Why counts, not file presence.
# DOC_AWARE: glossary +
Read the complete source ↗