Risk Tracking & Technical Debt Management

Enable systematic identification, tracking, prioritization, and management of technical risks and technical debt through structured analysis, proactive monitoring, and actionable remediation planning.

When to Use This Skill

• User describes technical concerns, code smells, or observed issues
• User asks to assess risk severity or technical debt priority
• User needs help creating remediation plans or mitigation strategies
• User wants to track risks or debt over time
• User asks for stakeholder-appropriate reporting
• User mentions terms like: "tech debt", "refactoring backlog", "security risk", "architectural concern", "code quality issues"

Core Workflows

1. Risk Identification & Assessment

When a user describes a potential technical risk:

1. Categorize the risk using references/risk-categories.md:

   • Security, Performance, Scalability, Architecture, Dependency, or Operational

2. Gather context by asking clarifying questions if needed:

   • What components are affected?
   • What's the potential user/business impact?
   • Are there existing mitigations?
   • What's the timeline concern?

3. Assess severity using likelihood and impact:

   • Likelihood: Rare, Unlikely, Possible, Likely, Almost Certain
   • Impact: Negligible, Minor, Moderate, Major, Severe
   • Use scripts/risk_assessment.py to calculate risk score

4. Document in structured format using assets/templates/risk-register-template.md

Example interaction:

User: "Our API doesn't have rate limiting and we're seeing some unusual traffic patterns."

Claude: This is an Operational/Security risk. Let me assess it:
- Category: Operational (with security implications)
- Likelihood: Likely (unprotected APIs are regularly targeted)
- Impact: Major (service disruption, potential abuse)
- Risk Score: 16 (4 × 4) - Critical priority

I'll help you document this in your risk register and create a mitigation plan.

2. Technical Debt Documentation

When a user identifies technical debt:

1. Classify the debt type using references/debt-types.md:

   • Code Quality, Documentation, Test Coverage, Infrastructure, Design, or Dependency

2. Capture context:

   • Where is the debt? (files, components)
   • Why does it exist? (historical context)
   • What would the proper solution be?

3. Assess impact using four factors:

   • Pain Level (1-5): Daily friction
   • Blast Radius (1-5): Areas/people affected
   • Remediation Cost (1-5): Effort required
   • Business Value (1-5): Value unlocked
   • Use scripts/debt_prioritization.py to calculate priority score

4. Document using assets/templates/debt-inventory-template.md

Example interaction:

User: "We have the same validation logic copied in 8 different controllers."

Claude: This is Code Quality debt (DRY violation). Let me assess:
- Pain Level: 4 (copy-paste errors are common)
- Blast Radius: 3 (affects multiple features)
- Remediation Cost: 2 (8 hours to extract to service)
- Business Value: 3 (prevents bugs, easier maintenance)
- Priority Score: 3.65 - High priority

This qualifies as a "Quick Win" - high value relative to low effort. I'll create a detailed debt record with remediation plan.

3. Prioritization & Planning

When a user needs help prioritizing multiple items:

1. For risks: Sort by risk score (likelihood × impact)
2. For debt: Use prioritization script to identify:
   • Quick Wins (high value, low cost)
   • Strategic Investments (high impact, higher cost)
3. Present recommendations with clear rationale
4. For conflicting priorities: Provide tradeoff analysis and phasing options

Consult references/remediation-patterns.md for proven approaches:

• Strangler Fig (gradual replacement)
• Characterization Tests (test before refactoring)
• Branch by Abstraction (parallel implementations)
• Extract and Isolate (focused improvement)
• Stop the Bleeding First (fix process, then backlog)

4. Remediation Planning

When creating actionable plans:

1. Select approach from references/remediation-patterns.md:

   • Avoid, Reduce, Transfer, or Accept (for risks)
   • Appropriate pattern for debt type

2. Detail steps:

   • Specific actions, not abstract guidance
   • Who should do it
   • How to verify completion
   • Estimated duration for each step

3. Include:

   • Dependencies and blockers
   • Testing strategy
   • Rollback plan
   • Success criteria

4. Estimate effort: Best case, expected, worst case

Always make plans actionable - each step must be concrete and verifiable.

5. Trend Analysis & Reporting

When analyzing historical data:

1. Use scripts/trend_analysis.py for quantitative analysis:

   • Debt over time (total, new, resolved, age)
   • Risk distribution by category and severity
   • ROI calculation for completed remediations

2. Identify patterns:

   • Increasing/decreasing trends
   • Concerning accumulation rates
   • Categories with most issues

3. Generate insights: Suggest process improvements based on patterns

4. Create reports appropriate for audience:

   • Executive: Business impact, resource requirements
   • Team: Technical details, action items
   • Stakeholders: Progress updates, timelines

Scripts Usage

Risk Assessment Calculator

# Single risk calculation
python3 scripts/risk_assessment.py --calculate "likely" "major"

# Multiple risks from file
python3 scripts/risk_assessment.py risk_data.json

Input format: See assets/templates/data-formats.json for schema.

