trinity-method-sdk 2.0.0

package/dist/templates/knowledge-base/ISSUES.md.template

@@ -0,0 +1,539 @@
+# ISSUES.md - {{PROJECT_NAME}}
+**Trinity Method v2.0 - Issue Intelligence System**
+**Technology Stack**: {{TECHNOLOGY_STACK}}
+**Framework**: {{PRIMARY_FRAMEWORK}}
+**Last Updated**: {{CURRENT_DATE}}
+
+---
+
+## 🔴 ACTIVE ISSUES
+
+### Critical (P0) - Immediate Action Required
+```yaml
+Issue_ID: {{PROJECT_PREFIX}}-C001
+Title: {{CRITICAL_ISSUE_TITLE}}
+Component: {{AFFECTED_COMPONENT}}
+Impact: {{IMPACT_DESCRIPTION}}
+Status: ACTIVE
+First_Seen: {{DATE}}
+Last_Seen: {{DATE}}
+Occurrences: {{COUNT}}
+
+Symptoms:
+  - {{SYMPTOM_1}}
+  - {{SYMPTOM_2}}
+
+Root_Cause: {{ROOT_CAUSE}}
+
+Investigation_Path:
+  1. {{INVESTIGATION_STEP_1}}
+  2. {{INVESTIGATION_STEP_2}}
+  3. {{INVESTIGATION_STEP_3}}
+
+Solution:
+  ```{{LANGUAGE}}
+  {{SOLUTION_CODE}}
+  ```
+
+Prevention:
+  - {{PREVENTION_1}}
+  - {{PREVENTION_2}}
+```
+
+### High Priority (P1) - Core Functionality
+[High priority issues affecting core features]
+
+### Medium Priority (P2) - User Experience
+[Issues affecting user experience but not blocking]
+
+### Low Priority (P3) - Enhancements
+[Minor issues and improvement opportunities]
+
+---
+
+## 📊 {{FRAMEWORK}}-SPECIFIC PATTERNS
+
+### Common {{FRAMEWORK}} Issues
+
+#### Pattern: {{FRAMEWORK_PATTERN_1}}
+**Frequency**: HIGH
+**Impact**: Performance/Functionality/Security
+**Category**: {{CATEGORY}}
+
+**Problem Description**:
+{{PROBLEM_DESCRIPTION}}
+
+**Typical Symptoms**:
+1. {{SYMPTOM_1}}
+2. {{SYMPTOM_2}}
+3. {{SYMPTOM_3}}
+
+**Investigation Approach**:
+```bash
+# {{FRAMEWORK}} specific investigation
+{{INVESTIGATION_COMMANDS}}
+```
+
+**Known Solutions**:
+```{{LANGUAGE}}
+// {{FRAMEWORK}} specific solution
+{{SOLUTION_PATTERN}}
+```
+
+**Prevention Measures**:
+- {{PREVENTION_MEASURE_1}}
+- {{PREVENTION_MEASURE_2}}
+- {{PREVENTION_MEASURE_3}}
+
+**Related Issues**: [{{RELATED_ISSUE_IDS}}]
+
+---
+
+## 🌍 UNIVERSAL DEVELOPMENT PATTERNS
+
+### State Management Issues
+
+#### Pattern: State Synchronization Failure
+**Frequency**: MEDIUM
+**Impact**: Data Integrity
+**Applicable To**: All frameworks with state management
+
+**Problem**: State becomes out of sync between components
+**Root Causes**:
+1. Race conditions in async operations
+2. Improper state mutation
+3. Missing state update propagation
+
+**Universal Solution Pattern**:
+```{{LANGUAGE}}
+// State synchronization pattern
+{{STATE_SYNC_PATTERN}}
+```
+
+### Performance Optimization Patterns
+
+#### Pattern: Render Performance Degradation
+**Frequency**: HIGH
+**Impact**: User Experience
+
+**Detection**:
+```javascript
+// Performance monitoring
+const performanceMonitor = {
+  measureRender: (component) => {
+    const startTime = performance.now();
+    // Render logic
+    const endTime = performance.now();
+    if (endTime - startTime > THRESHOLD) {
+      console.warn(`Slow render: ${component}`);
+    }
+  }
+};
+```
+
+### Security Patterns
+
+#### Pattern: Input Validation Bypass
+**Frequency**: MEDIUM
+**Impact**: CRITICAL
+
+**Prevention Strategy**:
+```{{LANGUAGE}}
+// Input validation pattern
+{{VALIDATION_PATTERN}}
+```
+
+---
+
+## 🔬 TRINITY METHOD PATTERNS
+
+### Investigation Protocol Issues
+
+#### Pattern: Investigation Scope Creep
+**Frequency**: HIGH
+**Impact**: Development Velocity
+
+**Problem**: Investigations expand beyond intended scope
+**Solution**:
+1. Set strict time boxes (30 min max)
+2. Document tangential findings separately
+3. Create follow-up investigations
+
+### Knowledge Capture Issues
+
+#### Pattern: Pattern Documentation Lag
+**Frequency**: MEDIUM
+**Impact**: Knowledge Reuse
+
+**Problem**: Patterns discovered but not documented immediately
+**Solution**:
+- Document patterns within the same session
+- Use pattern template immediately
+- Link to investigation that discovered it
+
+---
+
+## 📈 ISSUE METRICS
+
+### Pattern Recognition Statistics
+```yaml
+Total_Patterns_Identified: {{COUNT}}
+Patterns_This_Month: {{COUNT}}
+Most_Frequent_Pattern: {{PATTERN_NAME}}
+Success_Rate: {{PERCENTAGE}}%
+
+By_Category:
+  Performance: {{COUNT}}
+  Security: {{COUNT}}
+  State_Management: {{COUNT}}
+  Integration: {{COUNT}}
+  UI_UX: {{COUNT}}
+```
+
+### Issue Resolution Metrics
+```yaml
+Average_Resolution_Time:
+  P0_Critical: {{TIME}}
+  P1_High: {{TIME}}
+  P2_Medium: {{TIME}}
+  P3_Low: {{TIME}}
+
+First_Time_Fix_Rate: {{PERCENTAGE}}%
+Regression_Rate: {{PERCENTAGE}}%
+Pattern_Prevention_Rate: {{PERCENTAGE}}%
+```
+
+### Recurrence Tracking
+| Issue Pattern | First Seen | Last Seen | Occurrences | Status |
+|--------------|------------|-----------|-------------|---------|
+| {{PATTERN_1}} | {{DATE}} | {{DATE}} | {{COUNT}} | {{STATUS}} |
+| {{PATTERN_2}} | {{DATE}} | {{DATE}} | {{COUNT}} | {{STATUS}} |
+
+---
+
+## 🛠️ INVESTIGATION QUEUE
+
+### Pending Investigations
+1. **{{INVESTIGATION_1}}**
+   - Scope: {{SCOPE}}
+   - Estimated Time: {{TIME}}
+   - Dependencies: {{DEPENDENCIES}}
+
+2. **{{INVESTIGATION_2}}**
+   - Scope: {{SCOPE}}
+   - Estimated Time: {{TIME}}
+   - Dependencies: {{DEPENDENCIES}}
+
+### Completed Investigations (This Session)
+- [x] {{COMPLETED_1}} - See: trinity/investigations/{{DATE}}-{{INVESTIGATION}}.md
+- [x] {{COMPLETED_2}} - See: trinity/investigations/{{DATE}}-{{INVESTIGATION}}.md
+
+---
+
+## 🔄 ISSUE LIFECYCLE
+
+### Issue States
+```mermaid
+graph LR
+    A[Discovered] --> B[Investigated]
+    B --> C[Documented]
+    C --> D[Solution Implemented]
+    D --> E[Verified]
+    E --> F[Pattern Extracted]
+    F --> G[Closed]
+```
+
+### State Definitions
+1. **Discovered**: Issue identified but not investigated
+2. **Investigated**: Root cause analysis complete
+3. **Documented**: Full documentation in ISSUES.md
+4. **Solution Implemented**: Fix applied to codebase
+5. **Verified**: Fix confirmed working
+6. **Pattern Extracted**: Reusable pattern documented
+7. **Closed**: Issue resolved and knowledge captured
+
+---
+
+## 📝 ISSUE TEMPLATE
+
+```yaml
+Issue_ID: {{PROJECT_PREFIX}}-{{CATEGORY}}{{NUMBER}}
+Title: {{DESCRIPTIVE_TITLE}}
+Component: {{AFFECTED_COMPONENT}}
+Framework_Specific: {{YES/NO}}
+Impact: {{CRITICAL/HIGH/MEDIUM/LOW}}
+Status: {{ACTIVE/INVESTIGATING/RESOLVED}}
+
+Discovery:
+  Date: {{DATE}}
+  Discovered_By: {{METHOD/PERSON}}
+  Session: {{SESSION_ID}}
+
+Symptoms:
+  - {{SYMPTOM_1}}
+  - {{SYMPTOM_2}}
+
+Root_Cause_Analysis:
+  Investigation_Time: {{MINUTES}}
+  Root_Cause: {{DESCRIPTION}}
+  Contributing_Factors: [{{LIST}}]
+
+Solution:
+  Implementation_Time: {{MINUTES}}
+  Code_Changes: {{FILES_CHANGED}}
+  Tests_Added: {{TEST_COUNT}}
+
+Prevention:
+  Pattern_Created: {{YES/NO}}
+  Pattern_Location: trinity/patterns/{{PATTERN_FILE}}
+  Guidelines_Updated: {{YES/NO}}
+
+Metrics:
+  Recurrence_Risk: {{HIGH/MEDIUM/LOW}}
+  Similar_Issues_Prevented: {{COUNT}}
+```
+
+---
+
+## 🎯 PREVENTION STRATEGIES
+
+### Proactive Measures by Category
+
+#### Performance Issues
+1. Implement performance monitoring from start
+2. Set up automated performance testing
+3. Regular performance audits
+
+#### State Management Issues
+1. Define clear state ownership
+2. Implement state validation
+3. Use immutable state patterns
+
+#### Security Issues
+1. Input validation on all boundaries
+2. Regular security scanning
+3. Security review checklist
+
+#### Integration Issues
+1. Contract testing between components
+2. Mock external dependencies
+3. Integration test suite
+
+---
+
+## 📊 WEEKLY ISSUE REVIEW
+
+### Issues This Week
+- **New Issues**: {{COUNT}}
+- **Resolved Issues**: {{COUNT}}
+- **Patterns Discovered**: {{COUNT}}
+- **Investigations Completed**: {{COUNT}}
+
+### Trending Patterns
+1. {{TRENDING_PATTERN_1}} - {{OCCURRENCE_INCREASE}}%
+2. {{TRENDING_PATTERN_2}} - {{OCCURRENCE_INCREASE}}%
+
+### Action Items
+- [ ] Investigate {{HIGH_PRIORITY_PATTERN}}
+- [ ] Document {{UNDOCUMENTED_PATTERN}}
+- [ ] Implement prevention for {{RECURRING_ISSUE}}
+
+---
+
+## 🔗 RELATED DOCUMENTS
+
+- **Technical-Debt.md**: Detailed debt tracking
+- **ARCHITECTURE.md**: System design and components
+- **Trinity.md**: Methodology implementation
+- **To-do.md**: Pending fixes and improvements
+- **Pattern Library**: trinity/patterns/
+
+---
+
+## 📝 WHEN TO UPDATE THIS DOCUMENT
+
+This is a **living issue intelligence system** that should be updated continuously to capture patterns and prevent recurring issues.
+
+### Immediate Updates Required ⚠️
+
+Update **as soon as discovered** (real-time):
+
+- ✅ **New Issue Discovered**: Add to Active Issues with full details (symptoms, root cause, solution)
+- ✅ **Issue Resolved**: Move from Active to documented pattern, mark resolution date
+- ✅ **Pattern Recognized**: When same issue appears 2+ times, create pattern entry
+- ✅ **Investigation Complete**: Link investigation file, add root cause analysis
+- ✅ **New Framework Issue**: Add to {{FRAMEWORK}}-Specific Patterns section
+- ✅ **Universal Pattern Found**: Add to Universal Development Patterns (applies to all frameworks)
+- ✅ **Trinity Method Issue**: Document methodology issues in Trinity Method Patterns
+
+### Session Updates (Via `/trinity-end`) 🔄
+
+Update at end of each development session:
+
+- Close resolved issues from current session
+- Add new issues encountered during session
+- Update issue metrics (resolution time, recurrence rate)
+- Update pattern frequency counts
+- Link to completed investigations
+- Update weekly issue review section
+- Refresh trending patterns analysis
+
+### Weekly Reviews ⏰
+
+Track issue trends and prevention effectiveness:
+
+- Review issues added this week
+- Calculate pattern prevention success rate
+- Identify trending patterns (increasing occurrences)
+- Update action items for high-priority patterns
+- Assess investigation queue priorities
+
+### Monthly Audits 📅
+
+Deep pattern analysis and prevention strategy:
+
+- Pattern effectiveness review (which patterns prevent most issues)
+- Update prevention strategies based on learnings
+- Consolidate similar patterns
+- Archive resolved patterns that haven't recurred
+- Measure issue recurrence rate
+
+### Cross-Document Update Triggers 🔗
+
+**When updating ISSUES.md, also check:**
+
+- **[Technical-Debt.md](./Technical-Debt.md)**: Add technical debt items for issues that reveal debt
+- **[To-do.md](./To-do.md)**: Create tasks to fix active issues or implement prevention
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)**: Update if issue reveals architectural problem
+- **[Trinity.md](./Trinity.md)**: Update investigation protocols if new investigation approach discovered
+- **[CODING-PRINCIPLES.md](./CODING-PRINCIPLES.md)**: Add principle if issue reveals coding standard gap
+- **[TESTING-PRINCIPLES.md](./TESTING-PRINCIPLES.md)**: Add test requirement if issue was missed by tests
+
+### Update Scenarios - What to Change
+
+**Scenario: Bug Found During Development**
+```yaml
+Updates_Required:
+  - Active_Issues: Add new issue with P0/P1/P2/P3 priority
+  - Issue_Template: Fill with symptoms, root cause, solution
+  - Pattern_Check: Is this a recurring issue? Create pattern if yes
+  - Investigation_Link: Link to trinity/investigations/ file if investigation done
+  - Cross_References:
+    - To-do.md: Add fix task with priority
+    - Technical-Debt.md: Add debt if issue reveals shortcuts
+```
+
+**Scenario: Issue Resolved**
+```yaml
+Updates_Required:
+  - Active_Issues: Remove from active section
+  - Pattern_Extraction: If issue can recur, create pattern template
+  - Issue_Metrics: Update resolution metrics
+  - Prevention_Strategy: Add prevention measures to relevant section
+  - Cross_References:
+    - To-do.md: Mark related task complete
+    - Technical-Debt.md: Mark related debt resolved
+```
+
+**Scenario: Pattern Recognized (3+ occurrences)**
+```yaml
+Updates_Required:
+  - Pattern_Section: Create new pattern entry or update existing
+  - Pattern_Frequency: Update occurrence count
+  - Related_Issues: Link all issue IDs that match this pattern
+  - Prevention_Measures: Document how to prevent this pattern
+  - Pattern_Library: Create pattern file in trinity/patterns/
+  - Cross_References:
+    - Technical-Debt.md: Link pattern to debt if applicable
+    - CODING-PRINCIPLES.md: Add principle if pattern reveals standard gap
+```
+
+**Scenario: Investigation Completed**
+```yaml
+Updates_Required:
+  - Issue_Entry: Add investigation findings to root cause section
+  - Investigation_Queue: Remove from pending, add to completed
+  - Pattern_Discovery: Create pattern if investigation revealed one
+  - Resolution_Path: Document solution from investigation
+  - Cross_References:
+    - Trinity.md: Link investigation file
+    - Pattern_Library: Create pattern file if reusable solution found
+```
+
+**Scenario: Framework-Specific Issue Found**
+```yaml
+Updates_Required:
+  - Framework_Specific_Patterns: Add issue to {{FRAMEWORK}} section
+  - Frequency_Tracking: Mark as HIGH/MEDIUM/LOW based on likelihood
+  - Known_Solutions: Add framework-specific solution code
+  - Prevention_Measures: Add framework best practices to prevent
+  - Cross_References:
+    - AI-DEVELOPMENT-GUIDE.md: Update if framework workflow needs adjustment
+```
+
+### How to Update
+
+**Step-by-step process:**
+
+1. **Categorize Issue**: Is it Critical/High/Medium/Low priority? Framework-specific or universal?
+2. **Document Completely**: Fill issue template with all details (don't leave partial entries)
+3. **Check for Patterns**: Search document for similar issues (2+ = pattern)
+4. **Link Investigation**: If investigation file exists, link it
+5. **Update Metrics**: Increment counts, update averages
+6. **Cross-Reference**: Update related documents (To-do, Technical-Debt, etc.)
+7. **Pattern Library**: Create trinity/patterns/ file if reusable solution
+8. **Update Timestamp**: Set `Last Updated: {{CURRENT_DATE}}` to actual date
+
+**Quality Checklist:**
+- [ ] Issue has complete symptoms, root cause, and solution
+- [ ] Priority matches impact (P0 = production down, P1 = core feature broken, etc.)
+- [ ] Pattern frequency accurate (count all occurrences)
+- [ ] Links to investigation files valid
+- [ ] Cross-references to other docs updated
+- [ ] Prevention measures actionable
+
+### When NOT to Update ❌
+
+**Don't add to ISSUES.md if:**
+- Simple typo fixes (not a pattern)
+- Expected behavior misunderstood (user error, not issue)
+- Third-party library bugs (document in ARCHITECTURE dependencies instead)
+- One-time environment issues (not reproducible)
+- Feature requests (add to To-do.md instead)
+
+**When to merge issues:**
+- If two issues have same root cause, merge into single pattern
+- Update pattern frequency count to reflect all occurrences
+
+### Issue vs. Debt vs. Todo 🤔
+
+**Add to ISSUES.md when:**
+- Bug that can recur
+- Pattern that should be prevented
+- Framework-specific problem to watch for
+
+**Add to Technical-Debt.md when:**
+- Code quality problem (TODOs, complexity, coverage)
+- Known shortcut that needs refactoring
+- Accumulating technical burden
+
+**Add to To-do.md when:**
+- Task to complete
+- Feature to implement
+- One-time action item
+
+**Many items belong in multiple documents** (issue + debt + todo for fix).
+
+---
+
+**Document Status**: Living Issue Intelligence System
+**Update Frequency**: Real-time (as issues discovered) + session-based
+**Maintained By**: Development team using Trinity Method
+**Referenced By**: `/trinity-end` command for session updates
+**Pattern Library**: Creates trinity/patterns/ files
+**Last Updated**: {{CURRENT_DATE}}
+
+---
+
+*Issue tracking powered by Trinity Method v2.0*
+*Continuous pattern recognition and prevention system*