Technical Debt

Technical Debt

Technical debt audit and prioritization framework for PHP/Laravel (MySQL) and Node/TypeScript/React projects. Contains 42 rules across 10 categories covering code, security, design, dependency, test, performance, data, documentation, infrastructure, and process debt. Produces a ranked ledger (effort × impact) so teams know what to fix first, not just what's broken. Supports both coding reference and audit mode with PASS/FAIL/N/A output.

Metadata

• Version: 1.0.0
• Scope: PHP / Laravel (MySQL) + Node / TypeScript / React
• Rule Count: 42 rules across 10 categories
• License: MIT

How to Audit

When the user asks to "audit technical debt", "find tech debt", or "what should we refactor first" — run the checklist below against their codebase and produce a ranked debt ledger.

Audit Step 1: Determine Scope

• If arguments provided ($ARGUMENTS): audit only those paths or modules
• If no arguments: audit the entire repository starting from the root

Audit Step 2: Detect Project Stack

Inspect composer.json and package.json to determine which of the supported stacks (PHP/Laravel, Node/TypeScript/React, or both) is in use. Tooling commands (composer outdated, npm outdated, phpstan, eslint, knip, etc.) are chosen based on this detection.

Audit Step 3: Run Debt Checklist

Work through every item below. For each, output:

• PASS — brief confirmation of what was verified
• FAIL — exact file:line (or command output), description of the debt, effort estimate (S/M/L), and impact (LOW/MED/HIGH/CRITICAL)
• N/A — if the check does not apply to this project

Code Debt

• [ ] No duplicated blocks > 30 lines across files
• [ ] No function exceeds 50 lines or cyclomatic complexity > 10
• [ ] No class exceeds 300 lines or has > 15 public methods (god class)
• [ ] No unreachable code, unused exports, or commented-out blocks left in source
• [ ] No magic numbers or unexplained string literals in business logic
• [ ] No function exceeds 4 parameters (use a parameter object)

Security Debt

• [ ] No secrets, API keys, or credentials committed to source (or git history)
• [ ] Every public endpoint validates input via a schema / FormRequest / DTO
• [ ] Passwords hashed with bcrypt or argon2id; no MD5/SHA-1
• [ ] Sessions have a bounded lifetime; auth-sensitive endpoints rate-limited
• [ ] Security headers present (CSP, HSTS, X-Content-Type-Options, Referrer-Policy)
• [ ] Authorization (not just authentication) enforced on every protected route

Design Debt

• [ ] No circular dependencies between modules/packages
• [ ] Layers respect direction (UI → service → repository, never reversed)
• [ ] No "shotgun surgery" patterns (one change forcing edits in 5+ files)
• [ ] Abstractions hide implementation details (no leaking framework types across boundaries)

Dependency Debt

• [ ] No dependencies more than 2 major versions behind
• [ ] No abandoned/unmaintained packages (no release in > 24 months)
• [ ] No known CVEs reported by npm audit / composer audit at HIGH or CRITICAL
• [ ] No unused dependencies in package.json / composer.json

Test Debt

• [ ] Critical paths have integration test coverage
• [ ] No skipped/disabled tests without linked issue or removal date
• [ ] No known flaky tests left in main branch
• [ ] Test suite runs in under 10 minutes (or has explicit budget documented)

Performance Debt

• [ ] No N+1 query patterns on list endpoints (query count constant per request)
• [ ] No list endpoint returns an unbounded result set (pagination present)
• [ ] Frontend initial bundle within budget (~200 KB gzip); route-level code splitting in place
• [ ] Expensive read paths (aggregations, external APIs, static configs) are cached at a sensible layer

Data Debt

• [ ] Migrations are the only source of schema changes; production matches migration history
• [ ] All foreign-key and frequently-queried columns are indexed
• [ ] No orphaned child records; FK constraints enforced

Documentation Debt

• [ ] README reflects current setup and dev workflow
• [ ] No stale comments contradicting the code they describe
• [ ] Public APIs / exported modules have docblocks or type hints

Infrastructure Debt

• [ ] Runtime versions (Node, PHP) are on supported (non-EOL) releases
• [ ] No deprecated framework APIs in use (e.g., Laravel Route::get() deprecations)
• [ ] Build runs cleanly with zero warnings
• [ ] Secrets stored in a manager (Vault / Doppler / cloud SM); no long-lived shared credentials
• [ ] Structured logs, error tracking, p95 latency dashboards, and SLO-based alerts in place

Process Debt

• [ ] No TODO/FIXME/HACK comments older than 6 months without owner or ticket
• [ ] No @deprecated markers without a removal date or replacement
• [ ] Debt is tracked somewhere visible (issue tracker label, debt register, ADR)
• [ ] Every path has an owner (CODEOWNERS file present and current)
• [ ] No feature flags at 100% rollout for more than 6 weeks without a removal plan

Audit Step 4: Build the Debt Ledger

End the audit with a prioritized table:

## Technical Debt Ledger

| # | Category | Item | File / Location | Effort | Impact | Priority |
|---|----------|------|-----------------|--------|--------|----------|
| 1 | deps | jQuery 1.12 (8y old, 3 CVEs) | package.json:14 | L | CRITICAL | P0 |
| 2 | code | OrderService god class (820 lines) | app/Services/OrderService.php | M | HIGH | P1 |
| 3 | test | 12 disabled tests in auth/ | tests/Feature/Auth/* | S | HIGH | P1 |
...

## Summary
- **PASS:** X checks
- **FAIL:** Y checks
- **N/A:** Z checks
- **Top 3 to pay down first:** (list highest-priority items with rationale)

Priority formula: P0 = CRITICAL impact, P1 = HIGH impact, P2 = MED, P3 = LOW. Within a priority, sort by ascending effort (cheap wins first).

Effort scale:

• S = under a day
• M = 1–5 days
• L = more than a week (likely needs to be broken down)

When to Apply

Reference these guidelines when:

• Running a tech-debt audit on a codebase
• Planning a refactoring sprint or debt-paydown initiative
• Reviewing a PR that introduces shortcuts (and deciding whether to accept them)
• Building a debt register or backlog category in your issue tracker
• Justifying engineering investment to non-engineering stakeholders
• Onboarding to a new codebase and assessing its health
• Writing an ADR (architecture decision record) for a debt-related decision

Step 1: Detect Project Stack

Always detect the stack before running tooling. This skill targets PHP / Laravel (with MySQL) and Node / TypeScript / React projects; detection commands below assume one or both are present.

If both stacks are present (e.g., Laravel + Inertia + React), run audits for each.

Rule Categories by Priority

Quick Reference

1. Code Debt (CRITICAL)