Spec Interview

Spec Interview

Conducts in-depth interviews to gather comprehensive requirements, then generates detailed specification documents.

Execution Algorithm

Step 1: Parse Initial Request

Extract from user message:

Examples:

• "Interview me about building a task management app" → Topic extracted
• "Help me spec out a new authentication system" → Topic + domain
• "Ask me questions about redesigning our dashboard" → Topic + focus (UI/UX)

Initial acknowledgment: Briefly confirm the topic and explain the interview process.

Step 2: Generate First Question Set

Create 2-4 in-depth questions using AskUserQuestion tool.

Question Categories (rotate through these):

Question Quality Rules:

✅ DO Ask:

• "What happens when two users edit the same item simultaneously?"
• "How should the system behave when the external API is down?"
• "What's your priority: faster implementation or more flexible architecture?"
• "Who should have permission to delete data, and what's the recovery process?"

❌ DON'T Ask:

• "Do you want this to be fast?" (too obvious)
• "Should we use React?" (too specific without context)
• "Is security important?" (always yes, not insightful)

AskUserQuestion Format:

AskUserQuestion(
    questions=[
        {
            "question": "What happens when...",
            "header": "Edge Case",
            "options": [
                {"label": "Option A", "description": "What this means..."},
                {"label": "Option B", "description": "Trade-off here..."},
                {"label": "Option C", "description": "Alternative approach..."}
            ],
            "multiSelect": false
        },
        # 1-3 more questions
    ]
)

Important:

• Ask 2-4 questions per round (not overwhelming)
• Each question should reveal non-obvious insights
• Options should present real trade-offs, not obvious good/bad choices
• Headers should be short (max 12 chars): "Tech Stack", "User Flow", "Trade-off"

Step 3: Analyze Responses

After receiving answers, analyze what you learned:

Track Coverage:

• ✅ Technical architecture
• ✅ User experience flows
• ⚠️ Security concerns (needs more depth)
• ❌ Performance requirements (not covered yet)
• ❌ Testing strategy (not covered yet)

Identify Gaps:

• What critical aspects haven't been discussed?
• What answers raised new questions?
• What assumptions need validation?

Step 4: Generate Next Question Set

Based on gaps and new insights, ask 2-4 more questions.

Follow-up Strategy:

1. Drill deeper on concerning answers
2. Explore uncovered areas from the tracking list
3. Validate assumptions from previous responses
4. Challenge trade-offs if user chose all easy options

Example Progression:

Round 1: High-level architecture, main user flows Round 2: Edge cases, error handling, data consistency Round 3: Security, permissions, compliance Round 4: Performance, scalability, monitoring

Depth over breadth: Better to fully understand 3 critical areas than superficially cover 10.

Step 5: Determine Completion

Interview is complete when:

✅ Coverage criteria met:

• Core functionality clearly defined
• Critical edge cases discussed
• Major technical decisions made
• Key risks and trade-offs identified
• Non-obvious insights gathered

✅ Diminishing returns:

• New questions would be minor details
• User has given comprehensive answers
• No significant gaps remain

Don't over-interview:

• Stop at 3-5 rounds for simple features
• Stop at 5-8 rounds for complex projects
• If user is repeating themselves, move on

Step 6: Generate Specification Document

Create comprehensive spec document using all gathered information.

Spec Template:

# [Feature/Project Name] - Technical Specification

> **Generated**: YYYY-MM-DD  <!-- Must run `date '+%Y-%m-%d'` to get exact date. Never estimate. -->
> **Author**: [User name if known]
> **Status**: Draft

## 1. Overview

