ultra-builder-pro-cli 0.10.0 → 0.12.1

package/skills/ultra-research/steps/step-05-assumptions-validation.md

@@ -1,234 +0,0 @@
-# Step 05: Assumptions & Validation Plan
-
-## MANDATORY EXECUTION RULES
-
-- EXTRACT assumptions from ALL previous steps (00-04) — not just the obvious ones
-- PRIORITIZE by Impact × Uncertainty — focus on "leap of faith" assumptions
-- DESIGN cheap, fast experiments — not "build it and see"
-- WRITE output to spec file BEFORE presenting to user
-- ALL output in English (spec files); conversation in Chinese
-
-## PREREQUISITES
-
-- Steps 00-04 completed with [C]
-- `.ultra/specs/discovery.md` §0-4 exist
-
-## CONTEXT BOUNDARIES
-
-- Focus: What are we assuming? What's riskiest? How do we validate cheaply?
-- This is the LAST step of Round 0 — it synthesizes everything discovered so far
-- After this step, user decides: proceed to Round 1 or investigate further
-- Based on Alberto Savoia (Pretotyping) and Marty Cagan methodologies
-
-## SEARCH STRATEGY (MANDATORY)
-
-Execute these web searches:
-
-```
-Search: "{{product_domain}} validation methods pretotype MVP"
-Search: "{{product_domain}} common startup mistakes failed assumptions"
-Search: "landing page test fake door validation {{product_domain}}"
-Search: "{{product_domain}} customer interview validation techniques"
-```
-
-## EXECUTION SEQUENCE
-
-### 1. Extract Assumptions from Previous Steps
-
-Review §0-4 and extract assumptions across 5 categories:
-
-| Category | Source | What to look for |
-|----------|--------|-----------------|
-| **Value** | §0, §1 | Will users actually want this? |
-| **Usability** | §1 | Can users figure it out without help? |
-| **Feasibility** | §1 (solutions) | Can we build it with current technology? |
-| **Viability** | §2 | Does the business case work at these numbers? |
-| **Go-to-Market** | §3, §4 | Can we reach and convert our target users? |
-
-### 2. Prioritize Assumptions
-
-Map each assumption on Impact × Uncertainty:
-
-```
-                    High Impact
-                        │
-    VALIDATE FIRST ─────┼───── MONITOR
-    (Leap of Faith)     │     (Important but clear)
-                        │
-   Low Uncertainty ─────┼───── High Uncertainty
-                        │
-    IGNORE ─────────────┼───── INVESTIGATE
-    (Low stakes)        │     (Uncertain but low impact)
-                        │
-                    Low Impact
-```
-
-Focus on "Leap of Faith" quadrant: **High Impact + High Uncertainty**
-
-### 3. Design Validation Experiments
-
-For top 3-5 leap-of-faith assumptions, design cheap, fast experiments:
-
-**Experiment Design Framework:**
-
-| Element | Description |
-|---------|-------------|
-| Assumption | What exactly are we assuming? |
-| Category | Value / Usability / Feasibility / Viability / GTM |
-| Method | How will we test this? |
-| Success criteria | What result validates the assumption? |
-| Failure criteria | What result invalidates it? |
-| Effort | Hours/days to execute |
-| Timeline | When can we have results? |
-
-**Preferred Methods** (cheapest first):
-1. **Data analysis**: Existing data that proves/disproves the assumption
-2. **Customer interviews**: 5-10 targeted conversations
-3. **Fake door test**: Landing page with sign-up / "notify me" button
-4. **Concierge MVP**: Manually deliver the value to 3-5 users
-5. **Pretotype**: Mechanical Turk version of the product
-6. **Prototype**: Clickable mockup tested with real users
-7. **MVP**: Minimum viable version with real functionality
-
-### 4. Define Decision Framework
-
-For each experiment:
-
-```
-If experiment SUCCEEDS → [Next action]
-If experiment FAILS → [Pivot / Investigate / Kill]
-If results are AMBIGUOUS → [How to get clarity]
-```
-
-### 5. Write Output
-
-**WRITE IMMEDIATELY** to `.ultra/specs/discovery.md` §5:
-
-```markdown
-## §5 Key Assumptions & Validation Plan
-
-### Assumption Inventory
-
-| # | Assumption | Category | Impact | Uncertainty | Priority |
-|---|-----------|----------|--------|-------------|----------|
-| A1 | [Statement] | Value | High | High | **Validate First** |
-| A2 | [Statement] | Viability | High | High | **Validate First** |
-| A3 | [Statement] | GTM | High | Medium | **Validate First** |
-| A4 | [Statement] | Feasibility | Medium | High | Investigate |
-| A5 | [Statement] | Usability | Medium | Medium | Monitor |
-| A6 | [Statement] | Value | Low | Low | Ignore |
-
-### Leap-of-Faith Assumptions (Top 3-5)
-
-#### A1: [Assumption Statement]
-- **Category**: [Value / Viability / GTM / Feasibility / Usability]
-- **Why it matters**: [What happens if this is wrong]
-- **Current evidence**: [What we know from steps 00-04]
-- **Evidence gap**: [What we don't know]
-
-**Validation Experiment:**
-- **Method**: [Specific method]
-- **Success criteria**: [Measurable outcome that validates]
-- **Failure criteria**: [Measurable outcome that invalidates]
-- **Effort**: [Hours/days]
-- **Timeline**: [When results expected]
-
-**Decision Framework:**
-- ✅ If validated → [Proceed to Round 1]
-- ❌ If invalidated → [Pivot to X / Investigate Y / Kill]
-- ⚠️ If ambiguous → [Additional experiment Z]
-
-#### A2: [Assumption Statement]
-[Same structure]
-
-#### A3: [Assumption Statement]
-[Same structure]
-
-### Validation Roadmap
-
-| Week | Experiment | Assumption | Expected Result |
-|------|-----------|-----------|----------------|
-| 1 | [Experiment 1] | A1 | [What we'll learn] |
-| 1-2 | [Experiment 2] | A2 | [What we'll learn] |
-| 2-3 | [Experiment 3] | A3 | [What we'll learn] |
-
-### Round 0 Summary
-
-**Product Discovery Confidence**:
-- **Problem validation**: [X]% — [One-line summary]
-- **Opportunity space**: [X]% — [One-line summary]
-- **Market size**: [X]% — [One-line summary]
-- **Competitive position**: [X]% — [One-line summary]
-- **Strategy clarity**: [X]% — [One-line summary]
-- **Overall R0 confidence**: [X]%
-
-**Recommendation**: [Proceed to Round 1 / Validate assumptions first / Pivot]
-```
-
-### 6. Write Round 0 Research Report
-
-**WRITE** to `.ultra/docs/research/product-discovery-{date}.md`:
-
-```markdown
-# Round 0: Product Discovery & Strategy
-
-> **Confidence**: [X]%
-> **Steps completed**: 00-05
-> **Completed**: [date]
-
-## Key Findings
-[3-5 bullet points of most important discoveries]
-
-## Decisions Made
-[Strategic choices and their rationale]
-
-## Open Questions
-[What remains uncertain]
-
-## Assumptions to Validate
-[Top 3 from §5]
-```
-
-### 7. Present to User and Gate
-
-Show the complete Round 0 summary. Highlight:
-- The top 3 leap-of-faith assumptions
-- Overall confidence level
-- Recommendation (proceed / validate / pivot)
-
-```
-[C] Continue — Proceed to Round 1 (User & Scenario Discovery)
-[V] Validate — Pause to run validation experiments before continuing
-[P] Pivot — Rethink the product direction based on findings
-```
-
-**HALT — wait for user response before proceeding.**
-
-### 8. Handle Response
-
-- **[C]**: Load next step: `./step-10-user-personas.md`
-- **[V]**: Help design validation experiments in detail, then re-present gate when done
-- **[P]**: Restart from step-00 with revised direction
-
-## SUCCESS METRICS
-
-- Assumptions extracted from ALL previous steps (not just surface-level)
-- Each assumption categorized and prioritized
-- Top 3-5 have detailed validation experiments
-- Each experiment has clear success/failure criteria
-- Decision framework defined for each outcome
-- Round 0 research report written
-- Output written to discovery.md §5
-
-## FAILURE MODES
-
-- Only extracting obvious assumptions (missing viability, GTM)
-- Designing expensive experiments ("build an MVP") when cheaper options exist
-- No clear success/failure criteria for experiments
-- Missing the decision framework (what do we DO with the results?)
-- Overly optimistic confidence assessment
-- Not writing both spec file AND research report
-
-## NEXT STEP
-
-After user selects [C], read and follow: `./step-10-user-personas.md`

