benjaminshoemaker/tech-debt-check

Technical Debt Check Skill

Analyze the codebase for technical debt patterns that commonly accumulate during AI-assisted development.

Why This Matters

Research shows AI-generated code creates:

• 8x increase in code duplication (GitClear 2024)
• 1.64x more maintainability issues than human code
• Frequent DRY principle violations

This skill catches these issues before they compound.

Workflow Overview

Copy this checklist and track progress:

Tech Debt Check Progress:
- [ ] Step 1: Detect project type
- [ ] Step 2: Run duplication analysis
- [ ] Step 3: Run complexity analysis
- [ ] Step 4: Run file size analysis
- [ ] Step 5: Check for AI code smells
- [ ] Step 6: Generate report

Thresholds Reference

| Category | Metric | Good | Warning | Critical | |----------|--------|------|---------|----------| | Duplication | Duplicate % | <3% | 3-7% | >7% | | | Duplicate blocks | <5 | 5-15 | >15 | | | Lines per block | <10 | 10-20 | >20 | | Complexity | Avg complexity | <5 | 5-10 | >10 | | | Max complexity | <15 | 15-25 | >25 | | | Functions >10 | 0 | 1-3 | >3 | | File Size | Max file lines | <300 | 300-500 | >500 | | | Avg file lines | <150 | 150-250 | >250 | | | Files >300 lines | 0 | 1-3 | >3 |

Step 1: Detect Project Type

Identify the project's primary language and available tooling:

| File | Language | Tools Available | |------|----------|-----------------| | package.json | JavaScript/TypeScript | jscpd, eslint | | requirements.txt / pyproject.toml | Python | pylint, radon, flake8 | | Cargo.toml | Rust | cargo clippy | | go.mod | Go | staticcheck |

If no package manager found, fall back to file extension analysis.

Step 2: Duplication Analysis

Check for duplicate code blocks (a primary AI coding failure mode).

Using jscpd (JS/TS projects)

# Install if needed
npm list -g jscpd || npm install -g jscpd

# Run analysis
jscpd src/ --min-lines 5 --min-tokens 50 --reporters json --output .tech-debt-report/

Parse output for total duplicate lines, percentage, and specific blocks (file, start line, end line).

Manual detection (fallback)

If jscpd unavailable, use grep-based pattern matching for repeated code blocks.

Step 3: Complexity Analysis

JavaScript/TypeScript

Use eslint with complexity rules:

npx eslint src/ --rule '{"complexity": ["error", 10]}' --format json

Or check manually for:

• Functions with >10 branches
• Nested callbacks >3 levels deep
• Files with >300 lines

Python

Use radon for cyclomatic complexity:

radon cc src/ -a -s --json

Or use pylint:

pylint src/ --disable=all --enable=R0912,R0915 --output-format=json

Step 4: File Size Analysis

Large files often indicate poor separation of concerns. Find files exceeding thresholds:

find src/ -name "*.ts" -o -name "*.js" -o -name "*.py" | xargs wc -l | sort -rn | head -20

Step 5: AI Code Smell Detection

Check for patterns commonly produced by AI:

5.1 Excessive Error Handling

# Check try-catch density (ratio > 1:1 suggests over-defensive code)
echo "try blocks: $(grep -r 'try {' src/ | wc -l)"
echo "catch blocks: $(grep -r 'catch' src/ | wc -l)"

5.2 Unused Code

# TypeScript/JavaScript
npx eslint src/ --rule '{"no-unused-vars": "error"}' --format json

# Python
pylint src/ --disable=all --enable=W0611,W0612 --output-format=json

5.3 Inconsistent Patterns

Look for multiple implementations of the same concern (date formatting, HTTP clients, validation):

grep -r "new Date\|moment\|dayjs\|date-fns" src/ | cut -d: -f1 | sort | uniq -c
grep -r "fetch\|axios\|got\|request" src/ | cut -d: -f1 | sort | uniq -c

5.4 Comment Ratio

Healthy ratio is 10-20%. AI tends to over-comment or under-comment.

Step 6: Generate Report

TECHNICAL DEBT REPORT
=====================
Project: {name}
Analyzed: {timestamp}
Files scanned: {N}

SUMMARY
-------
Overall Health: GOOD | WARNING | CRITICAL
Tech Debt Score: {0-100} (lower is better)

DUPLICATION ({status})
----------------------
Duplicate code: {N} blocks, {X}% of codebase
Largest duplicates:
1. {file1}:{lines} ↔ {file2}:{lines} ({N} lines)
2. {file1}:{lines} ↔ {file2}:{lines} ({N} lines)

Action: Consider extracting to shared utility

COMPLEXITY ({status})
---------------------
Average complexity: {N}
High complexity functions:
1. {file}:{function} — complexity {N}
2. {file}:{function} — complexity {N}

Action: Refactor functions with complexity >15

FILE SIZE ({status})
--------------------
Large files (>300 lines):
1. {file} — {N} lines
2. {file} — {N} lines

Action: Split into smaller, focused modules

AI CODE SMELLS ({status})
-------------------------
- Excessive try-catch: {found/not found}
- Unused code: {N} instances
- Inconsistent patterns: {list}

Action: Review flagged patterns for consolidation

RECOMMENDATIONS
---------------
Priority fixes:
1. {specific action with file reference}
2. {specific action with file reference}
3. {specific action with file reference}

Deferred items:
- {lower priority items}

Integration with Phase Checkpoint

When invoked from /phase-checkpoint:

1. Run full analysis
2. Return summary status: PASSED | PASSED WITH NOTES | FAILED
3. FAILED if any CRITICAL thresholds exceeded
4. PASSED WITH NOTES if WARNING thresholds exceeded
5. PASSED if all metrics GOOD

Exit Criteria

| Result | Condition | |--------|-----------| | PASSED | All metrics in GOOD range | | PASSED WITH NOTES | Some WARNING, no CRITICAL | | FAILED | Any CRITICAL metric |

Limitations

• Duplication detection requires jscpd or similar tool
• Complexity analysis requires language-specific linters
• Manual review still needed for semantic duplication
• Cannot detect architectural debt or design issues

When Check Cannot Complete

If multiple CRITICAL thresholds are exceeded:

• Report all CRITICAL issues, not just the first
• Prioritize by impact: duplication first (compounds fastest), then complexity, then file size
• Ask user: "Fix issues incrementally or address all before proceeding?"
• If incremental: suggest tackling one category at a time

If required tools are not installed:

• Report which tools are missing and why they're needed
• Provide installation commands: npm install -g jscpd, pip install radon, etc.
• Fall back to manual pattern matching where possible
• Mark checks as SKIPPED (not FAILED) when tool unavailable

If codebase is too large for analysis:

• Report: "Codebase exceeds analysis threshold ({N} files)"
• Suggest: Focus on recently modified files: git diff --name-only HEAD~10
• Offer to run on specific directories instead
• Provide incremental analysis option

If analysis reveals overwhelming debt:

• Do NOT suggest fixing everything at once
• Prioritize: Top 3 highest-impact fixes only
• Suggest: Create tracking issue for remaining items
• Recommend: /add-todo for each deferred fix

Example

See references/example-output.md for a full example of tech debt check output on a TypeScript project with WARNING status.