agentleFS
SWEStashSWEStash/swe-workflow-skills/skills/technical-debt-review/SKILL.md

technical-debt-review

Skill1 starsChanged 9 days agoMITView on GitHub

Strategic codebase health assessment — identify hotspots, categorize debt, produce remediation roadmap.

  • Reads credentials

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Don't try to review everything.

    line 15
  2. Distinctive:

    Test files significantly longer than the code they test (over-specified tests that break on refactoring)

    line 37
  3. Distinctive:

    When the request is specifically an AI-slop audit (not a general debt roadmap for planning) — "audit this repo for AI slop", "full slop …

    line 69
  4. Distinctive:

    Avoid the "big rewrite" trap.

    line 122
  5. Distinctive:

    Use templates/debt-audit.md for the full audit format.

    line 142
  6. Distinctive:

    Tests before refactoring: Never refactor untested code without adding tests first — you won't know if the refactor is correct

    line 156

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Technical Debt Review

Produce a strategic picture of where the codebase is accumulating debt and what to do about it. The goal is a prioritized roadmap, not an exhaustive list of every imperfection.

Step 1: Identify Hotspots

Don't try to review everything. Focus on where pain is concentrated.

Code complexity signals:

  • Files or functions with high cyclomatic complexity (many branches, deep nesting)
  • Functions over ~50 lines — usually doing too much (SRP violation)
  • Classes over ~300 lines — usually a God class or multiple responsibilities
  • High number of parameters (> 5 usually indicates missing abstraction)

Change frequency signals (most valuable):

  • Files changed in almost every PR — high churn indicates poor separation of concerns or missing abstractions
  • Files that always require changes together — tight coupling that should be decoupled
  • Files with frequent bug fixes — instability indicates unclear ownership or poor test coverage
  • AI-assisted bulk commits — large multi-file commits landing at once and revised within days; churn-shortly-after-landing is the strongest slop signal

Structural signals:

  • Circular dependencies between modules
  • Modules that import from many other modules — likely a coordination layer doing too much
  • Dead code (functions/classes with no callers)

Test coverage signals:

  • Untested code paths in critical or high-churn files
  • Tests that only test happy paths (no edge cases, no error cases)
  • Test files significantly longer than the code they test (over-specified tests that break on refactoring)

If the request came with team pain points (where engineers slow down, code people avoid touching, where bugs keep appearing), weight those hotspots first. This skill runs in a forked context and cannot ask mid-run — when that input is missing, proceed on the code signals above and list "where does the team actually hurt?" under Open questions in the report.

Step 2: Categorize by Debt Type and Severity

For each hotspot, classify the debt:

Debt types:

TypeDescriptionTypical fix
Complexity debtFunctions/classes doing too muchExtract, decompose, simplify
Duplication debtSame logic in multiple placesExtract shared abstraction
Test debtMissing or low-quality testsAdd tests before refactoring anything else
Documentation debtUndocumented non-obvious behavior (docs missing)Add comments, docstrings, decision records
Documentation driftDocs describing behavior, endpoints, or flags that no longer existFix or delete the stale doc
Architecture debtWrong abstraction at system levelRestructure, introduce proper boundaries
Dependency debtOutdated, vulnerable, or abandoned librariesUpgrade or replace
Type debtany/casts silencing the checker, single-implementer interfaces "for testing", overly broad typesRestore real types; inline the interface
Config/scaffolding debtUnread config keys/flags, orphan .env entries, checked-in generated files, TODO scaffoldsDelete what nothing reads; regenerate instead of committing
Observability debtNo logging, metrics, or traceabilityAdd instrumentation

Severity:

  • Critical: Causing active bugs or security risks. Address immediately.
  • High: Slowing down every sprint. Blocking new features. Schedule for next quarter.
  • Medium: Painful but workable. Schedule when capacity allows.
  • Low: Noticeable but not impeding. Do it opportunistically when touching related code.

