1---2name: spec-interview-23description: Interviews users to build comprehensive project specifications. Use when starting a new project, feature, or when user needs help defining requirements through guided discovery.4---5
6<objective>
7Build complete, production-ready specifications through deep, systematic interviewing. Read existing SPEC.md if present, then probe the user about every aspect they haven't fully thought through: architecture decisions, edge cases, error states, UX flows, security concerns, performance tradeoffs, integration points, and failure modes.
8
9The goal is to surface hidden assumptions and force decisions BEFORE implementation begins.
10</objective>
11
12<essential_principles>
13
14<principle name="non_obvious_questions">
15Never ask questions the user has already answered or could trivially answer. Dig into:
16- What happens when X fails?
17- How does this interact with Y?
18- What's the migration path from current state?
19- Who's responsible when Z goes wrong?
20- What does success look like in 6 months?
21</principle>
22
23<principle name="progressive_depth">
24Start broad, then drill into areas of uncertainty. When user gives vague answers, probe deeper. When they're confident, move on. Detect hesitation and explore it.
25</principle>
26
27<principle name="tradeoff_forcing">
28Don't let users have everything. Force explicit tradeoffs:
29- "You mentioned both X and Y. These conflict because... which matters more?"
30- "This approach optimizes for A but sacrifices B. Is that acceptable?"
31</principle>
32
33<principle name="completeness_over_speed">
34Continue interviewing until EVERY section of the spec template has concrete answers. Vague sections = more questions. Only stop when the spec is implementation-ready.
35</principle>
36
37</essential_principles>
38
39<quick_start>
401. Check if SPEC.md exists and read it
412. Identify gaps, ambiguities, and untested assumptions
423. Begin interviewing using AskUserQuestionTool
434. Cover ALL domains systematically (see question_domains)
445. Write completed spec to SPEC.md
45</quick_start>
46
47<process>
48
49<step name="1_load_context">
50**Read existing spec if present:**
51```
52Read SPEC.md (or specified file path)
53```
54
55If exists: Analyze what's defined vs. what's missing or vague.
56If not: Start fresh, but ask about existing context (related systems, constraints, prior art).
57</step>
58
59<step name="2_initial_assessment">
60Before diving deep, establish scope with 2-3 broad questions:
61- What problem are you solving and for whom?
62- What's the minimal viable version vs. the full vision?
63- What constraints exist (time, tech stack, team, budget)?
64</step>
65
66<step name="3_systematic_interview">
67**Interview through ALL domains below.** Use AskUserQuestionTool with 2-4 targeted questions per round. Mix domains to keep conversation dynamic.
68
69**CRITICAL**: Each question must:
70- Be specific to THIS project (not generic)
71- Surface a decision or assumption
72- Have meaningful, distinct options
73- Force the user to commit to something
74</step>
75
76<step name="4_gap_detection">
77After each answer round, identify:
78- New questions raised by the answer
79- Contradictions with earlier answers
80- Areas where user seemed uncertain
81
82Probe these immediately before moving on.
83</step>
84
85<step name="5_write_spec">
86When all domains are covered and no ambiguities remain:
871. Use the template in `templates/spec-template.md`
882. Fill every section with concrete decisions
893. Mark any remaining open questions explicitly
904. Write to SPEC.md (or user-specified path)
91</step>
92
93</process>
94
95<question_domains>
96
97<domain name="problem_and_users">
98**Surface hidden assumptions about the problem:**
99- What's the actual pain point? (not the solution they've imagined)
100- Who are the real users? (roles, technical level, frequency of use)
101- What do users do TODAY without this? (current workarounds)
102- What would make users NOT use this? (adoption blockers)
103- How will you know if this succeeded? (measurable outcomes)
104</domain>
105
106<domain name="scope_and_boundaries">
107**Force explicit scope decisions:**
108- What's explicitly OUT of scope? (as important as what's in)
109- What's the MVP vs. v2 vs. "nice to have someday"?
110- What adjacent problems are you intentionally NOT solving?
111- What happens if scope must be cut by 50%? What survives?
112</domain>
113
114<domain name="architecture_and_technical">
115**Probe technical decisions and their implications:**
116- What's the data model? What are the core entities and relationships?
117- Where does state live? (client, server, database, cache)
118- What's the source of truth for X? (when there's duplication)
119- How does this scale? (10x users, 100x data, distributed team)
120- What's the deployment model? (self-hosted, SaaS, hybrid)
121- What's the upgrade/migration path from v1 to v2?
122- What technical debt are you knowingly taking on?
123</domain>
124
125<domain name="integration_and_dependencies">
126**Map the system boundaries:**
127- What external systems does this touch? (APIs, databases, services)
128- What happens when dependency X is down?
129- Who owns the integration contracts? How do they change?
130- What data flows in and out? What's the format/protocol?
131- Are there rate limits, quotas, or cost implications?
132</domain>
133
134<domain name="ui_and_ux">
135**Get specific about user experience:**
136- Walk through the primary user journey step-by-step
137- What's the first thing a new user sees/does?
138- How does the user recover from mistakes?
139- What feedback does the user get at each step?
140- What's the mobile/responsive story?
141- What accessibility requirements exist?
142- How does this look with 0 items? 1 item? 1000 items?
143</domain>
144
145<domain name="error_states_and_edge_cases">
146**Surface failure modes:**
147- What happens when network fails mid-operation?
148- What if the user does X twice rapidly?
149- What if data is malformed or missing fields?
150- What's the worst thing that could happen? How do we prevent it?
151- What does partial failure look like? (3 of 5 items succeed)
152- How do users know something went wrong?
153- What's the retry/recovery mechanism?
154</domain>
155
156<domain name="security_and_privacy">
157**Force security decisions:**
158- What data is sensitive? What's the classification?
159- Who can see/edit/delete what? (permission model)
160- How is authentication handled? (existing system? new?)
161- What audit trail is required?
162- What compliance requirements exist? (GDPR, SOC2, HIPAA)
163- What happens to data when user/account is deleted?
164</domain>
165
166<domain name="performance_and_reliability">
167**Establish non-functional requirements:**
168- What response times are acceptable? (p50, p95, p99)
169- What's the availability target? (99%, 99.9%, 99.99%)
170- What's the expected load? (requests/sec, concurrent users)
171- What happens under load? (graceful degradation vs. hard failure)
172- What's the data retention policy?
173- What's the backup/recovery strategy?
174</domain>
175
176<domain name="operations_and_maintenance">
177**Think about day 2:**
178- How will this be monitored? What alerts exist?
179- How do you debug when something goes wrong?
180- What does deployment look like? (CI/CD, manual, hybrid)
181- Who's on-call? What's the escalation path?
182- How is configuration managed? (env vars, config files, admin UI)
183- What's the rollback plan?
184</domain>
185
186<domain name="testing_and_quality">
187**Define quality gates:**
188- What must be tested? (unit, integration, e2e)
189- What's the test data strategy?
190- How do you test integrations with external systems?
191- What's the acceptance criteria for "done"?
192- Who approves releases?
193</domain>
194
195<domain name="timeline_and_phases">
196**Reality-check the plan:**
197- What's driving the timeline? (hard deadline, soft goal, ASAP)
198- What's the phased rollout plan?
199- What's the feature flag strategy?
200- What can be parallelized? What's serial?
201- What are the riskiest parts that need prototyping?
202</domain>
203
204</question_domains>
205
206<interview_techniques>
207
208<technique name="probing_vague_answers">
209When user says "it depends" or "we'll figure it out later":
210- "What specifically does it depend on?"
211- "What would need to be true for option A vs. option B?"
212- "If you had to decide RIGHT NOW, which way would you lean?"
213</technique>
214
215<technique name="revealing_assumptions">
216When user says something confidently:
217- "What would change if [assumption] turned out to be wrong?"
218- "How would you verify that [assumption] is true before building?"
219- "Have you seen this work elsewhere? What was different?"
220</technique>
221
222<technique name="forcing_priorities">
223When everything seems important:
224- "If you could only ship ONE of these, which one?"
225- "What would you cut if timeline was halved?"
226- "Which of these would you be embarrassed NOT to have?"
227</technique>
228
229<technique name="exploring_conflict">
230When two answers seem incompatible:
231- "Earlier you said X, but this suggests Y. How do these reconcile?"
232- "This creates a tradeoff between A and B. Where do you land?"
233</technique>
234
235</interview_techniques>
236
237<success_criteria>
238Interview is complete when:
239- [ ] All domains have been covered with project-specific questions
240- [ ] User has made explicit decisions on all tradeoffs
241- [ ] No "TBD" or "we'll figure it out" remains in critical areas
242- [ ] Edge cases and failure modes have concrete handling strategies
243- [ ] The spec could be handed to a developer who would know what to build
244- [ ] User confirms "this is complete enough to start building"
245</success_criteria>
246
247<spec_template_location>
248See `templates/spec-template.md` for the output structure.
249</spec_template_location>
majiayu000