Output: JSON with risk scores, levels, and priorities. Includes visual risk matrix for multiple risks.

Debt Prioritization

python3 scripts/debt_prioritization.py debt_data.json

Input: JSON with debt items including pain_level, blast_radius, remediation_cost, business_value.

Output: Prioritized list, quick wins identification, strategic investments, summary statistics.

Trend Analysis

# Analyze debt trends
python3 scripts/trend_analysis.py historical_debt.json

# Analyze risk trends
python3 scripts/trend_analysis.py historical_risk.json

# Calculate remediation ROI
python3 scripts/trend_analysis.py roi_data.json

Input: Historical snapshots with type field ('debt', 'risk', or 'roi').

Output: Trends over time, summary metrics, insights.

Reference Documents

Risk Categories (references/risk-categories.md)

Detailed guidance on six risk categories with indicators, assessment factors, examples, and mitigation patterns. Read this when categorizing risks or when user describes technical concerns.

Debt Types (references/debt-types.md)

Comprehensive catalog of six debt types with manifestations, impact indicators, remediation approaches, and estimation factors. Read this when classifying technical debt or when user reports code quality issues.

Remediation Patterns (references/remediation-patterns.md)

Proven approaches including general principles, risk mitigation strategies (Avoid/Reduce/Transfer/Accept), debt paydown patterns (Strangler Fig, Characterization Tests, etc.), and phased approaches. Read this when creating remediation plans or when user asks how to address risks/debt.

Templates

All templates in assets/templates/:

• risk-register-template.md: Complete risk register structure
• debt-inventory-template.md: Technical debt tracking document
• data-formats.json: JSON schemas for scripts

Use these templates as starting points, adapt to user's needs.

Best Practices

Assessment Consistency

• Use the same criteria for similar risks/debt across time
• Document rationale for ratings
• Reference specific indicators from category guides

Actionability

• Every plan must have concrete steps
• Include verification method for each action
• Specify owners and timelines
• No vague suggestions like "improve code quality"

Context Awareness

• Ask about team size, capacity, constraints when unknown
• Scale recommendations appropriately (startup vs enterprise)
• Consider technical maturity and risk tolerance
• Adapt language for different stakeholders

Communication

• Technical audience: Include details, root causes, technical approaches
• Executive audience: Focus on business impact, resource requirements, timelines
• Mixed audience: Lead with impact, provide technical details as appendix

Progressive Approach

Always recommend:

1. Phase 1: Stabilize - Stop making things worse
2. Phase 2: Quick Wins - Build momentum with visible improvements
3. Phase 3: Strategic - Address foundational issues (ongoing)

Common Patterns

User describes issue without categorization

1. Listen and understand the concern
2. Categorize based on indicators (read appropriate reference doc)
3. Assess and provide rating with justification
4. Offer to document in register/inventory

User has multiple items to prioritize

1. Gather data for all items (or use provided data)
2. Run prioritization script if quantitative
3. Identify quick wins and strategic items
4. Present sorted list with clear rationale
5. Suggest phased approach

User needs remediation plan

1. Understand the risk/debt from context
2. Select appropriate pattern from remediation-patterns.md
3. Break into specific steps with estimates
4. Include dependencies, testing, rollback
5. Define success criteria
6. Format clearly with sections

User wants stakeholder report

1. Determine audience (technical, executive, mixed)
2. Generate appropriate summary (read trends if historical data)
3. Translate technical details to business impact
4. Include visual elements (risk matrix, trend charts)
5. Provide recommendations and next steps

Anti-Patterns to Avoid

• Vague assessments: Always provide specific likelihood/impact ratings with justification
• Incomplete plans: Every plan needs steps, estimates, success criteria, rollback
• One-size-fits-all: Adapt to team context, don't give generic advice
• Overwhelming lists: Prioritize ruthlessly, identify quick wins
• Analysis paralysis: Recommend starting with simple approach, iterate
• Ignoring quick wins: Always highlight low-effort, high-value items
• No monitoring: Every risk/debt needs review frequency and metrics

Integration with Other Skills

This skill works well with:

• requirements-ac-writer: Create acceptance criteria for remediation work
• task-decomposition-planning: Break large remediation efforts into subtasks
• prompt-engineering: Generate prompts for specialized analysis agents
• documentation skills (docx, xlsx): Create formatted reports and inventories

When user requests comprehensive documentation or multi-agent coordination, consider recommending these complementary skills.

Success Metrics

Track effectiveness through:

• Percentage of documented vs undocumented risks/debt
• Average age of technical debt (trending down is healthy)
• Remediation completion rate vs plan
• Incident reduction after risk mitigation
• Developer velocity improvement after debt paydown
• Stakeholder satisfaction with clarity of communication

Remember

The goal is not perfection but continuous improvement. Help teams:

• Make technical debt and risks visible
• Make informed prioritization decisions
• Take concrete action with clear plans
• Measure progress over time
• Communicate effectively with stakeholders

Start where they are, build momentum with quick wins, and establish sustainable practices.