Deep guided elicitation for new projects. Archetype-aware, research-backed, multi-phase discovery with assumption tracking and Phase Transition Stories.
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.
A direct command skips the review prompt. Inspect the source before running it.
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."
