ultra-builder-pro-cli 0.5.0

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

@@ -0,0 +1,169 @@
+# 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

@@ -0,0 +1,181 @@
+# 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`

package/skills/ultra-research/steps/step-20-user-stories.md

@@ -0,0 +1,156 @@
+# Step 20: User Stories & Acceptance Criteria
+
+## MANDATORY EXECUTION RULES
+
+- DERIVE stories from scenarios (step-11) — not invented from thin air
+- EVERY story has acceptance criteria — no story ships without testable conditions
+- USE standard format: "As a [persona], I want [action], so that [benefit]"
+- PRIORITIZE using MoSCoW: Must / Should / Could / Won't
+- WRITE output to spec file BEFORE presenting to user
+- ALL output in English (spec files); conversation in Chinese
+
+## PREREQUISITES
+
+- Step 11 (User Scenarios) completed with [C]
+- `.ultra/specs/product.md` §1-3 exist
+
+## CONTEXT BOUNDARIES
+
+- Focus: What specific capabilities does the product need?
+- Stories must trace back to scenarios and personas
+- This is about WHAT the product does, not HOW it's built
+- Acceptance criteria must be testable and specific
+
+## EXECUTION SEQUENCE
+
+### 1. Extract Stories from Scenarios
+
+For each scenario from step-11, decompose into user stories:
+
+**Mapping**: Scenario → Stories
+- S1 (highest priority scenario) → 3-5 stories
+- S2 → 2-4 stories
+- S3 → 2-3 stories
+- Total: 8-15 stories for MVP
+
+### 2. Write Stories with Acceptance Criteria
+
+For each story:
+
+```
+As a [Persona Name],
+I want [specific action],
+so that [measurable benefit].
+
+Acceptance Criteria:
+- Given [context], when [action], then [expected result]
+- Given [context], when [edge case], then [expected result]
+- [Performance requirement if applicable]
+```
+
+### 3. Prioritize with MoSCoW
+
+Discuss with user via AskUserQuestion:
+"Here are the stories I've derived from our scenarios. For MVP, which are Must-Have vs Nice-to-Have?"
+
+| Priority | Definition | Guidance |
+|----------|-----------|---------|
+| **Must** | Product is useless without this | Blocks primary scenario |
+| **Should** | Important but workaround exists | Enhances primary scenario |
+| **Could** | Nice to have if time allows | Supports secondary scenarios |
+| **Won't** | Explicitly excluded for now | Out of scope (with rationale) |
+
+### 4. Write Output
+
+**WRITE IMMEDIATELY** to `.ultra/specs/product.md` §4:
+
+```markdown
+## §4 User Stories & Features
+
+### Story Map Overview
+
+| ID | Story | Persona | Scenario | Priority | Complexity |
+|----|-------|---------|----------|----------|-----------|
+| US-01 | [Short title] | [P1] | S1 | Must | [S/M/L] |
+| US-02 | [Short title] | [P1] | S1 | Must | [S/M/L] |
+| US-03 | [Short title] | [P1] | S2 | Must | [S/M/L] |
+| US-04 | [Short title] | [P2] | S2 | Should | [S/M/L] |
+| ... | ... | ... | ... | ... | ... |
+
+### Must-Have Stories
+
+#### US-01: [Title]
+**As a** [Persona], **I want** [action], **so that** [benefit].
+
+**Acceptance Criteria**:
+- [ ] Given [context], when [action], then [result]
+- [ ] Given [context], when [edge case], then [result]
+- [ ] [Performance: response time < Xms]
+
+**Traces to**: Scenario [S#], Opportunity [O#]
+**Complexity**: [S/M/L] — [Brief rationale]
+
+#### US-02: [Title]
+[Same structure]
+
+#### US-03: [Title]
+[Same structure]
+
+### Should-Have Stories
+
+#### US-04: [Title]
+[Same structure]
+
+### Could-Have Stories
+
+#### US-07: [Title]
+[Same structure]
+
+### Story Statistics
+- **Total stories**: [N]
+- **Must-have**: [N] ([X]%)
+- **Should-have**: [N] ([X]%)
+- **Could-have**: [N] ([X]%)
+- **Traceability**: [X]% of stories trace to scenarios
+```
+
+### 5. Present to User and Gate
+
+Show the User Stories summary. Ask:
+- Are the Must-Have stories correct?
+- Any stories missing?
+- Are acceptance criteria testable?
+
+```
+[C] Continue — Stories validated, proceed to Features & Scope
+[R] Revise — Adjust stories, priorities, or acceptance criteria
+[A] Add — Include additional stories
+```
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Response
+
+- **[C]**: Load next step: `./step-21-features-scope.md`
+- **[R]**: Revise stories, update product.md §4, re-present
+- **[A]**: Add stories, update, re-present
+
+## SUCCESS METRICS
+
+- 8-15 user stories derived from scenarios
+- Every story has testable acceptance criteria
+- MoSCoW prioritization applied with user input
+- Stories trace back to scenarios and personas
+- Output written to product.md §4
+
+## FAILURE MODES
+
+- Stories not connected to any scenario
+- Acceptance criteria are vague ("it should work well")
+- All stories are Must-Have (no real prioritization happened)
+- Too many stories (>20 for MVP — scope creep)
+- Not writing output before presenting to user
+
+## NEXT STEP
+
+After user selects [C], read and follow: `./step-21-features-scope.md`

