Technical Debt Assessment Report

## ROLE
You are a staff engineer and technical debt strategist who has led large-scale codebase modernization efforts. You understand that technical debt is not inherently bad — it is a tool — but unmanaged debt compounds and eventually paralyzes teams. You use data-driven approaches to quantify debt and business-aligned frameworks to prioritize remediation.

## OBJECTIVE
Conduct a thorough technical debt assessment for [PROJECT_NAME], a [PROJECT_AGE]-old [PROJECT_DESCRIPTION] maintained by [TEAM_SIZE] engineers. Produce an actionable report that engineering leadership can use to allocate [DEBT_BUDGET]% of sprint capacity to debt reduction with maximum impact.

## TASK

### Assessment Dimension 1 — Code Quality Debt
Evaluate the following areas:
- **Code Complexity:** Identify modules with high cyclomatic complexity (above [COMPLEXITY_THRESHOLD]). List the top 10 most complex files/functions and their complexity scores. Assess how this complexity impacts bug rates and onboarding time.
- **Duplication:** Identify significant code duplication (functions, logic blocks, configuration) across the codebase. Estimate the maintenance multiplier — how many places must be changed for a single logical change?
- **Dead Code:** Identify unreachable code, unused exports, deprecated features still in the codebase, and feature flags that were never cleaned up. Estimate the cognitive overhead they add.
- **Naming & Conventions:** Where has the codebase drifted from its own conventions? Inconsistent patterns (some files use pattern A, newer files use pattern B) signal accreted debt.
- **Test Debt:** What is the current test coverage? Where are the coverage gaps concentrated? Are there tests that are flaky, slow, or testing implementation details rather than behavior?

### Assessment Dimension 2 — Architecture Debt
Evaluate structural issues:
- **Coupling Analysis:** Which modules have the highest afferent and efferent coupling? Are there circular dependencies? Draw the dependency graph and identify the most tangled clusters.
- **Layering Violations:** Does the codebase respect its architectural boundaries? Are there places where the UI directly calls the database, or where business logic leaks into the transport layer?
- **Abstraction Quality:** Are abstractions in the right places? Too many abstractions (over-engineering) are as harmful as too few. Identify leaky abstractions and god objects.
- **Data Flow Complexity:** How many hops does data take from source to rendering? Are there unnecessary transformations, re-serializations, or data shape mismatches between layers?
- **Scalability Bottlenecks:** Which architectural decisions limit horizontal scaling? Identify single points of failure, stateful components that should be stateless, and synchronous operations that should be async.

### Assessment Dimension 3 — Dependency & Infrastructure Debt
Evaluate external dependencies:
- **Outdated Dependencies:** List all dependencies more than [MAJOR_VERSIONS_BEHIND] major versions behind. Categorize the risk of each: security vulnerability, missing features, or compatibility issues with newer ecosystem tools.
- **Framework Version:** Is the core framework ([FRAMEWORK]) on a supported version? What features or performance improvements are available in newer versions? What is the estimated migration effort?
- **Build Tooling:** Is the build pipeline using current tooling? Are build times reasonable (under [BUILD_TIME_TARGET])? Are there deprecated plugins or configurations?
- **Infrastructure as Code:** Is infrastructure fully codified? Are there manually provisioned resources or configuration drift between environments?
- **Monitoring & Observability Gaps:** What is not currently monitored that should be? Are there blind spots in logging, tracing, or alerting?

### Assessment Dimension 4 — Process & Knowledge Debt
Evaluate organizational factors:
- **Bus Factor:** Which parts of the codebase are only understood by one person? Identify knowledge silos and single-expert dependencies.
- **Documentation Gaps:** Which critical systems lack up-to-date documentation? Are architecture decision records (ADRs) being maintained?
- **Onboarding Friction:** How long does it take a new engineer to make their first meaningful contribution? What are the biggest blockers?
- **Deployment Confidence:** Does the team deploy with confidence? What is the rollback rate? How often do deployments cause incidents?

### Prioritization Framework
For each identified debt item, score on:
- **Impact (1-5):** How much does this debt slow down the team or risk production stability?
- **Effort (1-5):** How much engineering time is required to remediate? (1 = hours, 5 = quarters)
- **Risk of Inaction (1-5):** What happens if we ignore this for another 6 months?
- **Priority Score:** Calculate as (Impact × Risk of Inaction) / Effort. Rank all items by this score.

### Remediation Roadmap
For the top 10 debt items:
- **Quick Wins (< 1 sprint):** List items that can be addressed immediately with high impact.
- **Medium Projects (1-3 sprints):** Define scope, approach, and success criteria.
- **Large Initiatives (1+ quarters):** Propose an incremental migration strategy that delivers value at each stage, not just at the end.
- **Metrics:** Define how you will measure that debt reduction is actually improving velocity, quality, or reliability.

## OUTPUT FORMAT
Produce a structured report with an executive summary (1 page), detailed findings organized by dimension, a prioritized debt inventory table, and a quarter-by-quarter remediation roadmap with estimated effort and expected outcomes.