spec-interview

name	spec-interview
description	Interviews users to build project specs through guided discovery. Use when starting a new project or feature.
context	fork

Build 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.

The goal is to surface hidden assumptions and force decisions BEFORE implementation begins.

<essential_principles>

Never ask questions the user has already answered or could trivially answer. Dig into: - What happens when X fails? - How does this interact with Y? - What's the migration path from current state? - Who's responsible when Z goes wrong? - What does success look like in 6 months? Start 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. Don't let users have everything. Force explicit tradeoffs: - "You mentioned both X and Y. These conflict because... which matters more?" - "This approach optimizes for A but sacrifices B. Is that acceptable?" Continue interviewing until EVERY section of the spec template has concrete answers. Vague sections = more questions. Only stop when the spec is implementation-ready.

</essential_principles>

<quick_start>

1. Check if SPEC.md exists and read it
2. Identify gaps, ambiguities, and untested assumptions
3. Begin interviewing using AskUserQuestionTool
4. Cover ALL domains systematically (see question_domains)
5. Write completed spec to SPEC.md </quick_start>

**Read existing spec if present:** ``` Read SPEC.md (or specified file path) ```

If exists: Analyze what's defined vs. what's missing or vague. If not: Start fresh, but ask about existing context (related systems, constraints, prior art).

Before diving deep, establish scope with 2-3 broad questions: - What problem are you solving and for whom? - What's the minimal viable version vs. the full vision? - What constraints exist (time, tech stack, team, budget)? **Interview through ALL domains below.** Use AskUserQuestionTool with 2-4 targeted questions per round. Mix domains to keep conversation dynamic.

CRITICAL: Each question must:

• Be specific to THIS project (not generic)
• Surface a decision or assumption
• Have meaningful, distinct options
• Force the user to commit to something

After each answer round, identify: - New questions raised by the answer - Contradictions with earlier answers - Areas where user seemed uncertain

Probe these immediately before moving on.

When all domains are covered and no ambiguities remain: 1. Use the template in `templates/spec-template.md` 2. Fill every section with concrete decisions 3. Mark any remaining open questions explicitly 4. Write to SPEC.md (or user-specified path)

<question_domains>

**Surface hidden assumptions about the problem:** - What's the actual pain point? (not the solution they've imagined) - Who are the real users? (roles, technical level, frequency of use) - What do users do TODAY without this? (current workarounds) - What would make users NOT use this? (adoption blockers) - How will you know if this succeeded? (measurable outcomes) **Force explicit scope decisions:** - What's explicitly OUT of scope? (as important as what's in) - What's the MVP vs. v2 vs. "nice to have someday"? - What adjacent problems are you intentionally NOT solving? - What happens if scope must be cut by 50%? What survives? **Probe technical decisions and their implications:** - What's the data model? What are the core entities and relationships? - Where does state live? (client, server, database, cache) - What's the source of truth for X? (when there's duplication) - How does this scale? (10x users, 100x data, distributed team) - What's the deployment model? (self-hosted, SaaS, hybrid) - What technical debt are you knowingly taking on? **Map the system boundaries:** - What external systems does this touch? (APIs, databases, services) - What happens when dependency X is down? - Who owns the integration contracts? How do they change? - What data flows in and out? What's the format/protocol? - Are there rate limits, quotas, or cost implications? **Get specific about user experience:** - Walk through the primary user journey step-by-step - What's the first thing a new user sees/does? - How does the user recover from mistakes? - What feedback does the user get at each step? - What's the mobile/responsive story? - How does this look with 0 items? 1 item? 1000 items? **Surface failure modes:** - What happens when network fails mid-operation? - What if the user does X twice rapidly? - What if data is malformed or missing fields? - What's the worst thing that could happen? How do we prevent it? - What does partial failure look like? (3 of 5 items succeed) - How do users know something went wrong? **Force security decisions:** - What data is sensitive? What's the classification? - Who can see/edit/delete what? (permission model) - How is authentication handled? (existing system? new?) - What audit trail is required? - What compliance requirements exist? (GDPR, SOC2, HIPAA) **Establish non-functional requirements:** - What response times are acceptable? (p50, p95, p99) - What's the availability target? (99%, 99.9%, 99.99%) - What's the expected load? (requests/sec, concurrent users) - What happens under load? (graceful degradation vs. hard failure) **Think about day 2:** - How will this be monitored? What alerts exist? - How do you debug when something goes wrong? - What does deployment look like? (CI/CD, manual, hybrid) - What's the rollback plan? **Define quality gates:** - What must be tested? (unit, integration, e2e) - What's the test data strategy? - How do you test integrations with external systems? - What's the acceptance criteria for "done"? **Gather runtime verification info (critical for Ralph autonomous execution):** - What's the tech stack? (framework, language, package manager) - How do you start the dev server? What port does it run on? - What database is used? How do you connect and query it directly? - What test frameworks are set up? (Jest, Pytest, Playwright, Cypress, etc.) - Are there existing e2e tests? What runner and how to execute them? - What's the typecheck command? Lint command? Build command? - What ORM/migration tool is used? (Prisma, Alembic, Drizzle, etc.)

</question_domains>

<interview_techniques>

When user says "it depends" or "we'll figure it out later": - "What specifically does it depend on?" - "What would need to be true for option A vs. option B?" - "If you had to decide RIGHT NOW, which way would you lean?" When user says something confidently: - "What would change if [assumption] turned out to be wrong?" - "How would you verify that [assumption] is true before building?" When everything seems important: - "If you could only ship ONE of these, which one?" - "What would you cut if timeline was halved?"

</interview_techniques>

<success_criteria> Interview is complete when:

• All domains have been covered with project-specific questions
• User has made explicit decisions on all tradeoffs
• No "TBD" or "we'll figure it out" remains in critical areas
• Edge cases and failure modes have concrete handling strategies
• The spec could be handed to a developer who would know what to build
• User confirms "this is complete enough to start building" </success_criteria>

<spec_template_location> See templates/spec-template.md for the output structure. </spec_template_location>