Technical debt 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 before reporting findings. Use code-review 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. 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 for structural boundaries or dependency direction.
   • Use testing-strategy 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-testing-quality, and rust-antipatterns 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, security-review, and security-review-evidence for advisories, provenance, install scripts, vulnerable dependency paths, or other supply-chain trust questions.
   • Use documentation-engineering for documentation accuracy, public surfaces, examples, or setup journeys.
   • Use performance-review 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.