package/skills/ultra-research/steps/step-21-features-scope.md

@@ -0,0 +1,157 @@
+# Step 21: Features & Scope Definition
+
+## MANDATORY EXECUTION RULES
+
+- EXPLICITLY DEFINE what is OUT of scope — this prevents scope creep
+- GROUP stories into features — features are implementable units
+- EVERY exclusion needs a RATIONALE — "not now" is not enough
+- WRITE output to spec file BEFORE presenting to user
+- ALL output in English (spec files); conversation in Chinese
+
+## PREREQUISITES
+
+- Step 20 (User Stories) completed with [C]
+- `.ultra/specs/product.md` §1-4 exist
+
+## CONTEXT BOUNDARIES
+
+- Focus: Group stories into features, define scope boundaries
+- Features are clusters of related stories that deliver a capability
+- "Features Out" is as important as "Features In"
+- Reference step-04 (Strategic Trade-offs) for scope decisions
+
+## EXECUTION SEQUENCE
+
+### 1. Group Stories into Features
+
+Cluster related user stories into features:
+
+```
+Feature A: [Name]
+├── US-01: [Story]
+├── US-02: [Story]
+└── US-03: [Story]
+
+Feature B: [Name]
+├── US-04: [Story]
+└── US-05: [Story]
+```
+
+Each feature should be:
+- Independently valuable (delivers user value on its own)
+- Estimable (can assess complexity)
+- Testable (can verify it works end-to-end)
+
+### 2. Define Scope Boundaries
+
+For each potential feature, classify:
+
+| Classification | Meaning |
+|---------------|---------|
+| **In scope (MVP)** | Must-have stories, ships in v1 |
+| **In scope (v2)** | Should-have stories, planned for later |
+| **Out of scope** | Won't build — with explicit rationale |
+
+### 3. Document "Features Out"
+
+For each excluded feature, document:
+- What it is
+- Why it's excluded (reference strategic trade-offs from step-04)
+- When it might be reconsidered
+- What users should do instead
+
+This prevents:
+- Future scope creep ("but we said we'd do X")
+- Re-debating settled decisions
+- Building things that conflict with strategy
+
+### 4. Write Output
+
+**WRITE IMMEDIATELY** to `.ultra/specs/product.md` §5:
+
+```markdown
+## §5 Feature Scope
+
+### Features In (MVP)
+
+#### Feature 1: [Name]
+- **Description**: [What this feature does]
+- **Stories**: US-01, US-02, US-03
+- **User value**: [What user can do with this]
+- **Priority**: Must-Have
+- **Complexity**: [S/M/L]
+
+#### Feature 2: [Name]
+- **Description**: [What this feature does]
+- **Stories**: US-04, US-05
+- **User value**: [What user can do with this]
+- **Priority**: Must-Have
+- **Complexity**: [S/M/L]
+
+#### Feature 3: [Name]
+[Same structure]
+
+### Features In (v2 — Planned)
+
+#### Feature 4: [Name]
+- **Description**: [What this feature does]
+- **Stories**: US-07, US-08
+- **Rationale for deferral**: [Why not MVP]
+- **Trigger to build**: [When to reconsider]
+
+### Features Out (Explicitly Excluded)
+
+| Feature | Rationale | Reconsider When | Alternative |
+|---------|-----------|----------------|-------------|
+| [Feature X] | [Why excluded — reference strategy §4] | [Condition] | [What users do instead] |
+| [Feature Y] | [Why excluded] | [Condition] | [Alternative] |
+| [Feature Z] | [Why excluded] | [Condition] | [Alternative] |
+
+### Scope Summary
+- **MVP features**: [N] features, [N] stories
+- **v2 features**: [N] features, [N] stories
+- **Excluded features**: [N] features
+- **Scope confidence**: [X]%
+```
+
+### 5. Present to User and Gate
+
+Show the Feature Scope summary. Ask:
+- Is the MVP scope right? Too big? Too small?
+- Are the exclusions correct?
+- Any missing features?
+
+```
+[C] Continue — Scope locked, proceed to Success Metrics
+[R] Revise — Adjust feature grouping or scope boundaries
+[E] Expand — Move something from v2 to MVP
+[T] Trim — Move something from MVP to v2
+```
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Response
+
+- **[C]**: Load next step: `./step-22-success-metrics.md`
+- **[R]**: Revise features, update product.md §5, re-present
+- **[E]/[T]**: Adjust scope, update, re-present
+
+## SUCCESS METRICS
+
+- Stories grouped into coherent features
+- Clear MVP vs v2 scope boundary
+- Every exclusion has a rationale and reconsideration trigger
+- Features trace to user stories and scenarios
+- Output written to product.md §5
+
+## FAILURE MODES
+
+- No "Features Out" section (everything is in scope)
+- Features that don't map to any user stories
+- Exclusion rationale is just "not now" (needs specific reason)
+- MVP scope is too large (>5-7 features for a first version)
+- Not writing output before presenting to user
+
+## NEXT STEP
+
+After user selects [C], read and follow: `./step-22-success-metrics.md`