trinity-method-sdk 2.0.0

package/dist/templates/knowledge-base/Technical-Debt.md.template

@@ -0,0 +1,640 @@
+# Technical Debt Tracking - {{PROJECT_NAME}}
+**Trinity Method v2.0**
+**Technology Stack**: {{TECHNOLOGY_STACK}}
+**Framework**: {{PRIMARY_FRAMEWORK}}
+**Last Updated**: {{CURRENT_DATE}}
+
+---
+
+## 📊 DEBT METRICS DASHBOARD
+
+### Current Baseline Metrics
+```yaml
+Technical_Debt_Metrics:
+  Code_Quality:
+    TODO_Comments: {{TODO_COUNT}}
+    FIXME_Comments: {{FIXME_COUNT}}
+    HACK_Comments: {{HACK_COUNT}}
+    Console_Statements: {{CONSOLE_COUNT}}
+    Commented_Code_Blocks: {{COMMENTED_BLOCKS}}
+
+  File_Complexity:
+    Files_Over_500_Lines: {{FILES_500}}
+    Files_Over_1000_Lines: {{FILES_1000}}
+    Files_Over_3000_Lines: {{FILES_3000}}
+    Average_File_Length: {{AVG_LENGTH}}
+
+  Test_Coverage:
+    Overall_Coverage: {{OVERALL_COVERAGE}}%
+    Unit_Test_Coverage: {{UNIT_COVERAGE}}%
+    Integration_Coverage: {{INTEGRATION_COVERAGE}}%
+    Untested_Components: {{UNTESTED_COUNT}}
+
+  {{FRAMEWORK}}_Specific:
+    Deprecated_APIs: {{DEPRECATED_COUNT}}
+    Anti_Patterns: {{ANTIPATTERN_COUNT}}
+    Performance_Issues: {{PERF_ISSUE_COUNT}}
+    Security_Warnings: {{SECURITY_COUNT}}
+```
+
+### Trend Analysis
+```yaml
+Session_Comparison:
+  Previous_Session:
+    Date: {{PREV_DATE}}
+    Total_Debt_Score: {{PREV_SCORE}}
+    Critical_Items: {{PREV_CRITICAL}}
+
+  Current_Session:
+    Date: {{CURR_DATE}}
+    Total_Debt_Score: {{CURR_SCORE}}
+    Critical_Items: {{CURR_CRITICAL}}
+
+  Delta:
+    Score_Change: {{SCORE_DELTA}}
+    Trend: {{IMPROVING/DEGRADING/STABLE}}
+    Velocity: {{ITEMS_RESOLVED}}/session
+```
+
+---
+
+## 🔍 PATTERN LIBRARY
+
+### Recurring Technical Debt Patterns
+
+#### Pattern: {{PATTERN_NAME_1}}
+**Frequency**: Found in {{COUNT}} files
+**Category**: {{CATEGORY}}
+**Impact**: {{HIGH/MEDIUM/LOW}}
+**Debt Score**: {{SCORE}}/10
+
+**Files Affected**:
+```
+{{FILE_1}}:{{LINE_NUMBERS}}
+{{FILE_2}}:{{LINE_NUMBERS}}
+{{FILE_3}}:{{LINE_NUMBERS}}
+```
+
+**Pattern Description**:
+{{PATTERN_DESCRIPTION}}
+
+**Root Cause**:
+{{ROOT_CAUSE}}
+
+**Refactoring Template**:
+```{{LANGUAGE}}
+// Current (problematic) pattern
+{{CURRENT_CODE}}
+
+// Refactored solution
+{{REFACTORED_CODE}}
+```
+
+**Impact Analysis**:
+- **If Fixed**: Resolves {{COUNT}} issues across {{FILE_COUNT}} files
+- **If Ignored**: Technical debt compounds by {{PERCENTAGE}}% per month
+- **Effort Required**: {{HOURS}} hours
+- **ROI**: {{HIGH/MEDIUM/LOW}}
+
+---
+
+## 📈 ROOT CAUSE ANALYSIS
+
+### High-Impact Root Causes
+
+#### Root Cause: {{ROOT_CAUSE_1}}
+**Impact Multiplier**: 1:{{MULTIPLIER}} (1 fix resolves {{MULTIPLIER}} symptoms)
+**Debt Category**: {{CATEGORY}}
+**Priority**: {{CRITICAL/HIGH/MEDIUM/LOW}}
+
+**Affected Areas**:
+1. **{{COMPONENT_1}}**: {{ISSUE_COUNT}} issues
+2. **{{COMPONENT_2}}**: {{ISSUE_COUNT}} issues
+3. **{{COMPONENT_3}}**: {{ISSUE_COUNT}} issues
+
+**Symptoms Caused**:
+- {{SYMPTOM_1}}
+- {{SYMPTOM_2}}
+- {{SYMPTOM_3}}
+
+**Resolution Strategy**:
+```yaml
+Phase_1_Quick_Wins:
+  - {{QUICK_FIX_1}}
+  - {{QUICK_FIX_2}}
+  Time: {{HOURS}} hours
+
+Phase_2_Refactoring:
+  - {{REFACTOR_1}}
+  - {{REFACTOR_2}}
+  Time: {{DAYS}} days
+
+Phase_3_Prevention:
+  - {{PREVENTION_1}}
+  - {{PREVENTION_2}}
+  Time: Ongoing
+```
+
+---
+
+## 📝 TODO/FIXME/HACK INVENTORY
+
+### Critical (Security/Stability) - P0
+```yaml
+- File: {{FILE_PATH}}
+  Line: {{LINE}}
+  Type: {{TODO/FIXME/HACK}}
+  Content: "{{COMMENT_TEXT}}"
+  Impact: {{IMPACT_DESCRIPTION}}
+  Risk: CRITICAL
+  Resolution: {{RESOLUTION_PLAN}}
+```
+
+### High Priority (Performance/Quality) - P1
+[High priority technical debt items]
+
+### Medium Priority (Maintainability) - P2
+[Medium priority improvements]
+
+### Low Priority (Nice to Have) - P3
+[Low priority enhancements]
+
+---
+
+## 📏 COMPLEXITY ANALYSIS
+
+### Files Exceeding Complexity Thresholds
+
+#### Critical - Files Over 3000 Lines
+```yaml
+{{LARGE_FILE_1}}:
+  Lines: {{LINE_COUNT}}
+  Complexity_Score: {{COMPLEXITY}}
+  Components: {{COMPONENT_COUNT}}
+  Refactor_Strategy:
+    - Split into {{SUGGESTED_FILES}}
+    - Extract {{EXTRACTABLE_COMPONENTS}}
+    - Estimated_Effort: {{HOURS}} hours
+```
+
+#### Warning - Files Over 1000 Lines
+[Files that should be monitored and potentially refactored]
+
+#### Watch - Files Over 500 Lines
+[Files to watch for growing complexity]
+
+### Cyclomatic Complexity
+| File | Function | Complexity | Risk Level |
+|------|----------|------------|------------|
+| {{FILE}} | {{FUNCTION}} | {{SCORE}} | {{RISK}} |
+
+---
+
+## 🧪 TEST COVERAGE GAPS
+
+### Components Without Tests
+```yaml
+Critical_Untested:
+  {{COMPONENT_1}}:
+    Type: {{TYPE}}
+    Risk: CRITICAL
+    Functions: {{COUNT}}
+    Test_Effort: {{HOURS}} hours
+    Scope: COMPREHENSIVE
+```
+
+### Components With Insufficient Tests
+```yaml
+{{COMPONENT_NAME}}:
+  Current_Coverage: {{PERCENTAGE}}%
+  Target_Coverage: {{TARGET}}%
+  Gap: {{GAP}}%
+  Critical_Paths_Untested: [{{PATH_LIST}}]
+  Missing_Test_Types: [unit/integration/e2e]
+```
+
+### Test Debt Score
+```javascript
+const testDebtScore = {
+  untested_components: {{COUNT}},
+  insufficient_coverage: {{COUNT}},
+  missing_edge_cases: {{COUNT}},
+  no_integration_tests: {{COUNT}},
+  total_debt_score: {{SCORE}}/100
+};
+```
+
+---
+
+## 🔒 SECURITY DEBT
+
+### Security Warnings and Suppressions
+```yaml
+Security_Debt:
+  Suppressed_Warnings: {{COUNT}}
+  Vulnerable_Dependencies: {{COUNT}}
+  Unvalidated_Inputs: {{COUNT}}
+  Exposed_Secrets_Risk: {{COUNT}}
+  Missing_Security_Headers: {{COUNT}}
+```
+
+### Security Debt Items
+```yaml
+- Type: {{SECURITY_ISSUE_TYPE}}
+  Location: {{FILE}}:{{LINE}}
+  Severity: {{CRITICAL/HIGH/MEDIUM/LOW}}
+  Description: {{DESCRIPTION}}
+  Fix: {{FIX_DESCRIPTION}}
+  Effort: {{HOURS}} hours
+```
+
+---
+
+## ⚡ PERFORMANCE DEBT
+
+### Performance Bottlenecks
+```yaml
+{{BOTTLENECK_1}}:
+  Type: {{TYPE}}
+  Impact: {{MILLISECONDS}}ms delay
+  Frequency: {{CALLS_PER_MINUTE}}
+  Total_Impact: {{TOTAL_MS}}ms/min
+  Fix_Strategy: {{STRATEGY}}
+  Effort: {{HOURS}} hours
+```
+
+### Optimization Opportunities
+1. **{{OPTIMIZATION_1}}**: Save {{MS}}ms per operation
+2. **{{OPTIMIZATION_2}}**: Reduce memory by {{MB}}MB
+3. **{{OPTIMIZATION_3}}**: Decrease bundle by {{KB}}KB
+
+---
+
+## 🔄 DEBT REDUCTION PLAN
+
+### Sprint Planning - Next Session Priorities
+```yaml
+Priority_1_Quick_Wins:
+  - Task: {{TASK}}
+    Impact: Fixes {{COUNT}} issues
+    Effort: {{HOURS}} hours
+    ROI: {{HIGH/MEDIUM/LOW}}
+```
+
+### Quarter Planning - Strategic Improvements
+```yaml
+Q1_Goals:
+  - Reduce_TODO_Count: {{PERCENTAGE}}%
+  - Increase_Coverage: {{PERCENTAGE}}%
+  - Refactor_Large_Files: {{COUNT}} files
+  - Fix_Security_Issues: ALL critical
+```
+
+### Automation Opportunities
+```yaml
+Automatable_Fixes:
+  - Pattern: {{PATTERN}}
+    Files_Affected: {{COUNT}}
+    Automation_Method: {{METHOD}}
+    Time_Saved: {{HOURS}} hours
+```
+
+---
+
+## 📋 SESSION DEBT TRACKING
+
+### Added This Session
+```yaml
+New_Debt:
+  TODOs_Added: {{COUNT}}
+  FIXMEs_Added: {{COUNT}}
+  Coverage_Decreased: {{PERCENTAGE}}%
+  Files_Grew_Large: {{COUNT}}
+  New_Suppressions: {{COUNT}}
+```
+
+### Resolved This Session
+```yaml
+Debt_Resolved:
+  TODOs_Fixed: {{COUNT}}
+  FIXMEs_Resolved: {{COUNT}}
+  Coverage_Increased: {{PERCENTAGE}}%
+  Files_Refactored: {{COUNT}}
+  Suppressions_Removed: {{COUNT}}
+```
+
+### Net Change
+```yaml
+Session_Summary:
+  Overall_Debt_Score: {{IMPROVED/DEGRADED}} by {{POINTS}}
+  Trend: {{POSITIVE/NEGATIVE/NEUTRAL}}
+  Velocity: {{ITEMS_PER_SESSION}} items/session
+  Projected_Sessions_To_Target: {{COUNT}}
+```
+
+---
+
+## 🎯 SUCCESS METRICS & GOALS
+
+### Short-term Goals (Next 3 Sessions)
+```yaml
+Immediate_Targets:
+  TODO_Reduction: <{{TARGET}} (from {{CURRENT}})
+  Test_Coverage: >{{TARGET}}% (from {{CURRENT}}%)
+  Large_Files: <{{TARGET}} (from {{CURRENT}})
+  Critical_Security: 0 (from {{CURRENT}})
+```
+
+### Long-term Goals (Next Quarter)
+```yaml
+Strategic_Targets:
+  Overall_Debt_Score: <{{TARGET}}/100
+  Test_Coverage: >{{TARGET}}%
+  Code_Quality_Score: >{{TARGET}}/10
+  Performance_Score: >{{TARGET}}/10
+  Security_Score: {{TARGET}}/10
+```
+
+### Progress Tracking
+```javascript
+const debtReductionVelocity = {
+  current_velocity: {{ITEMS_PER_SESSION}},
+  required_velocity: {{REQUIRED_ITEMS}},
+  acceleration_needed: {{PERCENTAGE}}%,
+  sessions_to_goal: {{COUNT}},
+  on_track: {{true/false}}
+};
+```
+
+---
+
+## 📈 DEBT SCORING ALGORITHM
+
+### Debt Score Calculation
+```javascript
+const calculateDebtScore = () => {
+  const weights = {
+    todos: 1,
+    fixmes: 2,
+    hacks: 3,
+    untested: 5,
+    large_files: 3,
+    security: 10,
+    performance: 4
+  };
+
+  return {
+    code_quality_score: {{SCORE}},
+    test_coverage_score: {{SCORE}},
+    security_score: {{SCORE}},
+    performance_score: {{SCORE}},
+    maintainability_score: {{SCORE}},
+    total_debt_score: {{TOTAL_SCORE}}
+  };
+};
+```
+
+---
+
+## 🔗 RELATED DOCUMENTS
+
+- **ISSUES.md**: Active issues and patterns
+- **ARCHITECTURE.md**: System design decisions
+- **Trinity.md**: Methodology implementation
+- **To-do.md**: Actionable task list
+- **Pattern Library**: trinity/patterns/
+
+---
+
+## 📝 WHEN TO UPDATE THIS DOCUMENT
+
+This is a **living debt tracking system** that should be updated continuously to monitor and reduce technical debt.
+
+### Immediate Updates Required ⚠️
+
+Update **during development** (real-time):
+
+- ✅ **TODO/FIXME/HACK Added**: Increment debt counts immediately when adding code markers
+- ✅ **TODO/FIXME Resolved**: Decrement counts when removing debt markers
+- ✅ **Large File Created**: Update file complexity metrics when file >500 lines
+- ✅ **File Refactored**: Update complexity metrics when splitting/refactoring files
+- ✅ **Coverage Changes**: Update test coverage metrics after test additions/removals
+- ✅ **Security Issue Found**: Add to Security Debt section immediately
+- ✅ **Performance Bottleneck Identified**: Add to Performance Debt section
+- ✅ **Pattern Discovered**: Add to Pattern Library when recurring debt pattern found
+
+### Session Updates (Via `/trinity-end`) 🔄
+
+Update at end of each development session:
+
+- Recalculate all metrics (TODO count, file complexity, coverage)
+- Update Session Comparison (previous vs current metrics)
+- Add new debt from session work
+- Mark resolved debt from session work
+- Update trend analysis (improving/degrading/stable)
+- Calculate debt reduction velocity
+- Update ROI analysis for debt items
+
+### Weekly Reviews ⏰
+
+Track debt trends and prioritization:
+
+- Review debt metrics trend (week-over-week)
+- Identify highest-impact debt items (ROI analysis)
+- Update debt reduction plan priorities
+- Calculate velocity (debt items resolved per week)
+- Update Quick Wins section (easy, high-value items)
+
+### Monthly Audits 📅
+
+Deep debt analysis and strategic planning:
+
+- Full debt score recalculation
+- Pattern consolidation (merge similar debt patterns)
+- Quarterly goals assessment
+- Debt reduction strategy refinement
+- Automation opportunity identification
+
+### Cross-Document Update Triggers 🔗
+
+**When updating Technical-Debt.md, also check:**
+
+- **[ISSUES.md](./ISSUES.md)**: Link debt items to issues if debt causes recurring problems
+- **[To-do.md](./To-do.md)**: Create tasks to pay down critical/high-priority debt
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)**: Update if architectural debt revealed design problems
+- **[CODING-PRINCIPLES.md](./CODING-PRINCIPLES.md)**: Add principle if debt pattern reveals standard violation
+- **[TESTING-PRINCIPLES.md](./TESTING-PRINCIPLES.md)**: Update coverage targets if coverage debt significant
+
+### Update Scenarios - What to Change
+
+**Scenario: Added TODO/FIXME Comment**
+```yaml
+Updates_Required:
+  - TODO_FIXME_HACK_Inventory: Add new entry with file, line, description
+  - Debt_Metrics_Dashboard: Increment TODO_Comments count
+  - Priority_Assignment: Assign P0/P1/P2/P3 based on impact
+  - Session_Debt_Tracking: Add to "Added This Session" section
+  - Cross_References:
+    - To-do.md: Add task to resolve the TODO/FIXME
+```
+
+**Scenario: Refactored Large File (>500 lines → <300 lines)**
+```yaml
+Updates_Required:
+  - File_Complexity: Update file count metrics (Files_Over_500_Lines decrement)
+  - Complexity_Analysis: Update Average_File_Length
+  - Session_Debt_Tracking: Add to "Debt Resolved" section
+  - Trend_Analysis: Mark as IMPROVING
+  - Cross_References:
+    - ISSUES.md: Close related file complexity issues
+    - ARCHITECTURE.md: Update if component structure changed
+```
+
+**Scenario: Test Coverage Improved (75% → 85%)**
+```yaml
+Updates_Required:
+  - Test_Coverage: Update Overall_Coverage percentage
+  - Test_Coverage_Gaps: Remove components now covered
+  - Debt_Metrics_Dashboard: Update coverage metrics
+  - Session_Debt_Tracking: Document coverage increase
+  - Trend_Analysis: Mark Test_Coverage as IMPROVING
+  - Cross_References:
+    - TESTING-PRINCIPLES.md: Verify new coverage meets standards
+```
+
+**Scenario: Pattern Discovered (Code Duplication in 5 files)**
+```yaml
+Updates_Required:
+  - Pattern_Library: Create new pattern entry
+  - Root_Cause_Analysis: Document why duplication occurred
+  - Refactoring_Template: Provide solution for similar cases
+  - Impact_Analysis: Calculate ROI of fixing pattern
+  - Debt_Reduction_Plan: Add to Quick Wins or Strategic Improvements
+  - Cross_References:
+    - ISSUES.md: Link to duplication pattern if causes issues
+    - trinity/patterns/: Create pattern file
+```
+
+**Scenario: Security Vulnerability Fixed**
+```yaml
+Updates_Required:
+  - Security_Debt: Remove resolved vulnerability
+  - Debt_Metrics_Dashboard: Decrement Security_Warnings count
+  - Session_Debt_Tracking: Add to "Debt Resolved" section
+  - Prevention_Automation: Document how to prevent in future
+  - Cross_References:
+    - ISSUES.md: Close security issue
+    - CODING-PRINCIPLES.md: Add security principle if gap revealed
+```
+
+**Scenario: Performance Bottleneck Resolved**
+```yaml
+Updates_Required:
+  - Performance_Debt: Remove resolved bottleneck
+  - Optimization_Opportunities: Mark as completed
+  - Debt_Metrics_Dashboard: Update Performance_Issues count
+  - Impact_Analysis: Document performance improvement (ms saved)
+  - Cross_References:
+    - ARCHITECTURE.md: Update Performance Baselines
+    - ISSUES.md: Close performance issues
+```
+
+### How to Update
+
+**Step-by-step process:**
+
+1. **Run Metrics**: Execute debt metric calculations (grep TODO, count files, run coverage)
+2. **Compare Baseline**: Compare new metrics to previous session metrics
+3. **Update Sections**: Update relevant sections (metrics, patterns, priorities)
+4. **Calculate Trends**: Determine if debt is improving/degrading/stable
+5. **Update Cross-Refs**: Link related debt items to issues/todos
+6. **Prioritize**: Update debt reduction plan based on new ROI analysis
+7. **Update Timestamp**: Set `Last Updated: {{CURRENT_DATE}}` to actual date
+
+**Metric Calculation Commands** (for reference):
+```bash
+# Count TODO comments
+grep -r "TODO" src/ | wc -l
+
+# Count FIXME comments
+grep -r "FIXME" src/ | wc -l
+
+# Files over 500 lines
+find src/ -name "*.js" -exec wc -l {} \; | awk '$1 > 500' | wc -l
+
+# Test coverage
+npm run test:coverage -- --json | jq '.total.lines.pct'
+```
+
+**Quality Checklist:**
+- [ ] All metrics calculated with actual commands (not guessed)
+- [ ] Trend direction accurate (improving/degrading/stable)
+- [ ] ROI calculations realistic (effort vs impact)
+- [ ] Patterns have refactoring templates (actionable)
+- [ ] Cross-references to ISSUES/To-do updated
+- [ ] Debt reduction plan prioritized by ROI
+
+### When NOT to Update ❌
+
+**Don't update if:**
+- Metrics haven't changed (no new TODOs, files, coverage changes)
+- Only documentation updated (no code debt)
+- Third-party library issues (not project debt)
+- Debt is external dependency problem (out of team control)
+
+**Stale metrics are okay** if debt genuinely hasn't changed. Don't recalculate just to update timestamp.
+
+### Debt vs. Issue vs. Todo 🤔
+
+**Add to Technical-Debt.md when:**
+- Code quality problem (TODOs, complexity, coverage)
+- Known shortcut needing refactoring
+- Accumulating burden (technical interest)
+- Measurable metric (can track numerically)
+
+**Add to ISSUES.md when:**
+- Debt causes bugs or issues
+- Debt pattern causes recurring problems
+- Framework-specific debt pattern
+
+**Add to To-do.md when:**
+- Task to pay down specific debt item
+- Refactoring work planned
+- Debt resolution action item
+
+**Debt often triggers todos** (debt identified → todo created to fix it).
+
+### Metrics Update Frequency 📊
+
+**Real-time** (as code changes):
+- TODO/FIXME/HACK counts
+- File line counts
+
+**Per Session** (via `/trinity-end`):
+- Test coverage percentages
+- Debt score calculations
+- Trend analysis
+
+**Weekly**:
+- Velocity calculations
+- ROI analysis
+- Priority reassessment
+
+**Monthly**:
+- Full debt audit
+- Pattern consolidation
+- Strategic planning
+
+---
+
+**Document Status**: Living Debt Tracking System
+**Update Frequency**: Real-time (code changes) + session-based
+**Maintained By**: Development team using Trinity Method
+**Referenced By**: `/trinity-end` command for session updates
+**Metrics**: Automated via grep/find/coverage commands
+**Last Updated**: {{CURRENT_DATE}}
+
+---
+
+*Technical Debt tracking powered by Trinity Method v2.0*
+*Continuous monitoring and reduction system*