Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

tech-debt

Audit the codebase for structural improvement opportunities — SOLID/composability, code duplication, and unnecessary layering — using a parallel team of review agents. Ranks the 10 most impactful findings, excludes anything already in the open backlog, and walks the owner through them one at a time with full context; the owner decides per item whether to file it as a GitHub issue. Not tied to any issue; owner-invoked, never automatic.

rustyrazorblade · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add rustyrazorblade/skills --skill tech-debt

About this skill


name: tech-debt description: Audit the codebase for structural improvement opportunities — SOLID/composability, code duplication, and unnecessary layering — using a parallel team of review agents. Ranks the 10 most impactful findings, excludes anything already in the open backlog, and walks the owner through them one at a time with full context; the owner decides per item whether to file it as a GitHub issue. Not tied to any issue; owner-invoked, never automatic. argument-hint: [optional: scope to a path/module — default is the whole repo]

tech-debt — structural audit → ranked findings → owner files what's worth it

Foreground, standalone: no worktree, no issue coupling, no code edits. A team of review agents reads the whole codebase looking for structural debt, ranks what it finds, and the owner decides — one finding at a time — what's worth turning into real backlog work.

Steps

  1. Establish scope. Default is the whole repo. If the owner (or argument-hint) named a path/module, scope the review to it and say so up front.

  2. Snapshot the existing backlog, once, before spawning anything. The whole point is to never re-surface what's already known:

    gh issue list --state open --json number,title,url --limit 200
    

    Keep this list in context — you'll hand it to every lens agent below so they self-filter, and you'll do a final cross-check yourself before presenting anything to the owner.

  3. Spawn three lens agents in parallel (one Agent tool call each, sent together — not sequential), each subagent_type: general-purpose, model: opus (the strongest available tier — this is a deep, whole-codebase read, not a quick lookup). Give every lens the scope from step 1 and the open-issue list from step 2 verbatim, with the instruction to silently drop any candidate that duplicates an existing open issue's title/body rather than flagging it. Each lens returns its own ranked candidate list — file:line evidence, the concrete problem, and a concrete direction to fix it, never a vague "consider refactoring X":

    • SOLID / composability — "Is the codebase built from small, composable components, or from large ones doing several unrelated jobs? Find the worst violations: single-responsibility breaks (a class/module/function doing 2+ unrelated things), dependencies on concretions where an abstraction would decouple two things that shouldn't know about each other, and interfaces wide enough that most callers only use a slice of them. For each, name the smaller pieces it should split into."
    • Code duplication — "Find logic duplicated across files/modules that belongs in one shared place — not textually identical-only, but the same behavior re-implemented with minor variations (a strong signal the abstraction was never extracted, or drifted after copy-paste). For each, name where the shared module/function should live and what call sites would move to it."
    • Structure / layering — "Find unnecessary indirection: layers that just forward calls to the next layer with no logic of their own, wrapper types/interfaces with exactly one implementation and no test-seam justification, or a module boundary that's crossed so often in both directions it isn't really a boundary. For each, name what should collapse or merge."

    Each lens caps itself at its own strongest ~5-8 candidates rather than padding to hit a number — a lens with fewer genuine findings should return fewer.

  4. Merge, dedupe, and rank globally. Collect all three lenses' candidates. Two different lenses sometimes point at the same underlying spot (a god-class is both a SOLID violation and the reason its duplicated logic never got extracted) — merge those into one finding citing both angles rather than presenting it twice. Do your own pass against the step-2 backlog list too (lens-level self-filtering can miss a near-match) — drop anything that's substantially already an open issue. Rank what's left by impact: how much it currently costs (bug surface, onboarding friction, how often it's touched) weighed against how contained the fix is. Keep the top 10 — fewer if fewer genuinely impactful findings survive; never pad the list to reach 10.

  5. Present findings one at a time — full context, owner decides each one before you show the next. Don't dump the ranked list upfront. For each:

    [3 of 10] <one-line title>
    Lens: <SOLID | duplication | structure>
    Where: <file:line, file:line, ...>
    Problem: <what's actually wrong, concretely>
    Direction: <the shape of the fix — not a full design, just where it points>
    Impact: <why this one ranked where it did>
    

    Ask: file as a GitHub issue, skip, or adjust (owner can narrow/reshape it before it's filed). Never file anything without that per-item confirmation — the owner decides what enters the backlog, this skill only surfaces candidates.

  6. File exactly what the owner accepted, drafted with a distinct ## Direction section (not folded into Notes) — keep it as its own heading, verbatim; some downstream consumer of the filed issue may key off that section being present:

    gh issue create --title "<concise title>" --label "<P0|P1|P2|P3>" --label "status:ready" --label "type:tech-debt" \
      --body "## Scope
    <what this touches, in/out>
    
    ## Acceptance criteria
    - [ ] <behavior is unchanged — existing tests still pass unmodified, no public signature/error-contract/CLI/config/serialized-output change>
    - [ ] <the structural outcome itself — e.g. 'X and Y are split into single-responsibility units'>
    
    ## Direction
    <the finding's Direction field, verbatim — the shape of the fix, where it points>
    
    ## Notes / context
    Lens: <SOLID | duplication | structure>. Where: <file:line, file:line, ...>. Problem: <what's wrong>."
    

    The first acceptanc

Read the complete source ↗