technical-debt

What this skill does

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

| Signal | Stack | Tooling |
|--------|-------|---------|
| `composer.json` present | PHP / Laravel | `composer outdated`, `composer audit`, `phpstan`, `phpcs`, `phpmd`, `deptrac` |
| `package.json` present | Node / JS / TS / React | `npm outdated`, `npm audit`, `eslint`, `tsc --noEmit`, `knip`, `madge` |
| MySQL connection available | Database | `EXPLAIN`, `sys.schema_tables_with_full_table_scans`, `sys.schema_unused_indexes`, `sys.statement_analysis` |
| any repo | Secrets scan | `gitleaks git`, `trufflehog` |

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

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Code Debt | CRITICAL | `code-` |
| 2 | Security Debt | CRITICAL | `security-` |
| 3 | Design Debt | HIGH | `design-` |
| 4 | Dependency Debt | HIGH | `deps-` |
| 5 | Test Debt | HIGH | `test-` |
| 6 | Performance Debt | HIGH | `perf-` |
| 7 | Data Debt | HIGH | `data-` |
| 8 | Documentation Debt | MEDIUM | `docs-` |
| 9 | Infrastructure Debt | MEDIUM | `infra-` |
| 10 | Process Debt | MEDIUM | `process-` |

## Quick Reference

### 1. Code Debt (CRITICAL)

- `code-duplication` — Detect and conso