npx skills add ...
npx skills add ailabs-393/ai-labs-claude-skills --skill tech-debt-analyzer
npx skills add ailabs-393/ai-labs-claude-skills --skill tech-debt-analyzer
This skill should be used when analyzing technical debt in a codebase, documenting code quality issues, creating technical debt registers, or assessing code maintainability. Use this for identifying code smells, architectural issues, dependency problems, missing documentation, security vulnerabilities, and creating comprehensive technical debt documentation.
Systematically identify, analyze, document, and track technical debt in JavaScript/TypeScript codebases. This skill provides automated analysis tools, comprehensive debt categorization frameworks, and documentation templates to maintain a technical debt register.
Run automated scripts to detect technical debt indicators across the codebase.
Identify code quality issues using the automated detector:
The script analyzes:
any type in TypeScriptOutput Example:
Examine dependencies for debt indicators:
The script identifies:
Output Example:
Complement automated analysis with manual review for issues that require human judgment.
Architectural Debt:
Test Debt:
Documentation Debt:
Performance Debt:
Security Debt:
Organize findings using the standardized debt categories.
Refer to references/debt_categories.md for comprehensive details on:
Assign severity based on impact and urgency:
Critical:
High:
Medium:
Low:
| Impact / Effort | Low Effort | Medium Effort | High Effort |
|---|---|---|---|
| High Impact | Do First | Do Second | Plan & Do |
| Medium Impact | Do Second | Plan & Do | Consider |
| Low Impact | Quick Win | Consider | Avoid |
Create comprehensive documentation of technical debt.
Use the provided template to maintain a debt register:
Template Location: assets/DEBT_REGISTER_TEMPLATE.md
Structure:
Register Sections:
Document major technical decisions using ADRs to prevent future debt.
Template Location: assets/ADR_TEMPLATE.md
When to Create ADRs:
Example:
Create actionable plans to address technical debt.
Recommended Allocation:
Monitor debt reduction over time:
Metrics to Track:
Implement practices to minimize new technical debt.
Before approving PRs, verify:
Linting and Formatting:
Required Checks:
Weekly:
Monthly:
Quarterly:
Follow this workflow based on the situation:
Starting a new analysis? → Run automated scripts (detect_code_smells.py, analyze_dependencies.py) → Review output for high-severity issues → Conduct manual review for areas scripts can't detect → Go to documentation step
Documenting findings? → Copy DEBT_REGISTER_TEMPLATE.md to project root → Add each debt item with full details → Categorize by type and assign severity → Estimate effort and prioritize → Go to planning step
Planning debt reduction? → Sort by priority matrix (impact/effort) → Allocate sprint capacity (20% recommended) → Create tickets for top priority items → Schedule regular reviews
Making architectural decisions? → Copy ADR_TEMPLATE.md → Document context, options, and decision → Identify any debt being incurred → Add to debt register if applicable
Preventing new debt? → Implement code review checklist → Configure automated linting/testing → Set up regular maintenance schedule → Monitor metrics over time
Purpose: Automated code quality analysis
Usage:
Detects:
Output: Markdown report or JSON for programmatic processing
Purpose: Dependency health analysis
Usage:
Detects:
Output: Markdown report with recommendations
Comprehensive guide to technical debt types with:
Load this reference when:
Complete technical debt register template including:
Use this template to:
Architecture Decision Record template including:
Use this template to:
Complete workflow from analysis to resolution:
Week 1: Analysis
Week 1-2: Documentation
Week 2: Prioritization
Weeks 3-6: Remediation
Monthly: Review
Track these metrics to measure debt reduction effectiveness:
Quantity Metrics:
Quality Metrics:
Velocity Metrics:
Business Metrics:
# Dependency Analysis Report
**Package:** expense-tracker
**Dependencies:** 24
**Dev Dependencies:** 18
**Total Issues:** 7
## Deprecated/Outdated Packages (3)
### request [HIGH]
Using deprecated package - use axios, node-fetch, or got instead
- Current version: ^2.88.0
## Duplicate Functionality (2)
### HTTP client [MEDIUM]
Multiple packages for HTTP client: axios, node-fetch## DEBT-001: Complex UserService with 847 lines
**Category:** Code Quality
**Severity:** High
**Location:** src/services/UserService.ts
**Description:**
UserService has grown to 847 lines with multiple responsibilities
including authentication, profile management, and notification handling.
**Impact:**
- Business: Slows down feature development by 30%
- Technical: Difficult to test, high bug rate
- Risk: Changes frequently break unrelated functionality
**Proposed Solution:**
Split into separate services:
- AuthenticationService
- UserProfileService
- NotificationService
**Effort Estimate:** 3 days
**Priority Justification:** High churn area blocking new features
**Target Resolution:** Sprint 24# ADR-003: Migrate from Moment.js to date-fns
**Status:** Accepted
**Date:** 2024-01-15
## Context
Moment.js is deprecated and increases bundle size by 67KB.
Team needs a modern date library with tree-shaking support.
## Decision
Migrate to date-fns for date manipulation.
## Consequences
- Positive: Reduce bundle by 60KB, modern API, active maintenance
- Negative: Migration effort, learning curve for team
- Technical Debt: None - this resolves existing dependency debt{
"rules": {
"complexity": ["error", 10],
"max-lines-per-function": ["error", 50],
"max-params": ["error", 5],
"max-depth": ["error", 4],
"no-console": "warn"
}
}python3 scripts/detect_code_smells.py [src-dir] [--output json|markdown]python3 scripts/analyze_dependencies.py [package.json-path]# Run automated analysis
python3 scripts/detect_code_smells.py src --output markdown > debt_analysis.md
python3 scripts/analyze_dependencies.py package.json >> debt_analysis.md
# Manual review of critical areas
# - Authentication logic
# - Payment processing
# - Data models# Create debt register from template
cp assets/DEBT_REGISTER_TEMPLATE.md TECHNICAL_DEBT.md
# Add findings to register with:
# - Category and severity
# - Impact assessment
# - Effort estimation
# - Priority assignment# Team review session
# - Review all high/critical items
# - Discuss quick wins (high impact, low effort)
# - Allocate sprint capacity
# - Create tickets for top 5 items# Sprint work
# - Fix 2-3 debt items per sprint
# - Update debt register as items resolved
# - Create ADRs for major refactoring decisions
# - Monitor metrics# Trend analysis
# - Total debt (should decrease)
# - New debt rate (should be low)
# - Age of oldest items (should decrease)
# - Categories most affected
# Adjust strategy based on trends