ultra-builder-pro-cli 0.5.0

package/skills/ultra-research/steps/step-22-success-metrics.md

@@ -0,0 +1,195 @@
+# Step 22: Success Metrics
+
+## MANDATORY EXECUTION RULES
+
+- EVERY METRIC must have a specific numerical TARGET — not "improve X"
+- INCLUDE both business AND user metrics
+- DEFINE how each metric is MEASURED — not just what to measure
+- BASELINE required — you can't improve what you haven't measured
+- WRITE output to spec file BEFORE presenting to user
+- ALL output in English (spec files); conversation in Chinese
+
+## PREREQUISITES
+
+- Step 21 (Features & Scope) completed with [C]
+- `.ultra/specs/product.md` §1-5 exist
+
+## CONTEXT BOUNDARIES
+
+- Focus: How will we know if this product is succeeding?
+- Metrics must be measurable, specific, and time-bound
+- Connect metrics to strategic goals from step-04
+- This is the LAST step of Round 2
+
+## SEARCH STRATEGY (MANDATORY)
+
+Execute these web searches:
+
+```
+Search: "{{product_domain}} key metrics KPIs benchmarks"
+Search: "{{product_domain}} SaaS metrics success benchmarks"
+Search: "{{product_domain}} user engagement retention benchmarks"
+Search: "{{product_domain}} north star metric examples"
+```
+
+## EXECUTION SEQUENCE
+
+### 1. Define North Star Metric
+
+Ask user via AskUserQuestion:
+"What single metric best captures whether this product is delivering value? (e.g., 'Weekly active workflows completed', 'Time saved per user per week')"
+
+The North Star Metric should:
+- Reflect core value delivery
+- Be leading (not lagging)
+- Be actionable (team can influence it)
+
+### 2. Define Business Metrics
+
+| Metric | What to define |
+|--------|---------------|
+| Revenue/adoption targets | Month 1, 3, 6, 12 |
+| Growth rate | MoM or WoW targets |
+| Retention | Day 1, Day 7, Day 30 |
+| Conversion | Free → Paid (if applicable) |
+| Unit economics | CAC, LTV, LTV/CAC ratio |
+
+Use web search benchmarks for realistic targets.
+
+### 3. Define User Metrics
+
+| Metric | What to define |
+|--------|---------------|
+| Task completion | Success rate for key scenarios |
+| Time on task | vs baseline (current workflow) |
+| User satisfaction | NPS or CSAT target |
+| Feature adoption | % of users using key features |
+| Error rate | Failure frequency |
+
+### 4. Write Output
+
+**WRITE IMMEDIATELY** to `.ultra/specs/product.md` §6:
+
+```markdown
+## §6 Success Metrics
+
+### North Star Metric
+- **Metric**: [Name]
+- **Definition**: [Exactly what is measured]
+- **Current baseline**: [Current state or industry benchmark]
+- **Target**: [Specific number]
+- **Timeline**: [When to achieve]
+- **Measurement method**: [How to collect this data]
+
+### Business Metrics
+
+| Metric | Baseline | Target (M3) | Target (M6) | Target (M12) | How Measured |
+|--------|----------|-------------|-------------|--------------|-------------|
+| [Revenue/Users] | [N/A or current] | [Target] | [Target] | [Target] | [Method] |
+| [Growth rate] | [Benchmark] | [Target] | [Target] | [Target] | [Method] |
+| [Retention D30] | [Benchmark] | [Target] | [Target] | [Target] | [Method] |
+| [Conversion] | [Benchmark] | [Target] | [Target] | [Target] | [Method] |
+
+_Benchmark sources: [URLs]_
+
+### User Metrics
+
+| Metric | Baseline | Target | How Measured |
+|--------|----------|--------|-------------|
+| Task completion rate | [Current %] | [Target %] | [Method] |
+| Time on task | [Current min] | [Target min] | [Method] |
+| User satisfaction (NPS) | [Industry avg] | [Target] | [Survey] |
+| Feature adoption | [N/A] | [Target %] | [Analytics] |
+| Error rate | [Current %] | [Target %] | [Logging] |
+
+### Metric Prioritization
+
+| Priority | Metric | Why |
+|----------|--------|-----|
+| P0 (check daily) | [North Star] | [Core value signal] |
+| P0 (check daily) | [Critical metric] | [Business health] |
+| P1 (check weekly) | [Important metric] | [Growth signal] |
+| P2 (check monthly) | [Supporting metric] | [Quality signal] |
+
+### Anti-Metrics (What NOT to Optimize)
+
+| Anti-Metric | Why Not | What It Could Sacrifice |
+|------------|---------|------------------------|
+| [e.g., Page views] | [Vanity metric] | [Could sacrifice quality for clicks] |
+| [e.g., Time in app] | [Could mean confusion] | [Could sacrifice efficiency] |
+
+### Round 2 Summary
+
+**Feature Definition Confidence**:
+- **Story completeness**: [X]% — [One-line assessment]
+- **Scope clarity**: [X]% — [One-line assessment]
+- **Metric measurability**: [X]% — [One-line assessment]
+- **Overall R2 confidence**: [X]%
+```
+
+### 5. Write Round 2 Research Report
+
+**WRITE** to `.ultra/docs/research/feature-definition-{date}.md`:
+
+```markdown
+# Round 2: Feature Definition
+
+> **Confidence**: [X]%
+> **Steps completed**: 20-22
+> **Completed**: [date]
+
+## Key Findings
+[3-5 bullet points]
+
+## Stories Created
+[Count by priority: Must/Should/Could]
+
+## Scope Decisions
+[Key inclusions and exclusions]
+
+## Metrics Defined
+[North Star + top 3 metrics]
+```
+
+### 6. Present to User and Gate
+
+Show the Success Metrics summary. Ask:
+- Are the targets realistic?
+- Is the North Star metric right?
+- Any metrics missing?
+
+```
+[C] Continue — Metrics defined, proceed to Round 3 (Architecture Design)
+[R] Revise — Adjust targets or metrics
+[D] Discuss — Explore specific metric benchmarks
+```
+
+**HALT — wait for user response before proceeding.**
+
+### 7. Handle Response
+
+- **[C]**: Load next step: `./step-30-architecture-context.md`
+- **[R]**: Revise metrics, update product.md §6, re-present
+- **[D]**: Deep-dive specific benchmarks, then re-present gate
+
+## SUCCESS METRICS
+
+- North Star metric defined with baseline and target
+- Business metrics have specific targets at M3/M6/M12
+- User metrics have baselines and targets
+- Benchmark sources cited from web search
+- Anti-metrics defined (what NOT to optimize)
+- Round 2 research report written
+- Output written to product.md §6
+
+## FAILURE MODES
+
+- Metrics without specific targets ("improve retention")
+- No baseline or benchmark for comparison
+- Only business metrics, no user metrics (or vice versa)
+- Unrealistic targets (100% retention, 0% error rate)
+- Not writing output before presenting to user
+
+## NEXT STEP
+
+After user selects [C], read and follow: `./step-30-architecture-context.md`