For the AI-slop lens on these categories (per-pattern tells and when-it's-NOT-slop guidance), read the sibling skill's code-slop-cleanup/references/slop-patterns.md if installed.

AI-Slop Audit Mode

When the request is specifically an AI-slop audit (not a general debt roadmap for planning) — "audit this repo for AI slop", "full slop review", "what slop did the agents leave" — keep the same integrity discipline but shift the output:

  • Score the 14 slop categories, not the debt types. Duplication · premature abstraction · dead/unreachable code · defensive theater · verbose/inflated · comment slop · naming/organization · type slop · error-handling slop · test slop · dependency slop · structural/architectural · config/scaffolding · documentation drift. A scorecard row per category (count · worst severity · one-line note) is the map.
  • Find the systemic patterns — "fix once at the source." The highest-value section is not the finding list but the handful of root causes that parent it: "the same wiring ritual pasted 18× (P1)", "no shared test scaffold, so fixtures duplicate across 6 files (P2)", "one impure resolve() leaks SystemExit, forcing lossy handling at 7 callers (P3)." Collapse dozens of findings to a few roots, then fix the root.
  • Use the static-tooling method and the report format in references/slop-audit-method.md (per-language tool menu — jscpd/knip/vulture/deptry/ruff/mypy — plus git-churn and grep/diff verification) and write the report with templates/slop-audit.md.

Everything below (Audit Integrity, evidence, "Explicitly not flagged", method log) applies unchanged — a slop audit that invents findings is worse than one that misses them.

Audit Integrity — do not generate slop while hunting it

A wrong finding costs the audit more credibility than a missed one, and this skill runs in a forked context: the written report is the only artifact that survives, so an unevidenced finding is unfalsifiable downstream. Rules for every finding:

  • Evidence or it didn't happen. Cite path:line-range and quote the offending code minimally. No location, no finding.
  • Argue it, don't label it. State why the specific instance is unjustified here — what it costs and why the pattern lacks a reason that survives scrutiny. "I'd do it differently" is preference, not debt.
  • Attempt to disprove before flagging. Trace callers before declaring code dead (dynamic references, string-based lookups, DI, reflection, external consumers); check history before calling a config key unread. If a legitimate reason emerges, downgrade or drop.
  • Confidence, not assertion. Unverifiable usage claims get Confidence: Low with a note on what would confirm it — never asserted as fact.
  • Record what you didn't flag. An "Explicitly not flagged" section (items considered, reason they survived scrutiny) proves the audit was discerning and stops the team re-litigating.
  • Log the method. Tools/passes run with their commands, and anything not covered — unreadable files, missing test env — as named blind spots. If a tool wasn't available, say so; don't fabricate its results.

Step 3: Estimate Effort and Risk

For each hotspot, estimate:

Effort: hours/days/weeks of engineering work to address Risk: probability that addressing this introduces new bugs (higher for untested, complex code) Prerequisite: does this require tests before it can be safely changed? (almost always yes for High/Critical)

High-risk + no tests = address the tests first, before the underlying debt.

Step 4: Prioritize by Value-to-Cost Ratio

Score each item: (Severity × Impact on team velocity) / (Effort × Risk)

Prioritize in this order:

  1. Quick wins: Low effort, meaningful impact (inconsistent naming conventions, easy extractions)
  2. High pain, medium effort: The things that slow every sprint down — worth dedicated sprint time
  3. Strategic investments: High effort but unlocks future capability — needs executive buy-in and planned downtime from feature work
  4. Low impact: Log them, don't schedule them — address opportunistically

Avoid the "big rewrite" trap. Long rewrites stall feature work, introduce new bugs, and often fail to ship. Prefer incremental improvement over big-bang rewrites.

Step 5: Produce the Remediation Roadmap

Output a prioritized action plan:

Immediate (this sprint):

  • [Quick win 1]: estimated [X hours], owner [Name]
  • [Critical fix 1]: estimated [Y days], owner [Name]

Next quarter:

  • [High-priority debt 1]: estimated [X weeks], requires [tests/migration/team availability]

Backlog (do when touching related code):

  • [Medium items to address opportunistically]

Accepted debt (won't address):

  • [Items acknowledged but explicitly not worth fixing] — revisit if severity changes

Use templates/debt-audit.md for the full audit format.

Write the full audit to a file (default a gitignored location, e.g. .local/debt-review-<date>.md) and state its path in your final summary — this skill runs in a forked context: only the summary returns, everything unwritten is lost. Judgment calls that need user input (e.g. which subsystem matters most, unknown team pain points) go in an Open questions section of the report, never guessed silently.

Principles Applied

  • KISS: Simplify complexity first — complex code is the root cause of most other debt
  • DRY: Eliminate duplication — find the patterns, create the abstraction
  • SRP: Split God classes and functions doing multiple jobs into focused units
  • Tests before refactoring: Never refactor untested code without adding tests first — you won't know if the refactor is correct

Cross-Skill References

  • refactoring — use for the actual small-scale, test-protected code improvements identified in this review
  • architecture-design — use when debt is architectural (wrong boundaries, wrong abstractions at system level)
  • performance-optimization — use when debt is causing measurable performance problems, not just code cleanliness

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.