moai-adk 0.8.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

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

@@ -1,524 +0,0 @@
-# Interactive Discovery: TUI-Based Skill Requirement Gathering
-
-This guide covers using **moai-alfred-interactive-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-interactive-questions` Skill — TUI implementation
-
----
-
-**Version**: 0.1.0
-**Last Updated**: 2025-10-22
-**Framework**: MoAI-ADK + Claude Skills + skill-factory