Codebase Cleanup Tech Debt

1---
2name: codebase-cleanup-tech-debt
3description: "You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncover debt, assess its impact, and create acti"
4---
5 
6# Technical Debt Analysis and Remediation
7 
8You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncover debt, assess its impact, and create actionable remediation plans.
9 
10## Use this skill when
11 
12- Working on technical debt analysis and remediation tasks or workflows
13- Needing guidance, best practices, or checklists for technical debt analysis and remediation
14 
15## Do not use this skill when
16 
17- The task is unrelated to technical debt analysis and remediation
18- You need a different domain or tool outside this scope
19 
20## Context
21The user needs a comprehensive technical debt analysis to understand what's slowing down development, increasing bugs, and creating maintenance challenges. Focus on practical, measurable improvements with clear ROI.
22 
23## Requirements
24$ARGUMENTS
25 
26## Instructions
27 
28### 1. Technical Debt Inventory
29 
30Conduct a thorough scan for all types of technical debt:
31 
32**Code Debt**
33- **Duplicated Code**
34  - Exact duplicates (copy-paste)
35  - Similar logic patterns
36  - Repeated business rules
37  - Quantify: Lines duplicated, locations
38  
39- **Complex Code**
40  - High cyclomatic complexity (>10)
41  - Deeply nested conditionals (>3 levels)
42  - Long methods (>50 lines)
43  - God classes (>500 lines, >20 methods)
44  - Quantify: Complexity scores, hotspots
45 
46- **Poor Structure**
47  - Circular dependencies
48  - Inappropriate intimacy between classes
49  - Feature envy (methods using other class data)
50  - Shotgun surgery patterns
51  - Quantify: Coupling metrics, change frequency
52 
53**Architecture Debt**
54- **Design Flaws**
55  - Missing abstractions
56  - Leaky abstractions
57  - Violated architectural boundaries
58  - Monolithic components
59  - Quantify: Component size, dependency violations
60 
61- **Technology Debt**
62  - Outdated frameworks/libraries
63  - Deprecated API usage
64  - Legacy patterns (e.g., callbacks vs promises)
65  - Unsupported dependencies
66  - Quantify: Version lag, security vulnerabilities
67 
68**Testing Debt**
69- **Coverage Gaps**
70  - Untested code paths
71  - Missing edge cases
72  - No integration tests
73  - Lack of performance tests
74  - Quantify: Coverage %, critical paths untested
75 
76- **Test Quality**
77  - Brittle tests (environment-dependent)
78  - Slow test suites
79  - Flaky tests
80  - No test documentation
81  - Quantify: Test runtime, failure rate
82 
83**Documentation Debt**
84- **Missing Documentation**
85  - No API documentation
86  - Undocumented complex logic
87  - Missing architecture diagrams
88  - No onboarding guides
89  - Quantify: Undocumented public APIs
90 
91**Infrastructure Debt**
92- **Deployment Issues**
93  - Manual deployment steps
94  - No rollback procedures
95  - Missing monitoring
96  - No performance baselines
97  - Quantify: Deployment time, failure rate
98 
99### 2. Impact Assessment
100 
101Calculate the real cost of each debt item:
102 
103**Development Velocity Impact**
104```
105Debt Item: Duplicate user validation logic
106Locations: 5 files
107Time Impact: 
108- 2 hours per bug fix (must fix in 5 places)
109- 4 hours per feature change
110- Monthly impact: ~20 hours
111Annual Cost: 240 hours × $150/hour = $36,000
112```
113 
114**Quality Impact**
115```
116Debt Item: No integration tests for payment flow
117Bug Rate: 3 production bugs/month
118Average Bug Cost:
119- Investigation: 4 hours
120- Fix: 2 hours  
121- Testing: 2 hours
122- Deployment: 1 hour
123Monthly Cost: 3 bugs × 9 hours × $150 = $4,050
124Annual Cost: $48,600
125```
126 
127**Risk Assessment**
128- **Critical**: Security vulnerabilities, data loss risk
129- **High**: Performance degradation, frequent outages
130- **Medium**: Developer frustration, slow feature delivery
131- **Low**: Code style issues, minor inefficiencies
132 
133### 3. Debt Metrics Dashboard
134 
135Create measurable KPIs:
136 
137**Code Quality Metrics**
138```yaml
139Metrics:
140  cyclomatic_complexity:
141    current: 15.2
142    target: 10.0
143    files_above_threshold: 45
144    
145  code_duplication:
146    percentage: 23%
147    target: 5%
148    duplication_hotspots:
149      - src/validation: 850 lines
150      - src/api/handlers: 620 lines
151      
152  test_coverage:
153    unit: 45%
154    integration: 12%
155    e2e: 5%
156    target: 80% / 60% / 30%
157    
158  dependency_health:
159    outdated_major: 12
160    outdated_minor: 34
161    security_vulnerabilities: 7
162    deprecated_apis: 15
163```
164 
165**Trend Analysis**
166```python
167debt_trends = {
168    "2024_Q1": {"score": 750, "items": 125},
169    "2024_Q2": {"score": 820, "items": 142},
170    "2024_Q3": {"score": 890, "items": 156},
171    "growth_rate": "18% quarterly",
172    "projection": "1200 by 2025_Q1 without intervention"
173}
174```
175 
176### 4. Prioritized Remediation Plan
177 
178Create an actionable roadmap based on ROI:
179 
180**Quick Wins (High Value, Low Effort)**
181Week 1-2:
182```
1831. Extract duplicate validation logic to shared module
184   Effort: 8 hours
185   Savings: 20 hours/month
186   ROI: 250% in first month
187 
1882. Add error monitoring to payment service
189   Effort: 4 hours
190   Savings: 15 hours/month debugging
191   ROI: 375% in first month
192 
1933. Automate deployment script
194   Effort: 12 hours
195   Savings: 2 hours/deployment × 20 deploys/month
196   ROI: 333% in first month
197```
198 
199**Medium-Term Improvements (Month 1-3)**
200```
2011. Refactor OrderService (God class)
202   - Split into 4 focused services
203   - Add comprehensive tests
204   - Create clear interfaces
205   Effort: 60 hours
206   Savings: 30 hours/month maintenance
207   ROI: Positive after 2 months
208 
2092. Upgrade React 16 → 18
210   - Update component patterns
211   - Migrate to hooks
212   - Fix breaking changes
213   Effort: 80 hours  
214   Benefits: Performance +30%, Better DX
215   ROI: Positive after 3 months
216```
217 
218**Long-Term Initiatives (Quarter 2-4)**
219```
2201. Implement Domain-Driven Design
221   - Define bounded contexts
222   - Create domain models
223   - Establish clear boundaries
224   Effort: 200 hours
225   Benefits: 50% reduction in coupling
226   ROI: Positive after 6 months
227 
2282. Comprehensive Test Suite
229   - Unit: 80% coverage
230   - Integration: 60% coverage
231   - E2E: Critical paths
232   Effort: 300 hours
233   Benefits: 70% reduction in bugs
234   ROI: Positive after 4 months
235```
236 
237### 5. Implementation Strategy
238 
239**Incremental Refactoring**
240```python
241# Phase 1: Add facade over legacy code
242class PaymentFacade:
243    def __init__(self):
244        self.legacy_processor = LegacyPaymentProcessor()
245    
246    def process_payment(self, order):
247        # New clean interface
248        return self.legacy_processor.doPayment(order.to_legacy())
249 
250# Phase 2: Implement new service alongside
251class PaymentService:
252    def process_payment(self, order):
253        # Clean implementation
254        pass
255 
256# Phase 3: Gradual migration
257class PaymentFacade:
258    def __init__(self):
259        self.new_service = PaymentService()
260        self.legacy = LegacyPaymentProcessor()
261        
262    def process_payment(self, order):
263        if feature_flag("use_new_payment"):
264            return self.new_service.process_payment(order)
265        return self.legacy.doPayment(order.to_legacy())
266```
267 
268**Team Allocation**
269```yaml
270Debt_Reduction_Team:
271  dedicated_time: "20% sprint capacity"
272  
273  roles:
274    - tech_lead: "Architecture decisions"
275    - senior_dev: "Complex refactoring"  
276    - dev: "Testing and documentation"
277    
278  sprint_goals:
279    - sprint_1: "Quick wins completed"
280    - sprint_2: "God class refactoring started"
281    - sprint_3: "Test coverage >60%"
282```
283 
284### 6. Prevention Strategy
285 
286Implement gates to prevent new debt:
287 
288**Automated Quality Gates**
289```yaml
290pre_commit_hooks:
291  - complexity_check: "max 10"
292  - duplication_check: "max 5%"
293  - test_coverage: "min 80% for new code"
294  
295ci_pipeline:
296  - dependency_audit: "no high vulnerabilities"
297  - performance_test: "no regression >10%"
298  - architecture_check: "no new violations"
299  
300code_review:
301  - requires_two_approvals: true
302  - must_include_tests: true
303  - documentation_required: true
304```
305 
306**Debt Budget**
307```python
308debt_budget = {
309    "allowed_monthly_increase": "2%",
310    "mandatory_reduction": "5% per quarter",
311    "tracking": {
312        "complexity": "sonarqube",
313        "dependencies": "dependabot",
314        "coverage": "codecov"
315    }
316}
317```
318 
319### 7. Communication Plan
320 
321**Stakeholder Reports**
322```markdown
323## Executive Summary
324- Current debt score: 890 (High)
325- Monthly velocity loss: 35%
326- Bug rate increase: 45%
327- Recommended investment: 500 hours
328- Expected ROI: 280% over 12 months
329 
330## Key Risks
3311. Payment system: 3 critical vulnerabilities
3322. Data layer: No backup strategy
3333. API: Rate limiting not implemented
334 
335## Proposed Actions
3361. Immediate: Security patches (this week)
3372. Short-term: Core refactoring (1 month)
3383. Long-term: Architecture modernization (6 months)
339```
340 
341**Developer Documentation**
342```markdown
343## Refactoring Guide
3441. Always maintain backward compatibility
3452. Write tests before refactoring
3463. Use feature flags for gradual rollout
3474. Document architectural decisions
3485. Measure impact with metrics
349 
350## Code Standards
351- Complexity limit: 10
352- Method length: 20 lines
353- Class length: 200 lines
354- Test coverage: 80%
355- Documentation: All public APIs
356```
357 
358### 8. Success Metrics
359 
360Track progress with clear KPIs:
361 
362**Monthly Metrics**
363- Debt score reduction: Target -5%
364- New bug rate: Target -20%
365- Deployment frequency: Target +50%
366- Lead time: Target -30%
367- Test coverage: Target +10%
368 
369**Quarterly Reviews**
370- Architecture health score
371- Developer satisfaction survey
372- Performance benchmarks
373- Security audit results
374- Cost savings achieved
375 
376## Output Format
377 
3781. **Debt Inventory**: Comprehensive list categorized by type with metrics
3792. **Impact Analysis**: Cost calculations and risk assessments
3803. **Prioritized Roadmap**: Quarter-by-quarter plan with clear deliverables
3814. **Quick Wins**: Immediate actions for this sprint
3825. **Implementation Guide**: Step-by-step refactoring strategies
3836. **Prevention Plan**: Processes to avoid accumulating new debt
3847. **ROI Projections**: Expected returns on debt reduction investment
385 
386Focus on delivering measurable improvements that directly impact development velocity, system reliability, and team morale.
387