Tech Debt Analyzer

Technical Debt Analyzer

Overview

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.

Core Workflow

1. Automated Analysis

Run automated scripts to detect technical debt indicators across the codebase.

Code Smell Detection

Identify code quality issues using the automated detector:

python3 scripts/detect_code_smells.py src --output markdown

The script analyzes:

• Large Files: Files exceeding 500 lines
• Complex Functions: High cyclomatic complexity (>10) or long functions (>50 lines)
• Debt Markers: TODO, FIXME, HACK, XXX, BUG comments
• Console Statements: Debug statements left in code
• Weak Typing: Use of any type in TypeScript
• Long Parameters: Functions with >5 parameters
• Deep Nesting: Code nested >4 levels deep
• Magic Numbers: Hardcoded numeric values

Output 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
...

Dependency Analysis

Examine dependencies for debt indicators:

python3 scripts/analyze_dependencies.py package.json

The script identifies:

• Deprecated Packages: Known deprecated libraries (request, tslint, etc.)
• Duplicate Functionality: Multiple packages serving same purpose
• Version Issues: Overly loose or strict version constraints
• Security Concerns: Known vulnerable packages (requires audit data)

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

2. Manual Code Review

Complement automated analysis with manual review for issues that require human judgment.

Review Focus Areas

Architectural Debt:

• Tight coupling between components
• Missing abstractions
• Poor separation of concerns
• Circular dependencies

Test Debt:

• Missing test coverage for critical paths
• Fragile tests coupled to implementation
• No integration or E2E tests
• Slow test execution

Documentation Debt:

• Missing README or setup instructions
• No architecture documentation
• Outdated API docs
• Missing ADRs for major decisions

Performance Debt:

• N+1 query problems
• Inefficient algorithms
• Memory leaks
• Large bundle sizes

Security Debt:

• Missing input validation
• No authentication/authorization
• SQL injection vulnerabilities
• XSS vulnerabilities
• Exposed secrets

3. Categorize and Assess

Organize findings using the standardized debt categories.

Debt Categories

Refer to references/debt_categories.md for comprehensive details on:

1. Code Quality Debt: Code smells, complexity, duplication 2. Architectural Debt: Structure, coupling, abstractions 3. Test Debt: Coverage gaps, fragile tests 4. Documentation Debt: Missing or outdated docs 5. Dependency Debt: Outdated or problematic dependencies 6. Performance Debt: Inefficiencies and bottlenecks 7. Security Debt: Vulnerabilities and weaknesses 8. Infrastructure Debt: DevOps and deployment issues 9. Design Debt: UI/UX inconsistencies

Severity Assessment

Assign severity based on impact and urgency:

Critical:

• Security vulnerabilities
• Production-breaking issues
• Data loss risks
• Action: Immediate fix required

High:

• Significant performance problems
• Architectural issues blocking features
• High-risk untested code
• Action: Fix within current/next sprint

Medium:

• Code quality issues in frequently changed files
• Missing documentation
• Outdated dependencies (non-security)
• Action: Address within quarter

Low:

• Minor code smells
• Optimization opportunities
• Nice-to-have improvements
• Action: Address when convenient

Priority Matrix

4. Document Findings

Create comprehensive documentation of technical debt.

Technical Debt Register

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: 1. Active Debt Items: Current technical debt needing attention 2. Resolved Items: Historical record of fixed debt 3. Won't Fix Items: Debt accepted as acceptable trade-off 4. Trends: Analysis by category, severity, and age 5. Review Schedule: Regular maintenance plan

Architecture Decision Records (ADRs)

Document major technical decisions using ADRs to prevent future debt.

Template Location: assets/ADR_TEMPLATE.md

When to Create ADRs:

• Choosing frameworks or libraries
• Architectural changes
• Major refactoring decisions
• Technology migrations
• Performance optimization strategies

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

5. Prioritize and Plan

Create actionable plans to address technical debt.

Prioritization Approach

1. Critical Items: Add to current sprint immediately 2. High Items: Include in sprint planning 3. Medium Items: Add to quarterly roadmap 4. Low Items: Opportunistic fixes during related work

Time Allocation

Recommended Allocation:

• 20% of sprint capacity for technical debt
• Alternating sprints: feature sprint / debt sprint
• Dedicated quarterly "tech health" sprint

Tracking Progress