### Purpose
[What this feature/project does and why it's needed]

### Scope
**In Scope:**
- [Item 1]
- [Item 2]

**Out of Scope:**
- [Item 1]
- [Item 2]

## 2. Requirements

### Functional Requirements

#### FR-1: [Requirement Name]
- **Description**: [What it does]
- **Priority**: High/Medium/Low
- **Rationale**: [Why this is needed]
- **Acceptance Criteria**:
  - [ ] Criterion 1
  - [ ] Criterion 2

#### FR-2: [Next Requirement]
...

### Non-Functional Requirements

#### NFR-1: Performance
- [Specific performance requirements]

#### NFR-2: Security
- [Security requirements and concerns]

#### NFR-3: Scalability
- [Scalability considerations]

## 3. Technical Design

### Architecture Overview
[High-level architecture description]

[ASCII diagram or description]

### Technology Stack
- **Frontend**: [Choices and rationale]
- **Backend**: [Choices and rationale]
- **Database**: [Choices and rationale]
- **Infrastructure**: [Choices and rationale]

### Key Components

#### Component 1: [Name]
- **Responsibility**: [What it does]
- **Interfaces**: [How it connects]
- **Dependencies**: [What it needs]

### Data Models

#### Model 1: [Entity Name]
```typescript
interface Entity {
  id: string
  field1: Type
  field2: Type
}

4. User Experience

User Flows

Flow 1: [Happy Path]

1. User does X
2. System responds with Y
3. User sees Z

Flow 2: [Edge Case]

...

UI/UX Considerations

• [Key interaction patterns]
• [Accessibility requirements]
• [Error states and messaging]

5. Implementation Details

Phase 1: [MVP / Core Features]

• Task 1
• Task 2
• Task 3

Phase 2: [Enhancements]

• Task 1
• Task 2

Technical Decisions

Decision 1: [What was decided]

• Options Considered: A, B, C
• Chosen: B
• Rationale: [Why B over A and C]
• Trade-offs: [What we're giving up]

6. Edge Cases & Error Handling

Edge Case 1: [Scenario]

• Situation: [When this happens]
• Expected Behavior: [What should happen]
• Fallback: [If primary approach fails]

Error Scenarios

7. Security & Privacy

Security Considerations

• [Authentication approach]
• [Authorization rules]
• [Data encryption]
• [API security]

Privacy & Compliance

• [Data handling policies]
• [User consent requirements]
• [Compliance requirements (GDPR, etc.)]

8. Testing Strategy

Test Coverage

Unit Tests

• [What to unit test]

Integration Tests

• [What to integration test]

E2E Tests

• [Critical user flows to test]

Test Scenarios

1. Happy path: [Description]
2. Edge case 1: [Description]
3. Error case 1: [Description]

9. Risks & Mitigations

10. Open Questions

• Question 1 that needs resolution
• Question 2 that needs stakeholder input
• Question 3 requiring further research

11. Success Metrics

Key Metrics

• [Metric 1]: [Target value]
• [Metric 2]: [Target value]

Monitoring

• [What to monitor]
• [Alert thresholds]

12. References

Related Documents

• [Link to designs]
• [Link to API docs]
• [Link to research]

Interview Notes

[Summary of key insights from the interview process]

Next Steps:

1. Review and validate this specification
2. Share with stakeholders for feedback
3. Break down into implementable tasks
4. Update as requirements evolve

**Customization Rules:**
- Include only relevant sections (skip empty ones)
- Adapt depth to project complexity
- Preserve all insights from interview
- Use user's own language and examples where possible
- If user mentioned specific concerns, highlight them

---

### Step 7: Choose Save Location

**Options:**

1. **Current directory** (default)
   - Save as `[feature-name]-spec.md` in current working directory
   - Good for project-specific specs

2. **Ask user for location**
   - If they have a preferred docs directory
   - If this should go into a specific repo

**Filename format:**
- `[feature-name]-spec.md` (e.g., `task-management-spec.md`)
- Or user's preferred format if specified

---

### Step 8: Save Document

Use Write tool to create the specification file.

**Save location examples:**

./task-management-spec.md ./docs/specs/authentication-spec.md /Users/jaykim/Documents/Projects/myapp/specs/dashboard-redesign-spec.md

**If directory doesn't exist:**
```bash
mkdir -p path/to/directory

Step 9: Confirm to User

Show the user:

• ✅ Full path of saved specification
• 📋 Brief summary of what was captured
• 🎯 Next steps recommendation
• 💡 Suggest related actions

Example confirmation:

✅ Specification saved to: ./task-management-spec.md

📋 Captured:
- 12 functional requirements
- Architecture: React + Node.js + PostgreSQL
- 8 key user flows with edge cases
- Security: JWT auth + role-based permissions
- 3 implementation phases defined

🎯 Next Steps:
1. Review and validate the specification
2. Break down into tasks (I can help with this!)
3. Identify any missing requirements

Want me to:
- Create a task breakdown from this spec?
- Generate API endpoint definitions?
- Draft database migration scripts?

Trigger Phrases

English:

• "interview me"
• "interview me about [topic]"
• "help me spec this out"
• "gather requirements"
• "ask me questions about [topic]"
• "I want to build [X], ask me questions"

Korean:

• "인터뷰해줘"
• "[주제]에 대해 질문해줘"
• "요구사항 정리해줘"
• "스펙 작성 도와줘"

Interview Best Practices

1. Ask Non-Obvious Questions

Bad Questions:

• "Should this be secure?" (always yes)
• "Do you want good performance?" (too vague)
• "Should we use best practices?" (meaningless)

Good Questions:

• "When two users edit the same item simultaneously, should the last write win, or should we detect conflicts?"
• "If the external API is down, should we queue requests or fail immediately with an error?"
• "Would you prioritize a more flexible architecture that takes longer to build, or a simpler implementation that ships faster but is harder to extend later?"

2. Present Real Trade-offs

Bad Options:

• Option A: Fast, secure, scalable (obviously good)
• Option B: Slow, insecure, doesn't scale (obviously bad)

Good Options:

• Option A: Server-side rendering (better SEO, slower interactivity)
• Option B: Client-side rendering (faster interactivity, SEO challenges)
• Option C: Hybrid approach (best of both, more complexity)

3. Dig Deeper on Vague Answers

If user says:

• "Make it fast" → Ask: "Fast for what? Page load? API response? Complex queries?"
• "Standard security" → Ask: "OAuth? JWT? Session cookies? Rate limiting rules?"
• "Good UX" → Ask: "What happens when they click X? How do they recover from errors?"

4. Validate Assumptions

If user says something concerning:

• "We'll handle millions of users" → Ask: "How many concurrent users? What's the traffic pattern?"
• "It needs to be real-time" → Ask: "Real-time as in WebSockets, or polling every 5 seconds is fine?"

5. Know When to Stop

Stop when:

• Diminishing returns (trivial details)
• User is frustrated or repeating
• Core requirements are clear
• You have enough to write a useful spec

Don't stop when:

• Critical decisions are unclear
• User hasn't thought about edge cases
• Security/privacy concerns unaddressed

Quick Reference

When to Use

✅ Use this skill when:

• User wants to build something but hasn't fully thought through requirements
• User says "help me spec this" or "interview me about X"
• Complex feature needs thorough planning
• User prefers interactive Q&A over writing a doc themselves

❌ Skip when:

• User has already written detailed requirements (just review instead)
• User wants to start coding immediately (respect their preference)
• Very simple, well-defined task (1-2 questions max, not a full interview)

Error Handling

Examples

Example 1: Simple Feature

User: "Interview me about adding a dark mode feature"

Round 1:
Q1: How should users toggle dark mode?
Q2: Should the preference persist across sessions?
Q3: Should it respect system preferences?

Round 2:
Q1: What about images that look bad in dark mode?
Q2: Should third-party embeds (YouTube, etc.) also be dark?

→ Stop here (simple feature, enough detail)

Generate spec: 5-page document covering implementation

Example 2: Complex Project

User: "I want to build a real-time collaboration tool, interview me"

Round 1: Core functionality, main use cases
Round 2: Real-time sync approach, conflict resolution
Round 3: Permissions, security, data privacy
Round 4: Scalability, performance under load
Round 5: Edge cases, offline mode, error recovery
Round 6: Testing, deployment, monitoring

→ Stop here (complex project fully explored)

Generate spec: 20-page comprehensive document

Example 3: Focused Interview

User: "Interview me about improving our API rate limiting"

Round 1: Current problems, desired behavior
Round 2: Rate limit rules, per-user vs global
Round 3: How to handle violations, error messages
Round 4: Monitoring, alerting, bypass for admins

→ Stop here (focused topic, thorough coverage)

Generate spec: 8-page technical design

Related Skills

• learning-summary: For documenting the interview process itself
• project-insight: For analyzing existing codebase before planning new features
• planning-interview v2.0: Unified planning flow (PRD → User Journey → Tech Spec → Wireframe). Use spec-interview when you only need a technical spec without product planning context. Use planning-interview Phase 3 when you want the spec to reference PRD personas and features.

Tips

1. Build trust early: Start with easier questions to get user comfortable
2. Rotate categories: Don't ask 10 technical questions in a row
3. Use user's answers: Reference their previous answers in follow-up questions
4. Educate through options: Option descriptions can teach trade-offs
5. Flag disagreements: If their answers contradict, ask them to clarify
6. Preserve exact quotes: Use their words in the spec for clarity
7. Visual diagrams: Ask if they want to sketch flows (can describe verbally)
8. Celebrate completeness: When you have what you need, tell them!

Configuration

No configuration file needed. Saves to current directory by default or prompts user for location.

Advanced Usage

Batch Interview

User can interview for multiple features:

"Interview me about: 1) user authentication, 2) file uploads, 3) notifications"

Handle by:

• Interview each separately
• Generate separate specs
• Note dependencies between features

Resume Interview

If interrupted, user can say:

"Continue the interview about [topic]"

Read the partial spec and continue from where it left off.

Collaborative Spec

Multiple stakeholders:

"Interview me and my co-founder about our app"

Tag answers by person, note disagreements, highlight consensus decisions.