Initial commit
This commit is contained in:
Zhongwei Li
323
DECISIONS.md
Normal file
323
DECISIONS.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# Architecture Decisions
|
||||
|
||||
Documentation of key design decisions for Bubble Tea Maintenance Agent.
|
||||
|
||||
## Core Purpose Decision
|
||||
|
||||
**Decision**: Focus on maintenance/debugging of existing Bubble Tea apps, not design
|
||||
|
||||
**Rationale**:
|
||||
- ✅ Complements `bubbletea-designer` agent (design) with maintenance agent (upkeep)
|
||||
- ✅ Different problem space: diagnosis vs creation
|
||||
- ✅ Users have existing apps that need optimization
|
||||
- ✅ Maintenance is ongoing, design is one-time
|
||||
|
||||
**Alternatives Considered**:
|
||||
- Combined design+maintenance agent: Too broad, conflicting concerns
|
||||
- Generic Go linter: Misses Bubble Tea-specific patterns
|
||||
|
||||
---
|
||||
|
||||
## Data Source Decision
|
||||
|
||||
**Decision**: Use local tip-bubbltea-apps.md file as knowledge base
|
||||
|
||||
**Rationale**:
|
||||
- ✅ No internet required (offline capability)
|
||||
- ✅ Fast access (local file system)
|
||||
- ✅ Expert-curated knowledge (leg100.github.io)
|
||||
- ✅ 11 specific, actionable tips
|
||||
- ✅ Can be updated independently
|
||||
|
||||
**Alternatives Considered**:
|
||||
- Web scraping: Fragile, requires internet, slow
|
||||
- Embedded knowledge: Hard to update, limited
|
||||
- API: Rate limits, auth, network dependency
|
||||
|
||||
**Trade-offs**:
|
||||
- User needs to have tip file locally
|
||||
- Updates require manual file replacement
|
||||
|
||||
---
|
||||
|
||||
## Analysis Approach Decision
|
||||
|
||||
**Decision**: 6 separate specialized functions + 1 orchestrator
|
||||
|
||||
**Rationale**:
|
||||
- ✅ Single Responsibility Principle
|
||||
- ✅ Composable - can use individually or together
|
||||
- ✅ Testable - each function independently tested
|
||||
- ✅ Flexible - run quick diagnosis or deep analysis
|
||||
|
||||
**Structure**:
|
||||
1. `diagnose_issue()` - General problem identification
|
||||
2. `apply_best_practices()` - Validate against 11 tips
|
||||
3. `debug_performance()` - Performance bottleneck detection
|
||||
4. `suggest_architecture()` - Refactoring recommendations
|
||||
5. `fix_layout_issues()` - Lipgloss layout fixes
|
||||
6. `comprehensive_analysis()` - Orchestrates all 5
|
||||
|
||||
**Alternatives Considered**:
|
||||
- Single monolithic function: Hard to test, maintain, customize
|
||||
- 20 micro-functions: Too granular, confusing
|
||||
- Plugin architecture: Over-engineered for v1.0
|
||||
|
||||
---
|
||||
|
||||
## Code Parsing Strategy
|
||||
|
||||
**Decision**: Regex-based parsing instead of AST
|
||||
|
||||
**Rationale**:
|
||||
- ✅ Fast - no parse tree construction
|
||||
- ✅ Simple - easy to understand, maintain
|
||||
- ✅ Good enough - catches 90% of issues
|
||||
- ✅ No external dependencies (go/parser)
|
||||
- ✅ Cross-platform - pure Python
|
||||
|
||||
**Alternatives Considered**:
|
||||
- AST parsing (go/parser): More accurate but slow, complex
|
||||
- Token-based: Middle ground, still complex
|
||||
- LLM-based: Overkill, slow, requires API
|
||||
|
||||
**Trade-offs**:
|
||||
- May miss edge cases (rare nested structures)
|
||||
- Can't detect all semantic issues
|
||||
- Good for pattern matching, not deep analysis
|
||||
|
||||
**When to upgrade to AST**:
|
||||
- v2.0 if accuracy becomes critical
|
||||
- If false positive rate >5%
|
||||
- If complex refactoring automation is added
|
||||
|
||||
---
|
||||
|
||||
## Validation Strategy
|
||||
|
||||
**Decision**: Multi-layer validation with severity levels
|
||||
|
||||
**Rationale**:
|
||||
- ✅ Early error detection
|
||||
- ✅ Clear prioritization (CRITICAL > WARNING > INFO)
|
||||
- ✅ Actionable feedback
|
||||
- ✅ User can triage fixes
|
||||
|
||||
**Severity Levels**:
|
||||
- **CRITICAL**: Breaks UI, must fix immediately
|
||||
- **HIGH**: Significant performance/reliability impact
|
||||
- **MEDIUM**: Noticeable but not critical
|
||||
- **WARNING**: Best practice violation
|
||||
- **LOW**: Minor optimization
|
||||
- **INFO**: Suggestions, not problems
|
||||
|
||||
**Validation Layers**:
|
||||
1. Input validation (paths exist, files readable)
|
||||
2. Structure validation (result format correct)
|
||||
3. Content validation (scores in range, fields present)
|
||||
4. Semantic validation (recommendations make sense)
|
||||
|
||||
---
|
||||
|
||||
## Performance Threshold Decision
|
||||
|
||||
**Decision**: Update() <16ms, View() <3ms targets
|
||||
|
||||
**Rationale**:
|
||||
- 16ms = 60 FPS (1000ms / 60 = 16.67ms)
|
||||
- View() should be faster (called more often)
|
||||
- Based on Bubble Tea best practices
|
||||
- Leaves budget for framework overhead
|
||||
|
||||
**Measurement**:
|
||||
- Static analysis (pattern detection, not timing)
|
||||
- Identifies blocking operations
|
||||
- Estimates based on operation type:
|
||||
- HTTP request: 50-200ms
|
||||
- File I/O: 1-100ms
|
||||
- Regex compile: 1-10ms
|
||||
- String concat: 0.1-1ms per operation
|
||||
|
||||
**Future**: v2.0 could integrate pprof for actual measurements
|
||||
|
||||
---
|
||||
|
||||
## Architecture Pattern Decision
|
||||
|
||||
**Decision**: Heuristic-based pattern detection and recommendations
|
||||
|
||||
**Rationale**:
|
||||
- ✅ Works without user input
|
||||
- ✅ Based on complexity metrics
|
||||
- ✅ Provides concrete steps
|
||||
- ✅ Includes code templates
|
||||
|
||||
**Complexity Scoring** (0-100):
|
||||
- File count (10 points max)
|
||||
- Model field count (20 points)
|
||||
- Update() case count (20 points)
|
||||
- View() line count (15 points)
|
||||
- Custom message count (10 points)
|
||||
- View function count (15 points)
|
||||
- Concurrency usage (10 points)
|
||||
|
||||
**Pattern Recommendations**:
|
||||
- <30: flat_model (simple)
|
||||
- 30-70: multi_view or component_based (medium)
|
||||
- 70+: model_tree (complex)
|
||||
|
||||
---
|
||||
|
||||
## Best Practices Integration
|
||||
|
||||
**Decision**: Map each of 11 tips to automated checks
|
||||
|
||||
**Rationale**:
|
||||
- ✅ Leverages expert knowledge
|
||||
- ✅ Specific, actionable tips
|
||||
- ✅ Comprehensive coverage
|
||||
- ✅ Education + validation
|
||||
|
||||
**Tip Mapping**:
|
||||
1. Fast event loop → Check for blocking ops in Update()
|
||||
2. Debug dumping → Look for spew/io.Writer
|
||||
3. Live reload → Check for air config
|
||||
4. Receiver methods → Validate Update() receiver type
|
||||
5. Message ordering → Check for state tracking
|
||||
6. Model tree → Analyze model complexity
|
||||
7. Layout arithmetic → Validate lipgloss.Height() usage
|
||||
8. Terminal recovery → Check for defer/recover
|
||||
9. teatest → Look for test files
|
||||
10. VHS → Check for .tape files
|
||||
11. Resources → Info-only
|
||||
|
||||
---
|
||||
|
||||
## Error Handling Strategy
|
||||
|
||||
**Decision**: Return errors in result dict, never raise exceptions
|
||||
|
||||
**Rationale**:
|
||||
- ✅ Graceful degradation
|
||||
- ✅ Partial results still useful
|
||||
- ✅ Easy to aggregate errors
|
||||
- ✅ Doesn't break orchestrator
|
||||
|
||||
**Format**:
|
||||
```python
|
||||
{
|
||||
"error": "Description",
|
||||
"validation": {
|
||||
"status": "error",
|
||||
"summary": "What went wrong"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Philosophy**:
|
||||
- Better to return partial analysis than fail completely
|
||||
- User can act on what was found
|
||||
- Errors are just another data point
|
||||
|
||||
---
|
||||
|
||||
## Report Format Decision
|
||||
|
||||
**Decision**: JSON output with CLI-friendly summary
|
||||
|
||||
**Rationale**:
|
||||
- ✅ Machine-readable (JSON for tools)
|
||||
- ✅ Human-readable (CLI summary)
|
||||
- ✅ Composable (can pipe to jq, etc.)
|
||||
- ✅ Saveable (file output)
|
||||
|
||||
**Structure**:
|
||||
```python
|
||||
{
|
||||
"overall_health": 75,
|
||||
"sections": {
|
||||
"issues": {...},
|
||||
"best_practices": {...},
|
||||
"performance": {...},
|
||||
"architecture": {...},
|
||||
"layout": {...}
|
||||
},
|
||||
"priority_fixes": [...],
|
||||
"summary": "Executive summary",
|
||||
"estimated_fix_time": "2-4 hours",
|
||||
"validation": {...}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**Decision**: Unit tests per function + integration tests
|
||||
|
||||
**Rationale**:
|
||||
- ✅ Each function independently tested
|
||||
- ✅ Integration tests verify orchestration
|
||||
- ✅ Test fixtures for common scenarios
|
||||
- ✅ ~90% code coverage target
|
||||
|
||||
**Test Structure**:
|
||||
```
|
||||
tests/
|
||||
├── test_diagnose_issue.py # diagnose_issue() tests
|
||||
├── test_best_practices.py # apply_best_practices() tests
|
||||
├── test_performance.py # debug_performance() tests
|
||||
├── test_architecture.py # suggest_architecture() tests
|
||||
├── test_layout.py # fix_layout_issues() tests
|
||||
└── test_integration.py # End-to-end tests
|
||||
```
|
||||
|
||||
**Test Coverage**:
|
||||
- Happy path (valid code)
|
||||
- Edge cases (empty files, no functions)
|
||||
- Error cases (invalid paths, bad Go code)
|
||||
- Integration (orchestrator combines correctly)
|
||||
|
||||
---
|
||||
|
||||
## Documentation Strategy
|
||||
|
||||
**Decision**: Comprehensive SKILL.md + reference docs
|
||||
|
||||
**Rationale**:
|
||||
- ✅ Self-contained (agent doesn't need external docs)
|
||||
- ✅ Examples for every pattern
|
||||
- ✅ Education + automation
|
||||
- ✅ Quick reference guides
|
||||
|
||||
**Documentation Files**:
|
||||
1. **SKILL.md** - Complete agent instructions (8,000 words)
|
||||
2. **README.md** - Quick start guide
|
||||
3. **common_issues.md** - Problem/solution catalog
|
||||
4. **CHANGELOG.md** - Version history
|
||||
5. **DECISIONS.md** - This file
|
||||
6. **INSTALLATION.md** - Setup guide
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
**v2.0 Ideas**:
|
||||
- AST-based parsing for higher accuracy
|
||||
- Integration with pprof for actual profiling data
|
||||
- Automated fix application (not just suggestions)
|
||||
- Custom rule definitions
|
||||
- Visual reports
|
||||
- CI/CD integration
|
||||
- GitHub Action for PR checks
|
||||
- VSCode extension integration
|
||||
|
||||
**Criteria for v2.0**:
|
||||
- User feedback indicates accuracy issues
|
||||
- False positive rate >5%
|
||||
- Users request automated fixes
|
||||
- Adoption reaches 100+ users
|
||||
|
||||
---
|
||||
|
||||
**Built with Claude Code agent-creator on 2025-10-19**
|
||||
Reference in New Issue
Block a user