package/skills/ultra-research/steps/step-10-user-personas.md

@@ -1,169 +0,0 @@
-# Step 10: User Personas
-
-## MANDATORY EXECUTION RULES
-
-- WEB SEARCH REQUIRED — validate personas against real user research data
-- DEFINE 2-3 PERSONAS — not 1 (too narrow), not 5+ (too diluted)
-- PERSONAS ARE ABOUT GOALS AND PAIN POINTS — not demographics
-- CONNECT to step-00 (Q3: Desperate Specificity) and step-01 (Opportunities)
-- WRITE output to spec file BEFORE presenting to user
-- ALL output in English (spec files); conversation in Chinese
-
-## PREREQUISITES
-
-- Round 0 completed (steps 00-05) with [C], OR user chose "Feature Only" starting at step-10
-- `.ultra/specs/product.md` exists
-
-## CONTEXT BOUNDARIES
-
-- Focus: WHO are we building for? What drives them? What blocks them?
-- Personas represent real archetypes, not fictional characters
-- Each persona must connect to prioritized opportunities from step-01
-- This is Round 1 start — user scenarios follow in step-11
-
-## SEARCH STRATEGY (MANDATORY)
-
-Execute these web searches in parallel:
-
-```
-Search: "{{product_domain}} user persona research"
-Search: "{{product_domain}} target audience profile behavior"
-Search: "{{product_domain}} user needs pain points survey"
-Search: "{{product_domain}} jobs to be done customer segment"
-```
-
-## EXECUTION SEQUENCE
-
-### 1. Gather User Context
-
-Ask user via AskUserQuestion:
-"Based on our discovery work, who are the 2-3 types of people who would use this most? What do you already know about them?"
-
-Cross-reference with:
-- Step-00 §0: Target User Profile
-- Step-01 §1: Prioritized Opportunities
-- Step-04 §4: Target Segments
-
-### 2. Research Real User Behavior
-
-For each potential persona, search for:
-- How they currently solve the problem (workflows, tools)
-- What frustrates them most (forums, reviews, social media)
-- What motivates their work (career goals, KPIs)
-- How they discover and adopt new tools
-
-### 3. Build Persona Profiles
-
-For each persona (2-3), define:
-
-| Element | What to capture |
-|---------|----------------|
-| Name & Role | Descriptive title, not a real name |
-| Context | Where they work, team size, industry |
-| Goals | What they're trying to achieve (2-3) |
-| Pain points | What blocks them (2-3, connected to opportunities) |
-| Current workflow | How they solve the problem today |
-| Success metric | How THEY measure their own success |
-| Adoption trigger | What would make them try a new solution |
-| Objections | Why they might NOT adopt (barriers) |
-
-### 4. Write Output
-
-**WRITE IMMEDIATELY** to `.ultra/specs/product.md` §1-2:
-
-```markdown
-## §1 Problem Statement
-
-### Core Problem
-[One paragraph describing the problem, grounded in step-00 validation]
-
-### Who It Affects
-[Brief overview connecting problem to specific user types]
-
-### Current Impact
-- **Time cost**: [Hours/week wasted on workarounds]
-- **Money cost**: [$ lost to inefficiency]
-- **Opportunity cost**: [What they can't do because of this problem]
-
-## §2 User Personas
-
-### Persona 1: [Descriptive Name] (Primary)
-
-**Role**: [Job title / context]
-**Context**: [Where they work, team dynamics, industry]
-
-**Goals**:
-1. [Primary goal — what gets them promoted]
-2. [Secondary goal — what they care about daily]
-3. [Tertiary goal — nice to have]
-
-**Pain Points**:
-1. [Pain 1] — Connects to Opportunity [O#] from §1
-2. [Pain 2] — Connects to Opportunity [O#] from §1
-3. [Pain 3] — Source: [URL or user quote]
-
-**Current Workflow**:
-> [Step-by-step description of how they solve this today]
-> Tools used: [List of current tools/processes]
-> Time spent: [X hours/week]
-
-**Success Metric**: [How they measure their own success]
-**Adoption Trigger**: [What would make them try our solution]
-**Objections**: [Why they might resist — e.g., "too busy to learn new tool"]
-
-### Persona 2: [Descriptive Name] (Secondary)
-[Same structure]
-
-### Persona 3: [Descriptive Name] (Tertiary — optional)
-[Same structure]
-
-### Persona Prioritization
-
-| Persona | Urgency | Willingness to Pay | Reachability | Priority |
-|---------|---------|-------------------|-------------|----------|
-| [P1] | High | High | Medium | **Primary** |
-| [P2] | Medium | Medium | High | **Secondary** |
-| [P3] | Low | Low | High | **Tertiary** |
-```
-
-### 5. Present to User and Gate
-
-Show the Persona profiles. Ask user to validate:
-- Do these feel like real people they know?
-- Is anything missing from the profiles?
-- Is the prioritization correct?
-
-```
-[C] Continue — Personas validated, proceed to User Scenarios
-[R] Revise — Adjust persona details or prioritization
-[A] Add — Include an additional persona
-```
-
-**HALT — wait for user response before proceeding.**
-
-### 6. Handle Response
-
-- **[C]**: Load next step: `./step-11-user-scenarios.md`
-- **[R]**: Revise personas, update product.md §1-2, re-present
-- **[A]**: Add persona (max 3 total), update, re-present
-
-## SUCCESS METRICS
-
-- 2-3 personas defined with goals, pain points, and current workflows
-- Each persona connects to opportunities from step-01
-- Personas grounded in web research, not pure imagination
-- Clear prioritization with rationale
-- Output written to product.md §1-2
-
-## FAILURE MODES
-
-- Demographic-only personas ("25-35 year old male in tech")
-- Too many personas (>3 dilutes focus)
-- Pain points not connected to validated opportunities
-- No current workflow description
-- Missing adoption triggers and objections
-- Not writing output before presenting to user
-
-## NEXT STEP
-
-After user selects [C], read and follow: `./step-11-user-scenarios.md`

