flow-next-interview
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.
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.
| name | flow-next-interview |
|---|---|
| description | 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. |
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 withflowctl show, write back withflowctl epic set-plan - Flow task ID
fn-N.M: Fetch withflowctl show, write back withflowctl 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
Flow epic ID pattern: matches
fn-\d+(e.g., fn-1, fn-12)- Fetch:
$FLOWCTL show <id> --json - Read spec:
$FLOWCTL cat <id>
- Fetch:
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>
- Fetch:
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