Monitor debt reduction over time:

Metrics to Track:

• Total debt items (trend down)
• Debt by severity (critical should be 0)
• Debt age (old debt is concerning)
• Resolution rate (items fixed per sprint)
• New debt rate (items added per sprint)

6. Prevention Strategies

Implement practices to minimize new technical debt.

Code Review Checklist

Before approving PRs, verify:

• [ ] No code smells introduced (complexity, size, nesting)
• [ ] Tests added/updated with adequate coverage
• [ ] Documentation updated (README, comments, ADRs)
• [ ] No security vulnerabilities
• [ ] Performance impact considered
• [ ] No new dependencies without justification
• [ ] Follows team conventions and patterns

Automated Prevention

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:

• TypeScript strict mode enabled
• Minimum test coverage threshold (80%)
• No high-severity security vulnerabilities
• Bundle size limits enforced

Regular Maintenance

Weekly:

• Review and triage TODO/FIXME comments
• Update debt register with new findings

Monthly:

• Dependency updates (security patches)
• Debt register review
• Plan fixes for high-priority items

Quarterly:

• Full codebase debt analysis
• Architecture review
• Major dependency updates
• Trend analysis and strategy adjustment

Decision Tree

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

Tools and Scripts

detect_code_smells.py

Purpose: Automated code quality analysis

Usage:

python3 scripts/detect_code_smells.py [src-dir] [--output json|markdown]

Detects:

• Large files (>500 lines)
• Complex functions (complexity >10)
• Technical debt markers (TODO, FIXME, HACK)
• Console statements
• Weak TypeScript typing
• Long parameter lists (>5 params)
• Deep nesting (>4 levels)
• Magic numbers

Output: Markdown report or JSON for programmatic processing

analyze_dependencies.py

Purpose: Dependency health analysis

Usage:

python3 scripts/analyze_dependencies.py [package.json-path]

Detects:

• Deprecated packages (request, tslint, node-sass, etc.)
• Duplicate functionality (multiple date libs, http clients, etc.)
• Unsafe version constraints (*, latest)
• Overly strict versions (exact versions without ^ or ~)

Output: Markdown report with recommendations

Reference Documentation

debt_categories.md

Comprehensive guide to technical debt types with:

• 9 major debt categories
• Indicators and examples for each
• Impact assessment criteria
• Severity level definitions
• Measurement metrics
• Prevention strategies

Load this reference when:

• Need detailed examples of specific debt types
• Assessing severity and impact
• Understanding root causes
• Planning prevention strategies

Documentation Templates

DEBT_REGISTER_TEMPLATE.md

Complete technical debt register template including:

• Debt item structure
• Status tracking
• Impact assessment format
• Trend analysis sections
• Review schedule

Use this template to:

• Start a new debt register
• Standardize debt documentation
• Track debt across team/project

ADR_TEMPLATE.md

Architecture Decision Record template including:

• Context and problem statement
• Options considered
• Decision rationale
• Consequences (positive and negative)
• Implementation plan

Use this template to:

• Document major technical decisions
• Prevent future "why did we do this?" questions
• Track technical debt incurred by decisions

Best Practices

Analysis Best Practices

1. Run analysis regularly (weekly or bi-weekly) 2. Combine automated + manual review for comprehensive coverage 3. Focus on high-churn areas first for maximum impact 4. Involve the team in debt identification 5. Be objective - all codebases have debt

Documentation Best Practices

1. Be specific - include file names, line numbers, examples 2. Explain impact - why does this matter? 3. Propose solutions - don't just complain, suggest fixes 4. Estimate effort - helps with prioritization 5. Track trends - is debt increasing or decreasing?

Remediation Best Practices

1. Fix critical items immediately - especially security 2. Allocate consistent time - 20% of sprint capacity 3. Celebrate wins - track and recognize debt reduction 4. Don't let perfect be the enemy of good - incremental improvement 5. Prevent new debt - easier than fixing old debt

Communication Best Practices

1. Make debt visible - share metrics with stakeholders 2. Educate on impact - connect debt to business outcomes 3. Get buy-in - explain ROI of debt reduction 4. Regular updates - include in sprint reviews 5. Avoid blame - focus on improvement, not fault

Example Workflow

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

---

Success Metrics

Track these metrics to measure debt reduction effectiveness:

Quantity Metrics:

