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.

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 consolidate duplicated logic
• code-complexity — Cyclomatic and cognitive complexity thresholds
• code-long-functions — Function and method length limits
• code-god-classes — Class size and responsibility limits
• code-dead-code — Unused code, unreachable branches, commented blocks
• code-magic-numbers — Hardcoded literals in business logic
• code-long-parameter-lists — Functions with too many positional params

2. Security Debt (CRITICAL)

• security-secrets-in-code — API keys, passwords, tokens in source / history
• security-input-validation — Endpoints accepting untrusted input without schemas
• security-auth-hardening — Outdated auth, missing MFA, missing security headers

3. Design Debt (HIGH)

• design-tight-coupling — Excessive direct dependencies between modules
• design-circular-deps — Cyclic imports / requires
• design-leaky-abstractions — Framework types crossing layer boundaries
• design-shotgun-surgery — Changes that touch many files at once

4. Dependency Debt (HIGH)

• deps-outdated-versions — Major versions behind on dependencies
• deps-abandoned-packages — Unmaintained / abandoned libraries
• deps-security-advisories — Known CVEs in installed dependencies
• deps-unused-deps — Declared but unused packages

5. Test Debt (HIGH)

• test-coverage-gaps — Critical paths without tests
• test-flaky-tests — Tests with non-deterministic outcomes
• test-disabled-tests — Skipped tests left in the suite
• test-slow-tests — Tests blocking fast feedback

6. Performance Debt (HIGH)

• perf-n-plus-one — Linear request → quadratic database load
• perf-missing-pagination — Unbounded result sets
• perf-bundle-bloat — Heavy / unsplit frontend bundles
• perf-no-caching — Missing cache layers on read-heavy paths

7. Data Debt (HIGH)

• data-schema-drift — Production schema diverges from migrations
• data-missing-indexes — Hot queries doing sequential scans
• data-orphaned-records — Referential integrity gaps

8. Documentation Debt (MEDIUM)

• docs-stale-comments — Comments contradicting current behavior
• docs-outdated-architecture — README/architecture docs out of date
• docs-undocumented-api — Public APIs without docblocks or types

9. Infrastructure Debt (MEDIUM)

• infra-runtime-versions — EOL or near-EOL language/runtime versions
• infra-deprecated-apis — Framework deprecations still in use
• infra-build-warnings — Build/compile warnings ignored
• infra-secrets-management — Long-lived credentials, plain env files, leaked logs
• infra-monitoring-gaps — Missing logs, metrics, traces, alerts, or SLOs

10. Process Debt (MEDIUM)

• process-todo-fixme-aging — Aging TODO/FIXME/HACK comments
• process-deprecated-markers — @deprecated without removal plan
• process-debt-tracking — Debt visible in a register / backlog
• process-ownership-gaps — Code without an owning team (CODEOWNERS)
• process-feature-flags-lingering — Stale feature flags polluting code paths

Essential Patterns

Debt Ledger Output Format

| # | Category | Item                          | Location              | Effort | Impact   | Priority |
|---|----------|-------------------------------|-----------------------|--------|----------|----------|
| 1 | deps     | guzzle 6.x (5y behind)        | composer.json:18      | M      | HIGH     | P1       |
| 2 | code     | InvoiceService dup logic      | app/Services/Invoice* | S      | MEDIUM   | P2       |
| 3 | test     | 8 skipped tests in checkout/  | tests/Feature/Checkout| S      | HIGH     | P1       |

Effort × Impact Prioritization

              LOW       MEDIUM    HIGH      CRITICAL
S (<1d)   →   P3        P2        P1        P0
M (1-5d)  →   P3        P2        P1        P0
L (>1w)   →   P3        P3        P2        P1   (break down)

Cheap + high-impact items go first. Expensive items always get broken down before scheduling.

Tooling Cheatsheet

# PHP / Laravel
composer outdated --direct          # list outdated direct deps
composer audit                      # known CVEs
vendor/bin/phpstan analyse          # static analysis
vendor/bin/phpmd app text cleancode # mess detector

# Node / TS
npm outdated                        # list outdated deps
npm audit                           # known CVEs
npx depcheck                        # unused deps
npx tsc --noEmit                    # type errors
npx eslint . --max-warnings 0       # lint warnings

# Cross-language
git log --since="6 months ago" --diff-filter=A -p | grep -E "TODO|FIXME|HACK"
cloc .                              # lines of code per language

How to Use

Read individual rule files for detailed explanations and code examples:

rules/code-duplication.md
rules/design-circular-deps.md
rules/deps-outdated-versions.md
rules/test-flaky-tests.md
rules/process-todo-fixme-aging.md

Each rule file contains:

• YAML frontmatter with metadata (title, impact, tags)
• Brief explanation of why it matters
• How to detect (commands / patterns)
• Incorrect example with explanation
• Correct example or remediation strategy

References

• Martin Fowler — Technical Debt Quadrant
• Ward Cunningham — The Debt Metaphor
• SonarQube — Technical Debt Model
• OWASP Dependency-Check
• Snyk Open Source Vulnerability Database

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md