philoserf/skills/tech-debt

Technical Debt Analysis

Systematic methodology for identifying, classifying, and prioritizing technical debt across a codebase. This skill diagnoses — it produces an inventory and remediation roadmap but does not modify code.

When to Use

• User asks about technical debt, maintenance burden, or "what's slowing us down"
• Starting a new engagement with an unfamiliar codebase
• Before a major refactor to scope and prioritize work
• Periodic health check on code quality

Relationship to refactor-clean

These skills form a diagnose/treat pair:

• tech-debt = diagnose (what's wrong, how bad, what to fix first)
• refactor-clean = treat (how to fix it, verify quality after)

Run tech-debt first to build the inventory, then hand prioritized items to refactor-clean for execution.

Workflow

1. Scan

Walk the codebase and identify debt items using the debt categories.

• Glob for project structure and file sizes
• Grep for known smell patterns (TODO/FIXME/HACK, deeply nested code, large files)
• Read representative files in hotspot areas
• Classify each finding into its debt category

Scaling by codebase size:

| Files | Strategy | | ------ | -------------------------------------------------------------------------------------- | | < 50 | Read all non-trivial files | | 50–500 | Use Glob/Grep to identify hotspots; read the top 10 by smell-pattern hit density | | 500+ | Limit to top-level architecture, entry points, and files with 5+ smell pattern matches |

Note the sampling strategy used in the report Summary.

If the Glob scan returns no files, stop and ask the user to confirm the working directory. Do not synthesize findings from empty results.

If the user specifies a subdirectory or module scope, restrict all scanning to that path. Note the scope limitation in the report Summary and flag that cross-cutting debt (e.g., shared utilities outside scope) may be underreported.

2. Assess

Score each debt item using the ROI framework.

• Evaluate impact across velocity, quality, and risk dimensions
• Assign a risk level (Critical / High / Medium / Low)
• Estimate effort to remediate (T-shirt size: S / M / L / XL)
• Note the recurring cost if left unaddressed (e.g., developer-hours lost per sprint, growing bug surface, blocked capabilities)

3. Prioritize

Rank items into action tiers:

| Tier | Profile | Action | | ----------- | ------------------------ | ----------------------- | | Quick Wins | High impact, low effort | Address immediately | | Medium-Term | High impact, high effort | Plan for next cycle | | Long-Term | Moderate impact, large | Roadmap for future | | Skip | Low impact, high effort | Accept or revisit later |

4. Report

Deliver the analysis in structured format:

## Tech Debt Inventory

### Summary
- Total items found: N
- Critical: N | High: N | Medium: N | Low: N
- Sampling strategy: <all files | hotspot top-10 | architecture + heavy-smell>
- Scope: <full codebase | path/to/subdirectory (cross-cutting debt may be underreported)>

### Debt Items

| # | Category | Item | Location | Risk | Effort | Tier |
|---|----------|------|----------|------|--------|------|
| 1 | Code     | ...  | ...      | ...  | ...    | ...  |

### Prioritized Roadmap

#### Quick Wins
- [items with rationale]

#### Medium-Term
- [items with rationale]

#### Long-Term
- [items with rationale]

### Recommendations
- [key observations and suggested next steps]

Output Format

1. Debt Inventory — Categorized list with locations, risk levels, and effort estimates
2. Prioritized Roadmap — Action tiers with rationale for ordering
3. Recommendations — Sequencing and scoping advice (what to tackle first and why). Not implementation steps; those belong in refactor-clean.

Reference Files

Detailed taxonomy and scoring guidance:

• debt-categories.md — Debt types with detection criteria and measurement thresholds
• roi-framework.md — Impact assessment, risk classification, and prioritization tiers

Do not use when

• Finding specific bugs with file:line precision — use code-audit
• Deep structural refactor of one area — use refactor-clean
• Reviewing a specific staged or branch diff — use diff-review
• Auditing dependency health specifically — use deps-audit
• Performance profiling without structural concerns
• Single-file code review