Deep guided elicitation for new projects. Archetype-aware, research-backed, multi-phase discovery with assumption tracking and Phase Transition Stories.
Deep guided elicitation for new projects. Archetype-aware, research-backed, multi-phase discovery with assumption tracking and Phase Transition Stories.
Read references/question-scaffolding.md — these 8 rules apply to EVERY question you ask. Read @.claude/prompts/interactive-ux.md for the shared interactive UX protocol (AskUserQuestion format, progress tracking, confirmation gates).
Process Flow (authoritative)
START → Phase 1: Classification (archetype + scale + 5 universal questions)
→ Mode Selection:
→ [QUICK: --quick flag OR Quick Build scale]
→ 3-5 essential questions → 1 research → auto-pick tech → minimal backlog → DONE
→ [GUIDED: Standard scale — DEFAULT]
→ Phase 2 → 3 → 4 → 5 → 6 → 7 → DONE
→ [PLATFORM: --platform flag OR Platform scale]
→ All GUIDED phases + stakeholder/compliance/multi-user/ADRs → DONE
→ [PIONEERING: --pioneer flag OR Pioneering scale]
→ Core identity → deep research → spike planning → spike backlog → DONE
Phase 1: Classification
Show the opening progress bar:
---
**Discover** | Phase 1 of 7: Classification
[>....................] 0 of ~22 decisions
Coming up: What kind of project is this, and how big?
---
Let's start by understanding what kind of project this is. I'll ask 4-5 quick
questions to classify your idea — this takes about 2 minutes.
1A. Archetype Selection (recognition-based — use AskUserQuestion)
Analyze the user's idea description from Phase 0. Identify the top 3 matching archetypes. Present via AskUserQuestion:
header: "Project type"
question: "Based on your description, your project seems closest to one of these.
Which fits best? Select 'Other' to see all 11 options or describe
something different."
options:
- label: "[Best match] (Recommended)"
description: "[one-sentence archetype description]. Like [3 examples]."
- label: "[Second match]"
description: "[one-sentence description]. Like [3 examples]."
- label: "[Third match]"
description: "[one-sentence description]. Like [3 examples]."
If user selects "Other": display the full archetype card from references/scale-guide.md as text, then use a new AskUserQuestion with their indicated preference.
1B. Sub-variant Confirmation via Analogy (use AskUserQuestion)
Load the archetype's reference file for sub-variant examples. Present via AskUserQuestion:
header: "Sub-type"
question: "You said [archetype]. Is it more like one of these?
Select 'Other' if none quite fit."
options: [3 sub-variants from archetype file, each with description]
1C. Hybrid Check (use AskUserQuestion)
Based on the idea, identify the most likely secondary archetype. Present via :
Jump to Quick Start flow (below).
Jump to Pioneering flow (below).
Additional questions: stakeholders beyond end users, existing system integrations, compliance/regulatory requirements, non-functional requirements. See scaffolding in archetype file.
Use **AskUserQuestion** to check research impact:
Additional: domain modeling, multi-user-type journeys, API surface design, integration architecture.
Use **AskUserQuestion** confirmation gate (see `interactive-ux.md` format).
User approves No-Gos before proceeding.
Use **AskUserQuestion** for vision approval:
Use **AskUserQuestion** confirmation gate for feature list approval (see `interactive-ux.md`).
Use **AskUserQuestion** for story approval:
This step is MANDATORY. Do NOT skip it. Every file below must be populated with real content from discovery — not left as a template.
AskUserQuestion
header: "Hybrid?"
question: "Does your project also have a strong [other archetype] element?
Most real projects span 2 types."
options:
- label: "Yes, also [archetype]"
description: "This adds [archetype]-specific questions to make sure we cover
both aspects of your project."
- label: "No, just [primary]"
description: "We'll focus entirely on the [primary archetype] perspective."
- label: "Actually, it's more like..."
description: "Pick this if the secondary archetype I suggested doesn't feel right
but there IS a second element."
1D. Scale Classification (use AskUserQuestion)
Read references/scale-guide.md for the full definitions. Infer the most likely scale from the description's timeline, complexity, and scope. Present via AskUserQuestion:
header: "Scale"
question: "How big and complex is this project? This determines how deep we go
in planning. Select 'Other' if none of these fit."
options:
- label: "[Inferred scale] (Recommended)"
description: "[description]. [why this fits based on what user said]"
- label: "Quick Build"
description: "1-3 days. Single feature, one user type. Like a CLI tool or
game jam entry. We'll plan fast and start building immediately."
- label: "Standard"
description: "1-4 weeks. Frontend + backend + database. A proper MVP for a
target audience. Balanced planning and building."
- label: "Platform"
description: "1-6 months. Multiple services, user types, or integrations.
Thorough planning with architecture decisions and ADRs."
Note: If the recommended scale is one of the 3 listed, show it first with (Recommended) and replace it in the list with the 4th option (Pioneering: "Unknown timeline. Novel concept where the architecture IS the question. Needs research spikes first.").
"In one sentence, what is this?" (scaffold: "'It's [X] that [does Y]'")
"What existing thing is this most like? 'It's X meets Y.'"
"Where and when will people use this?" (scaffold: "Phone on bus? Desktop at work?")
"How long is a typical session?" (scaffold: "30 seconds? 5 minutes? An hour?")
"Timeline and who's building?" (scaffold: "Weekend? Month? Just you?")
1F. Mode Selection
Select mode from scale + flags. Save to vision/classification.md.
Show transition summary:
---
Phase 1 Complete: Classification
---
**Decided so far:**
- Archetype: [primary] (+ [secondary] if hybrid)
- Scale: [name]
- One-liner: "[X meets Y]"
- Context: [device], [session length], [timeline]
**Moving to Phase 2:** Core Identity — we'll explore what makes your project unique.
Phase 2: Core Identity (ARCHETYPE-SPECIFIC)
---
**Discover** | Phase 2 of 7: Core Identity
[===>................] 4 of ~22 decisions
Coming up: What makes your project unique?
---
Now let's explore the heart of your idea. I'll ask questions specific to your
type of project — this shapes everything that gets built.
Time: ~5 minutes of conversation.
Load the primary archetype reference from references/archetypes/{archetype}.md. If hybrid: also load secondary for supplementary questions.
Ask Core Identity Questions from the archetype file. RULES:
ONE question at a time, wait for answer
Every question includes scaffolding (see references/question-scaffolding.md)
Questions with clear options (e.g., "visual style", "monetization model") → use AskUserQuestion with the archetype file's options. Add to question text: "Select 'Other' to describe your own vision — more detail helps me build something closer to what you want."
Open-ended questions (e.g., "describe the experience", "what problem?") → ask conversationally with scaffolding examples
Vague answer → drill deeper with follow-up
"I don't know" → present 2-3 options via AskUserQuestion as a fallback
"You decide" → pick, mark as ASSUMED in DECISION_LOG, move on
Execute archetype-specific research protocol from references/research-protocols.md — section for the primary archetype. Present: "Here's the landscape..."
header: "Research"
question: "Here's what I found about the landscape. Does this change anything
about your concept?"
options:
- label: "No changes, continue (Recommended)"
description: "The research confirms the direction. Let's keep going."
- label: "Yes, I want to adjust"
description: "Something in the research changes how I think about this.
I'll describe what I want to change."
- label: "Tell me more about..."
description: "I want to dig deeper into a specific finding before deciding."
Save to vision/core-identity.md. Log decisions to docs/reference/DECISION_LOG.md (copy template from assets/decision-log.md if not exists).
Phase 3: Deep Elicitation (ARCHETYPE-SPECIFIC)
---
**Discover** | Phase 3 of 7: Deep Elicitation
[======>..............] 8 of ~22 decisions
Coming up: Detailed features, user journeys, and edge cases
---
We've defined WHAT you're building. Now let's go deep on HOW it works —
features, workflows, and edge cases. This is where your idea becomes a product.
Time: ~10-15 minutes.
3A. Archetype Deep Dive
Execute the full Phase 3 question bank from the archetype reference file. Produces: detailed experience/workflow description, feature map extracted from the experience, feature classification (MUST-HAVE / IMPORTANT / NICE / CUT).
Research Checkpoint 2: Feature-Level Research
For EACH must-have and important feature: search best implementation, common pitfalls, tutorials. Present per feature. User confirms or adjusts.
3B. Edge Case Exploration
Probe 6 dimensions (scaffolded per archetype): Boundaries, Errors, Users, States, Scale, Time. See archetype reference file for archetype-specific scaffolding.
Research Checkpoint 3: UX/Interaction Patterns
Search UX patterns, best practices, inspiration sources. Present pattern options with pros/cons. User selects preferred approaches.
Save to vision/deep-elicitation.md. Log decisions to DECISION_LOG.
3D. Persona Synthesis
After deep elicitation completes, synthesize user personas from ALL Phase 2-3 answers. Personas generated here are richer than the early D02 user notes because they're informed by feature maps, user journeys, and edge cases.
Generate 2-4 personas in the lean 6-field format:
## P[N]: [Name] — [Role] ([key context])-**CONTEXT:** [Environment, tech proficiency, device, constraints]
-**GOALS:** [What they're trying to achieve — observable outcomes]
-**FRUSTRATIONS:** [What blocks them today — drives acceptance criteria]
-**BEHAVIORS:** [How they interact with similar products — informs UX]
-**EVALUATES BY:** "[Question 1]?" / "[Question 2]?"
-**FAILURE LOOKS LIKE:** [What goes wrong for this persona — informs testing]
Rules for persona generation:
Derive from what the user SAID, not from archetypes or assumptions
Each persona must have a DISTINCT behavior pattern — if two personas differ only by demographics, merge them
Mark one as primary (★) — the persona the MVP is built for
Cap at 4 personas; more usually means overlapping segments
Verify with user via AskUserQuestion (multiSelect):
header: "User personas"
question: "Based on our conversation, I've identified these user types. Uncheck any
that don't fit, or select 'Other' to add a user type I missed.
I'll show the full persona cards after you confirm."
multiSelect: true
options:
- label: "P1: [Name] — [Role] (Recommended as primary)"
description: "GOALS: [goals]. FRUSTRATIONS: [frustrations].
EVALUATES BY: '[key question]?'"
- label: "P2: [Name] — [Role]"
description: "GOALS: [goals]. FRUSTRATIONS: [frustrations].
EVALUATES BY: '[key question]?'"
- label: "P3: [Name] — [Role]"
description: "GOALS: [goals]. FRUSTRATIONS: [frustrations].
EVALUATES BY: '[key question]?'"
After user confirms persona selection, if more than one persona confirmed, ask primary selection via AskUserQuestion:
header: "Primary persona"
question: "Which user should we prioritize when features conflict between personas?"
options: [one per confirmed persona, recommended = most frequently referenced in Phase 2-3]
For "Other" additions: ask 2-3 follow-up questions (context, goal, frustration), generate card, present for confirmation.
Save generated personas to docs/context/personas.md using the template format. Log persona decisions to DECISION_LOG with confidence CONFIRMED (user-verified) or ASSUMED (auto-generated in Quick mode).
Transition:
---
Phase 3 Complete: Deep Elicitation + Personas
---
**User personas confirmed:**
- ★ P1: [Name] — [Role] (primary)
- P2: [Name] — [Role]
**Moving to Phase 4:** Stress Testing — we'll test assumptions and identify risks.
Phase 4: Assumption Surfacing & Stress Testing
---
**Discover** | Phase 4 of 7: Stress Testing
[==========>..........] 12 of ~22 decisions
Coming up: Testing your assumptions and identifying risks
---
Every project has hidden assumptions. Let's surface them now — it's much
cheaper to discover problems in planning than in code.
Time: ~5-10 minutes.
4A. "What Needs To Be True"
Generate assumptions FROM Phases 2-3 decisions. User RATES them using AskUserQuestion — batch up to 4 assumptions per call:
questions: [
{
header: "Assumption 1"
question: "\"[assumption text]\". How confident are you?"
options:
- label: "Definitely true"
description: "I have evidence or strong experience that confirms this."
- label: "Probably true (Recommended)"
description: "Seems reasonable, but I'm not 100% sure."
- label: "Unknown"
description: "I genuinely don't know — this needs validation."
},
// ... up to 4 per call
]
Present by category: Desirability, Feasibility, Viability, Usability. Then: "Any other assumptions I missed?"
Research Checkpoint 4: Assumption Validation
For EACH "Unknown" and "Probably" assumption: run targeted web research (2-3 searches). Present findings, update confidence. Flag remaining unknowns as "needs spike."
4B. Pre-Mortem
Load archetype-specific failure scenarios from the archetype reference file. Rate each using AskUserQuestion — batch up to 4 scenarios per call:
questions: [
{
header: "Risk [N]"
question: "\"[failure scenario]\". How likely is this for your project?"
options:
- label: "Likely"
description: "This is a real risk I'm worried about. Let's plan a mitigation."
- label: "Possible"
description: "Could happen, but not my top concern. Worth noting."
- label: "Unlikely (Recommended)"
description: "Doesn't apply to my situation or I have this covered."
}
]
For each "Likely" or "Possible": ask mitigation strategy conversationally, log in assumption register.
4C. No-Gos Declaration
Auto-generate No-Gos from: features classified as CUT, scope boundaries from timeline, architectural constraints from research, user's "not what I want" moments. Present for user approval via AskUserQuestion with multiSelect:
header: "No-Gos"
question: "These are the things we're explicitly NOT building. Uncheck any
you disagree with. Select 'Other' to add more."
multiSelect: true
options:
- label: "[No-go 1]"
description: "[Why this is excluded and what happens if it creeps in]"
- label: "[No-go 2]"
description: "[Why excluded]"
- label: "[No-go 3]"
description: "[Why excluded]"
Save to docs/reference/ASSUMPTION_REGISTER.md (copy template from assets/assumption-register.md if not exists) + vision/stress-test.md.
Phase 5: Dimension Completeness Sweep
---
**Discover** | Phase 5 of 7: Technical Decisions
[============>........] 14 of ~22 decisions
Coming up: Frontend, backend, database, auth, hosting, and design choices
---
We've defined WHAT you're building. Now let's decide HOW to build it.
I'll present options for each technology layer with my recommendation.
For each choice, I'll research what's current. This takes ~5-15 minutes
depending on how many decisions are still open.
Read references/dimension-sweep.md for the full protocol. Load DECISION_LOG to identify what's already decided. Run through dimensions D04-D10, skipping items already covered by Phases 2-4. Scale determines depth per dimension. Use AskUserQuestion for every dimension (each has 2-4 options — perfect fit). Log ALL decisions to DECISION_LOG.
Research Checkpoint 5: Stack & Architecture
Search stack project structure, architecture patterns, testing strategy for the complete selected stack.
After cross-constraints are resolved, if ANY dimension decisions involve external services (accounts, API keys, external setup), run the external dependency summary from references/external-dependencies.md. This presents every external service commitment in one view so the user can confirm or revise choices before proceeding.
Skip when: All tech choices are self-hosted, open-source, or local — no external accounts needed.
Output saved to vision/external-dependencies.md — consumed by /ideate to generate setup prerequisite stories ordered before the features that depend on them.
Phase 6: Vision Synthesis
---
**Discover** | Phase 6 of 7: Vision Synthesis
[=================>...] 20 of ~22 decisions
Coming up: Reviewing the complete project vision
---
Almost there! I'm synthesizing everything into a project pitch.
You'll review it and approve before we generate the build plan.
Generate Shape Up pitch: PROBLEM/CONCEPT, APPETITE, SOLUTION, RABBIT HOLES, NO-GOS. Generate vision/project-pitch.md. Highlight every ASSUMED and SPECULATIVE decision — user confirms or changes each.
header: "Vision"
question: "Here's your complete project vision. I've highlighted all assumptions
and speculative decisions above. Ready to proceed to backlog generation?"
options:
- label: "Approved, generate backlog (Recommended)"
description: "The vision captures what I want to build. Let's create the
build plan."
- label: "I want to change specific items"
description: "The direction is right but some details need adjusting.
I'll tell you what to change."
- label: "Major rethink needed"
description: "The vision has drifted from what I intended.
Let's go back to an earlier phase."
Phase 7: MVP Scoping & Backlog Generation
---
**Discover** | Phase 7 of 7: Build Plan
[===================>] 21 of ~22 decisions
Coming up: Selecting MVP features and generating your build plan
---
Final phase! We'll select what goes in the MVP, define success criteria,
and generate your backlog of stories. After this, you're ready to build.
Read references/engineering-by-archetype.md for testing strategy and success criteria per archetype.
7A. MVP Feature Selection
Start with assumption register. Present feature list via AskUserQuestion with multiSelect — all must-haves pre-selected, nice-to-haves as options:
header: "MVP scope"
question: "Which features go in the MVP? Must-haves are listed first.
Uncheck anything you want to cut. Select 'Other' to add features."
multiSelect: true
options:
- label: "[Must-have feature 1] (Recommended)"
description: "Core to the value proposition. Cutting this weakens the MVP."
- label: "[Must-have feature 2] (Recommended)"
description: "[why it's essential]"
- label: "[Important feature]"
description: "Validates [assumption]. Not strictly required but de-risks."
- label: "[Nice-to-have feature]"
description: "Can ship without this. Adds polish but not core value."
For each: "Ship without this? Still validate core?" Yes → cut.
7B. Success Criteria (archetype-specific)
Define SUCCESS and FAIL thresholds + circuit breaker date per the archetype success criteria templates in references/engineering-by-archetype.md.
7C. Epic & Story Generation
Read references/scale-guide.md for scale-adapted epic structures. Read references/phase-transition-template.md for the Phase Transition epic. Generate epics with Phase Transition as the LAST epic. Shape stories self-contained where it makes sense: one complete outcome each (outcome over output), genuine prerequisites only in the Dependencies field, shared groundwork extracted into setup stories. Independent stories can later be built in parallel (/parallel-work); dependent ones are worked sequentially. For each story include: standard AC + archetype-specific AC layers, relevant decisions from DECISION_LOG, relevant assumptions from ASSUMPTION_REGISTER, No-Gos from project-pitch.md.
If vision/external-dependencies.md exists, generate an Infrastructure setup story for each external service. Each setup story: type infra, size SMALL, AC = account created + credentials in .env + connectivity verified, ordered immediately BEFORE the first feature story that depends on that service.
header: "Backlog"
question: "I've generated [N] stories across [M] epics. Here's the summary above.
Ready to finalize?"
options:
- label: "Approved, generate files (Recommended)"
description: "Create all backlog files. You can still adjust individual
stories later."
- label: "Adjust specific stories"
description: "The structure is right but some stories need changes.
I'll describe what to adjust."
- label: "Rethink the epic structure"
description: "The stories are fine but the epic grouping needs work."
Using all decisions, research findings, and user answers from Phases 1-6, populate these files. Each file must contain project-specific content, not placeholder comments.
From Phase 3D persona synthesis (already generated — verify exists):
docs/context/personas.md — Should already exist from Phase 3D. Verify it contains project-specific personas, not template placeholders. If missing (e.g., Phase 3D was skipped), generate now from Phase 2-3 user notes.
From vision/classification.md + vision/core-identity.md:
docs/context/project-overview.md — What this project is, who it's for, what problem it solves, archetype + scale classification
docs/context/product-context.md — Feature priorities, user journeys from Phase 3, validation plan from ASSUMPTION_REGISTER. Reference docs/context/personas.md for persona details (do not duplicate persona cards here).
From vision/deep-elicitation.md + DECISION_LOG.md (technical decisions):
docs/context/system-patterns.md — Populate each section:
Implementation Patterns: Architecture pattern from Phase 5 dimension sweep (e.g., MVC, hexagonal, event-driven). Reference the proposed module structure.
Architectural Conventions: Naming and organization conventions from CODING_STANDARDS.md decisions. Import direction rules from the proposed module map.
Error Handling Strategy: From Phase 3B edge case exploration (error dimension) + Phase 5 error handling decisions.
Testing Conventions: From DECISION_LOG testing framework decisions + TESTING_STRATEGY.md choices.
Implementation Recipes: From the proposed architecture, document how to add the project's primary entity (e.g., "To add a new API endpoint: 1. Create handler in... 2. Add route in...").
From DECISION_LOG.md (technical decisions from Phase 5 dimension sweep):
docs/context/tech-context.md — Stack choices (frontend, backend, database, auth, hosting), key libraries, API style, data layer decisions
From vision/stress-test.md + vision/project-pitch.md:
docs/reference/GROUND_RULES.md — No-Gos become MUST-NOT rules, key architectural constraints from dimension decisions become MUST rules, add 3-5 principles from the chosen architecture pattern
docs/context/error-patterns.md — Pre-mortem risks from Phase 4B as potential failure modes to watch for
From DECISION_LOG.md (if test framework was decided):
docs/reference/TESTING_STRATEGY.md — Test Infrastructure section filled with chosen test runner, coverage tool, test command, test location. Testing approach from references/engineering-by-archetype.md for the project's archetype.
From vision/classification.md (if project has no source files yet):
docs/context/project-structure.md — Proposed directory layout based on chosen stack and architecture pattern
From vision/project-pitch.md + DECISION_LOG.md (all scales):
README.md — Project README with these sections (cognitive funnel — broadest info first):
Title: Project name from discovery
Description: One-liner from project pitch, then 2-3 sentence expanded description from project-overview
Prerequisites: Runtime + version from tech decisions (e.g., "Python 3.11+", "Node 20+")
Getting Started: Install and run commands from tech stack decisions
Development: Table of dev commands — test, lint, format, build, typecheck from DECISION_LOG
Project Structure: Proposed directory layout from project-structure.md
Contributing: Link to CONTRIBUTING.md or brief conventions note referencing CODING_STANDARDS.md
License: From user's license decision if made, otherwise placeholder
Standard: populate all files above including full README.md
Platform: populate all files above + create initial ADRs in docs/adr/ for major architectural decisions (database, auth, hosting, API style)
Pioneering: populate CLAUDE.md + README.md (title, description, prerequisites) + tech-context.md (what's known) + project-overview.md. Mark other files as "post-spike" with a note about what spikes will determine.
Quick Start Mode
For Quick Build scale, or --quick flag, or user says "just start" / "skip the questions."
3-5 essential questions ONLY (archetype core question + who/device + ONE thing to nail)
1 quick research: landscape scan (2-3 searches)
Auto-generate 1 persona from answers (mark as ASSUMED). Confirm with user: "Your main user seems to be [X]. Sound right?" Save to docs/context/personas.md.
Auto-pick all technical decisions (mark as ASSUMED in DECISION_LOG)
If any auto-picked decisions involve external services (accounts, API keys, external setup), show a brief notice listing each service with its role, setup summary, and estimated time. No approval gate — informational only. Save to vision/external-dependencies.md so /ideate generates setup stories.
Generate minimal pitch + minimal backlog: E01 Core Build (3-5 stories) + E02-REVIEW Quick Phase Transition (3 stories). Include setup stories for any external services (from step 6) before the features that depend on them.
Start building immediately
Key: "Document as you go, not before you start." Phase Transition Stories still trigger a review loop.
Pioneering Mode
For Pioneering scale, or --pioneer flag, or Uncategorized archetype.
Core Identity questions + DEEP research (academic, patents, adjacent tech)
Generate 1-2 proto-personas from core identity answers, mark as ASSUMED. Save to docs/context/personas.md with note: "Proto-personas — refine after spikes."
