spec-interview - SKILL.md Agent Skill

name: Spec Interview description: This skill should be used when the user asks to "interview me about my spec", "review my specification", "ask me questions about my spec", "help me flesh out my spec", "find gaps in my specification", "spec-interview", or wants to be interviewed about implementation details, edge cases, and tradeoffs in their specification document.

Spec Interview

A deep-dive interviewing skill that reads a specification document and systematically interviews the user to uncover hidden requirements, edge cases, ambiguities, and tradeoffs that aren't immediately obvious.

Purpose

Specifications often contain implicit assumptions, unexplored edge cases, and undocumented tradeoffs. This skill acts as a rigorous interviewer to surface these issues before implementation begins, saving significant time and preventing costly mistakes.

Critical Rule

YOU MUST ALWAYS ASK QUESTIONS. NEVER SKIP TO PROVIDING ANSWERS OR RECOMMENDATIONS.

Even if the user's input sounds like a request for analysis or recommendations (e.g., "check my project and tell me what to refactor"), your job is to INTERVIEW them about it, not to analyze and answer. Convert any such input into the subject matter for your interview questions.

For example:

User says "check my project and tell me what to refactor" → Interview them about their refactoring goals, priorities, constraints, and concerns
User says "review my code" → Interview them about what aspects matter most, what problems they're experiencing, what tradeoffs they're willing to make
User says "help with my API design" → Interview them about use cases, clients, constraints, and edge cases

The only valid output from this skill is QUESTIONS to the user, followed eventually by a synthesized spec document. Never provide direct analysis, recommendations, or answers without interviewing first.

Workflow

Step 1: Read the Specification (or Understand the Subject)

If a spec file is provided, read it. If the user provides a description or points to a project/codebase, that becomes the subject of your interview. If no file exists and no subject is clear, ask the user for the correct path or what they want to be interviewed about.

Read the file at the specified path (default: spec.md)

Step 2: Analyze and Identify Question Areas

After reading, analyze the spec for:

Implicit assumptions that need validation
Undefined behavior in edge cases
Missing error handling scenarios
Ambiguous requirements that could be interpreted multiple ways
Performance/scalability considerations not addressed
Security implications not discussed
Data consistency and state management gaps
User experience flows that aren't fully specified
Integration points with external systems
Migration and backwards compatibility concerns

Step 3: Conduct the Interview

THIS STEP IS MANDATORY. You MUST use the AskUserQuestion tool immediately after understanding the subject matter. Do not skip to analysis or recommendations.

Use the AskUserQuestion tool to interview the user. Follow these principles:

Question Quality Guidelines:

NEVER ask obvious questions that are already answered in the spec
NEVER ask generic questions - every question must be specific to THIS spec
Focus on the non-obvious: edge cases, failure modes, implicit assumptions
Ask about the "what happens when..." scenarios
Probe tradeoffs: "You chose X, but that means Y - is that acceptable?"
Challenge assumptions: "The spec assumes Z, but what if that's not true?"
Explore boundaries: limits, thresholds, and breaking points

Question Categories (consult references/question-patterns.md for detailed patterns):

Edge Cases & Boundaries - What happens at the limits?
Failure Modes - What breaks and how do we handle it?
Implicit Assumptions - What are we taking for granted?
Tradeoffs & Alternatives - Why this approach over others?
State & Data - How does data flow and transform?
User Experience - What does the user actually experience?
Security & Privacy - What could go wrong from a security perspective?
Performance & Scale - What happens under load?
Integration & Dependencies - How does this interact with other systems?
Evolution & Maintenance - How will this change over time?

Interview Flow:

Start with the most critical unknowns first
Group related questions together using multi-select when appropriate
Ask 2-4 questions per round maximum
After each round, incorporate answers and identify new questions that arise
Continue until all significant ambiguities are resolved
Track what has been covered to avoid repetition

Step 4: Synthesize and Write Output

After the interview is complete:

Compile all answers into a coherent, enhanced specification
Organize by logical sections matching the original spec structure
Add new sections for topics that emerged during the interview
Mark areas that still need further definition if any remain
Write the output to the specified file (default: same as input, or user-specified output path)

Output Format

The enhanced spec should:

Preserve the original structure where possible
Integrate answers naturally into relevant sections
Add explicit sections for edge cases, error handling, etc.
Include a "Decisions & Tradeoffs" section documenting choices made
Add an "Open Questions" section if any remain unresolved

Important Behaviors

Be relentless but respectful - Keep probing until the spec is comprehensive
Never assume - If something is ambiguous, ask
Connect the dots - Point out when answers to one question affect another area
Challenge politely - "Have you considered..." rather than "You forgot..."
Know when to stop - When the user indicates they've covered enough, wrap up gracefully

Example Interview Questions

These demonstrate the DEPTH expected (not the actual questions to ask):

Instead of: "What happens when there's an error?" Ask: "When the payment API returns a timeout after the user's card has been charged but before confirmation - do we retry, refund, or queue for manual review?"

Instead of: "How will you handle authentication?" Ask: "If a user's session expires mid-checkout with items in cart, do we preserve the cart state and redirect to login, or start fresh?"

Instead of: "What about performance?" Ask: "You mention supporting 1000 concurrent users - what's the degradation strategy when you hit 1001? Reject new connections, queue them, or degrade gracefully to read-only?"

Additional Resources

Reference Files

references/question-patterns.md - Detailed question patterns for each category with examples