dirien/tech-debt

<!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. --> <!-- SPDX-License-Identifier: Apache-2.0 -->

Technical Debt Analysis

Investigate the codebase across 8 categories, score each finding by impact and effort, and generate a prioritized TECH_DEBT.md remediation plan. Four categories are analyzed directly; four delegate to specialized skills.

Prerequisite check

git --version 2>/dev/null && git rev-parse --is-inside-work-tree 2>/dev/null

If not in a git repository, warn but proceed — git history analysis will be unavailable but other checks still work.

Step 1: Project context

Gather baseline metrics before analysis:

echo "Project: $(basename $(pwd))"
echo "Files: $(find . -type f -name '*.go' -o -name '*.js' -o -name '*.ts' \
  -o -name '*.py' -o -name '*.rs' -o -name '*.cs' | grep -v node_modules \
  | grep -v vendor | grep -v .git | wc -l)"
echo "Branch: $(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
echo "Last commit: $(git log -1 --format='%h %s' 2>/dev/null)"

Detect project type (Go, Node, Python, .NET, Rust, mixed) from config files present.

Step 2: Delegated categories

For categories covered by specialized skills, delegate or note for future delegation:

Code quality — if the scout skill is available, run it against recently changed files. Scout identifies the top 3 improvement opportunities per file using Impact x Low-Risk scoring.

Linting — if the lint-fix skill is available, run its detection mode (Step 1 only) to identify which linting tools are configured and whether any are missing. Do not run the full fix pipeline.

Security — if the security-audit skill is available, run it for OWASP Top 10 analysis, secrets detection, supply chain assessment, and threat modeling. Include the security score in the tech debt scorecard.

Dependencies — if the dep-upgrade skill is available, run its audit step (Steps 1-2 only) to identify outdated and vulnerable packages with priority categorization. Include the dependency health score in the tech debt scorecard.

Design principles — if the design-principles skill is available, run it in delegated mode against the full codebase. It audits against SOLID, DRY, YAGNI, KISS, Law of Demeter, Separation of Concerns, Composition over Inheritance, and the 12-Factor code-relevant subset. Include the overall design health score in the tech debt scorecard and pull P1 findings into the remediation roadmap.

Step 3: Architecture analysis (direct)

Investigate the codebase for structural issues. See references/analysis-patterns.md for detailed patterns.

1. Check for god files — find files > 500 lines with mixed responsibilities
2. Check coupling — find files importing > 10 packages
3. Check layer violations — look for database/HTTP logic in wrong layers
4. Check for circular dependencies — trace import patterns
5. Identify the 3-5 most impactful architecture issues — focus on what blocks new feature development or causes bugs

Step 4: Test analysis (direct)

Measure test health. See references/analysis-patterns.md for detailed patterns.

1. Measure coverage — run coverage tools if available
2. Calculate test/code ratio — count test files vs code files
3. Identify critical untested paths — trace entry points and check for test coverage at each step
4. Flag test anti-patterns — tests with no assertions, sleep synchronization, shared state, implementation testing
5. Check for missing test types — are there only unit tests? Integration? E2E?

Step 5: Documentation analysis (direct)

Check documentation completeness. See references/analysis-patterns.md for detailed patterns.

1. Essential files — README.md, CONTRIBUTING.md, CHANGELOG.md, architecture docs, API docs
2. API documentation coverage — ratio of documented public functions/types vs total
3. Stale documentation — references to files, functions, or patterns that no longer exist
4. Missing ADRs — significant architectural decisions without recorded rationale

Step 6: Infrastructure analysis (direct)

Assess operational readiness. See references/analysis-patterns.md for detailed patterns.

1. CI/CD — check for workflow configs, test automation, deploy automation
2. Deployment — Dockerfile, container config, deployment scripts
3. Observability — structured logging, error tracking, metrics, alerts
4. Configuration — env vars vs hardcoded values, secrets management

Step 7: Score each category

Score every category 0-10 using the scoring rubric in references/scoring-guide.md. Assign impact (LOW/MEDIUM/HIGH/CRITICAL) and effort (S/M/L/XL) to each finding.

Calculate priority: P1 (high impact, low effort) through P4 (low impact, high effort).

Step 8: Generate TECH_DEBT.md

Write the report using the template in references/scoring-guide.md. Include:

• Executive summary with overall health score (sum of 9 categories, out of 90)
• Scorecard table with all 9 categories
• Detailed findings per category with evidence and remediation
• Remediation roadmap organized by priority (P1 → P4)
• Success metrics with current and target values

Run markdownlint on the generated file.

Step 9: Present summary

Show the user:

1. Scorecard table (8 categories, scores, top issue per category)
2. Overall health score (X/80)
3. P1 items requiring immediate attention
4. Top 5 remediation priorities with estimated effort
5. Ask which items to address first