package/skills/ultra-research/steps/step-11-user-scenarios.md

@@ -1,181 +0,0 @@
-# Step 11: User Scenarios
-
-## MANDATORY EXECUTION RULES
-
-- DEFINE 3-5 SCENARIOS — each with trigger, flow, and outcome
-- SCENARIOS ARE USER JOURNEYS — not feature lists
-- CONNECT each scenario to a specific persona from step-10
-- INCLUDE the emotional arc — frustration → discovery → relief
-- WRITE output to spec file BEFORE presenting to user
-- ALL output in English (spec files); conversation in Chinese
-
-## PREREQUISITES
-
-- Step 10 (User Personas) completed with [C]
-- `.ultra/specs/product.md` §1-2 exist
-
-## CONTEXT BOUNDARIES
-
-- Focus: In what situations do users encounter this problem? What's the journey?
-- Scenarios describe WHEN and HOW users interact, not WHAT the product does
-- Each scenario should be a story the user can picture happening
-- Prioritize scenarios by frequency and pain severity
-
-## EXECUTION SEQUENCE
-
-### 1. Identify Key Scenarios
-
-For each persona from step-10, ask:
-- What triggers them to need a solution? (the "aha" moment)
-- What's the most common situation? (daily/weekly use)
-- What's the most painful situation? (highest frustration)
-- What's the most valuable situation? (highest ROI)
-
-Ask user via AskUserQuestion:
-"For [Primary Persona], what's the most common situation where they hit this problem? Walk me through a typical day."
-
-### 2. Map Scenario Details
-
-For each scenario (3-5), capture:
-
-| Element | Description |
-|---------|-------------|
-| Trigger | What event causes the user to need a solution? |
-| Context | Where are they? What device? What time pressure? |
-| Current flow | How they handle it today (the painful way) |
-| Desired flow | How they WISH they could handle it |
-| Success outcome | What does "done well" look like? |
-| Failure outcome | What happens if they fail? |
-| Frequency | How often does this scenario occur? |
-| Emotional arc | Frustration → Action → Resolution |
-
-### 3. Prioritize Scenarios
-
-Score by:
-- **Frequency** (1-5): How often does this happen?
-- **Pain severity** (1-5): How painful is the current experience?
-- **Value** (1-5): How much value does solving this create?
-
-Priority Score = Frequency × Pain × Value
-
-### 4. Write Output
-
-**WRITE IMMEDIATELY** to `.ultra/specs/product.md` §3:
-
-```markdown
-## §3 User Scenarios
-
-### Scenario Overview
-
-| # | Scenario | Persona | Frequency | Pain | Value | Score |
-|---|----------|---------|-----------|------|-------|-------|
-| S1 | [Name] | [P1] | 5 | 4 | 5 | 100 |
-| S2 | [Name] | [P1] | 4 | 5 | 4 | 80 |
-| S3 | [Name] | [P2] | 3 | 4 | 4 | 48 |
-| S4 | [Name] | [P2] | 2 | 3 | 3 | 18 |
-
-### Scenario 1: [Descriptive Name] ⭐ Primary
-
-**Persona**: [Persona Name]
-**Frequency**: [Daily / Weekly / Monthly]
-
-**Trigger**: [What event causes this scenario]
-**Context**: [Where, when, device, time pressure]
-
-**Current Flow** (painful):
-1. [Step 1 — what they do today]
-2. [Step 2 — where friction occurs]
-3. [Step 3 — workaround they use]
-4. [Step 4 — outcome and time wasted]
-
-> 💬 *"[User quote or typical complaint that captures the frustration]"*
-
-**Desired Flow** (with our product):
-1. [Step 1 — trigger detected]
-2. [Step 2 — streamlined action]
-3. [Step 3 — fast resolution]
-4. [Step 4 — outcome achieved in less time]
-
-**Success Outcome**: [What "done well" looks like — specific and measurable]
-**Failure Outcome**: [What happens if they fail — consequences]
-**Emotional Arc**: [Frustration with X] → [Discovery of solution] → [Relief / satisfaction]
-
-### Scenario 2: [Descriptive Name]
-[Same structure]
-
-### Scenario 3: [Descriptive Name]
-[Same structure]
-
-### Round 1 Summary
-
-**User & Scenario Discovery Confidence**:
-- **Persona accuracy**: [X]% — [One-line assessment]
-- **Scenario coverage**: [X]% — [One-line assessment]
-- **Overall R1 confidence**: [X]%
-```
-
-### 5. Write Round 1 Research Report
-
-**WRITE** to `.ultra/docs/research/user-scenario-{date}.md`:
-
-```markdown
-# Round 1: User & Scenario Discovery
-
-> **Confidence**: [X]%
-> **Steps completed**: 10-11
-> **Completed**: [date]
-
-## Key Findings
-[3-5 bullet points]
-
-## Personas Defined
-[Names and one-line descriptions]
-
-## Scenarios Prioritized
-[Top 3 with scores]
-
-## Surprises
-[What was unexpected]
-```
-
-### 6. Present to User and Gate
-
-Show the User Scenarios summary. Ask:
-- Do these scenarios feel realistic?
-- Is anything missing from the journey?
-- Is the prioritization right?
-
-```
-[C] Continue — Scenarios validated, proceed to Round 2 (Feature Definition)
-[R] Revise — Adjust scenario details or prioritization
-[A] Add — Include additional scenario
-```
-
-**HALT — wait for user response before proceeding.**
-
-### 7. Handle Response
-
-- **[C]**: Load next step: `./step-20-user-stories.md`
-- **[R]**: Revise scenarios, update product.md §3, re-present
-- **[A]**: Add scenario (max 5 total), update, re-present
-
-## SUCCESS METRICS
-
-- 3-5 scenarios defined with full detail
-- Each scenario connected to a persona
-- Current flow AND desired flow documented
-- Scenarios prioritized by Frequency × Pain × Value
-- Round 1 research report written
-- Output written to product.md §3
-
-## FAILURE MODES
-
-- Scenarios that describe features instead of user journeys
-- Missing the "current flow" (how users cope today)
-- No emotional arc (scenarios feel clinical, not human)
-- All scenarios for one persona (need coverage across personas)
-- Not writing output before presenting to user
-
-## NEXT STEP
-
-After user selects [C], read and follow: `./step-20-user-stories.md`