• Total debt items (trending down)
• Debt by severity (zero critical)
• Debt items per 1000 LOC

Quality Metrics:

• Test coverage (trending up)
• Cyclomatic complexity (trending down)
• Average file/function size (stable or decreasing)

Velocity Metrics:

• Debt items resolved per sprint
• New debt items per sprint (should be low)
• Time to resolve (should decrease)

Business Metrics:

• Bug rate (should decrease)
• Feature delivery speed (should increase)
• Developer satisfaction (should increase)

ADR-XXX: [Short Title of Decision]

Status: [Proposed / Accepted / Deprecated / Superseded]

Date: [YYYY-MM-DD]

Deciders: [List of people involved in the decision]

Technical Story: [Description, ticket/issue URL]

---

Context and Problem Statement

[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]

Key Constraints:

• [List any constraints that limit the solution space]

Key Requirements:

• [List must-have requirements]

---

Decision Drivers

[List the factors that influenced the decision, e.g.:]

• [driver 1, e.g., performance requirement]
• [driver 2, e.g., team expertise]
• [driver 3, e.g., cost constraints]
• [etc.]

---

Considered Options

Option 1: [Name]

Description: [Brief description of this option]

Pros:

• [good, because...]
• [good, because...]

Cons:

• [bad, because...]
• [bad, because...]

Effort: [Estimated effort]

---

Option 2: [Name]

Description: [Brief description of this option]

Pros:

• [good, because...]
• [good, because...]

Cons:

• [bad, because...]
• [bad, because...]

Effort: [Estimated effort]

---

Option 3: [Name]

[Repeat structure for each option considered]

---

Decision Outcome

Chosen option: "[Option X: Name]"

Rationale: [Explain why this option was chosen. What makes it the best choice given the context and decision drivers?]

---

Consequences

Positive Consequences

• [e.g., improvement of quality attribute satisfaction, follow-up decisions required, ...]
• [...]

Negative Consequences

• [e.g., compromising quality attribute, follow-up decisions required, ...]
• [...]

Technical Debt

[Any technical debt being incurred as a result of this decision? How will it be tracked?]

---

Implementation

Action Items:

• [ ] [Implementation task 1]
• [ ] [Implementation task 2]
• [ ] [etc.]

Timeline: [Expected implementation timeline]

Rollback Plan: [How to revert this decision if needed]

---

Validation

Success Metrics: [How will we measure if this decision was correct?]

Review Date: [When should we review this decision?]

---

References

• [Link to supporting documents]
• [Link to related ADRs]
• [Link to research/benchmarks]

---

Notes

[Any additional notes, context, or discussion points]

Technical Debt Register

Project: [Project Name] Last Updated: [Date] Maintained By: [Team/Person]

Summary

• Total Debt Items: 0
• Critical: 0
• High: 0
• Medium: 0
• Low: 0
• Estimated Total Effort: 0 days

---

Active Debt Items

DEBT-001: [Brief Description]

Category: [Code Quality / Architecture / Test / Documentation / Dependency / Performance / Security / Infrastructure / Design]

Severity: [Critical / High / Medium / Low]

Created: [YYYY-MM-DD]

Location:

• File(s): path/to/file.ts
• Component/Module: [Name]

Description: [Detailed description of the technical debt issue]

Impact:

• Business Impact: [How does this affect users, features, or business goals?]
• Technical Impact: [How does this affect code quality, maintainability, or performance?]
• Risk: [What could go wrong if left unaddressed?]

Root Cause: [Why was this shortcut taken? Deadline pressure, lack of knowledge, evolving requirements, etc.]

