feat: Add tech-debt-tracker POWERFUL-tier skill
Complete technical debt management system with three interconnected tools: • debt_scanner.py - AST-based Python analysis + regex patterns for multi-language debt detection • debt_prioritizer.py - Multiple prioritization frameworks (CoD, WSJF, RICE) with sprint planning • debt_dashboard.py - Historical trend analysis, health scoring, and executive reporting Features: - 15+ debt types detected (complexity, duplicates, security, architecture, etc.) - Business impact analysis with ROI calculations - Health scoring (0-100) with trend forecasting - Executive and engineering stakeholder reports - Zero external dependencies, stdlib only - Comprehensive documentation and sample data Addresses: tech debt identification, prioritization, tracking, and stakeholder communication
This commit is contained in:
Leo
@@ -0,0 +1,335 @@
|
||||
# Technical Debt Prioritization Framework
|
||||
|
||||
## Introduction
|
||||
|
||||
Technical debt prioritization is a critical capability that separates high-performing engineering teams from those struggling with maintenance burden. This framework provides multiple approaches to systematically prioritize technical debt based on business value, risk, effort, and strategic alignment.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Business Value Alignment
|
||||
Technical debt work must connect to business outcomes. Every debt item should have a clear story about how fixing it supports business goals.
|
||||
|
||||
### 2. Evidence-Based Decisions
|
||||
Use data, not opinions, to drive prioritization. Measure impact, track trends, and validate assumptions with evidence.
|
||||
|
||||
### 3. Cost-Benefit Optimization
|
||||
Balance the cost of fixing debt against the cost of leaving it unfixed. Sometimes living with debt is the right business decision.
|
||||
|
||||
### 4. Risk Management
|
||||
Consider both the probability and impact of negative outcomes. High-probability, high-impact issues get priority.
|
||||
|
||||
### 5. Sustainable Pace
|
||||
Debt work should be sustainable over time. Avoid boom-bust cycles of neglect followed by emergency remediation.
|
||||
|
||||
## Prioritization Frameworks
|
||||
|
||||
### Framework 1: Cost of Delay (CoD)
|
||||
|
||||
**Best For**: Teams with clear business metrics and well-understood customer impact.
|
||||
|
||||
**Formula**: `Priority Score = (Business Value + Urgency + Risk Reduction) / Effort`
|
||||
|
||||
**Components**:
|
||||
|
||||
**Business Value (1-10 scale)**
|
||||
- Customer impact: How many users affected?
|
||||
- Revenue impact: Direct effect on business metrics
|
||||
- Strategic value: Alignment with business goals
|
||||
- Competitive advantage: Market positioning benefits
|
||||
|
||||
**Urgency (1-10 scale)**
|
||||
- Time sensitivity: How quickly does value decay?
|
||||
- Dependency criticality: Does this block other work?
|
||||
- Market timing: External deadlines or windows
|
||||
- Regulatory pressure: Compliance requirements
|
||||
|
||||
**Risk Reduction (1-10 scale)**
|
||||
- Security risk mitigation: Vulnerability reduction
|
||||
- Reliability improvement: Stability gains
|
||||
- Compliance risk: Regulatory issue prevention
|
||||
- Technical risk: Architectural problem prevention
|
||||
|
||||
**Effort Estimation**
|
||||
- Development time in story points or days
|
||||
- Risk multiplier for uncertainty (1.0-2.0x)
|
||||
- Skill requirements and availability
|
||||
- Cross-team coordination needs
|
||||
|
||||
**Example Calculation**:
|
||||
```
|
||||
Authentication module refactor:
|
||||
- Business Value: 8 (affects all users, blocks SSO)
|
||||
- Urgency: 7 (blocks Q2 enterprise features)
|
||||
- Risk Reduction: 9 (high security risk)
|
||||
- Total Numerator: 24
|
||||
- Effort: 3 weeks = 15 story points
|
||||
- CoD Score: 24/15 = 1.6
|
||||
```
|
||||
|
||||
### Framework 2: Weighted Shortest Job First (WSJF)
|
||||
|
||||
**Best For**: SAFe/Agile environments with portfolio-level planning.
|
||||
|
||||
**Formula**: `WSJF = (Business Value + Time Criticality + Risk Reduction) / Job Size`
|
||||
|
||||
**Scoring Guidelines**:
|
||||
|
||||
**Business Value (1-20 scale)**
|
||||
- User/business value from fixing this debt
|
||||
- Direct revenue or cost impact
|
||||
- Strategic importance to business objectives
|
||||
|
||||
**Time Criticality (1-20 scale)**
|
||||
- How user/business value declines over time
|
||||
- Dependency on other work items
|
||||
- Fixed deadlines or time-sensitive opportunities
|
||||
|
||||
**Risk Reduction/Opportunity Enablement (1-20 scale)**
|
||||
- Risk mitigation value
|
||||
- Future opportunities this enables
|
||||
- Options this preserves or creates
|
||||
|
||||
**Job Size (1-20 scale)**
|
||||
- Relative sizing compared to other debt items
|
||||
- Include uncertainty and risk factors
|
||||
- Consider dependencies and coordination overhead
|
||||
|
||||
**WSJF Bands**:
|
||||
- **Highest (WSJF > 10)**: Do immediately
|
||||
- **High (WSJF 5-10)**: Next quarter priority
|
||||
- **Medium (WSJF 2-5)**: Planned work
|
||||
- **Low (WSJF < 2)**: Backlog
|
||||
|
||||
### Framework 3: RICE (Reach, Impact, Confidence, Effort)
|
||||
|
||||
**Best For**: Product-focused teams with user-centric metrics.
|
||||
|
||||
**Formula**: `RICE Score = (Reach × Impact × Confidence) / Effort`
|
||||
|
||||
**Components**:
|
||||
|
||||
**Reach (number or percentage)**
|
||||
- How many developers/users affected per period?
|
||||
- Percentage of codebase impacted
|
||||
- Number of features that would benefit
|
||||
|
||||
**Impact (1-3 scale)**
|
||||
- 3 = Massive impact
|
||||
- 2 = High impact
|
||||
- 1 = Medium impact
|
||||
- 0.5 = Low impact
|
||||
- 0.25 = Minimal impact
|
||||
|
||||
**Confidence (percentage)**
|
||||
- How confident are you in your estimates?
|
||||
- Based on evidence, not gut feeling
|
||||
- 100% = High confidence with data
|
||||
- 80% = Medium confidence with some data
|
||||
- 50% = Low confidence, mostly assumptions
|
||||
|
||||
**Effort (story points or person-months)**
|
||||
- Total effort from all team members
|
||||
- Include design, development, testing, deployment
|
||||
- Account for coordination and communication overhead
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Legacy API cleanup:
|
||||
- Reach: 5 teams × 4 developers = 20 people per quarter
|
||||
- Impact: 2 (high - significantly improves developer experience)
|
||||
- Confidence: 80% (have done similar cleanups before)
|
||||
- Effort: 8 story points
|
||||
- RICE: (20 × 2 × 0.8) / 8 = 4.0
|
||||
```
|
||||
|
||||
### Framework 4: Technical Debt Quadrants
|
||||
|
||||
**Best For**: Teams needing to understand debt context and strategy.
|
||||
|
||||
Based on Martin Fowler's framework, categorize debt into quadrants:
|
||||
|
||||
**Quadrant 1: Reckless & Deliberate**
|
||||
- "We don't have time for design"
|
||||
- **Strategy**: Immediate remediation
|
||||
- **Priority**: Highest - created knowingly with poor justification
|
||||
|
||||
**Quadrant 2: Prudent & Deliberate**
|
||||
- "We must ship now and deal with consequences"
|
||||
- **Strategy**: Planned remediation
|
||||
- **Priority**: High - was right decision at time, now needs attention
|
||||
|
||||
**Quadrant 3: Reckless & Inadvertent**
|
||||
- "What's layering?"
|
||||
- **Strategy**: Education and process improvement
|
||||
- **Priority**: Medium - focus on preventing more
|
||||
|
||||
**Quadrant 4: Prudent & Inadvertent**
|
||||
- "Now we know how we should have done it"
|
||||
- **Strategy**: Opportunistic improvement
|
||||
- **Priority**: Low - normal part of learning
|
||||
|
||||
### Framework 5: Risk-Impact Matrix
|
||||
|
||||
**Best For**: Risk-averse organizations or regulated environments.
|
||||
|
||||
Plot debt items on 2D matrix:
|
||||
- X-axis: Likelihood of negative impact (1-5)
|
||||
- Y-axis: Severity of negative impact (1-5)
|
||||
|
||||
**Priority Quadrants**:
|
||||
- **Critical (High likelihood, High impact)**: Immediate action
|
||||
- **Important (High likelihood, Low impact OR Low likelihood, High impact)**: Planned action
|
||||
- **Monitor (Medium likelihood, Medium impact)**: Watch and assess
|
||||
- **Accept (Low likelihood, Low impact)**: Document decision to accept
|
||||
|
||||
**Impact Categories**:
|
||||
- **Security**: Data breaches, vulnerability exploitation
|
||||
- **Reliability**: System outages, data corruption
|
||||
- **Performance**: User experience degradation
|
||||
- **Compliance**: Regulatory violations, audit findings
|
||||
- **Productivity**: Team velocity reduction, developer frustration
|
||||
|
||||
## Multi-Framework Approach
|
||||
|
||||
### When to Use Multiple Frameworks
|
||||
|
||||
**Portfolio-Level Planning**:
|
||||
- Use WSJF for quarterly planning
|
||||
- Use CoD for sprint-level decisions
|
||||
- Use Risk-Impact for security review
|
||||
|
||||
**Team Maturity Progression**:
|
||||
- Start with simple Risk-Impact matrix
|
||||
- Progress to RICE as metrics improve
|
||||
- Advanced teams can use CoD effectively
|
||||
|
||||
**Context-Dependent Selection**:
|
||||
- **Regulated industries**: Risk-Impact primary, WSJF secondary
|
||||
- **Product companies**: RICE primary, CoD secondary
|
||||
- **Enterprise software**: CoD primary, WSJF secondary
|
||||
|
||||
### Combining Framework Results
|
||||
|
||||
**Weighted Scoring**:
|
||||
```
|
||||
Final Priority = 0.4 × CoD_Score + 0.3 × RICE_Score + 0.3 × Risk_Score
|
||||
```
|
||||
|
||||
**Tier-Based Approach**:
|
||||
1. Security/compliance items (Risk-Impact)
|
||||
2. High business value items (RICE/CoD)
|
||||
3. Developer productivity items (WSJF)
|
||||
4. Technical excellence items (Quadrants)
|
||||
|
||||
## Implementation Guidelines
|
||||
|
||||
### Setting Up Prioritization
|
||||
|
||||
**Step 1: Choose Primary Framework**
|
||||
- Consider team maturity, organization culture, available data
|
||||
- Start simple, evolve complexity over time
|
||||
- Ensure framework aligns with business planning cycles
|
||||
|
||||
**Step 2: Define Scoring Criteria**
|
||||
- Create rubrics for each scoring dimension
|
||||
- Use organization-specific examples
|
||||
- Train team on consistent application
|
||||
|
||||
**Step 3: Establish Review Cadence**
|
||||
- Weekly: New urgent items
|
||||
- Bi-weekly: Sprint planning integration
|
||||
- Monthly: Portfolio review and reprioritization
|
||||
- Quarterly: Framework effectiveness review
|
||||
|
||||
**Step 4: Tool Integration**
|
||||
- Use existing project management tools
|
||||
- Automate scoring where possible
|
||||
- Create dashboards for stakeholder communication
|
||||
|
||||
### Common Pitfalls
|
||||
|
||||
**Analysis Paralysis**
|
||||
- **Problem**: Spending too much time on perfect prioritization
|
||||
- **Solution**: Use "good enough" decisions, iterate quickly
|
||||
|
||||
**Ignoring Business Context**
|
||||
- **Problem**: Purely technical prioritization
|
||||
- **Solution**: Always include business stakeholder perspective
|
||||
|
||||
**Inconsistent Application**
|
||||
- **Problem**: Different teams using different approaches
|
||||
- **Solution**: Standardize framework, provide training
|
||||
|
||||
**Over-Engineering the Process**
|
||||
- **Problem**: Complex frameworks nobody uses
|
||||
- **Solution**: Start simple, add complexity only when needed
|
||||
|
||||
**Neglecting Stakeholder Buy-In**
|
||||
- **Problem**: Engineering-only prioritization decisions
|
||||
- **Solution**: Include product, business stakeholders in framework design
|
||||
|
||||
### Measuring Framework Effectiveness
|
||||
|
||||
**Leading Indicators**:
|
||||
- Framework adoption rate across teams
|
||||
- Time to prioritization decision
|
||||
- Stakeholder satisfaction with decisions
|
||||
- Consistency of scoring across team members
|
||||
|
||||
**Lagging Indicators**:
|
||||
- Debt reduction velocity
|
||||
- Business outcome improvements
|
||||
- Technical incident reduction
|
||||
- Developer satisfaction improvements
|
||||
|
||||
**Review Questions**:
|
||||
1. Are we making better debt decisions than before?
|
||||
2. Do stakeholders trust our prioritization process?
|
||||
3. Are we delivering measurable business value from debt work?
|
||||
4. Is the framework sustainable for long-term use?
|
||||
|
||||
## Stakeholder Communication
|
||||
|
||||
### For Engineering Leaders
|
||||
|
||||
**Monthly Dashboard**:
|
||||
- Debt portfolio health score
|
||||
- Priority distribution by framework
|
||||
- Progress on high-priority items
|
||||
- Framework effectiveness metrics
|
||||
|
||||
**Quarterly Business Review**:
|
||||
- Debt work business impact
|
||||
- Framework ROI analysis
|
||||
- Resource allocation recommendations
|
||||
- Strategic debt initiative proposals
|
||||
|
||||
### For Product Managers
|
||||
|
||||
**Sprint Planning Input**:
|
||||
- Debt items affecting feature velocity
|
||||
- User experience impact from debt
|
||||
- Feature delivery risk from debt
|
||||
- Opportunity cost of debt work vs features
|
||||
|
||||
**Roadmap Integration**:
|
||||
- Debt work timing with feature releases
|
||||
- Dependencies between debt work and features
|
||||
- Resource allocation for debt vs features
|
||||
- Customer impact communication
|
||||
|
||||
### for Executive Leadership
|
||||
|
||||
**Executive Summary**:
|
||||
- Overall technical health trend
|
||||
- Business risk from technical debt
|
||||
- Investment recommendations
|
||||
- Competitive implications
|
||||
|
||||
**Key Metrics**:
|
||||
- Debt-adjusted development velocity
|
||||
- Technical incident trends
|
||||
- Customer satisfaction correlations
|
||||
- Team retention and satisfaction
|
||||
|
||||
This prioritization framework should be adapted to your organization's context, but the core principles of evidence-based, business-aligned, systematic prioritization should remain constant.
|
||||
Reference in New Issue
Block a user