package/skills/ultra-research/steps/step-30-architecture-context.md

@@ -0,0 +1,154 @@
+# Step 30: Architecture Context
+
+## MANDATORY EXECUTION RULES
+
+- WEB SEARCH REQUIRED — verify technology claims against official docs
+- USE Context7 MCP for framework/library documentation lookups
+- ARCHITECTURE FOLLOWS PRODUCT — decisions must trace to product requirements
+- WRITE output to spec file BEFORE presenting to user
+- ALL output in English (spec files); conversation in Chinese
+
+## PREREQUISITES
+
+- Round 2 completed (steps 20-22) with [C], OR user chose "Architecture Change" starting at step-30
+- `.ultra/specs/architecture.md` exists
+
+## CONTEXT BOUNDARIES
+
+- Focus: Quality goals, constraints, and system context (arc42 §1-3)
+- Decisions must be grounded in product requirements from product.md
+- This is about WHAT the system must achieve, not HOW to build it (that's step-31)
+
+## SEARCH STRATEGY (MANDATORY)
+
+```
+Search: "{{product_domain}} architecture quality attributes"
+Search: "{{product_domain}} system integration patterns"
+Search: "{{product_domain}} technical constraints regulations"
+```
+
+Use Context7 MCP for specific framework/library documentation.
+
+## EXECUTION SEQUENCE
+
+### 1. Define Quality Goals
+
+Derive from product.md §6 (Success Metrics) and user scenarios:
+
+| Quality Attribute | Concrete Scenario | Priority |
+|------------------|-------------------|----------|
+| Performance | [e.g., "API response < 200ms for 95th percentile"] | [1-3] |
+| Scalability | [e.g., "Handle 10K concurrent users"] | [1-3] |
+| Security | [e.g., "SOC 2 compliance, encrypted at rest"] | [1-3] |
+| Availability | [e.g., "99.9% uptime, < 5min recovery"] | [1-3] |
+| Maintainability | [e.g., "New developer productive in < 1 week"] | [1-3] |
+
+Ask user via AskUserQuestion: "Which quality attributes matter most? Performance? Security? Scalability?"
+
+### 2. Identify Constraints
+
+**Technical constraints**:
+- Required platforms/browsers
+- Mandatory integrations
+- Technology restrictions (e.g., "must use Python for ML team compatibility")
+
+**Organizational constraints**:
+- Team size and skill profile
+- Budget limitations
+- Timeline constraints
+
+**Regulatory constraints**:
+- Data privacy (GDPR, CCPA)
+- Industry regulations
+- Compliance requirements
+
+### 3. Map System Context
+
+Identify all external systems and interfaces:
+
+**Users**: Who interacts with the system?
+**External systems**: What APIs, services, databases does it connect to?
+**Data flows**: What data enters and leaves the system?
+
+### 4. Write Output
+
+**WRITE IMMEDIATELY** to `.ultra/specs/architecture.md` §1-3:
+
+```markdown
+## §1 Quality Goals
+
+| Priority | Quality Attribute | Scenario | Metric |
+|----------|------------------|----------|--------|
+| 1 | [Attribute] | [Concrete scenario] | [Measurable target] |
+| 2 | [Attribute] | [Concrete scenario] | [Measurable target] |
+| 3 | [Attribute] | [Concrete scenario] | [Measurable target] |
+
+## §2 Constraints
+
+### Technical Constraints
+| Constraint | Rationale | Impact |
+|-----------|-----------|--------|
+| [Constraint] | [Why this exists] | [What it limits] |
+
+### Organizational Constraints
+| Constraint | Rationale | Impact |
+|-----------|-----------|--------|
+| [Constraint] | [Why this exists] | [What it limits] |
+
+### Regulatory Constraints
+| Constraint | Rationale | Impact |
+|-----------|-----------|--------|
+| [Constraint] | [Why this exists] | [What it limits] |
+
+## §3 System Context
+
+### Context Diagram
+
+**Users**:
+- [User type 1]: [How they interact]
+- [User type 2]: [How they interact]
+
+**External Systems**:
+| System | Direction | Data | Protocol | Notes |
+|--------|-----------|------|----------|-------|
+| [System A] | Inbound | [What data] | [REST/gRPC/etc] | [Notes] |
+| [System B] | Outbound | [What data] | [Protocol] | [Notes] |
+| [System C] | Bidirectional | [What data] | [Protocol] | [Notes] |
+
+**Data Flows**:
+- [User] → [System] → [External]: [Description of flow]
+- [External] → [System] → [User]: [Description of flow]
+```
+
+### 5. Present to User and Gate
+
+```
+[C] Continue — Context defined, proceed to Solution Strategy
+[R] Revise — Adjust quality goals, constraints, or context
+```
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Response
+
+- **[C]**: Load next step: `./step-31-solution-strategy.md`
+- **[R]**: Revise, update architecture.md §1-3, re-present
+
+## SUCCESS METRICS
+
+- Quality goals are specific and measurable (not "good performance")
+- Constraints identified across technical/organizational/regulatory
+- System context shows all external interfaces
+- All quality goals trace to product requirements
+- Output written to architecture.md §1-3
+
+## FAILURE MODES
+
+- Vague quality goals ("system should be fast")
+- Missing regulatory constraints
+- System context missing key external integrations
+- Quality goals not derived from product requirements
+
+## NEXT STEP
+
+After user selects [C], read and follow: `./step-31-solution-strategy.md`

package/skills/ultra-research/steps/step-31-solution-strategy.md

@@ -0,0 +1,172 @@
+# Step 31: Solution Strategy & Tech Stack
+
+## MANDATORY EXECUTION RULES
+
+- WEB SEARCH REQUIRED — verify all technology claims
+- USE Context7 MCP for framework documentation
+- COMPARE TOP 3 OPTIONS for every major tech decision
+- EVERY CHOICE needs RATIONALE — "it's popular" is not enough
+- WRITE output to spec file BEFORE presenting to user
+- ALL output in English (spec files); conversation in Chinese
+
+## PREREQUISITES
+
+- Step 30 (Architecture Context) completed with [C]
+- `.ultra/specs/architecture.md` §1-3 exist
+
+## CONTEXT BOUNDARIES
+
+- Focus: Tech stack selection with evidence-based rationale (arc42 §4)
+- Decisions must satisfy quality goals from §1
+- Decisions must respect constraints from §2
+- Compare options — never recommend without alternatives analyzed
+
+## SEARCH STRATEGY (MANDATORY)
+
+For each major technology decision:
+
+```
+Search: "[option A] vs [option B] vs [option C] {{product_domain}} 2024 2025"
+Search: "[chosen framework] production performance benchmarks"
+Search: "[chosen framework] scalability limitations"
+Search: "[chosen database] vs alternatives for {{use_case}}"
+```
+
+Use Context7 MCP: Query official docs for each selected technology.
+
+## EXECUTION SEQUENCE
+
+### 1. Identify Key Technology Decisions
+
+Based on system context (§3) and quality goals (§1):
+
+| Decision Area | What to Decide |
+|--------------|---------------|
+| Language/Runtime | Primary programming language |
+| Web Framework | API/web framework |
+| Database | Primary data store |
+| Caching | Caching layer (if needed) |
+| Authentication | Auth approach |
+| Hosting | Cloud/infrastructure |
+| CI/CD | Build and deploy pipeline |
+| Monitoring | Observability stack |
+
+### 2. Compare Options (Top 3 per Decision)
+
+For each decision, research and compare 3 options:
+
+| Criterion | Option A | Option B | Option C |
+|-----------|---------|---------|---------|
+| Quality goal fit | [How it meets §1 goals] | ... | ... |
+| Constraint fit | [How it respects §2] | ... | ... |
+| Community/maturity | [Stars, contributors, releases] | ... | ... |
+| Performance | [Benchmarks with source] | ... | ... |
+| Learning curve | [Team skill match] | ... | ... |
+| Cost | [Licensing, hosting costs] | ... | ... |
+
+### 3. Make Decisions with Rationale
+
+For each decision:
+- **Chosen**: [Option]
+- **Rationale**: [Why this one — reference quality goals and constraints]
+- **Trade-off accepted**: [What we give up]
+- **Risk**: [What could go wrong]
+- **Migration path**: [How to change if this doesn't work]
+
+### 4. Write Output
+
+**WRITE IMMEDIATELY** to `.ultra/specs/architecture.md` §4:
+
+```markdown
+## §4 Solution Strategy
+
+### Technology Decisions
+
+#### Language & Runtime
+- **Chosen**: [Language/Runtime]
+- **Alternatives considered**: [Option B], [Option C]
+- **Rationale**: [Why — reference §1 quality goals]
+- **Trade-off**: [What we give up]
+- **Source**: [Benchmark/doc URL]
+
+#### Web Framework
+- **Chosen**: [Framework]
+- **Alternatives considered**: [Option B], [Option C]
+- **Rationale**: [Why]
+- **Trade-off**: [What we give up]
+- **Source**: [URL]
+
+#### Database
+- **Chosen**: [Database]
+- **Alternatives considered**: [Option B], [Option C]
+- **Rationale**: [Why]
+- **Trade-off**: [What we give up]
+- **Source**: [URL]
+
+#### Authentication
+- **Chosen**: [Approach]
+- **Alternatives considered**: [Option B], [Option C]
+- **Rationale**: [Why]
+- **Source**: [URL]
+
+#### Hosting & Infrastructure
+- **Chosen**: [Platform]
+- **Alternatives considered**: [Option B], [Option C]
+- **Rationale**: [Why]
+- **Estimated cost**: [$X/month at launch scale]
+- **Source**: [URL]
+
+### Tech Stack Summary
+
+| Layer | Technology | Version | Purpose |
+|-------|-----------|---------|---------|
+| Frontend | [Tech] | [Ver] | [What it does] |
+| Backend | [Tech] | [Ver] | [What it does] |
+| Database | [Tech] | [Ver] | [What it does] |
+| Cache | [Tech] | [Ver] | [What it does] |
+| Auth | [Tech] | [Ver] | [What it does] |
+| Hosting | [Tech] | - | [What it does] |
+| CI/CD | [Tech] | - | [What it does] |
+| Monitoring | [Tech] | - | [What it does] |
+
+### Decision Confidence
+- **Overall**: [X]%
+- **Most confident**: [Decision] — [Why]
+- **Least confident**: [Decision] — [Risk]
+```
+
+### 5. Present to User and Gate
+
+```
+[C] Continue — Tech stack defined, proceed to Building Blocks
+[R] Revise — Reconsider specific technology choices
+[D] Discuss — Deep-dive on a specific decision
+```
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Response
+
+- **[C]**: Load next step: `./step-32-building-blocks.md`
+- **[R]**: Revise decisions, update architecture.md §4, re-present
+- **[D]**: Deep-dive with additional research, then re-present
+
+## SUCCESS METRICS
+
+- Top 3 options compared for every major decision
+- Every choice has explicit rationale referencing quality goals
+- Trade-offs stated honestly
+- All claims verified via web search or Context7
+- Output written to architecture.md §4
+
+## FAILURE MODES
+
+- Single option considered ("just use React")
+- No rationale beyond popularity
+- Ignoring constraints from §2
+- Not verifying version compatibility
+- Technology choices that conflict with quality goals
+
+## NEXT STEP
+
+After user selects [C], read and follow: `./step-32-building-blocks.md`

package/skills/ultra-research/steps/step-32-building-blocks.md

@@ -0,0 +1,188 @@
+# Step 32: Building Blocks & Runtime Scenarios
+
+## MANDATORY EXECUTION RULES
+
+- MODULE DECOMPOSITION must follow Functional Core / Imperative Shell pattern
+- EVERY MODULE must trace to at least one feature from product.md §5
+- RUNTIME SCENARIOS must cover the top 3 user scenarios from product.md §3
+- WRITE output to spec file BEFORE presenting to user
+- ALL output in English (spec files); conversation in Chinese
+
+## PREREQUISITES
+
+- Step 31 (Solution Strategy) completed with [C]
+- `.ultra/specs/architecture.md` §1-4 exist
+
+## CONTEXT BOUNDARIES
+
+- Focus: Module decomposition and runtime behavior (arc42 §5-6)
+- Structure follows: `src/{domain/, application/usecases/, infrastructure/}`
+- Domain logic is pure (no IO); Infrastructure handles IO
+- This step bridges product (WHAT) to code (HOW)
+
+## EXECUTION SEQUENCE
+
+### 1. Module Decomposition
+
+Based on features from product.md §5 and tech stack from §4:
+
+**Layer structure**:
+```
+src/
+├── domain/           # Functional Core (pure logic)
+│   ├── entities/     # Domain objects
+│   ├── values/       # Value objects
+│   └── services/     # Domain services (pure functions)
+├── application/      # Use cases (orchestration)
+│   └── usecases/     # One file per use case
+├── infrastructure/   # Imperative Shell (IO)
+│   ├── http/         # HTTP handlers/routes
+│   ├── persistence/  # Database repositories
+│   └── external/     # External API clients
+└── config/           # Configuration
+```
+
+Map each feature to modules:
+- Feature 1 → domain/entities/X, application/usecases/Y, infrastructure/http/Z
+
+### 2. Define Key Interfaces
+
+For each module boundary, define the contract:
+
+| Interface | Provider | Consumer | Data |
+|-----------|---------|----------|------|
+| [Interface A] | [Module] | [Module] | [DTO/Entity] |
+
+### 3. Runtime Scenarios
+
+For the top 3 user scenarios from product.md §3, describe the runtime flow:
+
+**Scenario S1**: [Name]
+```
+User → HTTP Handler → Use Case → Domain Service → Repository → Database
+                                                              ↓
+User ← HTTP Response ← Use Case ← Domain Entity ← Repository ← Query Result
+```
+
+### 4. Write Output
+
+**WRITE IMMEDIATELY** to `.ultra/specs/architecture.md` §5-6:
+
+```markdown
+## §5 Building Block View
+
+### Level 1: System Decomposition
+
+| Module | Layer | Responsibility | Dependencies |
+|--------|-------|---------------|-------------|
+| [Module A] | Domain | [What it does] | None (pure) |
+| [Module B] | Application | [What it orchestrates] | [Module A] |
+| [Module C] | Infrastructure | [What IO it handles] | [Module B] |
+
+### Module Details
+
+#### domain/
+- **entities/[Entity]**: [Description, key fields, business rules]
+- **values/[ValueObject]**: [Description, validation rules]
+- **services/[Service]**: [Pure functions, input → output]
+
+#### application/usecases/
+- **[UseCase1]**: [Input → orchestration → output]
+- **[UseCase2]**: [Input → orchestration → output]
+
+#### infrastructure/
+- **http/[Handler]**: [Routes, request/response mapping]
+- **persistence/[Repository]**: [Database operations]
+- **external/[Client]**: [External API integration]
+
+### Feature → Module Mapping
+
+| Feature | Domain | Application | Infrastructure |
+|---------|--------|------------|---------------|
+| [Feature 1] | [Entities] | [UseCases] | [Handlers, Repos] |
+| [Feature 2] | [Entities] | [UseCases] | [Handlers, Repos] |
+
+## §6 Runtime Scenarios
+
+### Scenario 1: [S1 Name from product.md]
+
+**Trigger**: [User action]
+**Flow**:
+1. User sends [request type] to [endpoint]
+2. [Handler] validates input, maps to [DTO]
+3. [UseCase] orchestrates: loads [Entity] via [Repository]
+4. [DomainService] applies business logic (pure)
+5. [Repository] persists result
+6. [Handler] returns [response]
+
+**Data flow**: [Input] → [Transformation] → [Output]
+**Error paths**: [What can go wrong and how it's handled]
+
+### Scenario 2: [S2 Name]
+[Same structure]
+
+### Scenario 3: [S3 Name]
+[Same structure]
+
+### Round 3 Summary
+
+**Architecture Design Confidence**:
+- **Quality goal coverage**: [X]%
+- **Tech stack confidence**: [X]%
+- **Module clarity**: [X]%
+- **Overall R3 confidence**: [X]%
+```
+
+### 5. Write Round 3 Research Report
+
+**WRITE** to `.ultra/docs/research/architecture-design-{date}.md`:
+
+```markdown
+# Round 3: Architecture Design
+
+> **Confidence**: [X]%
+> **Steps completed**: 30-32
+> **Completed**: [date]
+
+## Key Decisions
+[Tech stack choices with rationale]
+
+## Architecture Pattern
+[Functional Core / Imperative Shell overview]
+
+## Risk Areas
+[Where architecture is weakest]
+```
+
+### 6. Present to User and Gate
+
+```
+[C] Continue — Architecture defined, proceed to Round 4 (Deployment & Quality)
+[R] Revise — Adjust modules or scenarios
+```
+
+**HALT — wait for user response before proceeding.**
+
+### 7. Handle Response
+
+- **[C]**: Load next step: `./step-40-deployment.md`
+- **[R]**: Revise, update architecture.md §5-6, re-present
+
+## SUCCESS METRICS
+
+- Every module traces to a feature
+- Functional Core / Imperative Shell separation clear
+- Top 3 runtime scenarios documented with data flow
+- Error paths identified
+- Round 3 research report written
+
+## FAILURE MODES
+
+- Modules that don't map to any feature (orphan code)
+- Business logic in infrastructure layer
+- Missing error paths in runtime scenarios
+- No interface contracts between modules
+
+## NEXT STEP
+
+After user selects [C], read and follow: `./step-40-deployment.md`