Proposed Solution: [How should this be addressed? What's the ideal fix?]

Effort Estimate: [X hours/days]

Priority Justification: [Why this severity level? Why fix this now vs later?]

Dependencies:

• Blocks: [List items this blocks]
• Blocked By: [List items blocking this]
• Related: [List related debt items]

Status: [Open / In Progress / Resolved / Won't Fix]

Assignee: [Name or Unassigned]

Target Resolution: [YYYY-MM-DD or Sprint/Quarter]

Notes:

• [Any additional context, discussion, or updates]

---

DEBT-002: [Brief Description]

[Repeat structure above for each debt item]

---

Resolved Debt Items

DEBT-XXX: [Brief Description]

Resolved Date: [YYYY-MM-DD] Resolution: [How it was fixed] Effort Spent: [Actual time taken] Lessons Learned: [What we learned from this]

---

Won't Fix Items

DEBT-XXX: [Brief Description]

Decision Date: [YYYY-MM-DD] Reason: [Why we decided not to fix this] Decision Maker: [Name/Team]

---

Debt Trends

By Category

• Code Quality: X items
• Architecture: X items
• Test: X items
• Documentation: X items
• Dependency: X items
• Performance: X items
• Security: X items
• Infrastructure: X items
• Design: X items

By Severity

• Critical: X items
• High: X items
• Medium: X items
• Low: X items

Aging

• < 1 month: X items
• 1-3 months: X items
• 3-6 months: X items
• 6-12 months: X items
• > 1 year: X items

---

Review Schedule

• Weekly: Triage new items, update status
• Monthly: Review high priority items, plan fixes
• Quarterly: Full debt review, trend analysis

---

Guidelines

When to Add Items

Add technical debt items when:

• Taking a shortcut to meet a deadline
• Discovering code smells during development
• Identifying architectural improvements
• Finding missing tests or documentation
• Detecting performance issues
• Discovering security concerns

How to Prioritize

Use this framework: 1. Critical: Security issues, production blockers, data loss risks 2. High: Blocks features, significant performance issues, high-churn areas 3. Medium: Quality issues, missing tests, outdated dependencies 4. Low: Minor improvements, optimizations, nice-to-haves

When to Fix

• Critical: Immediately
• High: Within current/next sprint
• Medium: Within quarter
• Low: When convenient or during refactoring

How to Prevent

• Code review checklist
• Automated linting and testing
• Regular dependency updates
• Documentation requirements
• Architecture reviews

Technical Debt Categories and Assessment

Overview

Technical debt represents shortcuts, workarounds, or suboptimal solutions that reduce long-term code quality and maintainability. This reference provides a comprehensive framework for identifying, categorizing, and assessing technical debt.

Debt Categories

1. Code Quality Debt

Code that works but is difficult to understand, maintain, or extend.

Indicators

Code Smells:

• Large files (>500 lines)
• Long functions (>50 lines)
• High cyclomatic complexity (>10)
• Deep nesting (>4 levels)
• Long parameter lists (>5 parameters)
• Duplicate code
• Magic numbers
• Unclear naming

Examples:

// Bad: Complex function with multiple responsibilities
function processUserData(data: any) {
  if (data && data.user) {
    const user = data.user;
    if (user.age > 18 && user.status === 'active') {
      if (user.permissions) {
        for (let perm of user.permissions) {
          if (perm.type === 'admin') {
            // Deep nesting, unclear logic
            if (perm.scope === 'full') {
              return { access: 'granted', level: 'admin' };
            }
          }
        }
      }
    }
  }
  return { access: 'denied' };
}

Impact:

• High maintenance cost
• Difficult to understand and modify
• Error-prone
• Slows down development

Priority: Medium to High (depending on frequency of changes)

---

2. Architectural Debt

Structural issues in how code is organized and components interact.

Indicators

Tight Coupling:

• Components directly depend on implementation details
• Difficult to test in isolation
• Changes cascade across modules

Poor Separation of Concerns:

• Business logic mixed with UI code
• Data access mixed with business logic
• Multiple responsibilities in single module

Missing Abstractions:

• No clear interfaces or contracts
• Direct dependencies on concrete implementations
• Difficulty swapping implementations

Examples:

// Bad: Component tightly coupled to API implementation
function UserProfile() {
  const [user, setUser] = useState(null);

  useEffect(() => {
    // Direct API call in component
    fetch('https://api.example.com/users/123')
      .then(res => res.json())
      .then(data => setUser(data));
  }, []);

  // UI logic mixed with data transformation
  const displayName = user ?
    `${user.firstName} ${user.lastName}`.toUpperCase() : '';

  return <div>{displayName}</div>;
}

Impact:

• Difficult to modify or extend
• Hard to test
• Rigid architecture
• Prevents reuse

Priority: High (affects long-term maintainability)

---

3. Test Debt

Insufficient or inadequate test coverage.

Indicators

• Missing tests for critical functionality
• Low code coverage (<80%)
• No integration or E2E tests
• Fragile tests that break frequently
• Tests coupled to implementation details
• Slow test suite

Test Coverage Gaps:

• Untested edge cases
• Missing error handling tests
• No security tests
• No performance tests

Examples:

// Bad: Test coupled to implementation
test('UserService', () => {
  const service = new UserService();

  // Testing internal implementation details
  expect(service.internalCache).toBeDefined();
  expect(service.apiClient.baseUrl).toBe('https://api.example.com');
});

// Missing: Actual behavior tests
// - Does it fetch users correctly?
// - Does it handle errors?
// - Does it cache properly?

Impact:

• Fear of refactoring
• Bugs slip into production
• Regression issues
• Slow development velocity

Priority: High for critical paths, Medium for others

---

4. Documentation Debt

Missing or outdated documentation.

Indicators

• No README or setup instructions
• Missing API documentation
• Outdated architecture diagrams
• No inline comments for complex logic
• Missing decision records (ADRs)
• No changelog

Examples:

// Bad: Complex logic with no explanation
function calculatePrice(items, user, promo) {
  return items.reduce((acc, item) =>
    acc + item.price * (1 - (user.tier === 'gold' ? 0.15 :
    user.tier === 'silver' ? 0.10 : 0)) *
    (promo?.code === 'SAVE20' ? 0.8 : 1), 0
  ) * (user.country === 'US' ? 1.07 : 1);
}

// Good: Documented logic
/**
 * Calculate final price with tier discounts and tax
 *
 * Applies:
 * - Tier discount (Gold: 15%, Silver: 10%, Bronze: 0%)
 * - Promo code discount (SAVE20: 20% off)
 * - Sales tax (US: 7%, Other: 0%)
 */
function calculatePrice(items, user, promo) {
  // Implementation with clear structure
}

Impact:

• Onboarding takes longer
• Knowledge loss when developers leave
• Duplicate work
• Poor decision making

Priority: Medium (varies by project)

---

5. Dependency Debt

Issues with third-party libraries and packages.

Indicators

• Outdated dependencies
• Deprecated packages
• Security vulnerabilities
• Unused dependencies
• Version conflicts
• Duplicate functionality

Examples:

{
  "dependencies": {
    "moment": "^2.24.0",      // Deprecated, use date-fns or dayjs
    "request": "^2.88.0",     // Deprecated, use axios or node-fetch
    "tslint": "^6.1.0",       // Deprecated, use ESLint
    "lodash": "^4.17.21",     // AND
    "underscore": "^1.13.1"   // Duplicate functionality
  }
}

Impact:

• Security vulnerabilities
• Missing features and bug fixes
• Larger bundle sizes
• Maintenance burden

Priority: High for security issues, Medium for others

---

6. Performance Debt

Code that works but performs poorly.

Indicators

• N+1 query problems
• Missing database indexes
• Inefficient algorithms
• Memory leaks
• Large bundle sizes
• Slow API responses
• Unnecessary re-renders

Examples:

// Bad: N+1 query problem
async function getUsersWithPosts() {
  const users = await db.users.findAll();

  // Separate query for each user!
  for (const user of users) {
    user.posts = await db.posts.findByUserId(user.id);
  }

  return users;
}

// Good: Single query with join
async function getUsersWithPosts() {
  return db.users.findAll({
    include: [{ model: db.posts }]
  });
}

Impact:

• Poor user experience
• Higher infrastructure costs
• Scalability issues
• Customer churn

Priority: High for user-facing features, Medium for internal tools

---

7. Security Debt

Security vulnerabilities and weaknesses.

Indicators

• Missing input validation
• No authentication/authorization
• Exposed secrets in code
• SQL injection vulnerabilities
• XSS vulnerabilities
• CSRF vulnerabilities
• Insecure dependencies

Examples:

// Bad: SQL injection vulnerability
function getUser(userId: string) {
  const query = `SELECT * FROM users WHERE id = ${userId}`;
  return db.query(query);
}

// Bad: XSS vulnerability
function displayComment(comment: string) {
  document.getElementById('comment').innerHTML = comment;
}

// Bad: Exposed secrets
const API_KEY = 'sk_live_abc123xyz789';

Impact:

• Data breaches
• Legal liability
• Reputation damage
• Financial loss

Priority: Critical (immediate fix required)

---

8. Infrastructure/DevOps Debt

Issues with deployment, CI/CD, and infrastructure.

Indicators

• Manual deployment process
• No CI/CD pipeline
• Missing environment configs
• No monitoring or logging
• No backup strategy
• Hardcoded configuration
• Missing disaster recovery

Examples:

// Bad: Hardcoded environment-specific values
const config = {
  apiUrl: 'https://prod-api.example.com',
  dbHost: '10.0.1.52',
  cacheEnabled: true
};

// Good: Environment-based configuration
const config = {
  apiUrl: process.env.API_URL,
  dbHost: process.env.DB_HOST,
  cacheEnabled: process.env.CACHE_ENABLED === 'true'
};

Impact:

• Deployment errors
• Downtime
• Difficult rollbacks
• Slow incident response

Priority: High (reduces operational risk)

---

9. Design Debt

UI/UX issues and inconsistencies.

Indicators

• Inconsistent styling
• No design system
• Accessibility issues
• Poor responsive design
• Inconsistent user flows
• Duplicate components

Examples:

// Bad: Inconsistent button styling across app
<button style={{background: 'blue', padding: '10px'}}>Submit</button>
<button className="btn-primary">Submit</button>
<Button color="primary" size="lg">Submit</Button>

// Good: Consistent design system
<Button variant="primary">Submit</Button>

Impact:

• Poor user experience
• Brand inconsistency
• Accessibility compliance issues
• Higher development cost

Priority: Medium (varies by product)

---

Assessment Framework

Severity Levels

Critical:

• Security vulnerabilities
• Production-breaking issues
• Data loss risks
• Immediate action required

High:

• Significant performance issues
• Architectural problems blocking features
• High-risk areas with no tests
• Action required within sprint

Medium:

• Code quality issues
• Missing documentation
• Outdated dependencies (non-security)
• Address in next few sprints

Low:

• Minor code smells
• Optimization opportunities
• Nice-to-have improvements
• Address when convenient

Impact Assessment

Business Impact:

• Does it affect user experience?
• Does it block new features?
• Does it increase costs?
• Does it create risk?

Technical Impact:

• How difficult to fix?
• How widespread is the issue?
• How frequently is code changed?
• What's the maintenance burden?

Urgency:

• Is it getting worse over time?
• Will it be harder to fix later?
• Is there a deadline or trigger event?

Prioritization Matrix

---

Measurement Metrics

Code Quality Metrics

• Lines of Code (LOC): Track file/function sizes
• Cyclomatic Complexity: Measure code complexity
• Code Duplication: Percentage of duplicated code
• Test Coverage: Percentage of code covered by tests
• Code Churn: Frequency of changes to files

Dependency Metrics

• Outdated Dependencies: Count of packages behind latest
• Vulnerable Dependencies: Count with known CVEs
• Dependency Age: Time since last update
• Bundle Size: Total size of dependencies

Development Metrics

• Build Time: Time to build project
• Test Execution Time: Time to run test suite
• Deployment Frequency: How often code is deployed
• Lead Time: Time from commit to production
• MTTR: Mean time to recovery from incidents

---

Documentation Standards

Required Documentation

1. README.md

• Project overview
• Setup instructions
• Development workflow
• Testing approach

2. Architecture Docs

• System architecture diagram
• Data flow diagrams
• Technology stack
• Key design decisions

3. API Documentation

• Endpoint descriptions
• Request/response formats
• Authentication
• Error codes

4. Code Comments

• Complex algorithms
• Non-obvious business logic
• Workarounds and their reasons
• TODOs with context

5. ADRs (Architecture Decision Records)

• Context for major decisions
• Alternatives considered
• Rationale for choice
• Consequences

---

Prevention Strategies

Code Review Checklist

• [ ] No code smells introduced
• [ ] Tests added/updated
• [ ] Documentation updated
• [ ] No security vulnerabilities
• [ ] Performance considered
• [ ] Accessibility addressed
• [ ] No new dependencies without justification

Automated Prevention

• Linting: ESLint, TypeScript strict mode
• Formatting: Prettier, consistent style
• Testing: Required minimum coverage
• Security: Automated vulnerability scanning
• Performance: Bundle size limits, lighthouse CI
• Dependencies: Automated update PRs (Dependabot)

Regular Maintenance

• Weekly: Review TODO/FIXME comments
• Monthly: Dependency updates
• Quarterly: Architecture review
• Annually: Major refactoring initiatives