--- name: Flow Interview slug: flow-interview category: AI Engineering description: Flow Interview conducts a deep interview about a spec, task, or spec file to capture implementation details before work begins. Use it to refine requirements, clarify scope, and write the results back through Flow task tracking. github: "https://github.com/gmickel/flow-next/tree/main/optimization/interview/baseline" language: Python stars: 685 forks: 54 install: "npx degit https://github.com/gmickel/flow-next/tree/main/optimization/interview/baseline ~/.claude/skills/baseline" installs_to: ~/.claude/skills/baseline source_path: optimization/interview/baseline/SKILL.md collection_size: 25 category_size: 2451 collection_url: "https://dirskills.com/collections/gmickel/flow-next" added: 2026-08-23T05:20:54.732Z last_synced: 2026-08-23T05:20:54.732Z canonical_url: "https://dirskills.com/skills/flow-interview" --- # Flow Interview Flow Interview conducts a deep interview about a spec, task, or spec file to capture implementation details before work begins. Use it to refine requirements, clarify scope, and write the results back through Flow task tracking. **Install:** ```bash npx degit https://github.com/gmickel/flow-next/tree/main/optimization/interview/baseline ~/.claude/skills/baseline ``` ## README # Flow interview Conduct an extremely thorough interview about a task/spec and write refined details back. **IMPORTANT**: This plugin uses `.flow/` for ALL task tracking. Do NOT use markdown TODOs, plan files, TodoWrite, or other tracking methods. All task state must be read and written via `flowctl`. ## Preamble **CRITICAL: flowctl is BUNDLED — NOT installed globally.** `which flowctl` will fail (expected). Define once; subsequent blocks use `$FLOWCTL`: ```bash FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl" [ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl" ``` ## Pre-check: Local setup version If `.flow/meta.json` exists and has `setup_version`, compare to plugin version: ```bash SETUP_VER=$(jq -r '.setup_version // empty' .flow/meta.json 2>/dev/null) PLUGIN_JSON="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/.claude-plugin/plugin.json" PLUGIN_VER=$(jq -r '.version' "$PLUGIN_JSON" 2>/dev/null || echo "unknown") if [[ -n "$SETUP_VER" && "$PLUGIN_VER" != "unknown" ]]; then [[ "$SETUP_VER" = "$PLUGIN_VER" ]] || echo "Plugin updated to v${PLUGIN_VER}. Run /flow-next:setup to refresh local scripts (current: v${SETUP_VER})." fi ``` Continue regardless (non-blocking). **Role**: technical interviewer, spec refiner **Goal**: extract complete implementation details through deep questioning (40+ questions typical) ## Input Full request: $ARGUMENTS Accepts: - **Flow spec ID** `fn-N-slug` (e.g., `fn-1-add-oauth`) or legacy `fn-N`/`fn-N-xxx`: Fetch with `flowctl show`, write back with `flowctl spec set-plan` - **Flow task ID** `fn-N-slug.M` (e.g., `fn-1-add-oauth.2`) or legacy `fn-N.M`/`fn-N-xxx.M`: Fetch with `flowctl show`, write back with `flowctl task set-description/set-acceptance` - **File path** (e.g., `docs/spec.md`): Read file, interview, rewrite file - **Empty**: Prompt for target 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. Default scope when no scope flag is passed: `technical` (1.0.2 backward-compat). ```bash # 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') # `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(" ")') ``` The section-write policy for the resolved scope is computed by `flowctl scope write-policy`, called BEFORE any markdown edit. It returns which sections the pass MAY write and which it MUST preserve byte-for-byte (per the fn-44 spec Edge Cases merge contract): ```bash # Build the current-sections JSON from the existing spec (T2 wires this). # `flowctl scope write-policy --current-sections-json -` then emits # {writable, preserved, decision_context, placeholder_write} as JSON. WRITE_POLICY=$(echo "$CURRENT_SECTIONS" | "$FLOWCTL" scope write-policy "$SCOPE" --current-sections-json -) ``` The question-bank path for the resolved scope is resolved by `flowctl scope bank`, called when loading the question taxonomy: ```bash # Resolves to questions-business.md, questions-technical.md, or (for `both`) # the technical bank path (both-mode reads both banks). BANK_PATH=$("$FLOWCTL" scope bank "$SCOPE") ``` The full pass-aware behavior (loading the resolved bank, per-section writes that honor the policy, technical-pass-reads-business-sections-first) lives in the "Scope-aware pass behavior" section below. The skill MUST call these subcommands rather than re-implementing parse/policy logic inline. ### Parse `--docs` / `--no-docs` / `--strategy` / `--no-strategy` flags Strip the four doc-aware override flags from `$ARGUMENTS` before input-type detection so they don't get confused for a Flow ID or path: ```bash RAW_ARGS="$ARGUMENTS" DOC_AWARE_FORCE="" # "" = autodetect, "on" = forced on, "off" = forced off (controls glossary + decisions) STRATEGY_AWARE_FORCE="" # "" = autodetect, "on" = forced on, "off" = forced off (controls strategy independently) # Glossary + decisions: --docs / --no-docs (mutually exclusive; --no-docs wins) if [[ "$RAW_ARGS" == *"--no-docs"* ]]; then DOC_AWARE_FORCE="off" RAW_ARGS="${RAW_ARGS//--no-docs/}" elif [[ "$RAW_ARGS" == *"--docs"* ]]; then DOC_AWARE_FORCE="on" RAW_ARGS="${RAW_ARGS//--docs/}" fi # Strategy: explicit --strategy / --no-strategy always wins. Otherwise --docs / --no-docs cascades. # Order: explicit pair first (mutually exclusive; --no-strategy wins on conflict), then docs cascade. if [[ "$RAW_ARGS" == *"--no-strategy"* ]]; then STRATEGY_AWARE_FORCE="off" RAW_ARGS="${RAW_ARGS//--no-strategy/}" elif [[ "$RAW_ARGS" == *"--strategy"* ]]; then STRATEGY_AWARE_FORCE="on" RAW_ARGS="${RAW_ARGS//--strategy/}" elif [[ "$DOC_AWARE_FORCE" == "off" ]]; then # --no-docs alone cascades to strategy: matrix row 3 says all three off. STRATEGY_AWARE_FORCE="off" elif [[ "$DOC_AWARE_FORCE" == "on" ]]; then # --docs alone cascades to strategy: matrix row 2 says all three on. STRATEGY_AWARE_FORCE="on" fi RAW_ARGS=$(printf "%s" "$RAW_ARGS" | tr -s ' ' | sed 's/^ //;s/ $//') # RAW_ARGS now contains the Flow ID / file path / empty. ``` Each pair is mutually exclusive (the `if/elif` checks the negation first so it wins on conflict). The `--docs` / `--strategy` tokens get left in the residual `RAW_ARGS` after stripping, which surfaces downstream as an unrecognized argument — loud failure beats silent acceptance of conflicting state. **Flag matrix** — doc-aware flags (rows describe glossary / decisions / strategy gates): | Flags | Glossary | Decisions | Strategy | |-------|----------|-----------|----------| | (default) | autodetect | autodetect | autodetect | | `--docs` | on | on | on | | `--no-docs` | off | off | off | | `--no-docs --strategy` | off | off | on | | `--docs --no-strategy` | on | on | off | `--docs` / `--no-docs` cascade to strategy when no explicit `--strategy` / `--no-strategy` is passed (matrix rows 2 + 3). Explicit `--strategy` / `--no-strategy` always wins (matrix rows 4 + 5) and is the only way to drive a different value into strategy than into glossary + decisions. The matrix is the contract. **Scope x doc/strategy** — the `--scope` axis is orthogonal to the doc-aware matrix above. Each row of this table is a valid combination: | Scope | Doc-aware default | Pass behavior | |-------|------------------|---------------| | `--scope=technical` (default, also `--tech`) | autodetect cascade above runs | tech-owned sections (Architecture / API Contracts / Edge Cases / verifiable AC); preserves biz sections byte-for-byte; reads biz sections when populated, silent when absent | | `--scope=business` (also `--biz`) | autodetect cascade still runs; doc-awareness does NOT auto-activate from biz pass alone (`R26` adds project-docs investigation independently) | biz-owned sections (Goal & Context / Boundaries / outcome AC / `### Motivation`); preserves tech sections byte-for-byte; writes placeholder `*Pending technical-scope interview pass.*` ONLY under EMPTY tech sections | | `--scope=both` | autodetect cascade runs | runs biz pass first, then tech pass; same merge contract applies in each phase | R26 project-docs investigation is gated on `SCOPE=business` (and the biz-pass phase of `both`) — runs BEFORE drafting the first biz question, regardless of doc-aware autodetect state. ### Doc-aware autodetect Decide whether doc-aware mode (behaviors a-e below) 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 above. ```bash # DOC_AWARE: glossary + decisions DOC_AWARE=0 if [[ "$DOC_AWARE_FORCE" == "on" ]]; then DOC_AWARE=1 elif [[ "$DOC_AWARE_FORCE" == "off" ]]; then DOC_AWARE=0 else TERMS=$("$FLOWCTL" glossary list --json 2>/dev/null | jq -r '.total_terms // 0') DECS=$("$FLOWCTL" memory list --track knowledge --category decisions --json 2>/dev/null | jq -r '.entries | length // 0') if [[ "${TERMS:-0}" -gt 0 || "${DECS:-0}" -gt 0 ]]; then DOC_AWARE=1 fi fi # STRATEGY_AWARE: strategy (independent of DOC_AWARE — autodetects on its own signal) STRATEGY_AWARE=0 if [[ "$STRATEGY_AWARE_FORCE" == "on" ]]; then STRATEGY_AWARE=1 elif [[ "$STRATEGY_AWARE_FORCE" == "off" ]]; then STRATEGY_AWARE=0 else STRAT_FILLED=$("$FLOWCTL" strategy status --json 2>/dev/null | jq -r '.sections_filled // 0') if [[ "${STRAT_FILLED:-0}" -ge 1 ]]; then STRATEGY_AWARE=1 fi fi ``` 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 (`--docs` / `--no-docs` and `--strategy` / `--no-strategy`) override (a)+(b) and (c) independently per the matrix above. **Why `total_terms > 0` and `sections_filled >= 1` rather than `[[ -f ]]`:** `flowctl glossary remove` leaves a `# Glossary` H1 husk after the last term is removed; `flowctl strategy` leaves a frontmatter-plus-H1 husk under the same R18 invariant. Both files are project state, intentionally retained. A presence-only check would false-positive on an empty husk and surface phantom doc-aware questions when no canonical vocabulary / strategic intent is actually defined. `glossary list --json` and `strategy status --json` walk the file and count populated entries; both report zero for a husk. When `DOC_AWARE=1`, behaviors (a)-(d) below layer onto the standard interview workflow. When `STRATEGY_AWARE=1`, behavior (e) layers on. When both are 0, the interview proceeds exactly as today. ## Detect Input Type **Handle-recognition rule (R16):** do NOT gate on a hard "must start with `fn-`" check. Before treating a single-token arg as a file path or freeform, route it through `$FLOWCTL show --json` — flowctl's widened resolver (fn-52.10) maps a tracker key (`wor-17` / `wor-17.M`) to its linked spec/task, so a resolvable handle is the existing spec/task, never a new idea. Patterns 1-2 below are the common case; pattern 3 generalizes them to any resolvable handle. 1. **Flow spec ID pattern**: matches `fn-\d+(-[a-z0-9-]+)?` (e.g., fn-1-add-oauth, fn-12, fn-2-fix-login-bug) - Fetch: `$FLOWCTL show --json` - Read spec: `$FLOWCTL cat ` 2. **Flow task ID pattern**: matches `fn-\d+(-[a-z0-9-]+)?\.\d+` (e.g., fn-1-add-oauth.3, fn-12.5) - Fetch: `$FLOWCTL show --json` - Read spec: `$FLOWCTL cat ` - Also get parent spec context: `$FLOWCTL cat ` 3. **Resolvable tracker handle**: any single-token arg (not an `.md` path) that `$FLOWCTL show --json` resolves — e.g. a Linear key `wor-17` (spec) or `wor-17.3` (task). Use the canonical id from the JSON; a `.`-containing handle is a task (fetch parent spec too), otherwise a spec. Treat exactly like patterns 1-2; never re-create. 4. **File path**: a path-like token / `.md` extension that does NOT resolve via `flowctl show` - Read file contents - If file doesn't exist, ask user to provide valid path ## Interview Process **CRITICAL REQUIREMENT**: You MUST use the `AskUserQuestion` tool for every question. - DO NOT output questions as text - DO NOT list questions in your response - ONLY ask questions via AskUserQuestion tool calls - Group 2-4 related questions per tool call - Expect 40+ questions total for complex specs **Anti-pattern (WRONG)**: ``` Question 1: What database should we use? Options: a) PostgreSQL b) SQLite c) MongoDB ``` **Correct pattern**: Call AskUserQuestion tool with question and options. ### Question Format: Lead with Recommendation Every `AskUserQuestion` body must include the agent's recommended option AND a confidence tier. Mirrors the canonical phrasing in `flow-next-audit/SKILL.md:64` ("Lead with the recommended option and a one-sentence rationale"). Call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded. Fall back to numbered options in plain text only when the tool is unreachable. Pattern: - `question.body`: ". Recommended: — . Confidence: [high | judgment-call | your-call]." - `question.options`: neutral labels (no "(recommended)" markers — recommendation goes in the body; neutral options reduce anchoring) Confidence tiers (mandatory — pick one per question): - `[high]` — strong codebase signal or convention match. Recommendation is load-bearing; user can usually accept. - `[judgment-call]` — slight lean but reasonable people disagree. User's call carries weight. - `[your-call]` — agent has no signal. "I genuinely don't know — your priority / domain knowledge / preference." The `[your-call]` tier is **mandatory** when the agent has no basis for a recommendation. Skills that always recommend train users to defer (RLHF imitation of human bravado). Say so explicitly. Examples (one per tier): - `[high]`: "Where should the new validator live? Recommended: `src/utils/validation.ts` — three sibling validators (`validateEmail`, `validatePhone`, `validateUrl`) already live there and the test suite imports from that module. Confidence: [high]." Options: `src/utils/validation.ts`, `src/validators/`, `new module`. - `[judgment-call]`: "Cache TTL for the rate-limiter? Recommended: 60s — short enough that drift stays bounded, long enough that the cache earns its keep. Confidence: [judgment-call]." Options: `30s`, `60s`, `300s`, `no cache`. - `[your-call]`: "What error code should we return when the upstream API times out? Recommended: none — this depends on what callers expect and I don't see existing convention to copy. Confidence: [your-call]." Options: `502`, `503`, `504`, `408`. ### Question Order: Walk the Decision Tree Walk down branches of the decision tree in dependency order. Don't ask about implementation details before establishing whether they're needed. Concrete rules: 1. **Cap branch depth at 4.** Research shows >4 prior turns rarely improves question quality — drop deeper threads, ask about something else. Heuristic; revisit if too restrictive in real use. 2. **Discover-as-you-go**, not pre-compute. Adapt the next question based on prior answers. Don't lock a tree before you start. 3. **Surface abandoned branches.** When an answer prunes a sub-tree, say so explicitly: "Skipping persistence questions — you said no DB." 4. **One `AskUserQuestion` call per turn**, period — never queue multiple tool calls back-to-back. Within that single call you may bundle 2-4 closely-related sub-questions per the existing batching rule above; do NOT pad with loosely-related questions just to hit four. The intent: one focused checkpoint per turn so the user isn't barraged with unrelated decisions in parallel. Use multi-select within a sub-question when options are non-exclusive. Example flow: > Q: "Does this feature need persistence?" > A: "No, ephemeral state is fine." > [agent prunes the {DB choice, schema design, migration plan} sub-tree] > Q: "Skipped DB questions — you said ephemeral. Next: how should this state survive page reloads?" ### Investigate Codebase Before Asking Before every question, classify it via the [questions-shared.md](questions-shared.md) **Pre-Question Taxonomy** (hoisted out of the per-scope banks so both biz and tech reference the same classifier): - **Codebase-answerable** ("what exists / how it's wired / what conventions live here") → use Read / Grep / Glob to answer; log to spec's `## Resolved via Codebase` section with file:line evidence. - **Glossary-lookup-answerable** (`DOC_AWARE=1` only) — terms with a canonical entry in the nearest-ancestor `GLOSSARY.md` → silently resolve from the entry; log to spec's `## Glossary Conflicts` section only when the user's wording diverges from canonical AND the term is load-bearing (see behavior (a) below). - **User-judgment-required** ("what should exist / what tradeoff to make / what priority") → ask via `AskUserQuestion`. If you find yourself answering a "should" question via grep, that's the bug. Stop and ask the user. #### Code-versus-assertion contradiction (`DOC_AWARE=1` — behavior (c)) When grep / Read reveals the code disagrees with something the user asserted ("we already have X at path Y" but Y is gone, or "the auth flow uses OAuth" but the code uses API keys), do **not** silently log under `## Resolved via Codebase`. Surface the contradiction as an `AskUserQuestion`: - **header**: `Code mismatch?` - **body**: `Code shows at ; you said . Recommended: . Confidence: [].` - **options**: frozen — `match-code` (revise spec to align with what's there), `update-code` (treat the assertion as the goal; flag the divergence as a task), `clarify` (user explains; agent re-investigates with new context). Confidence tier: `[high]` when grep evidence is unambiguous (file does not exist, function signature is clearly different); `[judgment-call]` when interpretation is at play (similar names, partial overlap, recent rename). Never silently pick a side — the user owns the resolution. The bar for surfacing: a meaningful contradiction that affects spec correctness. If the user says "the validator returns boolean" and grep shows it returns `Result`, surface. If the user paraphrases a function's role and grep shows the role matches but the implementation differs in unrelated detail, log under `## Resolved via Codebase` and move on. ## Scope-aware pass behavior The interview runs in one of three scoped modes resolved by `flowctl scope resolve` (above). Each scope writes a different set of sections back to the spec and reads a different set as context. The full merge contract — which sections each pass writes, which it preserves byte-for-byte, and how `## Decision Context` H3 promotion works — is computed by `flowctl scope write-policy` (called BEFORE any markdown edit). The structural canon for sections is `plugins/flow-next/templates/spec.md` (per R17 — never re-embed the section list inline; cross-link the template). ### Compute the write policy Before writing anything back, build the current-sections-state JSON from the existing spec markdown (or an empty object for new specs) and call `scope write-policy`. The policy result tells you which sections are writable, which are preserved, and how to handle the `## Decision Context` substructure conditional. **One policy call per pass** — when `SCOPE == both`, compute the biz policy first, run the biz pass, then **recompute** the current-sections state from the post-biz-pass result and compute a fresh technical policy for phase 2. A single pre-edit policy call for `both` cannot correctly decide tech-pass `Decision Context` shape (the biz pass may have promoted FLAT → substructured) or tech-pass placeholder replacement (biz pass may have written `*Pending technical-scope intervi