proagents 1.0.0

package/proagents/existing-projects/technical-debt-handling.md

@@ -0,0 +1,644 @@
+# Technical Debt Handling
+
+Manage and reduce technical debt during ProAgents adoption.
+
+---
+
+## Overview
+
+Technical debt in existing projects includes:
+- Low test coverage
+- Security vulnerabilities
+- Outdated dependencies
+- Missing documentation
+- Inconsistent patterns
+- Code quality issues
+
+ProAgents helps track and gradually reduce debt without blocking progress.
+
+---
+
+## Technical Debt Categories
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   Technical Debt Inventory                   │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Testing Debt          Documentation Debt                   │
+│  ─────────────         ──────────────────                   │
+│  • Low coverage        • Missing README                     │
+│  • Missing tests       • Outdated docs                      │
+│  • Flaky tests         • No API docs                        │
+│  • No E2E tests        • No architecture docs               │
+│                                                             │
+│  Code Quality Debt     Security Debt                        │
+│  ─────────────────     ─────────────                        │
+│  • Code smells         • Vulnerabilities                    │
+│  • High complexity     • Outdated deps                      │
+│  • Duplication         • Hardcoded secrets                  │
+│  • Poor naming         • Missing auth checks                │
+│                                                             │
+│  Pattern Debt          Infrastructure Debt                  │
+│  ────────────          ──────────────────                   │
+│  • Multiple patterns   • No CI/CD                           │
+│  • Legacy code         • Manual deployments                 │
+│  • Inconsistency       • No monitoring                      │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Debt Assessment
+
+### Running Assessment
+
+```bash
+# Full technical debt assessment
+/debt-assess
+
+# Assess specific category
+/debt-assess --category testing
+/debt-assess --category security
+/debt-assess --category patterns
+
+# Quick assessment
+/debt-assess --quick
+```
+
+### Assessment Output
+
+```yaml
+technical_debt_assessment:
+  date: "2024-01-15"
+  overall_score: 45  # 0-100 (lower = more debt)
+
+  categories:
+    testing:
+      score: 35
+      issues:
+        - type: "low_coverage"
+          severity: "high"
+          details: "Overall coverage 35%, target 80%"
+          files_affected: 234
+
+        - type: "missing_tests"
+          severity: "high"
+          details: "Critical paths untested"
+          paths:
+            - "src/services/paymentService.ts"
+            - "src/services/authService.ts"
+
+        - type: "flaky_tests"
+          severity: "medium"
+          count: 5
+
+    security:
+      score: 60
+      issues:
+        - type: "vulnerable_dependencies"
+          severity: "high"
+          count: 3
+
+        - type: "hardcoded_secrets"
+          severity: "critical"
+          files: 2
+
+    documentation:
+      score: 40
+      issues:
+        - type: "outdated_readme"
+          severity: "medium"
+          last_updated: "2022-06-15"
+
+        - type: "missing_api_docs"
+          severity: "medium"
+          endpoints_undocumented: 45
+
+    code_quality:
+      score: 55
+      issues:
+        - type: "high_complexity"
+          severity: "medium"
+          files: 12
+
+        - type: "code_duplication"
+          severity: "low"
+          percentage: 8
+
+    patterns:
+      score: 50
+      issues:
+        - type: "inconsistent_patterns"
+          severity: "medium"
+          patterns: ["redux", "zustand", "context"]
+```
+
+---
+
+## Debt Tracking
+
+### Debt Registry
+
+```yaml
+# proagents/debt/registry.yaml
+
+debt_items:
+  - id: "DEBT-001"
+    category: "testing"
+    type: "low_coverage"
+    created: "2024-01-15"
+    severity: "high"
+    status: "open"
+    description: "Payment service has 0% test coverage"
+    location: "src/services/paymentService.ts"
+    estimated_effort: "4 hours"
+    assigned_to: null
+    target_date: null
+
+  - id: "DEBT-002"
+    category: "security"
+    type: "hardcoded_secret"
+    created: "2024-01-15"
+    severity: "critical"
+    status: "in_progress"
+    description: "API key hardcoded in config"
+    location: "src/config/api.ts:15"
+    estimated_effort: "1 hour"
+    assigned_to: "dev-1"
+    target_date: "2024-01-20"
+
+  - id: "DEBT-003"
+    category: "patterns"
+    type: "legacy_code"
+    created: "2024-01-15"
+    severity: "low"
+    status: "open"
+    description: "Class components in admin module"
+    location: "src/admin/**"
+    estimated_effort: "8 hours"
+    assigned_to: null
+    target_date: null
+```
+
+### Debt Dashboard
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   Technical Debt Dashboard                   │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Total Debt Items: 45                                       │
+│  ├── Critical: 2 🔴                                        │
+│  ├── High: 12 🟠                                           │
+│  ├── Medium: 18 🟡                                         │
+│  └── Low: 13 🟢                                            │
+│                                                             │
+│  Status:                                                    │
+│  ├── Open: 35                                              │
+│  ├── In Progress: 7                                        │
+│  └── Resolved (this month): 8                              │
+│                                                             │
+│  By Category:                                               │
+│  Testing ████████████░░░░░░░░ 12                           │
+│  Security ██████░░░░░░░░░░░░░░ 6                           │
+│  Documentation ████████░░░░░░░░░░░░ 8                      │
+│  Code Quality ██████████░░░░░░░░░░ 10                      │
+│  Patterns ██████████░░░░░░░░░░ 9                           │
+│                                                             │
+│  Trend: ↓ 15% from last month                              │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Debt Reduction Strategies
+
+### Strategy 1: Touch-and-Fix
+
+```yaml
+touch_and_fix:
+  description: "Fix debt when you touch related code"
+
+  trigger: "Developer modifies a file"
+
+  actions:
+    - check_debt_items_for_file
+    - suggest_fixes
+    - track_if_skipped
+
+  example:
+    scenario: "Developer modifies paymentService.ts"
+    debt_found: "No tests for this file"
+    suggestion: "Add tests while you're here? (30 min estimated)"
+    options:
+      - "Add tests now"
+      - "Create debt ticket for later"
+      - "Skip (not recommended)"
+
+  configuration:
+    enforce: false  # Suggest, don't block
+    track_skips: true
+    max_additional_time: "30%"  # Don't suggest if > 30% extra work
+```
+
+### Strategy 2: Dedicated Sprints
+
+```yaml
+dedicated_sprints:
+  description: "Allocate time specifically for debt reduction"
+
+  allocation:
+    - option: "20% of each sprint"
+      suitable_for: "Continuous improvement"
+
+    - option: "Full debt sprint monthly"
+      suitable_for: "Larger items"
+
+    - option: "Quarterly debt week"
+      suitable_for: "Major refactoring"
+
+  prioritization:
+    - "Critical security issues first"
+    - "High-impact items second"
+    - "Quick wins (< 1 hour) third"
+    - "Low priority last"
+
+  tracking:
+    sprint_goal: "Reduce debt score by 5 points"
+    metrics:
+      - "Items resolved"
+      - "Debt score change"
+      - "Coverage improvement"
+```
+
+### Strategy 3: New Code Standards
+
+```yaml
+new_code_standards:
+  description: "Prevent new debt, fix old gradually"
+
+  for_new_code:
+    testing:
+      coverage_minimum: 80%
+      required_tests: ["unit", "integration"]
+      enforce: true
+
+    documentation:
+      required: true
+      minimum: ["function_docs", "readme_update"]
+
+    code_quality:
+      max_complexity: 10
+      no_code_smells: true
+
+  for_existing_code:
+    testing:
+      required: false
+      suggest_on_touch: true
+
+    documentation:
+      required: false
+      auto_generate: true
+
+    code_quality:
+      required: false
+      track_issues: true
+```
+
+---
+
+## Handling Specific Debt Types
+
+### Testing Debt
+
+```yaml
+testing_debt:
+  assessment:
+    current_coverage: 35%
+    target_coverage: 80%
+    gap: 45%
+
+  strategy:
+    phase_1:
+      name: "Critical paths"
+      focus:
+        - "Payment processing"
+        - "Authentication"
+        - "Core business logic"
+      target: "+15% coverage"
+
+    phase_2:
+      name: "High-traffic code"
+      focus:
+        - "Most modified files"
+        - "Bug-prone areas"
+      target: "+15% coverage"
+
+    phase_3:
+      name: "Everything else"
+      focus:
+        - "Remaining code"
+      target: "+15% coverage"
+
+  tools:
+    - name: "Coverage report"
+      command: "/test-coverage"
+    - name: "Untested code finder"
+      command: "/find-untested"
+    - name: "Test generator"
+      command: "/generate-tests [file]"
+
+  configuration:
+    block_pr_below: null  # Don't block existing
+    require_for_new: 80%
+    report_in_pr: true
+```
+
+### Security Debt
+
+```yaml
+security_debt:
+  priority: "HIGHEST"
+
+  immediate_actions:
+    critical:
+      - "Remove hardcoded secrets"
+      - "Patch critical vulnerabilities"
+      timeline: "24 hours"
+
+    high:
+      - "Update vulnerable dependencies"
+      - "Fix authentication gaps"
+      timeline: "1 week"
+
+  process:
+    1_scan: "/security-scan"
+    2_prioritize: "Critical → High → Medium → Low"
+    3_fix: "Dedicated security sprint if needed"
+    4_verify: "/security-scan --verify"
+
+  automation:
+    dependency_scanning: "daily"
+    secret_detection: "pre-commit"
+    vulnerability_alerts: true
+
+  configuration:
+    block_critical: true
+    block_high: false
+    report_all: true
+```
+
+### Documentation Debt
+
+```yaml
+documentation_debt:
+  assessment:
+    readme: "outdated"
+    api_docs: "50% coverage"
+    code_docs: "25% coverage"
+
+  strategy:
+    auto_generate:
+      enabled: true
+      scope: ["api", "components", "functions"]
+      output: "proagents/docs/"
+
+    manual_priority:
+      - "Architecture decisions"
+      - "Setup guide"
+      - "Contribution guide"
+
+  commands:
+    - name: "Generate all docs"
+      command: "/doc-full"
+    - name: "Update README"
+      command: "/doc-readme"
+    - name: "API documentation"
+      command: "/doc-api"
+
+  configuration:
+    auto_update: true
+    mark_generated: true
+    require_for_new_code: true
+```
+
+### Code Quality Debt
+
+```yaml
+code_quality_debt:
+  assessment:
+    complexity:
+      high_complexity_files: 12
+      average_complexity: 15
+      target: 10
+
+    duplication:
+      percentage: 8%
+      target: 3%
+
+    code_smells:
+      count: 45
+      categories: ["long_methods", "large_classes", "deep_nesting"]
+
+  strategy:
+    refactoring:
+      approach: "gradual"
+      trigger: "when_touched"
+
+    tools:
+      - name: "Complexity report"
+        command: "/quality-complexity"
+      - name: "Duplication finder"
+        command: "/quality-duplicates"
+      - name: "Code smell detector"
+        command: "/quality-smells"
+
+  configuration:
+    block_new_smells: true
+    suggest_refactoring: true
+    max_complexity_new_code: 10
+```
+
+---
+
+## Debt Prevention
+
+### Pre-commit Checks
+
+```yaml
+pre_commit:
+  checks:
+    - name: "No hardcoded secrets"
+      tool: "detect-secrets"
+      block: true
+
+    - name: "Tests for new code"
+      tool: "coverage-check"
+      block: false
+      warn: true
+
+    - name: "Complexity check"
+      tool: "complexity-check"
+      threshold: 15
+      block: false
+
+    - name: "Lint check"
+      tool: "eslint"
+      block: true
+```
+
+### PR Checks
+
+```yaml
+pr_checks:
+  required:
+    - name: "No new security issues"
+      tool: "security-scan"
+
+    - name: "Coverage not decreased"
+      tool: "coverage-compare"
+
+  informational:
+    - name: "New debt items"
+      tool: "debt-scan"
+      display: "pr_comment"
+
+    - name: "Quality metrics"
+      tool: "quality-report"
+      display: "pr_comment"
+```
+
+### Continuous Monitoring
+
+```yaml
+continuous_monitoring:
+  daily:
+    - "Dependency vulnerability scan"
+    - "Secret detection"
+
+  weekly:
+    - "Full debt assessment"
+    - "Quality trend report"
+
+  monthly:
+    - "Debt reduction progress report"
+    - "Priority reassessment"
+```
+
+---
+
+## Reporting
+
+### Debt Trends Report
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│               Technical Debt Trends - Q1 2024               │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Debt Score (0-100, higher is better)                       │
+│                                                             │
+│  100│                                                       │
+│   80│                                    ╱────              │
+│   60│                        ╱──────────╱                   │
+│   40│            ╱──────────╱                               │
+│   20│  ─────────╱                                           │
+│    0│                                                       │
+│     └────────────────────────────────────────────           │
+│      Jan   Feb   Mar   Apr   May   Jun                      │
+│                                                             │
+│  Items Resolved:                                            │
+│  Jan: 5 │ Feb: 8 │ Mar: 12 │ Apr: 15 │ May: 10 │ Jun: 8    │
+│                                                             │
+│  Coverage:                                                  │
+│  Jan: 35% │ Feb: 42% │ Mar: 55% │ Apr: 62% │ May: 70%      │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Sprint Report
+
+```markdown
+# Debt Reduction Sprint Report
+
+## Sprint: 2024-W03
+
+### Goals
+- [ ] Resolve 5 high-priority items
+- [x] Increase coverage by 5%
+- [x] Fix all critical security issues
+
+### Resolved Items
+| ID | Category | Description | Effort |
+|----|----------|-------------|--------|
+| DEBT-002 | Security | Hardcoded API key | 1h |
+| DEBT-005 | Testing | Payment tests | 4h |
+| DEBT-008 | Docs | Update README | 2h |
+
+### Metrics
+- Debt score: 45 → 52 (+7)
+- Coverage: 35% → 42% (+7%)
+- Items resolved: 8
+- Items added: 3 (net: -5)
+
+### Blockers
+- DEBT-010 blocked by external dependency update
+
+### Next Sprint
+- Focus on remaining security items
+- Continue coverage improvement
+```
+
+---
+
+## Configuration
+
+```yaml
+# proagents.config.yaml
+
+technical_debt:
+  tracking:
+    enabled: true
+    registry_path: "proagents/debt/registry.yaml"
+
+  assessment:
+    run_on_init: true
+    run_weekly: true
+
+  thresholds:
+    critical_block: true
+    high_warn: true
+    medium_track: true
+    low_track: true
+
+  reduction:
+    strategy: "touch_and_fix"
+    sprint_allocation: 20%
+    suggest_fixes: true
+
+  prevention:
+    new_code_standards: true
+    block_new_debt: false  # Suggest, don't block
+
+  reporting:
+    weekly_report: true
+    pr_comments: true
+    dashboard: true
+```
+
+---
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/debt-assess` | Run debt assessment |
+| `/debt-status` | View debt dashboard |
+| `/debt-list` | List all debt items |
+| `/debt-add` | Add debt item manually |
+| `/debt-resolve [id]` | Mark item as resolved |
+| `/debt-report` | Generate debt report |
+| `/debt-trends` | View debt trends |