Spec Interview - Claude Code skill for turning rough ideas into comprehensive technical specifications through deep interviewing

SKILL.md

name

description

spec-interview

Conduct deep technical interviews to create comprehensive specifications. Use when the user has a feature idea (sentence, paragraph, or reference link) and wants to flesh it out into a complete SPEC.md. Triggers on "spec interview", "interview me about", "help me spec out", "create a spec for", or when user provides a rough idea and wants thorough requirements gathering. This skill asks non-obvious, in-depth questions and continues until the specification is complete.

Spec Interview

Transform rough ideas into comprehensive technical specifications through deep, iterative interviewing.

When to Use

• User has a vague idea: "I want to build an activity log plugin"
• User has a reference: "Build something like [link]"
• User has a rough SPEC that needs fleshing out
• Before starting Ralph-style autonomous development

Interview Philosophy

Ask non-obvious questions. Don't ask things you could figure out or that have obvious answers. Focus on:

• Decisions that require human judgment
• Tradeoffs the user needs to weigh
• Edge cases and concerns
• Things that would block implementation if unknown

Go deep, not wide. Better to thoroughly explore one area than superficially cover everything.

Continue until complete. Don't stop after a few questions. Keep interviewing until the spec is genuinely ready for implementation.

Interview Process

Phase 1: Understand the Core

Start by understanding the basic idea. If user provided:

• Just an idea: Ask what problem they're solving and for whom
• A reference/link: Fetch and analyze it, then ask what aspects they want to adopt/change
• Existing rough spec: Read it, identify gaps

Phase 2: Deep Dive Questions

Use the AskUserQuestion tool for structured input. Ask about:

Technical Implementation

• Architecture decisions with real tradeoffs
• Database design choices
• Performance considerations at scale
• Security implications
• Integration points

User Experience

• User flows that aren't obvious
• Edge cases in the UI
• Error states and recovery
• Accessibility requirements

Business & Scope

• What's explicitly OUT of scope (non-goals)
• Prioritization when tradeoffs exist
• Free vs paid feature splits (if applicable)
• Success metrics

Concerns & Risks

• What could go wrong
• Dependencies on external systems
• Maintenance burden
• Migration/upgrade paths

Phase 3: Iterate Until Complete

After each round of answers:

1. Identify what's still unclear or has gaps
2. Ask follow-up questions on those areas
3. Don't move on until an area is solid

Signs you're NOT done:

• Implementation details are still vague
• User stories lack clear acceptance criteria
• Technical approach hasn't been decided
• Edge cases haven't been addressed

Phase 4: Write the Spec

Once interviewing is complete, write a comprehensive SPEC.md with:

# {Project Name} - Technical Specification

## Overview
What this is and why it exists.

## Goals
Primary and secondary objectives.

## Non-Goals
What this explicitly will NOT do.

## User Stories
Each with acceptance criteria that are specific and verifiable.

## Technical Architecture
- Database schema
- File structure
- Key classes/components
- Integration points

## User Interface
- Admin pages/screens
- User-facing elements
- Key user flows

## Security Considerations
Authentication, authorization, data protection.

## Performance Requirements
Scale targets, optimization strategies.

## Implementation Phases
Ordered list of what to build first, second, etc.

## Testing Requirements
What needs to be tested and how.

## Open Questions
Anything still unresolved (should be minimal).

Question Guidelines

Good questions (non-obvious, require thought):

• "For high-traffic sites generating thousands of events/hour, should logging be synchronous or queued? Each has tradeoffs..."
• "If both free and pro versions exist, what's the upgrade path - replace plugin or license unlock?"
• "Should the plugin track its own activity (admin viewed logs, exported data)?"

Bad questions (obvious, don't ask):

• "Should we use secure coding practices?" (obviously yes)
• "Do you want it to work?" (obviously yes)
• "Should errors be handled?" (obviously yes)

Output

Save the completed specification to SPEC.md in the project root (or update existing file).

After Completion

Break the spec into phases that can be individually tested and verified before moving on to the next phase.