1---2name: spec-interview3description: Interviews users to build project specs through guided discovery. Use when starting a new project or feature.4---56<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.89The goal is to surface hidden assumptions and force decisions BEFORE implementation begins.10</objective>1112<essential_principles>1314<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>2223<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>2627<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>3233<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>3637</essential_principles>3839<quick_start>401. Check if SPEC.md exists and read it412. Identify gaps, ambiguities, and untested assumptions423. Begin interviewing using AskUserQuestionTool434. Cover ALL domains systematically (see question_domains)445. Write completed spec to SPEC.md45</quick_start>4647<process>4849<step name="1_load_context">50**Read existing spec if present:**51```52Read SPEC.md (or specified file path)53```5455If 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>5859<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>6566<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.6869**CRITICAL**: Each question must:70- Be specific to THIS project (not generic)71- Surface a decision or assumption72- Have meaningful, distinct options73- Force the user to commit to something74</step>7576<step name="4_gap_detection">77After each answer round, identify:78- New questions raised by the answer79- Contradictions with earlier answers80- Areas where user seemed uncertain8182Probe these immediately before moving on.83</step>8485<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 decisions893. Mark any remaining open questions explicitly904. Write to SPEC.md (or user-specified path)91</step>9293</process>9495<question_domains>9697<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>105106<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>113114<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 technical debt are you knowingly taking on?122</domain>123124<domain name="integration_and_dependencies">125**Map the system boundaries:**126- What external systems does this touch? (APIs, databases, services)127- What happens when dependency X is down?128- Who owns the integration contracts? How do they change?129- What data flows in and out? What's the format/protocol?130- Are there rate limits, quotas, or cost implications?131</domain>132133<domain name="ui_and_ux">134**Get specific about user experience:**135- Walk through the primary user journey step-by-step136- What's the first thing a new user sees/does?137- How does the user recover from mistakes?138- What feedback does the user get at each step?139- What's the mobile/responsive story?140- How does this look with 0 items? 1 item? 1000 items?141</domain>142143<domain name="error_states_and_edge_cases">144**Surface failure modes:**145- What happens when network fails mid-operation?146- What if the user does X twice rapidly?147- What if data is malformed or missing fields?148- What's the worst thing that could happen? How do we prevent it?149- What does partial failure look like? (3 of 5 items succeed)150- How do users know something went wrong?151</domain>152153<domain name="security_and_privacy">154**Force security decisions:**155- What data is sensitive? What's the classification?156- Who can see/edit/delete what? (permission model)157- How is authentication handled? (existing system? new?)158- What audit trail is required?159- What compliance requirements exist? (GDPR, SOC2, HIPAA)160</domain>161162<domain name="performance_and_reliability">163**Establish non-functional requirements:**164- What response times are acceptable? (p50, p95, p99)165- What's the availability target? (99%, 99.9%, 99.99%)166- What's the expected load? (requests/sec, concurrent users)167- What happens under load? (graceful degradation vs. hard failure)168</domain>169170<domain name="operations_and_maintenance">171**Think about day 2:**172- How will this be monitored? What alerts exist?173- How do you debug when something goes wrong?174- What does deployment look like? (CI/CD, manual, hybrid)175- What's the rollback plan?176</domain>177178<domain name="testing_and_quality">179**Define quality gates:**180- What must be tested? (unit, integration, e2e)181- What's the test data strategy?182- How do you test integrations with external systems?183- What's the acceptance criteria for "done"?184</domain>185186<domain name="verification_environment">187**Gather runtime verification info (critical for Ralph autonomous execution):**188- What's the tech stack? (framework, language, package manager)189- How do you start the dev server? What port does it run on?190- What database is used? How do you connect and query it directly?191- What test frameworks are set up? (Jest, Pytest, Playwright, Cypress, etc.)192- Are there existing e2e tests? What runner and how to execute them?193- What's the typecheck command? Lint command? Build command?194- What ORM/migration tool is used? (Prisma, Alembic, Drizzle, etc.)195</domain>196197</question_domains>198199<interview_techniques>200201<technique name="probing_vague_answers">202When user says "it depends" or "we'll figure it out later":203- "What specifically does it depend on?"204- "What would need to be true for option A vs. option B?"205- "If you had to decide RIGHT NOW, which way would you lean?"206</technique>207208<technique name="revealing_assumptions">209When user says something confidently:210- "What would change if [assumption] turned out to be wrong?"211- "How would you verify that [assumption] is true before building?"212</technique>213214<technique name="forcing_priorities">215When everything seems important:216- "If you could only ship ONE of these, which one?"217- "What would you cut if timeline was halved?"218</technique>219220</interview_techniques>221222<success_criteria>223Interview is complete when:224- [ ] All domains have been covered with project-specific questions225- [ ] User has made explicit decisions on all tradeoffs226- [ ] No "TBD" or "we'll figure it out" remains in critical areas227- [ ] Edge cases and failure modes have concrete handling strategies228- [ ] The spec could be handed to a developer who would know what to build229- [ ] User confirms "this is complete enough to start building"230</success_criteria>231232<spec_template_location>233See `templates/spec-template.md` for the output structure.234</spec_template_location>
shir-bruchim