nledford/engineering-review-board / skills/technical-debt-audit
technical-debt-audit
VerifiedPerform repository-wide or focused technical-debt audits covering maintainability, complexity, duplication, dependency health, testing gaps, architecture erosion, documentation drift, and remediation priorities. Use when the user asks to assess accumulated debt, modernization risk, change friction, quick wins, or blockers to future work or scaling. Do not use for an ordinary diff review, an active unexplained failure, implementation, or a vulnerability-only audit.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.5 KB |
SKILL.md
View on GitHub---
name: technical-debt-audit
description: Perform repository-wide or focused technical-debt audits covering maintainability, complexity, duplication, dependency health, testing gaps, architecture erosion, documentation drift, and remediation priorities. Use when the user asks to assess accumulated debt, modernization risk, change friction, quick wins, or blockers to future work or scaling. Do not use for an ordinary diff review, an active unexplained failure, implementation, or a vulnerability-only audit.
---
# Technical Debt Audit
Use this skill to identify accumulated decisions that repeatedly increase change
cost, defect risk, cognitive load, upgrade friction, or operational burden. A
technical-debt audit is a repository portfolio assessment, not a style pass or a
request to collect every local code smell.
Always apply
[`review-verification-protocol`](../review-verification-protocol/SKILL.md)
before reporting findings. Use
[`code-review`](../code-review/SKILL.md) instead when the primary artifact is a
diff, pull request, or completed change rather than accumulated repository debt.
## Boundaries
- Do not treat a current correctness bug, active vulnerability, isolated smell,
old dependency, TODO, or long file as technical debt without evidence of
recurring cost, risk, or blocked evolution.
- Route active unexplained failures to
[`systematic-debugging`](../systematic-debugging/SKILL.md). Route
vulnerability-only or supply-chain-only audits to the matching security skill.
- Remain read-only unless the user separately requests remediation and the
active agent has edit authority. Loading this skill grants no permission,
delegation, planning, or execution authority.
- When the user explicitly requests tooling evidence and the active role permits
it, use only approved evidence commands. Prefer documented repository recipes,
inspect their command surface first, and remember that builds, procedural
macros, tests, and repository-defined tools can execute repository-controlled
code. Do not install or update missing tools or dependencies, apply automatic
fixes, or broaden an audit into remediation.
- Ordinary ignored build and cache output is compatible with a read-only audit
only when the role permits the command. Never modify tracked inputs, lockfiles,
checked-in generated output, or durable plans as part of evidence collection.
- Derive languages, frameworks, modules, entry points, conventions, commands,
and validation lanes from the repository. Do not impose a preferred
architecture or toolchain.
- Return zero findings when the evidence does not establish material debt. Never
pad categories or convert cosmetic preferences into findings.
## Workflow
1. **Set the audit frame.**
- Confirm whether the scope is repository-wide or focused.
- Establish the repository's maintenance horizon, active areas, declared
conventions, and the future work or scaling concerns that make debt costly.
- Distinguish systemic debt from defects, security incidents, accepted
trade-offs, speculative cleanup, and temporary work with an owner or exit
condition.
2. **Build the Repository overview.**
- Identify primary languages, frameworks, package managers, build tooling,
test tooling, and deployment or runtime surfaces.
- Map top-level folders, key modules, entry points, public boundaries, data
stores, and important dependency direction.
- Read applicable README, CONTRIBUTING, AGENTS, architecture records, and
repository-native commands before judging convention drift.
3. **Collect evidence.**
- Inspect source, tests, manifests, lockfiles, build and CI configuration,
documentation, generated boundaries, TODO/FIXME markers, and relevant local
history when available.
- Prefer repository-native static analysis, coverage, dependency, and audit
output when execution is authorized and safe. Otherwise name the exact
unrun check and the uncertainty it leaves.
- For every attempted tool check, record tool availability, the exact command,
exit status, and a short sanitized excerpt that supports the interpretation.
A failed command can establish a tooling, environment, or invocation
limitation without establishing a product-code finding.
- Search references and registrations before claiming code, exports,
dependencies, routes, configuration, or compatibility paths are unused.
4. **Apply proportionate lenses.**
- **Code quality:** duplicated concepts or behavior, complexity hotspots,
deep nesting, oversized responsibilities, inconsistent async or error
handling, stale commented-out blocks, obsolete abstractions, dead code,
unused exports, and hard-to-change APIs.
- **Dependency health:** unused direct dependencies, upgrade blockers,
deprecated or unsupported packages, maintenance risk, stale toolchains,
vulnerable resolved versions, and costly transitive or bootstrap surfaces.
- **Testing:** risk coverage by module or boundary, critical untested paths,
skipped or quarantined tests, flakiness, slow feedback, over-mocking,
environment fragility, and missing architecture or contract guards.
- **Architecture and design:** coupling, cycles, unclear ownership, leaky or
missing abstractions, shared dumping grounds, convention violations, and
boundary erosion that increases future migration cost.
- **Documentation and operations:** stale setup guidance, missing public or
extension-boundary documentation, undocumented non-obvious logic,
configuration drift, fragile build/deploy knowledge, and absent recovery or
upgrade guidance.
5. **Load focused companions only when evidence warrants them.**
- Use [`architecture-review`](../architecture-review/SKILL.md) for structural
boundaries or dependency direction.
- Use [`testing-strategy`](../testing-strategy/SKILL.md) for suite confidence,
flakiness, test levels, or module coverage.
- Use language engineering or anti-pattern skills for ecosystem-specific
code, package-manager, and static-analysis semantics.
- For Rust async web applications, use
[`rust-async-web`](../rust-async-web/SKILL.md),
[`rust-testing-quality`](../rust-testing-quality/SKILL.md), and
[`rust-antipatterns`](../rust-antipatterns/SKILL.md) as the evidence
warrants. The Rust async web skill routes Axum + Leptos SSR audits to its
focused setup, feature-matrix, hydration, routing, and runtime reference.
- Use
[`dependency-supply-chain-review`](../dependency-supply-chain-review/SKILL.md),
[`security-review`](../security-review/SKILL.md), and
[`security-review-evidence`](../security-review-evidence/SKILL.md) for
advisories, provenance, install scripts, vulnerable dependency paths, or
other supply-chain trust questions.
- Use [`documentation-engineering`](../documentation-engineering/SKILL.md)
for documentation accuracy, public surfaces, examples, or setup journeys.
- Use [`performance-review`](../performance-review/SKILL.md) only when
workload or measurement evidence makes performance debt decision-relevant.
6. **Control evidence quality.**
- Quote only the smallest relevant sanitized output excerpt, normally one to
five lines. Do not paste full logs when an exit status and focused excerpt
establish the claim.
- Cite numeric coverage only from observed coverage output. Without it,
provide a qualitative module or boundary map such as strong, partial, weak,
or absent and cite the tests inspected.
- Treat outdated, deprecated, unmaintained, or vulnerable dependency claims
as current facts requiring authoritative evidence. A manifest or lockfile
proves local versions, not current maintenance or advisory status.
- Classify unverified tool-dependent concerns as hypotheses and list the
validation needed to confirm them.
7. **Deduplicate and prioritize.**
- Group symptoms under the smallest evidenced root cause.
- Rank by severity, likelihood or recurrence, breadth, debt interest, cost of
delay, remediation effort, migration risk, expected benefit, and sequencing
dependencies.
- Prefer durable corrections and recurrence guards over broad rewrites.
## Finding Standard
For every finding include:
- **ID and title**; **Priority**; **Severity**; **Likelihood**;
**Confidence**; **Classification**
- **Scope and evidence**; **Impact and debt interest**; **Durable fix**
- **Effort:** Small / Medium / Large, with the main sizing assumption
- **Expected benefit**; **Dependencies and sequencing**; **Verification**
Keep severity, likelihood, confidence, and priority distinct: severity is the
consequence, likelihood is recurrence or realization risk, confidence is the
strength of evidence, and priority synthesizes those factors with cost of delay,
effort, and sequencing.
## Output
Return, in order:
1. **Repository overview**
2. **Evidence reviewed and limitations**
3. **Prioritized findings** using the Finding Standard
4. **Quick wins** — high expected benefit, small effort, and low migration risk
5. **Strategic blockers** — debt blocking future work, upgrades, operations, or
scaling
6. **Longer-term improvement program** — larger sequenced remediation, if any
7. **Accepted trade-offs and positive evidence** worth preserving
8. **Skipped validation and residual risk**
9. **Conclusion:** Healthy / Improvement Program Recommended / Material
Remediation Required
When no material debt is found, say so explicitly, retain the overview and
evidence sections, and omit empty recommendation categories.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |