This skill should be used when the user has an idea for an application and wants to develop it into a complete specification. Activated when the user asks to "turn my idea into a spec", "help me spec out my app", "I have an idea for an app", "idea to specification", "spec from scratch", "flesh out my idea", "help me define my app", "plan out my application", "brainstorm my app idea", "what would I need to specify", or wants to go from a rough concept to a detailed, technology-agnostic specification document set.
From project-docsnpx claudepluginhub ichabodcole/project-docs-scaffold-template --plugin project-docsThis skill uses the workspace's default tool permissions.
references/interview-guide.mdFetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Retrieves current documentation, API references, and code examples for libraries, frameworks, SDKs, CLIs, and services via Context7 CLI. Ideal for API syntax, configs, migrations, and setup queries.
Uses ctx7 CLI to fetch current library docs, manage AI coding skills (install/search/generate), and configure Context7 MCP for AI editors.
Transform a rough application idea into a complete set of technology-agnostic
specification documents through structured, iterative interviews. The goal is to
progressively detail every domain of the application until the specification is
comprehensive enough to hand off to the implementation-blueprint skill or
directly to a developer.
The output follows the same specification format produced by the generate-spec
skill, ensuring consistency across the plugin's workflow: idea → spec →
blueprint → build.
Track specification completeness as a percentage throughout the process. Display this at the start of each interview round:
Specification Progress: [████████░░░░░░░░░░░░] 40%
Divide the specification into weighted domains. Each domain contributes to the total based on its complexity weight. A domain is "complete" when its core entities, rules, states, and edge cases are documented.
| Domain Category | Weight | Examples |
|---|---|---|
| Core data model | 25% | Entities, relationships, field definitions |
| User interface | 20% | Screens, navigation, component inventory |
| Business logic | 20% | Rules, calculations, state machines |
| User flows | 15% | Journeys, interactions, session lifecycle |
| System behavior | 10% | Audio, notifications, background tasks |
| Edge cases & errors | 10% | Validation, empty states, error handling |
Update the percentage after each round based on what has been covered. The progression is not linear - early rounds cover more ground at a surface level, later rounds fill in depth.
| Round | Expected Progress | Focus |
|---|---|---|
| 1 | 0% → 15% | Core concept and scope |
| 2 | 15% → 35% | Data model and entities |
| 3 | 35% → 55% | Screens and user flows |
| 4 | 55% → 70% | Business logic and rules |
| 5 | 70% → 85% | System behavior and integrations |
| 6 | 85% → 95% | Edge cases and polish |
| 7+ | 95% → 100% | Review, gaps, and sign-off |
Each round below lists key questions. For expanded question banks organized by domain, read references/interview-guide.md.
Start by understanding the idea at a high level. Ask the user to describe their app in a few sentences, then ask focused follow-ups.
Questions to cover:
After Round 1, produce:
Present the summary and domain list to the user for confirmation before proceeding. This is the foundation everything else builds on - correct misunderstandings here.
Identify every entity the application needs to store or manage.
Questions to cover:
After Round 2, produce:
Map out what the user sees and does.
Questions to cover:
After Round 3, produce:
Define how the application behaves.
Questions to cover:
After Round 4, produce:
Cover the non-UI aspects of the application.
Questions to cover (conditionally relevant):
Skip questions that don't apply based on what was learned in earlier rounds.
After Round 5, produce:
Fill gaps and handle the unexpected.
Questions to cover:
After Round 6, produce:
Review the complete specification set for gaps.
Process:
Completion criteria:
Write specification files to docs/specifications/ (or user-specified location)
using the same structure and conventions as the generate-spec skill:
For spec writing templates and conventions, read
../generate-spec/references/spec-writing-guide.md.
Choose the appropriate structure based on complexity discovered during interviews:
Simple apps (≤8 spec files): Flat structure with numbered files.
Medium apps (9-15 spec files): Group related specs into subdirectories by domain.
Complex apps (15+ spec files or multi-app): Subdirectories per app or major subsystem.
| Interview Round | Typical Spec File(s) |
|---|---|
| Round 1: Elevator Pitch | 01-overview.md |
| Round 2: Data Model | XX-data-management.md, entity-specific specs |
| Round 3: Screens & Flows | XX-user-interface.md |
| Round 4: Business Logic | Entity-specific specs (e.g., XX-timers.md, XX-sessions.md) |
| Round 5: System Behavior | Domain specs (e.g., XX-audio.md, XX-notifications.md) |
| Round 6: Edge Cases | Distributed across all relevant spec files |
| Round 7: Review | Updates across all files, XX-settings.md if not yet written |
Number files in a logical reading order: overview first, then data entities, then systems, then UI, then cross-cutting concerns (statistics, settings).
Start Round 1 with even broader questions: "What kind of app is this?" (productivity, game, social, tool, etc.). Use analogies: "Is it more like a todo app, a journal, or a dashboard?" Narrow down before proceeding.
If the user jumps to implementation details ("I want it in React with Tailwind"), acknowledge the preference, note it for the blueprint phase, and redirect: "Great, we'll capture that when we get to the implementation blueprint. For now, let's focus on what the app does, not how it's built."
If new features keep emerging, maintain a "Future Enhancements" section. Gently ask: "Is this needed for the first version, or is it a future addition?" Keep the core spec focused.
If the idea targets multiple platforms (web + mobile, etc.), treat platform-specific behavior as a cross-cutting concern. Write one unified specification set with platform-specific callouts where behavior diverges (e.g., "On mobile: bottom navigation. On desktop: sidebar navigation."). Do not duplicate entire spec files per platform.
The percentage is an estimate. If the user feels it should be higher or lower, adjust. The purpose is shared understanding of how much work remains, not precision.
For detailed guidance on conducting effective specification interviews: