Technical Debt Skill | Agent Skills

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

Full Compiled Document

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

Agent Skills: Technical Debt

Install this agent skill to your local

Skill Files