Smithery is now a part of Arcade.dev! Read more in our announcement here
This skill should be used when analyzing technical debt in a codebase, documenting code quality issues, creating technical debt registers, or assessing code maintainability...
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:
python3 scripts/detect_code_smells.py src --output markdown
The script analyzes:
any type in TypeScriptOutput Example:
# Technical Debt Analysis Report
**Files Analyzed:** 127
**Total Lines:** 15,432
**Total Issues:** 89
### Issues by Severity
- HIGH: 23
- MEDIUM: 41
- LOW: 25
## Large Files (12 issues)
### High Priority
- src/components/Dashboard.tsx (847 lines): File too large
- src/services/DataProcessor.ts (623 lines): File too large
...
Examine dependencies for debt indicators:
python3 scripts/analyze_dependencies.py package.json
The script identifies:
Output Example:
# 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
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:
## 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
Register Sections:
Document major technical decisions using ADRs to prevent future debt.
Template Location: assets/ADR_TEMPLATE.md
When to Create ADRs:
Example:
# 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
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:
{
"rules": {
"complexity": ["error", 10],
"max-lines-per-function": ["error", 50],
"max-params": ["error", 5],
"max-depth": ["error", 4],
"no-console": "warn"
}
}
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:
python3 scripts/detect_code_smells.py [src-dir] [--output json|markdown]
Detects:
Output: Markdown report or JSON for programmatic processing
Purpose: Dependency health analysis
Usage:
python3 scripts/analyze_dependencies.py [package.json-path]
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
# 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
Week 1-2: Documentation
# 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
Week 2: Prioritization
# Team review session
# - Review all high/critical items
# - Discuss quick wins (high impact, low effort)
# - Allocate sprint capacity
# - Create tickets for top 5 items
Weeks 3-6: Remediation
# Sprint work
# - Fix 2-3 debt items per sprint
# - Update debt register as items resolved
# - Create ADRs for major refactoring decisions
# - Monitor metrics
Monthly: Review
# 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
Track these metrics to measure debt reduction effectiveness:
Quantity Metrics:
Quality Metrics:
Velocity Metrics:
Business Metrics:
