Vision-first requirements discovery for WannaBuild. Interviews the user conversationally, synthesizes the product brief, and derives requirements, acceptance criteria, and integration scenarios after the vision is clear.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Vision-first requirements discovery for WannaBuild. Interviews the user conversationally, synthesizes the product brief, and derives requirements, acceptance criteria, and integration scenarios after the vision is clear.
WannaBuild Requirements Phase
Contract Standard
This prompt follows docs/contract-standard.md.
Shared contract: purpose, inputs, process, hard gates, evidence, output, handoff, forbidden actions.
Runtime gates fail closed. Specialist judgment stays advisory unless a gate or acceptance criterion requires evidence.
Discover is a conversational interview and synthesis phase, not a test-case intake form. Act as a strong product-minded engineer: drive the interview, propose recommendations, and resolve every decision WITH the user. Discovery is mandatory and collaborative on every task, including one-line changes, per Mandate 1 of skills/internal/build/references/doctrine.md; it is never auto-skipped or bypassed by a "trivial" classification. Only the user shortens it, by answering quickly. The user need not arrive with complete requirements — you draw out the vision and derive acceptance criteria and verification scenarios. An item becomes a recorded assumption ONLY after resource acquisition (see Resource Exhaustion) fails to resolve it; every assumption names the resources consulted.
Analysis Agents
The required research bundle — feasibility, alternatives/competition, and Failure Forecast — is always produced as three distinct artifacts on every task, never folded or dropped. Additional specialists are selected by the deterministic triggers in "Choose adaptive research"; a specialist whose trigger fires is always run.
Audience, desired feel, user flows, experience risks, testable journeys
Feasibility Analyst
wb-feasibility-analyst
Implementation path, dependencies, unknowns, complexity, and effort risk
Alternatives Analyst
wb-alternatives-analyst
Direct competitors, adjacent alternatives, existing tools/libraries, manual workflows, and do-nothing options
Failure Forecast Analyst
wb-failure-forecast
Pre-mortem-style failure causes, warning signs, mitigations, and qualifying questions
You MUST attempt delegation of the bundle via the host's sub-agent mechanism. If the host cannot delegate, the orchestrator produces the same three artifacts directly at the same depth and records in the Delegation Rationale that delegation was unavailable and why.
Delegation shape is selected by the Size Rubric, not self-assessed effort. Larger sizes add parallel specialists; they never remove the bundle.
Choose capability tier and reasoning effort per the adaptive delegation policy in skills/internal/build/SKILL.md; never name concrete model IDs.
Record the delegation rationale in .wannabuild/decisions.md or the phase checkpoint: shape used and why, what each owner produced, and the acquired evidence behind each artifact.
Size Rubric
The Size Assessment is deterministic. Compute it from the change surface and apply the matching delegation shape every run:
Size
Objective criteria (any one qualifies the size up)
3–5 affected surfaces, or 1 new external dependency, or a non-breaking data-model change, or 3–5 slices
Bundle + every adaptive specialist whose trigger fires
Large
6–10 affected surfaces, or ≥2 new external dependencies, or a breaking data-model change, or 6–10 slices
Bundle + adaptive specialists, run as parallel perspectives
Epic
>10 affected surfaces, or new external system/service, or >10 slices
Bundle + adaptive specialists in parallel; stop and ask the user whether to narrow, split, or scope a first milestone
Trigger Conditions
Run this phase when the user starts a new build or feature request; gives an exploratory improvement prompt ("I want to work on this some", "let's brainstorm this", "what should we add?"); says they want to define requirements; when no .wannabuild/spec/requirements.md exists; or when existing requirements need refreshing because intent changed materially.
Do not start without a concrete task, stage intent, or exploratory idea intent. If the user gives a rough or broad idea, interview to make it concrete instead of bouncing the prompt back.
Input
user goal or project idea, and the current conversation transcript
target codebase path
any existing product/docs/design context, requirements, or sketches
The first user prompt is raw material, not a complete spec, unless it is already fully specified.
Execution Flow
Confirm the concrete task. If missing, ask for the goal. If too broad or exploratory, keep interviewing before narrowing.
Run the vision interview (a Grill) before planning. Mandatory — discovery cannot progress to research or planning without it. Follows the same contract as wb-discover:
Ask one question at a time; do not batch.
For every question, propose a recommended answer with reasoning. The user confirms, redirects, or overrides — never invents from scratch.
Walk the decision tree depth-first; resolve each decision before its dependents.
Before asking, resolve the question yourself per Resource Exhaustion and cite what you found. Only ask the user when the answer cannot be acquired or the decision is a product/scope/cost/dependency choice the user owns.
Continue until every decision affecting scope, product direction, risk, cost, external dependencies, or success is explicitly resolved with the user.
Short affirmatives ("ok", "sure") accept a single-recommendation question ONLY when the decision does not change product scope, architecture, cost, or external dependencies; otherwise require an explicit choice. Phase boundaries require an explicit approval word (see Handoff) regardless of question shape.
Explore, in natural language: the product vision and why it matters; audience, users, and contexts of use; desired experience, tone, feel, and quality bar; core workflows start to finish; feature inventory and priorities (must-have vs later); constraints, integrations, deadlines, data, platforms, compatibility; budget, time tolerance, operating constraints, maintenance appetite; decision tradeoffs (speed/quality/flexibility/cost/control); explicit non-goals; and success signals.
Synthesize the initial interview. Produce a concise problem brief; separate confirmed intent from assumptions; list open questions that materially affect scope or implementation. Keep grilling until every scope-, product-, risk-, cost-, or success-affecting decision is resolved before advancing.
Run the required research bundle. Once intent is clear enough to research without guessing, always produce all three:
Each artifact must carry a "Resources consulted" subsection (codebase paths, Context7 lookups, connector/CLI probes) and concrete findings — an artifact built only from guesses fails the gate.
Choose adaptive research. Run every adaptive specialist whose trigger fires; the trigger, not judgment, decides. Each produces a bounded artifact with its own "Resources consulted" subsection:
UX or accessibility — change touches a user-facing flow, screen, or interaction
security or privacy — change touches auth, secrets, personal data, permissions, or external input
external integrations — change calls or depends on any external API, service, or connector; exercise the real surface (MCP connectors such as Supabase/Railway/Neon/Vercel, provider CLIs, live API docs via Context7), do not infer it
data model, migration, or compatibility — change adds, alters, or migrates persisted data
compliance or policy — change touches regulated data, billing, or policy-governed behavior
performance or scale — change affects a hot path, large dataset, or concurrency
monetization, pricing, or market positioning — change affects what is sold or how it is priced
domain-specific research — task names a domain whose rules you cannot derive from the codebase
Record in the Delegation Rationale every specialist that fired and every one whose trigger did not, with the concrete reason.
Ask research-informed qualifying questions. Synthesize the bundle and adaptive findings into .wannabuild/outputs/discovery/followup-questions.md. Surface every question that materially changes scope, product direction, risk, cost, or success (per Resource Exhaustion, only questions you could not answer yourself). Present options with a recommended answer where a path forward exists.
Derive requirements after the vision is qualified. Turn interview, research, and agent outputs into feature priorities; user stories/jobs-to-be-done; scope boundaries; acceptance criteria; integration test scenarios; risks, assumptions, and success metrics; and research synthesis with Failure Forecast impact. Derive test scenarios after the clarified vision, main flows, and desired behavior are understood.
Present the synthesized requirements and stop at the boundary. See Handoff.
Agent Invocation Pattern
When delegating, pass the interview transcript and the specific question each agent owns. Example shape:
Task(subagent_type="<selected specialist>", run_in_background=<true when independent>)
prompt: "Analyze the discovery transcript and codebase for <specific ownership area>.
Focus on <scope/UX/risk/etc.>.
Write full findings to .wannabuild/outputs/discovery/<artifact>.md.
Return ONLY: 'COMPLETE - [one sentence]. Report at <path>'"
The orchestrator selects specialists by the adaptive-research triggers, parallelism by the Size Rubric, and capability tier from the task evidence — never fixed model names.
Resource Exhaustion (mandatory)
Before recording any fact as an unknown, assumption, open question, or blocker, you MUST first attempt to obtain it from available resources and record exactly what you tried, per Mandate 2 of skills/internal/build/references/doctrine.md:
Read the real codebase, package manifests, lockfiles, and config to resolve how the project works today.
Read live library, framework, and API docs via Context7 for version, capability, and feasibility questions.
Probe the actual integration surface for any external dependency — MCP connectors (Supabase, Railway, Neon, Vercel), provider CLIs, and live API docs.
Generate fixtures, read existing data shapes, or stand up a local/ephemeral environment when a question needs runtime evidence.
"Missing env", "no access", or "can't check" is never grounds to stop or skip an artifact — it is grounds to acquire the resource (anything safe, local, and reversible), or, only for billable, outward-facing, or destructive acquisition, to stop and ask the user with the specific resource named. If an acquisition attempt fails, log it in .wannabuild/outputs/acquisition-log.json (what was needed, which tools/connectors/CLIs were attempted, the result) so assert-acquisition-attempted can verify it. A blocker, unknown, or assumption with no logged attempt does not pass.
Synthesis
After analysis completes, the orchestrator writes .wannabuild/spec/requirements.md, merging all inputs into one coherent spec: user interview transcript, existing requirements/docs, codebase facts, required research outputs, specialist outputs, and orchestrator assumptions/decisions. If specialist outputs conflict, resolve it explicitly in the spec or ask the user when the choice changes product intent.
Runtime verifies the durable artifacts and .wannabuild/state.json discovery evidence. It cannot prove a host truly spawned an agent, so the skill contract owns delegation behavior.
Output Artifact
The phase produces .wannabuild/spec/requirements.md:
# Requirements Spec## Vision Brief
[What the user wants to create, why it matters, and what "great" should feel like.]
## Project Overview
[1-2 sentences: what this is and who it is for.]
## Audience and Use Context-**Primary users:** [who, goals, context]
-**Secondary users:** [optional]
## Desired Experience and Feel- [Tone, pacing, quality bar, UX personality, trust/safety expectations, visual or interaction feel if relevant]
## Core User Flows### [Flow Name]1. [User/system step]
2. [User/system step]
3. [Successful end state]
## Feature Inventory and Priorities### Must Have- [Feature] - [why it matters]
### Should Have- [Feature] - [why it matters]
### Later / Deferred- [Feature] - [why deferred]
## Size Assessment**Estimate:** [Tiny/Small/Medium/Large/Epic]
**Confidence:** [High/Medium/Low]
**Rationale:** [Why this size]
## User Stories / Jobs To Be Done1. As a [user], I want [feature], so that [value]
## Acceptance Criteria- [ ] [Testable criterion derived from the clarified vision]
## Research Synthesis### Feasibility- [Implementation path, dependencies, unknowns, and effort risks]
-**Resources consulted:** [codebase paths, Context7 doc lookups, connector/CLI probes used to verify dependency/version reality — a dependency or version is "unknown" only after these failed]
### Alternatives and Competition- [Direct competitors, adjacent alternatives, existing tools/libraries, manual workflow, do-nothing option]
### Failure Forecast Impact- [Likely failure causes, warning signs, mitigations, and requirements changes]
## Qualified Decisions- [Decision clarified after research and user follow-up]
## Scope### In Scope- [Capability that will be built]
### Out of Scope- [Capability explicitly deferred]
## Integration Test Scenarios### [Flow or Story Name]-**Happy path:** [expected flow and assertion]
-**Failure path:** [failure mode and expected behavior]
-**Edge cases:** [important boundaries derived after the main flow is understood]
## Assumptions and Open Questions### Assumptions- [Inference made by the orchestrator] — **resources consulted:** [codebase paths, Context7 lookups, connector/CLI probes that were tried and failed to resolve this before it became an assumption]
### Open Questions- [Question that still matters, with the resources already tried and why they did not resolve it, or "None"]
## Scope Risks
| Risk | Severity | Notes |
|---|---|---|
| [risk] | High/Med/Low | [details] |
## Success Metrics- [How to know the project succeeded]
## Delegation Rationale-**Shape:** [single-owner / one specialist / parallel specialists, per the Size Rubric]
-**Delegation:** [attempted via host sub-agents, or produced directly because the host cannot delegate]
-**Specialists fired:** [each adaptive specialist that ran and why; each whose trigger was absent and the concrete reason]
-**Evidence:** [the acquired evidence behind each artifact — codebase paths, Context7 lookups, connector/CLI probes]
State Update
After writing the required discovery artifacts and requirements.md, merge-update .wannabuild/state.json (write only these fields; preserve all others):
In guided mode (the default), always present the captured vision, core flows, scope, assumptions (each with resources consulted), and verification direction, then STOP at the Discover -> Plan boundary and require an explicit approval word ("go", "proceed", "approved", "continue", "next", "lgtm", "do it") before planning. A vague acknowledgment ("ok", "sure") never crosses the boundary. In autonomous mode, still present the synthesis, then continue automatically, stopping to ask when unresolved ambiguity changes product direction, scope, cost, or risk.
User Interaction
At the boundary, present the synthesis and hold until an explicit approval word arrives:
Here's what I've captured: the vision, core flows, feature priorities, scope
boundaries, assumptions (with what I checked to resolve each), and how we'll
verify the work. Say "go" / "proceed" / "approved" to move on to Plan, or tell
me what to change.
The user can approve and continue, clarify the vision or feel, add/remove/reprioritize features, change scope, or answer open questions. If the user changes the vision materially, re-run only the affected synthesis or specialist analysis; the bundle's three artifacts are always refreshed when the vision changes materially.
Quality Checklist
Vision, audience, desired feel, and core flows are captured
Feature priorities distinguish must-have from deferred ideas
Each assumption names the resources consulted and was recorded only after acquisition failed
Each open question records the resources already tried, and materially changes scope, product direction, risk, cost, or success
Every user story and every core flow has at least one testable acceptance criterion derived from the clarified vision
Integration test scenarios and edge cases exist for every core flow
Scope boundaries are explicit
Size assessment is computed from the Size Rubric with rationale
Delegation rationale records shape, delegation availability, specialists fired/not-fired, and acquired evidence
Each bundle artifact (feasibility, alternatives/competition, Failure Forecast) carries a "Resources consulted" subsection with concrete findings and affected follow-ups
Every adaptive specialist whose trigger fired produced an artifact with a "Resources consulted" subsection
Any blocker, unknown, or unmet need has a logged attempt in .wannabuild/outputs/acquisition-log.json
The user explicitly approved the synthesis at the Discover -> Plan boundary (guided mode)
scripts/wannabuild-session.sh assert-discovery-ready . passes before Plan
Contract Validation
Before handoff to Design, run — and only proceed once both pass (read the error, fix the artifact or state, re-run):
User has existing requirements: Treat them as input, then interview for missing vision, flows, feel, priorities, assumptions, and non-goals before formatting.
User only knows the vibe: Keep asking vision and flow questions until a concrete task and success signal exist.
Scope is too large: Mark it Epic and ask whether to narrow, split, or plan a first milestone.
User changes mind mid-phase: Re-synthesize affected sections and re-run the specialists whose inputs changed; never drop a bundle artifact to save effort.
Greenfield vs. existing project: Adapt the interview and analysis to the actual codebase and user context.
Testing conversation overwhelms the user: Move test derivation later; capture the user's desired behavior first.
