ultra-builder-pro-cli 0.5.0

package/skills/ultra-research/steps/step-00-problem-validation.md

@@ -0,0 +1,154 @@
+# Step 00: Problem Validation
+
+## MANDATORY EXECUTION RULES
+
+- NEVER skip this step — unvalidated problems lead to wasted research
+- DO NOT generate solutions — this step validates the PROBLEM only
+- ASK questions ONE AT A TIME via AskUserQuestion — do not batch
+- PUSH on vague answers — "interesting" is not validation, "paying for it" is
+- WRITE output to spec file BEFORE presenting to user
+- ALL output in English (spec files); conversation in Chinese
+
+## PREREQUISITES
+
+- `.ultra/specs/discovery.md` exists (created by /ultra-init)
+- User has provided initial product idea or description
+
+## CONTEXT BOUNDARIES
+
+- Focus: Is this problem real, painful, and worth solving?
+- NOT about solutions, features, or architecture
+- NOT about market size (that's step-02)
+- You are a skeptical advisor, not a cheerleader
+
+## EXECUTION SEQUENCE
+
+### 1. Detect Product Stage
+
+Ask via AskUserQuestion to determine which forcing questions apply:
+
+| Stage | Indicators | Questions |
+|-------|-----------|-----------|
+| Pre-product (idea, no users) | No existing product | Q1, Q2, Q3 |
+| Has users (not paying) | Product exists, free users | Q2, Q4, Q5 |
+| Has paying customers | Revenue exists | Q4, Q5, Q6 |
+| Pure engineering/infra | Internal tool, no market | Q2, Q4 only |
+
+### 2. Ask Forcing Questions (ONE AT A TIME)
+
+For each applicable question, ask via AskUserQuestion. Push until you hear the "evidence" column — not the "red flags" column.
+
+#### Q1: Demand Reality
+**Ask**: "What is the strongest evidence someone actually wants this — not 'is interested,' but would be genuinely upset if it disappeared?"
+- **Push until you hear**: Specific behavior — paying, expanding usage, panicking when it breaks
+- **Red flags**: "People say it's interesting", waitlist signups, VC enthusiasm
+
+#### Q2: Status Quo
+**Ask**: "What are users doing RIGHT NOW to solve this — even badly? What does that workaround cost them?"
+- **Push until you hear**: Specific workflow — hours wasted, dollars lost, tools duct-taped together
+- **Red flags**: "Nothing — no solution exists" (if nobody is doing anything, the problem may not be painful enough)
+
+#### Q3: Desperate Specificity
+**Ask**: "Name the actual human who needs this most. Title? What gets them promoted? What gets them fired?"
+- **Push until you hear**: A name, a role, a specific consequence they face
+- **Red flags**: Category-level answers: "enterprises", "SMBs", "marketing teams"
+
+#### Q4: Narrowest Wedge
+**Ask**: "What is the smallest version someone would pay real money for — this week, not after you build the platform?"
+- **Push until you hear**: One feature, one workflow, shippable in days
+- **Red flags**: "Need full platform first", "can't strip it down"
+
+#### Q5: Observation & Surprise
+**Ask**: "Have you watched someone use this without helping them? What surprised you?"
+- **Push until you hear**: A specific surprise that contradicted assumptions
+- **Red flags**: "We sent a survey", "nothing surprising"
+
+#### Q6: Future-Fit
+**Ask**: "If the world looks meaningfully different in 3 years, does your product become more essential or less?"
+- **Push until you hear**: Specific claim about how user's world changes and why that increases value
+- **Red flags**: "Market growing 20% per year", "AI makes everything better"
+
+### 3. Smart-Skip Rules
+
+- If an earlier answer already covers a later question, skip it
+- If user says "just do it" or provides a fully formed plan → fast-track with note
+- Maximum 4 questions per session — prioritize by stage
+
+### 4. Synthesize & Write Output
+
+**WRITE IMMEDIATELY** to `.ultra/specs/discovery.md` §0:
+
+```markdown
+## §0 Problem Validation Summary
+
+### Product Stage
+- **Stage**: [Pre-product / Has users / Has paying customers / Engineering/Infra]
+- **Evidence**: [What indicates this stage]
+
+### Demand Signal
+- **Strength**: [Strong / Moderate / Weak / Unvalidated]
+- **Evidence**: [Specific behaviors observed]
+- **Risk**: [What could invalidate this demand]
+
+### Status Quo Analysis
+- **Current solutions**: [What users do today]
+- **Cost of workaround**: [Time, money, friction]
+- **Switching motivation**: [Why they'd change]
+
+### Target User Profile
+- **Primary**: [Specific role/person description]
+- **Stakes**: [What gets them promoted / fired]
+- **Pain frequency**: [Daily / Weekly / Occasional]
+
+### Narrowest Wedge
+- **MVP scope**: [Single feature/workflow]
+- **Willingness to pay**: [Evidence level]
+- **Ship timeline**: [Days / Weeks / Months]
+
+### Validation Confidence
+- **Overall**: [X]%
+- **Strongest signal**: [What gives most confidence]
+- **Biggest risk**: [What could be wrong]
+- **Recommended next step**: [Proceed / Investigate further / Pivot]
+```
+
+### 5. Present to User and Gate
+
+Show the Problem Validation Summary to user.
+
+Present assessment honestly — if the problem feels weak, say so. Better to catch it now.
+
+```
+[C] Continue — Problem validated, proceed to Opportunity Discovery
+[R] Revise — Discuss specific concerns before proceeding
+[P] Pivot — Problem is weak, explore different angle
+```
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Response
+
+- **[C]**: Load next step: `./step-01-opportunity-discovery.md`
+- **[R]**: Discuss concerns, revise §0, re-present
+- **[P]**: Help user reframe the problem, restart step-00
+
+## SUCCESS METRICS
+
+- Product stage correctly identified
+- At least 2 forcing questions asked and answered with evidence
+- Problem Validation Summary written to discovery.md §0
+- Confidence assessment is honest (not inflated)
+- User has explicitly confirmed [C] before proceeding
+
+## FAILURE MODES
+
+- Asking all 6 questions regardless of stage (wastes user time)
+- Accepting vague answers without pushing ("people are interested" → push harder)
+- Skipping this step because user seems confident
+- Inflating confidence to keep user happy
+- Not writing output before presenting to user
+- Proceeding without explicit [C] confirmation
+
+## NEXT STEP
+
+After user selects [C], read and follow: `./step-01-opportunity-discovery.md`

package/skills/ultra-research/steps/step-01-opportunity-discovery.md

@@ -0,0 +1,172 @@
+# Step 01: Opportunity Discovery
+
+## MANDATORY EXECUTION RULES
+
+- WEB SEARCH REQUIRED — verify opportunities against real market data
+- Frame opportunities from CUSTOMER perspective, not product perspective
+- Generate multiple solutions per opportunity — never commit to the first idea
+- WRITE output to spec file BEFORE presenting to user
+- ALL output in English (spec files); conversation in Chinese
+
+## PREREQUISITES
+
+- Step 00 (Problem Validation) completed with [C]
+- `.ultra/specs/discovery.md` §0 exists
+
+## CONTEXT BOUNDARIES
+
+- Focus: Map the opportunity space using Opportunity Solution Tree (Teresa Torres)
+- Opportunities are CUSTOMER NEEDS, not features
+- Frame as: "I struggle to..." / "I wish I could..." / "It frustrates me that..."
+- Based on *Continuous Discovery Habits* methodology
+
+## SEARCH STRATEGY (MANDATORY)
+
+Execute these web searches in parallel:
+
+```
+Search: "{{product_domain}} user pain points complaints"
+Search: "{{product_domain}} customer needs unmet"
+Search: "{{product_domain}} market gaps opportunities"
+Search: "{{product_domain}} user research findings"
+```
+
+Citation requirement: Every factual claim MUST include `Source: [URL]`
+No-source claims → mark as `⚠️ Speculation`
+
+## EXECUTION SEQUENCE
+
+### 1. Define Desired Outcome
+
+Ask user via AskUserQuestion:
+"What single measurable business/product outcome are we pursuing? (e.g., 'Reduce customer onboarding time by 50%', 'Reach $1M ARR in 12 months')"
+
+If user is unsure, help them formulate one from step-00 findings.
+
+### 2. Map Opportunity Space
+
+Using web search results + step-00 insights, identify 5-8 customer opportunities.
+
+**Frame each opportunity from customer perspective:**
+- BAD: "Add AI-powered search" (this is a solution)
+- GOOD: "I struggle to find relevant results in large document collections" (this is an opportunity)
+
+### 3. Prioritize Opportunities
+
+Score each opportunity using Dan Olsen's Opportunity Score:
+
+```
+Opportunity Score = Importance × (1 - Satisfaction)
+```
+
+Where:
+- **Importance** (1-10): How much does this matter to the target user?
+- **Satisfaction** (0-1): How well do current solutions address this? (0 = not at all, 1 = perfectly)
+
+Rank by score. Focus on top 2-3 opportunities.
+
+### 4. Solution Brainstorm
+
+For each top opportunity (top 2-3), generate 3+ solution approaches from different perspectives:
+
+| Perspective | Approach |
+|------------|---------|
+| PM perspective | User workflow optimization |
+| Designer perspective | Experience/interaction innovation |
+| Engineer perspective | Technical capability leverage |
+
+**Rule**: Never commit to the first idea. The best solution often emerges from comparing alternatives.
+
+### 5. Write Output
+
+**WRITE IMMEDIATELY** to `.ultra/specs/discovery.md` §1:
+
+```markdown
+## §1 Opportunity Space
+
+### Desired Outcome
+- **Outcome**: [Single measurable outcome]
+- **Metric**: [How we measure it]
+- **Timeline**: [When we expect to see movement]
+
+### Opportunity Map
+
+| # | Opportunity (Customer Framing) | Importance | Satisfaction | Score | Source |
+|---|-------------------------------|-----------|-------------|-------|--------|
+| O1 | "I struggle to..." | 9 | 0.2 | 7.2 | [URL] |
+| O2 | "I wish I could..." | 8 | 0.3 | 5.6 | [URL] |
+| O3 | "It frustrates me that..." | 7 | 0.4 | 4.2 | [URL] |
+| O4 | ... | ... | ... | ... | ... |
+| O5 | ... | ... | ... | ... | ... |
+
+### Prioritized Opportunities (Top 3)
+
+#### Opportunity 1: [Customer-framed description]
+- **Importance**: [X]/10 — [Why this matters]
+- **Current satisfaction**: [X] — [How users cope today]
+- **Score**: [X]
+- **Evidence**: [Source URL]
+
+**Solution Approaches:**
+1. **PM approach**: [Description] — Pros: [...] Cons: [...]
+2. **Design approach**: [Description] — Pros: [...] Cons: [...]
+3. **Engineering approach**: [Description] — Pros: [...] Cons: [...]
+
+#### Opportunity 2: [Customer-framed description]
+[Same structure]
+
+#### Opportunity 3: [Customer-framed description]
+[Same structure]
+
+### Opportunities Deprioritized
+| # | Opportunity | Score | Reason for Deprioritization |
+|---|------------|-------|-----------------------------|
+| O4 | ... | ... | [Why not now] |
+| O5 | ... | ... | [Why not now] |
+
+### Key Insight
+[One paragraph: What is the non-obvious insight from this opportunity analysis?]
+```
+
+### 6. Present to User and Gate
+
+Show the Opportunity Space summary. Highlight:
+- The top 3 opportunities and why they ranked highest
+- Any surprising findings from web research
+- Which solution approaches seem most promising
+
+```
+[C] Continue — Opportunity space mapped, proceed to Market Assessment
+[R] Revise — Adjust opportunity scoring or add missing opportunities
+[D] Discuss — Explore specific opportunities in more depth
+```
+
+**HALT — wait for user response before proceeding.**
+
+### 7. Handle Response
+
+- **[C]**: Load next step: `./step-02-market-assessment.md`
+- **[R]**: Revise scoring/opportunities, update discovery.md §1, re-present
+- **[D]**: Deep-dive into specific opportunity, then re-present gate
+
+## SUCCESS METRICS
+
+- Desired outcome is specific and measurable
+- At least 5 opportunities identified, framed from customer perspective
+- Opportunity scores calculated with importance and satisfaction ratings
+- Top 3 opportunities each have 3+ solution approaches
+- All factual claims have source citations
+- Output written to discovery.md §1
+
+## FAILURE MODES
+
+- Framing opportunities as features/solutions instead of customer needs
+- Scoring without web research evidence
+- Only generating 1 solution per opportunity
+- Accepting user's first solution idea without exploring alternatives
+- Missing citation sources for market claims
+- Not writing output before presenting to user
+
+## NEXT STEP
+
+After user selects [C], read and follow: `./step-02-market-assessment.md`

package/skills/ultra-research/steps/step-02-market-assessment.md

@@ -0,0 +1,195 @@
+# Step 02: Market Assessment
+
+## MANDATORY EXECUTION RULES
+
+- WEB SEARCH REQUIRED — no market sizing without real data
+- USE DUAL APPROACH — both top-down and bottom-up estimates required
+- CROSS-VALIDATE — if top-down and bottom-up differ by >3x, investigate why
+- CITE EVERY NUMBER — no unsupported market figures
+- WRITE output to spec file BEFORE presenting to user
+- ALL output in English (spec files); conversation in Chinese
+
+## PREREQUISITES
+
+- Step 01 (Opportunity Discovery) completed with [C]
+- `.ultra/specs/discovery.md` §0-1 exist
+
+## CONTEXT BOUNDARIES
+
+- Focus: How big is this market? Is it worth pursuing?
+- Use the prioritized opportunities from step-01 to scope the market
+- This is about MARKET SIZE, not competitive positioning (that's step-03)
+
+## SEARCH STRATEGY (MANDATORY)
+
+Execute these web searches in parallel:
+
+```
+Search: "{{product_domain}} market size TAM 2024 2025 2026"
+Search: "{{product_domain}} market growth rate CAGR forecast"
+Search: "{{product_domain}} industry revenue report"
+Search: "{{product_domain}} market segmentation analysis"
+Search: "{{product_domain}} pricing model average revenue per user"
+```
+
+**Source priority**: Industry reports (Gartner, Statista, IBISWorld, Grand View Research) > Company filings > News articles > Blog posts
+
+## EXECUTION SEQUENCE
+
+### 1. Top-Down Estimate (TAM → SAM → SOM)
+
+Start with the broadest market definition and narrow down:
+
+**TAM (Total Addressable Market)**:
+- What is the total global market for this category?
+- Search for industry reports with specific dollar figures
+- Include year and source for every number
+
+**SAM (Serviceable Available Market)**:
+- What slice of TAM can we actually serve?
+- Filter by: geography, customer segment, technology fit, regulatory access
+- Show the filtering logic explicitly
+
+**SOM (Serviceable Obtainable Market)**:
+- What can we realistically capture in 1-3 years?
+- Consider: team size, distribution, brand, competition
+- Be honest — first-year SOM for a startup is tiny
+
+### 2. Bottom-Up Estimate
+
+Calculate independently from unit economics:
+
+```
+SOM = Target customers × Conversion rate × Average revenue per customer × Retention
+```
+
+For each variable:
+- **Target customers**: How many potential users in your target segment? (Source required)
+- **Conversion rate**: What % will actually adopt? (Industry benchmark required)
+- **ARPU**: What will they pay? (Comparable pricing data required)
+- **Retention**: Annual retention rate? (Industry benchmark required)
+
+### 3. Cross-Validation
+
+Compare top-down SOM vs bottom-up SOM:
+- If within 2x: Good — use the average
+- If 2-3x apart: Acceptable — note the range and explain the gap
+- If >3x apart: Investigate — one of your assumptions is wrong
+
+### 4. Growth Driver Analysis
+
+Identify 3-5 factors that will grow or shrink this market:
+
+For each driver:
+- **Direction**: Expanding or contracting?
+- **Magnitude**: How much impact?
+- **Timeline**: When does this take effect?
+- **Evidence**: Source URL
+
+### 5. Write Output
+
+**WRITE IMMEDIATELY** to `.ultra/specs/discovery.md` §2:
+
+```markdown
+## §2 Market Assessment
+
+### Market Sizing Summary
+
+| Metric | Current Estimate | 2-3 Year Projection | Source |
+|--------|-----------------|---------------------|--------|
+| TAM | $[X]B | $[X]B | [URL] |
+| SAM | $[X]M | $[X]M | [URL] |
+| SOM | $[X]M | $[X]M | Calculated |
+
+### Top-Down Analysis
+
+#### TAM: $[X]B ([Year])
+- **Definition**: [What market category]
+- **Source**: [Report name + URL]
+- **Growth**: [X]% CAGR ([Year]-[Year])
+
+#### SAM: $[X]M
+- **TAM filter 1**: [Geographic] — reduces to $[X]B
+- **TAM filter 2**: [Segment] — reduces to $[X]M
+- **TAM filter 3**: [Technology fit] — reduces to $[X]M
+
+#### SOM: $[X]M (Year 1-3)
+- **Realistic capture**: [X]% of SAM
+- **Basis**: [Why this share is achievable]
+- **Comparable**: [Similar company achieved X% in Y time]
+
+### Bottom-Up Analysis
+
+| Variable | Value | Source |
+|----------|-------|--------|
+| Target customers | [N] | [URL or calculation] |
+| Conversion rate | [X]% | [Industry benchmark + URL] |
+| ARPU (annual) | $[X] | [Comparable pricing + URL] |
+| Retention rate | [X]% | [Industry benchmark + URL] |
+| **Year 1 Revenue** | **$[X]** | **Calculated** |
+| **Year 3 Revenue** | **$[X]** | **Calculated** |
+
+### Cross-Validation
+- **Top-down SOM**: $[X]M
+- **Bottom-up Year 3**: $[X]M
+- **Ratio**: [X]x
+- **Assessment**: [Within range / Gap explanation]
+
+### Growth Drivers
+
+| # | Driver | Direction | Impact | Timeline | Source |
+|---|--------|-----------|--------|----------|--------|
+| 1 | [Technology trend] | Expanding | High | 1-2yr | [URL] |
+| 2 | [Regulatory change] | Expanding | Medium | 2-3yr | [URL] |
+| 3 | [Demographic shift] | Expanding | Medium | 3-5yr | [URL] |
+| 4 | [Competitive pressure] | Contracting | Low | Now | [URL] |
+
+### Market Assessment Confidence
+- **Overall confidence**: [X]%
+- **Strongest data point**: [What we're most sure about]
+- **Weakest assumption**: [What could be most wrong]
+- **Recommendation**: [Market worth pursuing / Needs more validation / Too small]
+```
+
+### 6. Present to User and Gate
+
+Show the Market Assessment summary. Highlight:
+- Whether top-down and bottom-up estimates align
+- The single biggest growth driver
+- Any concerns about market size or timing
+
+```
+[C] Continue — Market assessed, proceed to Competitive Landscape
+[R] Revise — Adjust assumptions or investigate discrepancies
+[S] Search more — Need additional data on specific aspect
+```
+
+**HALT — wait for user response before proceeding.**
+
+### 7. Handle Response
+
+- **[C]**: Load next step: `./step-03-competitive-landscape.md`
+- **[R]**: Revise assumptions, update discovery.md §2, re-present
+- **[S]**: Execute targeted searches, update analysis, re-present
+
+## SUCCESS METRICS
+
+- Both top-down AND bottom-up estimates completed
+- Every dollar figure has a source citation
+- Cross-validation performed with gap analysis
+- At least 3 growth drivers identified with evidence
+- Confidence assessment is honest
+- Output written to discovery.md §2
+
+## FAILURE MODES
+
+- Using only top-down OR only bottom-up (need both)
+- Market figures without source citations
+- Inflating SOM to make the opportunity look bigger
+- Ignoring >3x gap between top-down and bottom-up
+- Using stale data (>2 years old) without noting limitations
+- Not writing output before presenting to user
+
+## NEXT STEP
+
+After user selects [C], read and follow: `./step-03-competitive-landscape.md`