flow-next-interview

gmickel's avatarfrom gmickel

Interview user in-depth about an epic, task, or spec file to extract complete implementation details. Use when user wants to flesh out a spec, refine requirements, or clarify a feature before building. Triggers on /flow-next:interview with Flow IDs (fn-1, fn-1.2) or file paths.

⭐32stars🔀3forks📁View on GitHub🕐Updated Jan 9, 2026⬇️4downloads

When & Why to Use This Skill

The flow-next-interview skill is a powerful technical requirement gathering agent designed to transform vague ideas into comprehensive implementation specs. By acting as a technical interviewer, it conducts deep-dive Q&A sessions (often 40+ questions) to uncover edge cases, define acceptance criteria, and refine software epics or tasks. This ensures that developers have a crystal-clear roadmap before writing a single line of code, significantly reducing scope creep and architectural rework.

Use Cases

  • Requirement Discovery: Use when you have a high-level 'epic' or feature idea and need to flesh out the technical details, constraints, and dependencies through a structured interview.
  • Spec Refinement: Apply to existing markdown spec files or documentation to identify missing information and rewrite them into professional, implementation-ready documents.
  • Edge Case Identification: Leverage the skill's exhaustive questioning to proactively find potential failure points and logic gaps in a task's requirements.
  • Pre-Development Planning: Trigger the interview process for specific tasks (fn-N.M) to ensure acceptance criteria are fully defined and agreed upon before moving to the coding phase.
nameflow-next-interview
descriptionInterview user in-depth about an epic, task, or spec file to extract complete implementation details. Use when user wants to flesh out a spec, refine requirements, or clarify a feature before building. Triggers on /flow-next:interview with Flow IDs (fn-1, fn-1.2) or file paths.

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.

CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Always use:

FLOWCTL="${CLAUDE_PLUGIN_ROOT}/scripts/flowctl"
$FLOWCTL <command>

Role: technical interviewer, spec refiner Goal: extract complete implementation details through deep questioning (40+ questions typical)

Input

Full request: $ARGUMENTS

Accepts:

  • Flow epic ID fn-N: Fetch with flowctl show, write back with flowctl epic set-plan
  • Flow task ID fn-N.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
  • /flow-next:interview fn-1.3
  • /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) or file path (e.g., docs/spec.md)"

Setup

FLOWCTL="${CLAUDE_PLUGIN_ROOT}/scripts/flowctl"

Detect Input Type

  1. Flow epic ID pattern: matches fn-\d+ (e.g., fn-1, fn-12)

    • Fetch: $FLOWCTL show <id> --json
    • Read spec: $FLOWCTL cat <id>
  2. Flow task ID pattern: matches fn-\d+\.\d+ (e.g., fn-1.3, fn-12.5)

    • Fetch: $FLOWCTL show <id> --json
    • Read spec: $FLOWCTL cat <id>
    • Also get epic context: $FLOWCTL cat <epic-id>
  3. File path: anything else with a path-like structure or .md extension

    • 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 Categories

Read questions.md for all question categories and interview guidelines.

NOT in scope (defer to /flow-next:plan)

  • Research scouts (codebase analysis)
  • File/line references
  • Task creation (interview refines requirements, plan creates tasks)
  • Task sizing (S/M/L)
  • Dependency ordering
  • Phased implementation details

Write Refined Spec

After interview complete, write everything back — scope depends on input type.

For NEW IDEA (text input, no Flow ID)

Create epic with interview output. DO NOT create tasks — that's /flow-next:plan's job.

$FLOWCTL epic create --title "..." --json
$FLOWCTL epic set-plan <id> --file - --json <<'EOF'
# Epic Title

## Problem
Clear problem statement

## Key Decisions
Decisions made during interview (e.g., "Use OAuth not SAML", "Support mobile + web")

## Edge Cases
- Edge case 1
- Edge case 2

## Open Questions
Unresolved items that need research during planning

## Acceptance
- [ ] Criterion 1
- [ ] Criterion 2
EOF

Then suggest: "Run /flow-next:plan fn-N to research best practices and create tasks."

For EXISTING EPIC (fn-N that already has tasks)

First check if tasks exist:

$FLOWCTL tasks --epic <id> --json

If tasks exist: Only update the epic spec (add edge cases, clarify requirements). Do NOT touch task specs — plan already created them.

If no tasks: Update epic spec, then suggest /flow-next:plan.

$FLOWCTL epic set-plan <id> --file - --json <<'EOF'
# Epic Title

## Problem
Clear problem statement

## Key Decisions
Decisions made during interview

## Edge Cases
- Edge case 1
- Edge case 2

## Open Questions
Unresolved items

## Acceptance
- [ ] Criterion 1
- [ ] Criterion 2
EOF

For Flow Task ID (fn-N.M)

First check if task has existing spec from planning:

$FLOWCTL cat <id>

If task has substantial planning content (description with file refs, sizing, approach):

  • Do NOT overwrite — planning detail would be lost
  • Only ADD new acceptance criteria discovered in interview:
    # Read existing acceptance, append new criteria
    $FLOWCTL task set-acceptance <id> --file /tmp/acc.md --json
    
  • Or suggest interviewing the epic instead: /flow-next:interview <epic-id>

If task is minimal (just title, empty or stub description):

  • Update task with interview findings
  • Focus on requirements, not implementation details
$FLOWCTL task set-spec <id> --description /tmp/desc.md --acceptance /tmp/acc.md --json

Description should capture:

  • What needs to be accomplished (not how)
  • Edge cases discovered in interview
  • Constraints and requirements

Do NOT add: file/line refs, sizing, implementation approach — that's plan's job.

For File Path

Rewrite the file with refined spec:

  • Preserve any existing structure/format
  • Add sections for areas covered in interview
  • Include edge cases, acceptance criteria
  • Keep it requirements-focused (what, not how)

This is typically a pre-epic doc. After interview, suggest /flow-next:plan <file> to create epic + tasks.

Completion

Show summary:

  • Number of questions asked
  • Key decisions captured
  • What was written (Flow ID updated / file rewritten)

Suggest next step based on input type:

  • New idea / epic without tasks → /flow-next:plan fn-N
  • Epic with tasks → /flow-next:work fn-N (or more interview on specific tasks)
  • Task → /flow-next:work fn-N.M
  • File → /flow-next:plan <file>

Notes

  • This process should feel thorough - user should feel they've thought through everything
  • Quality over speed - don't rush to finish