🧱 Technical Debt Analysis Skill

This skill enables an AI agent to systematically identify, classify, and prioritize technical debt across code, tests, architecture, dependencies, and delivery pipelines.

🎯 When to Use

Use this skill when you need to:

• •Assess the health and sustainability of a codebase
• •Identify quality risks hidden behind “working” systems
• •Understand why testing is slow, flaky, or ineffective
• •Prioritize refactoring work with clear impact and ROI
• •Prepare input for technical roadmap or quality initiatives
• •Decide what technical debt to fix vs consciously accept

🧭 Operational Workflow

The agent must follow the phases below in order. Skipping discovery or evidence collection is not allowed.

Phase 0: Context & Strategy Selection (Mandatory)

Before analysis, clarify the context.

Ask (or infer safely if explicitly stated):

• •System type: Frontend / Backend / API / Test Automation / Platform
• •Current pain points: bugs, regressions, slow CI, flaky tests, low confidence
• •Scope of analysis: whole repo / module / test layer only
• •Constraints: time, legacy code, “no refactors”, compliance
• •Goal: awareness / prioritization / remediation planning

If information is missing, mark as TBD and list assumptions explicitly.

Phase 1: Debt Signal Collection (Evidence First)

Identify observable signals, not conclusions.

Possible signal sources:

• •Code structure (complexity, duplication, coupling)
• •Test behavior (flakiness, runtime, coverage gaps)
• •CI/CD signals (build time, retry patterns, failure rates)
• •Dependency metadata (age, CVEs, maintenance status)
• •Change history (hotspots, frequent fixes)
• •Documentation gaps (missing ADRs, tribal knowledge)

If no signal or evidence exists, do not report debt - log it as an assumption or unknown.

Phase 2: Debt Classification (Use a Fixed Taxonomy)

Every debt item must be classified into one primary category:

• •Code Debt – smells, complexity, duplication
• •Test Debt – missing tests, flaky tests, slow feedback, weak assertions
• •Architecture Debt – tight coupling, layering violations, unclear boundaries
• •Dependency Debt – outdated, risky, abandoned libraries
• •Process Debt – slow CI, manual steps, poor feedback loops
• •Documentation Debt – missing ADRs, unclear ownership, tribal knowledge

Optional secondary category may be added if justified.

Phase 3: Risk & Impact Assessment

Each debt item must be evaluated using risk-based thinking:

• •Impact: What breaks or slows if this remains?
• •Likelihood: How often does it cause issues?
• •Quality Risk: Bug escape, regression risk, confidence loss
• •Test Impact: Does it reduce testability or reliability?

Use simple scales (Low / Medium / High) but justify each rating.

🧾 Output Schema (Strict)

The final output must be a markdown file named: TECHNICAL_DEBT_REPORT.md and follow the structure below.

0️⃣ Document Metadata

• •Version: 0.x
• •Status: Draft / Review / Approved
• •Scope Analyzed:
• •Owner:
• •Date:
• •Assumptions:

1️⃣ Executive Summary

• •Overall technical debt health: Low / Medium / High
• •Top 5 debt drivers (by risk)
• •Major quality or testing risks identified
• •Recommended next actions (short list)

2️⃣ Debt Inventory (Atomic Records)

Each debt item must be listed as an atomic record.

Debt ID:
Category:
Location (files/modules/tests):
Description:
Observed Evidence:
Impact:
Likelihood:
Quality/Test Impact:
Fix Options:
Estimated Effort (S/M/L):
Recommendation:

Rules:

• •No evidence → no debt item
• •Avoid generic wording (“code is messy”)
• •Be precise and scoped

3️⃣ Test & Quality Risk Summary

Summarize how technical debt affects:

• •Bug escape probability
• •Regression risk
• •Test coverage effectiveness
• •Test stability and execution time
• •Confidence in releases

Highlight test debt explicitly, even if code debt dominates.

4️⃣ Prioritization & Decision Matrix

Group debt items into:

• •Fix Now – high risk, high impact
• •Fix Soon – important but not blocking
• •Accept for Now – conscious debt with rationale

Explain why some debt should not be fixed yet.

5️⃣ Remediation Roadmap (Incremental)

For top-priority items:

• •Suggested remediation steps
• •Safer refactoring strategies (test-first if needed)
• •Dependencies or prerequisites
• •Validation strategy (how we know it improved)

Avoid “big bang” rewrites unless explicitly justified.

6️⃣ Change Impact & ROI Notes

For major fixes, describe:

• •What becomes easier to test
• •What risks are reduced
• •What developer or QA friction is removed

This section is critical for stakeholder buy-in.

🧠 AI Safety & Quality Rules

DO

• •Base findings on observable evidence
• •Explicitly list assumptions
• •Treat test debt as first-class technical debt
• •Prefer incremental, test-safe remediation
• •Acknowledge uncertainty

DON’T

• •Hallucinate intent or design decisions
• •Recommend refactors without test safety
• •Over-optimize cosmetic issues
• •Treat all debt as equally urgent

✅ AI Self-Review Checklist

Before finalizing:

• • Every debt item has evidence
• • Debt categories are used consistently
• • Test impact is explicitly analyzed
• • Risks are justified, not guessed
• • “Acceptable debt” is documented
• • Recommendations are realistic and incremental

🎯 Outcome

When applied correctly, this skill produces a credible, actionable, and architecturally sound technical debt assessment that:

• •improves system quality,
• •strengthens test effectiveness,
• •reduces long-term risk,
• •and supports informed decision-making.