tech-debt

Tech Debt Skill

Use this skill when asked to find tech debt, stale patterns, or maintenance issues in a codebase.

The user may scope the sweep to specific directories or modules (e.g., "sweep crates/agentty/src/app"). When a scope is given, restrict traversal to those paths. When no scope is given, sweep the full codebase.

Workflow

1. Read Project Context

   • Read the root AGENTS.md for project conventions, architecture references, and style rules.
   • Identify which directories and modules are relevant to the sweep (respecting any user-provided scope).

2. Traverse Target Directories

   • Navigate into each target directory and read the nearest available AGENTS.md for local conventions, entry points, and change guidance.
   • Use the architecture docs and module routers to prioritize which files and modules to inspect when no deeper local guide exists.

3. Analyze for Tech Debt

   • TODOs and FIXMEs: Find TODO, FIXME, HACK, and XXX comments that indicate deferred work.
   • Outdated Patterns: Identify deprecated API usage, legacy code paths retained without justification, and patterns that conflict with current project conventions.
   • Inconsistent Error Handling: Flag mixed error handling strategies (e.g., unwrap() alongside proper Result propagation), swallowed errors, and missing error context.
   • Missing Documentation: Note public types, traits, and functions lacking doc comments, especially in areas with complex logic.
   • Stale Dependencies: Look for pinned dependency versions that lag behind current releases, unused dependencies, or feature flags that are no longer needed.
   • Dead Code: Identify unused functions, modules, imports, or feature gates that can be removed.
   • Test Gaps: Flag critical logic paths that lack test coverage or tests that are marked #[ignore].
   • Convention Violations: Check code against the project conventions discovered in Step 1 (e.g., naming rules, module layout, import style, constructor patterns) and flag deviations.

4. Return Findings as a Task List

   • Structure your answer as a prioritized markdown task list.
   • Use the format below for each finding.

Task List Format

# Tech Debt Report

## Summary
[Brief overview: total finding count, highest-risk area, and overall codebase health impression.]

## Critical
- [ ] **[Title]** — `[file/module scope]`
  [Description of the issue and why it is critical.]

## High
- [ ] **[Title]** — `[file/module scope]`
  [Description of the issue and recommended action.]

## Medium
- [ ] **[Title]** — `[file/module scope]`
  [Description of the issue and recommended action.]

## Low
- [ ] **[Title]** — `[file/module scope]`
  [Description of the issue and recommended action.]

Priority Guidelines