Spec Interview

Spec Interview

When to Use

Use this skill when:

• Feature requirements are vague or incomplete
• You have a general idea but lack specifics
• Stakeholders said "you know what I mean"
• The spec has obvious gaps
• Making assumptions that could be wrong

What It Does

The agent interviews you to uncover unknown unknowns in your feature specification, focusing on questions that would change architectural decisions.

How to Execute

Step 1: Review Initial Spec

Analyze what the user provided:

• Explicit requirements (what they said)
• Implicit requirements (what they assumed)
• Missing details
• Ambiguous areas

Step 2: Categorize Gaps

Identify question categories:

Scope & Boundaries:

• What's in scope vs out of scope?
• Edge cases to handle?
• MVP vs future iterations?

User Experience:

• What happens when...?
• Error states and recovery?
• Loading and async states?

Technical Decisions:

• Performance requirements?
• Data consistency needs?
• Integration points?
• Security considerations?

Architecture Impact:

• Does this change existing patterns?
• New abstractions needed?
• Migration strategy for existing data?

Step 3: Prioritize Questions

Sort by impact on implementation:

1. Architecture-changing: Would change core approach
2. High-impact: Significant implementation difference
3. Medium-impact: Affects specific modules
4. Low-impact: Nice to clarify but not blocking

Step 4: Conduct Interview (One Question at a Time)

Use the ask_user_question tool for each question. Ask one question at a time — present it, wait for the answer, then proceed to the next. This keeps the interview focused and lets the user's answer to one question influence follow-ups.

Guidelines for using ask_user_question:

• Set header to a short category label (max 16 chars), e.g. "Architecture", "Scope", "UX", "Edge Cases"
• Write a clear question string with context about why you're asking
• Provide 2-4 concrete options with concise label (1-5 words) and descriptive description explaining trade-offs
• After the user answers, acknowledge the choice and explain how it impacts the implementation before asking the next question
• Architecture-changing questions first, then high-impact, then medium-impact

Example — single question call:

ask_user_question(questions: [{
  header: "Architecture",
  question: "Where should the export process run? Large exports could time out or block the web process.",
  options: [
    {
      label: "Synchronous HTTP",
      description: "Simple, returns CSV directly in response — but risky for large datasets that could timeout"
    },
    {
      label: "Background job + email",
      description: "More robust: process asynchronously, email link when done — requires job queue and storage"
    },
    {
      label: "Streaming download",
      description: "Immediate start, handles large data, no queuing needed — but more complex to implement"
    }
  ]
}])

When to use open-ended instead of multiple choice:

• Exploring unknown design space where you can't enumerate options
• After multiple-choice answers that surface unexpected direction
• For rank/priority questions ("Which features are most important?")
• Set options with 2-4 broader paths, or use ask_user_question's single-select custom answer ("Type something") for truly open exploration

Step 5: Process Answers

After each answer:

• Acknowledge the choice and its implications
• Update your mental model
• Decide if follow-up questions are needed (you can dig deeper before moving on)
• Identify decisions that need documentation

Step 6: Summarize

After all questions are answered:

• Summarize the key architectural decisions made
• Flag decisions the user deferred ("decide for me" or "skip")
• Outline next steps with confidence level

Question Patterns

These show how to translate each pattern into an ask_user_question call.

Architecture-Changing

// One question at a time
ask_user_question(questions: [{
  header: "Architecture",
  question: "How should we handle authentication for this feature? This determines whether we modify the current auth flow or build a new one.",
  options: [
    {
      label: "Extend existing auth",
      description: "Adds to current flow — simpler but may create coupling"
    },
    {
      label: "New auth abstraction",
      description: "Clean separation — more upfront work, more flexible long-term"
    },
    {
      label: "External auth service",
      description: "Offload entirely — fastest to build, adds third-party dependency"
    }
  ]
}])

Scope Clarification

ask_user_question(questions: [{
  header: "Scope",
  question: "Should this feature support multiple organizations from the start?",
  options: [
    {
      label: "Yes, initial release",
      description: "Adds 2-3 more integration points and multi-tenant data isolation now"
    },
    {
      label: "Later if needed",
      description: "Simpler initial build, but may require data migration later"
    },
    {
      label: "Not needed at all",
      description: "Single-tenant only — keeps everything simple"
    }
  ]
}])