moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-cc-skill-factory/INTERACTIVE-DISCOVERY.md

@@ -0,0 +1,524 @@
+# Interactive Discovery: TUI-Based Skill Requirement Gathering
+
+This guide covers using **moai-alfred-ask-user-questions** Skill to engage users through interactive dialogue and clarify Skill requirements.
+
+---
+
+## Why Interactive Discovery?
+
+### The Problem: Vague Requests
+
+```
+❌ User says: "Create a Skill for testing"
+   Questions: Which language? Which framework?
+   Framework? Testing framework? Unit/integration/e2e?
+   Target audience? Experience level?
+   Result: Ambiguous Skill that doesn't match intent
+```
+
+### The Solution: Structured TUI Surveys
+
+```
+✅ skill-factory says: "Let me ask a few questions..."
+   ↓
+   Survey 1: Programming language (Python/TypeScript/Go/etc.)
+   Survey 2: Testing scope (Unit/integration/e2e/all)
+   Survey 3: Target experience (Beginner/intermediate/advanced)
+   Survey 4: Must-have features (Mocking/fixtures/CI integration)
+   ↓
+   Result: Crystal-clear Skill requirements
+```
+
+---
+
+## Interactive Discovery Process
+
+### Phase 0a: Problem Definition
+
+**Goal**: Understand what problem this Skill solves.
+
+**TUI Survey Pattern 1: Domain Selection**
+
+```
+┌─ SKILL FACTORY: INTERACTIVE DISCOVERY ────────────────────┐
+│                                                             │
+│ What problem domain does this Skill address?              │
+│                                                             │
+│ ▶ Debugging & Troubleshooting                             │
+│   Performance Analysis & Optimization                     │
+│   Code Quality & Best Practices                           │
+│   Testing & Quality Assurance                             │
+│   Infrastructure & DevOps                                │
+│   Data Processing & Transformation                       │
+│   Security & Cryptography                                │
+│   Other / Custom: [text input]                           │
+│                                                             │
+│ [↑↓ Navigate] [Enter: Select] [Esc: Cancel]              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**When to use this survey**:
+- First question to narrow scope
+- Establishes technology/domain context
+- Helps with WebSearch queries later
+
+**Follow-up question**:
+```
+┌─ SKILL FACTORY: FRAMEWORK/TECHNOLOGY ─────────────────────┐
+│                                                             │
+│ Within [Domain], which technology/framework?              │
+│                                                             │
+│ ▶ Python (Flask/Django/FastAPI/etc.)                     │
+│   TypeScript (Express/Next.js/NestJS/etc.)               │
+│   Go (Standard library/Gin/etc.)                         │
+│   Rust (Axum/Actix/etc.)                                │
+│   Java (Spring/Quarkus/etc.)                            │
+│   Other: [text input]                                   │
+│                                                             │
+│ [↑↓ Navigate] [Enter: Select]                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Outcome**: `selected_domain` + `selected_tech` captured
+
+---
+
+### Phase 0b: Scope Clarification
+
+**Goal**: Define what's in scope vs. out of scope.
+
+**TUI Survey Pattern 2: Feature Priority (Multi-select)**
+
+```
+┌─ SKILL FACTORY: FEATURE PRIORITY ──────────────────────────┐
+│                                                             │
+│ Which features are MUST-HAVE? (Select multiple)          │
+│                                                             │
+│ ☑ Core concepts & fundamentals                          │
+│ ☑ Practical examples & patterns                         │
+│ ☐ Error handling & debugging                            │
+│ ☑ Performance optimization                              │
+│ ☐ Security best practices                               │
+│ ☐ Deployment & CI/CD integration                        │
+│ ☐ Testing strategies                                    │
+│ ☐ Monitoring & observability                            │
+│                                                             │
+│ [↑↓ Navigate] [Space: Toggle] [Enter: Continue]          │
+└────────────────────────────────────────────────────────────┘
+```
+
+**Selection capture**:
+```python
+must_have_features = [
+    "core_concepts",
+    "practical_examples",
+    "performance_optimization"
+]
+```
+
+**Outcome**: Feature priority list
+
+---
+
+### Phase 0c: Target Audience
+
+**Goal**: Understand who will use this Skill.
+
+**TUI Survey Pattern 3: Experience Level**
+
+```
+┌─ SKILL FACTORY: TARGET AUDIENCE ──────────────────────────┐
+│                                                             │
+│ Who is the PRIMARY audience?                              │
+│                                                             │
+│   Beginners (< 1 year experience)                        │
+│   Intermediate (1-3 years)                               │
+│ ▶ Advanced (3+ years)                                    │
+│   All levels (mixed audience)                            │
+│   Hiring managers / Non-technical                       │
+│                                                             │
+│ [↑↓ Navigate] [Enter: Select]                            │
+└────────────────────────────────────────────────────────────┘
+```
+
+**Outcome**: `target_audience_level` captured
+
+---
+
+### Phase 0d: Special Considerations
+
+**Goal**: Capture any unique requirements or constraints.
+
+**TUI Survey Pattern 4: Version & Maturity**
+
+```
+┌─ SKILL FACTORY: FRAMEWORK VERSION ────────────────────────┐
+│                                                             │
+│ Which version of [Framework]?                             │
+│                                                             │
+│   Latest stable (auto-detect)                            │
+│ ▶ Latest LTS (Long-term support)                         │
+│   Specific version: [text input]                         │
+│   "Support multiple versions (e.g., 3.9+)"              │
+│                                                             │
+│ [↑↓ Navigate] [Enter: Select]                            │
+└────────────────────────────────────────────────────────────┘
+```
+
+**Outcome**: `framework_version` specified
+
+---
+
+### Phase 0e: Requirements Summary & Confirmation
+
+After all surveys, present summary for user confirmation:
+
+```
+┌─ SKILL FACTORY: REVIEW YOUR SELECTIONS ───────────────────┐
+│                                                             │
+│ ✓ Problem Domain: Performance Analysis & Optimization   │
+│ ✓ Technology: Python + Profiling Tools                  │
+│ ✓ Must-Have: Core concepts, examples, optimization tips│
+│ ✓ Audience: Advanced (3+ years)                         │
+│ ✓ Framework: Python 3.12 LTS                           │
+│                                                             │
+│ Ready to begin research and Skill creation?              │
+│                                                             │
+│  [✓ Yes, proceed] [← Go back, modify]                   │
+└────────────────────────────────────────────────────────────┘
+```
+
+**Outcome**: Confirmed `SkillRequirements` charter
+
+---
+
+### Phase 0f: Version Awareness & Stability Matrix (NEW)
+
+**Goal**: Capture version requirements to ensure all Skills reference latest stable versions (as of 2025-10-22).
+
+**CRITICAL**: All Skills MUST specify exact tool/framework versions. Outdated version references create stale content.
+
+**TUI Survey Pattern 5: Stable Version Requirements**
+
+```
+┌─ SKILL FACTORY: VERSION MATRIX ───────────────────────────────┐
+│                                                                 │
+│ For [Framework], which tool versions should we reference?    │
+│ (Defaults shown: 2025-10-22 stable versions)                 │
+│                                                                 │
+│ Framework Versions:                                            │
+│ • Python:     3.13.1 (latest)  ▶ 3.12.7 (LTS)                │
+│ • Node.js:    23.0.0  (latest)  ▶ 22.11.0 (LTS)              │
+│ • Go:         1.23.3  (latest)  ▶ 1.22.x (older)             │
+│ • Rust:       1.82.0  (latest)  ▶ MSRV: 1.70+                │
+│ • Java:       23.0.1  (latest)  ▶ 21.0.x (LTS)               │
+│                                                                 │
+│ Tool Versions (Python ecosystem example):                      │
+│ ☑ pytest 8.4.2 (testing framework)                           │
+│ ☑ ruff 0.13.1 (linting/formatting)                           │
+│ ☑ uv 0.9.3 (package manager)                                 │
+│ ☑ mypy 1.8.0 (type checking)                                 │
+│ ☑ FastAPI 0.115.0 (web framework)                            │
+│ ☑ Pydantic 2.7.0 (data validation)                           │
+│                                                                 │
+│ [↑↓ Navigate] [Space: Toggle] [Enter: Continue]              │
+│                                                                 │
+│ Want to customize versions? [Yes] / [No, use defaults]        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Version Selection Capture**:
+```python
+framework_versions = {
+    "python": "3.13.1",
+    "tools": [
+        "pytest:8.4.2",
+        "ruff:0.13.1",
+        "uv:0.9.3",
+        "mypy:1.8.0"
+    ]
+}
+```
+
+**Available Stable Version Matrix** (referenced as source of truth):
+
+| Framework   | Latest | LTS        | EOL Date      | Ref                                    |
+| ----------- | ------ | ---------- | ------------- | -------------------------------------- |
+| **Python**  | 3.13.1 | 3.12.7     | 3.12: 2028-10 | [python.org](https://python.org)       |
+| **Node.js** | 23.0.0 | 22.11.0    | 22.x: 2025-10 | [nodejs.org](https://nodejs.org)       |
+| **Go**      | 1.23.3 | 1.22.x     | 1.22: 2025-02 | [golang.org](https://golang.org)       |
+| **Rust**    | 1.82.0 | MSRV: 1.70 | N/A           | [rust-lang.org](https://rust-lang.org) |
+| **Java**    | 23.0.1 | 21.0.x     | 21: 2028-09   | [oracle.com](https://oracle.com)       |
+
+**When This Survey Is Needed**:
+- ✅ Creating a new Skill (always)
+- ✅ Updating existing Skill (quarterly version checks)
+- ✅ Migrating to new major version (breaking changes detected)
+- ✅ Security updates required (security advisory found)
+
+**Related Document**: `.moai/memory/VERSION-TRACKING.md` — Comprehensive version matrix for all 23 languages and 50+ frameworks
+
+**Outcome**: `stable_versions` captured with explicit tool/framework version numbers
+
+---
+
+### Phase 0g: Final Confirmation with Version Summary
+
+Enhanced confirmation step that includes version matrix:
+
+```
+┌─ SKILL FACTORY: FINAL REVIEW ────────────────────────────────┐
+│                                                                 │
+│ ✓ Problem Domain: Testing & Quality Assurance               │
+│ ✓ Technology: TypeScript + Vitest                           │
+│ ✓ Must-Have: Core, patterns, mocking, optimization          │
+│ ✓ Audience: Intermediate (1-3 years)                        │
+│ ✓ Framework Version: Vitest 2.0.5 (latest)                 │
+│ ✓ Tool Versions:                                             │
+│   • TypeScript: 5.3.x                                        │
+│   • Vitest: 2.0.5                                            │
+│   • Biome: 1.7.x (linter/formatter)                         │
+│   • Node.js: 22.11.0 (LTS recommended)                      │
+│                                                                 │
+│ ✓ Research Focus: Latest 2025 patterns with these versions   │
+│                                                                 │
+│ Ready to research and generate Skill?                         │
+│ (This will reference current stable versions)                │
+│                                                                 │
+│  [✓ Yes, proceed] [← Go back, modify versions]              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Outcome**: Confirmed `SkillRequirements` charter with **explicit version matrix**
+
+---
+
+## TUI Survey Design Best Practices
+
+### 1. Progressive Narrowing
+
+```
+Survey 1: Broad domain (5-8 options)
+   ↓ User selects one
+Survey 2: Specific tech within domain (5-8 options)
+   ↓ User selects one or more
+Survey 3: Features/scope (multi-select from pool)
+   ↓ User checks boxes
+Survey 4: Advanced options (if needed, 3-4 options)
+   ↓ User selects one
+Survey 5: Confirmation summary
+   ↓ User confirms or goes back
+```
+
+### 2. Sensible Defaults
+
+```
+❌ Bad (requires user to know exact answer):
+  □ How many lines of code per section?
+  □ Which specific exception types?
+  □ What is the exact API response format?
+
+✅ Good (offers reasonable defaults):
+  □ Code size: Small (under 50 lines) / Medium / Large
+  □ Exception handling: Basic (try/except) / Advanced (custom types)
+  □ API responses: JSON (default) / XML / Protocol Buffers
+```
+
+### 3. Custom Input Fallback
+
+```
+┌─ Survey ──────────────────────────────────────────────────┐
+│                                                             │
+│ ▶ Option 1 (predefined)                                 │
+│   Option 2 (predefined)                                 │
+│   Option 3 (predefined)                                 │
+│   Other / Custom: [________________]  ← For unknown cases│
+│                                                             │
+└───────────────────────────────────────────────────────────┘
+```
+
+### 4. Multi-Select for Complex Requirements
+
+```
+Question: "Which testing patterns are important?"
+(Users can select multiple)
+
+☑ Unit testing
+☑ Integration testing
+☐ End-to-end testing
+☑ Mocking & fixtures
+☐ Performance testing
+```
+
+**Result**: More accurate feature prioritization
+
+---
+
+## Example: Complete Interactive Discovery Flow
+
+### Scenario: "I want a Skill for TypeScript testing"
+
+**Step 1: Problem Domain** → User selects "Testing & Quality Assurance"
+
+**Step 2: Technology** → User selects "TypeScript"
+
+**Step 3: Testing Framework** → User selects "Vitest"
+
+**Step 4: Must-Have Features**
+- Core concepts ✓
+- Unit testing patterns ✓
+- Mocking with Vitest ✓
+- Performance optimization ✓
+- CI/CD integration ✗
+
+**Step 5: Audience** → "Intermediate (1-3 years)"
+
+**Step 6: Framework Version** → "Latest stable"
+
+**Step 7: Confirmation**
+```
+✓ Domain: Testing & Quality Assurance
+✓ Technology: TypeScript + Vitest
+✓ Features: Core, patterns, mocking, optimization
+✓ Audience: Intermediate
+✓ Version: Vitest latest stable
+
+Ready to research and generate Skill?
+```
+
+**Result**: skill-factory now has precise requirements for web research and Skill generation
+
+---
+
+## Failure Modes & Recovery
+
+### 🔴 User Provides No/Invalid Selection
+
+```
+User: [Presses Escape 3 times]
+system: "It seems you'd like to cancel. Should I stop?"
+
+Recovery:
+1. Offer explicit yes/no confirmation
+2. Or: Restart with fresh survey
+3. Or: Use defaults and proceed
+```
+
+### 🟡 User Selects Contradictory Options
+
+```
+User selects:
+  Domain: "Data Processing"
+  Technology: "Kubernetes"
+  ↑ Mismatch! Kubernetes is DevOps, not data processing
+
+Detection: skill-factory notices mismatch
+Response: "I noticed you selected Data Processing but Kubernetes
+ is typically DevOps-related. Did you mean... Kafka or Spark?"
+```
+
+### 🟢 User Enters Custom Value
+
+```
+User selects: "Other / Custom"
+skill-factory: "What specific technology would you like?"
+User: "MicroPython for IoT devices"
+Result: WebSearch targets "MicroPython IoT best practices 2025"
+```
+
+---
+
+## Integration with WebSearch Phase
+
+### From Interactive Discovery → To WebSearch
+
+```
+TUI Survey Captures:
+├─ domain: "Testing & Quality Assurance"
+├─ technology: "TypeScript"
+├─ framework: "Vitest"
+├─ features: ["core", "patterns", "mocking", "optimization"]
+├─ audience: "intermediate"
+└─ version: "latest-stable"
+
+↓
+
+skill-factory builds WebSearch queries:
+1. "TypeScript Vitest latest 2025 best practices"
+2. "Vitest async testing patterns modern"
+3. "TypeScript testing mocking strategies"
+4. "Vitest performance optimization official docs"
+5. "TypeScript Vitest breaking changes migration"
+
+↓
+
+WebSearch findings INFORM the Skill
+(See WEB-RESEARCH.md for details)
+```
+
+---
+
+## Effective Question Design
+
+### DO: Ask Open-Ended Questions
+
+```
+✅ "What specific problem do you want to solve?"
+   (Allows detailed answer)
+
+❌ "Do you want testing?"
+   (Yes/No is too limiting)
+```
+
+### DO: Provide Context
+
+```
+✅ "Target audience: who will use this?
+   (Beginner developers might need more examples)
+   - Beginners
+   - Intermediate
+   - Advanced"
+
+❌ "Target audience?"
+   (Too vague, user doesn't know what you need)
+```
+
+### DO: Use Sensible Grouping
+
+```
+✅ Survey 1: Pick ONE (narrowing)
+   Survey 2: Pick ONE (further narrowing)
+   Survey 3: Pick MULTIPLE (features/scope)
+   Survey 4: Confirmation
+
+❌ Survey 1: Pick MULTIPLE (confusing)
+   Survey 2: Pick ONE (conflicting)
+```
+
+---
+
+## Capturing Requirements for WebSearch
+
+Map survey answers to research queries:
+
+| Survey Answer | WebSearch Topic | Example Query                       |
+| ------------- | --------------- | ----------------------------------- |
+| Python 3.12   | Latest version  | "Python 3.12 best practices 2025"   |
+| Async testing | Modern pattern  | "async/await testing patterns 2025" |
+| Performance   | Optimization    | "performance profiling tools 2025"  |
+| Security      | Compliance      | "OWASP security patterns 2025"      |
+
+---
+
+## Related Resources
+
+- [SKILL.md](SKILL.md) — Main Skill framework
+- [WEB-RESEARCH.md](WEB-RESEARCH.md) — Using discoveries in research
+- [skill-factory.md](../../agents/alfred/skill-factory.md) — Sub-Agent orchestration
+- `moai-alfred-ask-user-questions` Skill — TUI implementation
+
+---
+
+**Version**: 0.1.0
+**Last Updated**: 2025-10-22
+**Framework**: MoAI-ADK + Claude Skills + skill-factory