# Tech Debt Audit

Thorough, file-cited technical debt audit across 9 dimensions using AST-grep...

- Repository: https://github.com/code-yeongyu/oh-my-openagent (70577 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add code-yeongyu/oh-my-openagent --skill tech-debt-audit -g -a claude-code -y`
Codex: `npx skills add code-yeongyu/oh-my-openagent --skill tech-debt-audit -g -a codex -y`
Cursor: `npx skills add code-yeongyu/oh-my-openagent --skill tech-debt-audit -g -a cursor -y`
Gemini CLI: `npx skills add code-yeongyu/oh-my-openagent --skill tech-debt-audit -g -a gemini-cli -y`

## Description

Thorough, file-cited technical debt audit across 9 dimensions using AST-grep (tree-sitter), grep, LSP, and language-native tooling. Produces TECH_DEBT_AUDIT.md with severity, effort estimates, and prioritized fixes. Use when asked for codebase health check, tech debt audit, architecture review, code quality assessment, or cleanup planning. Triggers: 'tech debt', 'technical debt', 'debt audit', 'code health', 'technical debt audit', 'codebase health check', 'find tech debt', 'debt analysis', 'audit code quality'.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Tech Debt Audit Protocol

Model-agnostic technical debt audit for oh-my-openagent (OMO). Uses OMO's built-in tools (`grep`, `glob`, `bash` with `sg`, `read`, `lsp_diagnostics`, `task`). Produces a grounded, citable `TECH_DEBT_AUDIT.md` artifact.

## Output

Write results to `TECH_DEBT_AUDIT.md` in the repo root with:

1. **Executive Summary**, 3-5 sentences: overall health, worst dimension, quick wins count
2. **Mental Model**, the repo's architecture in 1 paragraph (what it does, stack, module boundaries)
3. **Findings Table**, columns: ID, Category, File:Line, Severity (Critical/High/Medium/Low), Effort (Hours), Description, Recommendation
4. **Top 5 Priorities**, ranked by impact/effort ratio
5. **Quick Wins Checklist**, items under 30 minutes each
6. **"Looks Bad But Is Fine"**, patterns that look like debt but are intentional
7. **Open Questions**, things the maintainer should clarify

## Phase 0: Orient

### Standard (always run)
1. `glob("**/*.ts")` / `glob("**/*.py")` / etc, map the language stack
2. `glob("**/package.json")` + `read()`, dependencies and build tooling
3. `bash("git log --oneline -200")`, churn: find highest-change files
4. `glob("**/*")` + basic math, find largest files (>300 LOC are candidates)
5. Cross-reference high-churn + large = debt hot zones
6. Write the mental model paragraph in your own working context

## Phase 1: Audit Across 9 Dimensions

Use OMO tools for each dimension. Run parallel tool calls within each dimension. Every finding MUST cite `file:line:col`.

### 1. Architectural Decay

#### Standard (always run)
- `bash("sg -p \"import { $$$ } from '$SRC'\" -l ts .")`, map module graph, look for circular patterns
- `bash("sg -p \"class $NAME { $$$ }\" -l ts .")`, check for god classes
- `grep("TODO|FIXME|HACK|XXX|WORKAROUND|TEMP")`, tagged debt markers
- `grep("async|await")` on sync-looking files, misplaced async boundaries
- `bash("wc -l <file>")` on each large file found in Phase 0

The rest: https://github.com/code-yeongyu/oh-my-openagent/blob/HEAD/.agents/skills/tech-debt-audit/SKILL.md