Initial commit

DECISIONS.md

@@ -0,0 +1,158 @@
+# Architecture Decisions
+
+Documentation of key design decisions for Bubble Tea Designer skill.
+
+## Data Source Decision
+
+**Decision**: Use local charm-examples-inventory instead of API
+**Rationale**:
+- ✅ No rate limits or authentication needed
+- ✅ Fast lookups (local file system)
+- ✅ Complete control over inventory structure
+- ✅ Offline capability
+- ✅ Inventory can be updated independently
+
+**Alternatives Considered**:
+- GitHub API: Rate limits, requires authentication
+- Web scraping: Fragile, slow, unreliable
+- Embedded database: Adds complexity, harder to update
+
+**Trade-offs**:
+- User needs to have inventory locally (optional but recommended)
+- Updates require re-cloning repository
+
+## Analysis Approach
+
+**Decision**: 6 separate analysis functions + 1 comprehensive orchestrator
+**Rationale**:
+- ✅ Modularity - each function has single responsibility
+- ✅ Testability - easy to test individual components
+- ✅ Flexibility - users can call specific analyses
+- ✅ Composability - orchestrator combines as needed
+
+**Structure**:
+1. analyze_requirements() - NLP requirement extraction
+2. map_components() - Component scoring and selection
+3. select_patterns() - Example file matching
+4. design_architecture() - Structure generation
+5. generate_workflow() - Implementation planning
+6. comprehensive_tui_design_report() - All-in-one
+
+## Component Matching Algorithm
+
+**Decision**: Keyword-based scoring with manual taxonomy
+**Rationale**:
+- ✅ Transparent - users can see why components selected
+- ✅ Predictable - consistent results
+- ✅ Fast - O(n) search with indexing
+- ✅ Maintainable - easy to add new components
+
+**Alternatives Considered**:
+- ML-based matching: Overkill, requires training data
+- Fuzzy matching: Less accurate for technical terms
+- Rule-based expert system: Too rigid
+
+**Scoring System**:
+- Keyword match: 60 points max
+- Use case match: 40 points max
+- Total: 0-100 score per component
+
+## Architecture Generation Strategy
+
+**Decision**: Template-based with customization
+**Rationale**:
+- ✅ Generates working code immediately
+- ✅ Follows Bubble Tea best practices
+- ✅ Customizable per archetype
+- ✅ Educational - shows proper patterns
+
+**Templates Include**:
+- Model struct with components
+- Init() with proper initialization
+- Update() skeleton with message routing
+- View() with component rendering
+
+## Validation Strategy
+
+**Decision**: Multi-layer validation (requirements, components, architecture, workflow)
+**Rationale**:
+- ✅ Early error detection
+- ✅ Quality assurance
+- ✅ Helpful feedback to users
+- ✅ Catches incomplete designs
+
+**Validation Levels**:
+- CRITICAL: Must fix (empty description, no components)
+- WARNING: Should review (low coverage, many components)
+- INFO: Optional improvements
+
+## File Organization
+
+**Decision**: Modular scripts with shared utilities
+**Rationale**:
+- ✅ Clear separation of concerns
+- ✅ Reusable utilities
+- ✅ Easy to test
+- ✅ Maintainable codebase
+
+**Structure**:
+```
+scripts/
+  main analysis scripts (6)
+  utils/
+    shared utilities
+    validators/
+      validation logic
+```
+
+## Pattern Matching Approach
+
+**Decision**: Inventory-based with ranking
+**Rationale**:
+- ✅ Leverages existing examples
+- ✅ Provides concrete references
+- ✅ Study order optimization
+- ✅ Realistic time estimates
+
+**Ranking Factors**:
+- Component usage overlap
+- Complexity match
+- Code quality/clarity
+
+## Documentation Strategy
+
+**Decision**: Comprehensive references with patterns and best practices
+**Rationale**:
+- ✅ Educational value
+- ✅ Self-contained skill
+- ✅ Reduces external documentation dependency
+- ✅ Examples for every pattern
+
+**References Created**:
+- Component guide (what each component does)
+- Design patterns (common architectures)
+- Best practices (dos and don'ts)
+- Example designs (complete real-world cases)
+
+## Performance Considerations
+
+**Optimizations**:
+- Inventory loaded once, cached in memory
+- Pre-computed component taxonomy
+- Fast keyword matching (no regex)
+- Minimal allocations in hot paths
+
+**Trade-offs**:
+- Memory usage: ~5MB for loaded inventory
+- Startup time: ~100ms for inventory loading
+- Analysis time: <1 second for complete report
+
+## Future Enhancements
+
+Potential improvements for v2.0:
+- Interactive mode for requirement refinement
+- Code generation (full implementation, not just scaffolding)
+- Live preview of designs
+- Integration with Go module initialization
+- Custom component definitions
+- Save/load design sessions