interview-framework

Interview Framework

Adaptive brainstorming dialogue algorithm for all spec phases. Each phase command provides its own exploration territory (phase-specific areas to probe).

Option Limit Rule

Each question must have 2-4 options (max 4). Keep the most relevant options, combine similar ones.

Recommendation Format

Every question asked via AskUserQuestion in Phase 1 leads with the recommended option (except when options are symmetric, in which case [Recommended] may be omitted):

AskUserQuestion:
  question: "[Context-aware question referencing prior answers]. [One sentence rationale for the recommendation.]"
  options:
    - "[Recommended] [Option text -- the AI's suggested answer]"
    - "[Alternative 1]"
    - "[Alternative 2 if needed]"
    - "Other"

Rules:

• [Recommended] is a label prefix on the first option only.
• The rationale sits in the question text, not the option label.
• Option count still 2-4 max (Option Limit Rule preserved).
• If there is no meaningful recommendation (truly symmetric choice), omit the [Recommended] label rather than placing it arbitrarily.

Example:

AskUserQuestion:
  question: "Where should the spec live? You only have one specs directory configured, so the default is fine unless you want to reorganize."
  options:
    - "[Recommended] ./specs/ (default)"
    - "Let me configure a different path"
    - "Other"

Parallel Codebase-First Discovery

Before asking ANY question, determine whether the answer is a codebase fact, a prior-memory fact, a current-docs fact, or a user decision:

• Codebase fact: discoverable by reading code, config, or existing specs (e.g., which framework is used, whether an interface already exists, what a file currently does). Delegate to an Explore subagent. Never ask the user.
• Prior-memory fact: discoverable by querying the user's claude-mem history (e.g., "did we already decide on Postgres for this product?", "what stack did we pick last quarter?"). Delegate to a general-purpose subagent invoking mcp__plugin_claude-mem_mcp-search__* tools. Never ask the user.
• Current-docs fact: discoverable from official docs of a named library/framework/SDK/API (e.g., "does node-pty support Windows?", "is OAuth-PKCE required for this provider?"). Delegate to a research-analyst subagent (preferring Context7 MCP via its tool surface). Never ask the user.
• User decision: a preference, priority, trade-off, or constraint that only the user can answer (e.g., which of two viable approaches, what the success criteria are, what's in scope). Ask via AskUserQuestion.

Discover in parallel BEFORE the first question

<mandatory> Before asking the FIRST interview question, the coordinator MUST fan out all discoverable facts in ONE message:

• One Explore agent per orthogonal codebase concern
• One general-purpose agent (claude-mem search) if the project has prior history
• One research-analyst agent per named candidate library/framework </mandatory>

Asking the user before exhausting parallel discovery is the Question-before-discovery anti-pattern (see ${CLAUDE_PLUGIN_ROOT}/references/bounded-parallel-dispatch.md Discovery domain, anti-pattern #14). The interview becomes lower-leverage when its [Recommended] options aren't grounded in evidence.

Synthesis → interview

After parallel discovery returns:

1. Mark each pre-identified question as answered by discovery (drop from interview) or still needs user decision (keep).
2. For kept questions, derive [Recommended] from synthesis findings; never fabricate a recommendation without evidence.
3. Run the interview in a single tight pass. Re-discover only if a user answer materially changes the search space.

Only ask what you cannot discover yourself.

Completion Signal Detection

After each response, check for early completion signals using token-based matching:

completionSignals = ["done", "proceed", "skip", "enough", "that's all", "continue", "next"]

tokens = tokenize(userResponse.lower())  # split on whitespace/punctuation
for signal in completionSignals:
  if signal in tokens:  # exact token match, not substring
    -> SKIP remaining questions, move to PROPOSE APPROACHES

3-Phase Overview

Phase 1: UNDERSTAND (Decision-Tree)

Read all available context (.progress.md, prior artifacts, goal text). Build a question tree from the exploration territory with dependency ordering. Traverse the tree: auto-resolve codebase facts via exploration, ask user only about decisions. Each question leads with [Recommended] answer. No fixed question caps. Exit when all nodes resolved or user signals completion.

See references/algorithm.md for full pseudocode.

Phase 2: PROPOSE APPROACHES

Synthesize dialogue into 2-3 distinct approaches. Each includes: name, description, trade-offs. Lead with recommendation. Present via AskUserQuestion. Maximum 3 approaches (more causes decision fatigue). Trade-offs must be honest. No straw-man alternatives.

See references/algorithm.md for full pseudocode.

Phase 3: CONFIRM & STORE

Brief recap to user of key decisions and chosen approach. If user corrects something, update before storing. Store in .progress.md under Context Accumulator pattern.

See references/algorithm.md for full pseudocode.

Adaptive Depth (Other Responses)

When user selects "Other": ask a context-specific follow-up (never generic "elaborate"). Reference what the user typed. Continue until clarity or 5 rounds. Do not increment askedCount for follow-ups.

See references/examples.md for example follow-up patterns.

Context Accumulator Pattern

After each interview, update .progress.md: read existing content, append new section under "## Interview Responses" with descriptive keys reflecting what was discussed. Include the chosen approach.

See references/examples.md for storage format.

References

• references/algorithm.md -- Full 3-phase pseudocode (UNDERSTAND decision-tree, PROPOSE APPROACHES, CONFIRM & STORE)
• references/examples.md -- Example interview questions, "Other" response handling, context storage format