flow-interview

gmickel's avatarfrom gmickel

Interview user in-depth about a spec, bead, or feature idea to extract complete implementation details. Use when user wants to flesh out a spec, refine requirements, discuss technical details, clarify a feature before building, or asks to be interviewed about their idea. Triggers on "interview me", "ask me questions about", "flesh out this spec", "refine requirements", "help me think through".

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

When & Why to Use This Skill

The Flow Interview skill is a sophisticated technical requirement refiner designed to bridge the gap between high-level ideas and actionable development plans. By conducting exhaustive, multi-layered interviews (often exceeding 40 questions), it extracts critical implementation details, identifies technical dependencies, and uncovers edge cases. It seamlessly integrates with project management systems to automatically update task 'beads' or refine markdown documentation, ensuring that engineering teams have a crystal-clear roadmap before coding begins.

Use Cases

  • Technical Requirement Refinement: Transform a vague feature request into a comprehensive, actionable specification with clear acceptance criteria.
  • Pre-Development Discovery: Conduct a deep-dive interview to identify hidden technical blockers, dependencies, and architectural constraints for a new project epic.
  • Automated Task Decomposition: Automatically generate granular subtasks and update project management 'beads' based on the outcomes of a thorough technical interview.
  • Documentation Auditing: Read existing SPEC.md files and use the interview process to fill in missing technical details, ensuring documentation is complete and engineering-ready.
nameflow-interview
descriptionInterview user in-depth about a spec, bead, or feature idea to extract complete implementation details. Use when user wants to flesh out a spec, refine requirements, discuss technical details, clarify a feature before building, or asks to be interviewed about their idea. Triggers on "interview me", "ask me questions about", "flesh out this spec", "refine requirements", "help me think through".

Flow interview

Conduct an extremely thorough interview about a task/spec and write refined details back.

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

Input

Full request: #$ARGUMENTS

Accepts:

  • Beads ID (e.g., gno-42, bd-123, app-12): Fetch with bd show, write back with bd update
  • File path (e.g., docs/spec.md, SPEC.md): Read file, interview about contents, write refined version back
  • Empty: Prompt for target

Examples:

  • /flow:interview gno-42
  • /flow:interview docs/oauth-spec.md
  • /flow:interview SPEC.md

If empty, ask: "What should I interview you about? Give me a bead ID (e.g., gno-42) or file path (e.g., docs/spec.md)"

Detect Input Type

  1. Beads ID pattern: matches [a-z]+-\d+ (e.g., gno-42, bd-123, app-7)

    • Fetch: bd show <id> --json
    • If type is "epic", also: bd list --parent=<id> --json to get subtasks
  2. 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.

Write Refined Spec

After interview complete, write everything back.

For Beads ID

Single task:

echo "<refined description>" | bd update <id> --body-file -
bd update <id> --acceptance="<acceptance criteria>"

Epic:

  1. Update epic description: echo "<summary>" | bd update <id> --body-file -
  2. Create/update subtasks:
    • New: bd create --title="..." --description="..." --parent=<id>
    • Existing: echo "<details>" | bd update <subtask-id> --body-file -
  3. Add dependencies if discovered: bd dep add <task> <depends-on>

Include in description:

  • Clear problem statement
  • Technical approach with specifics
  • Key decisions made during interview
  • Edge cases to handle
  • Dependencies/blockers discovered

For File Path

Rewrite the file with refined spec:

  • Preserve any existing structure/format
  • Add sections for areas covered in interview
  • Include technical details, edge cases, acceptance criteria
  • Keep it actionable and specific

Completion

Show summary:

  • Number of questions asked
  • Key decisions captured
  • What was written (bead updated / file rewritten)
  • Suggest next step: /flow:plan or /flow:work

Notes

  • Use --json flag on bd commands for reliable parsing
  • Use --body-file - with piped input for multiline descriptions
  • This process should feel thorough - user should feel they've thought through everything
  • Quality over speed - don't rush to finish