tech-debt-audit

# Tech Debt Audit Protocol

Model-agnostic technical debt audit for oh-my-openagent (OMO). Uses OMO's built-in tools (`ast_grep_search`, `grep`, `glob`, `bash`, `read`, `lsp_diagnostics`, `task`) plus **optional CodeGraph MCP** for enhanced code graph analysis when available. Produces a grounded, citable `TECH_DEBT_AUDIT.md` artifact.

## CodeGraph Enhancement (Optional)

If you have [CodeGraph](https://github.com/colbymchenry/codegraph) installed (check with `codegraph status`), its MCP tools (`codegraph_search`, `codegraph_callers`, `codegraph_callees`, `codegraph_impact`, `codegraph_explore`, etc.) can supersede or augment the standard tool searches in the dimensions marked below. CodeGraph gives you:
- **Symbol search** — instant by-name lookup via FTS5
- **Call graph analysis** — callers/callees for any function
- **Impact analysis** — blast radius before changing any symbol
- **Smart context building** — entry points, related symbols, and snippets in one call
- **Framework-aware routes** — URL patterns linked to their handlers

To use CodeGraph, ensure the `codegraph` MCP server is configured in your project's `.mcp.json` or global MCP config. The skill will auto-detect CodeGraph by checking if `codegraph` MCP tools are available. Sub-agents spawned via `task()` cannot use CodeGraph — they use the standard tool fallback.

---

## 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

### CodeGraph Enhancement (if available)
Instead of guessing module boundaries, query the code graph:

```
codegraph_explore(query="architecture overview and main modules")
```
This returns symbol relationships and source grouped by file. Use the structure as your architectural mental model instead of hand-inferring it from directory names.

```
codegraph_explore(query="main entry points and execution flow")
```
This surfaces entry points and call chains. Use these to understand how the code actually flows vs how the directory layout suggests it flows.

## 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)
- `ast_grep_search(pattern="import { $$$ } from '$SRC'", lang="typescript")` — map module graph, look for circular patterns
- `ast_grep_search(pattern="class $NAME { $$$ }", lang="typescript")` — 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

#### CodeGraph Enhancement (if available)

**Dead code detection:**
```
codegraph_callers(symbol="<suspected-dead-function>")
codegraph_callers(symbol="<suspected-dead-class>")
```
Run `codegraph_callers` on suspected dead exports found via grep/glob. If the result shows zero callers (excluding test files), it's dead code.

**Circular dependency detection:**
```
codegraph_impact(target="<module-or-file>", direction="upstream")
```
Use `codegraph_impact` on key modules to trace their dependents. If A depends on B and B depends on A, that's a cycle.

**Architecture boundaries:**
```
codegraph_explore(query="module dependencies and architecture boundaries")
```
Use `codegraph_explore` to survey actual module structure.

#### What to flag
- Files > 500 LOC (god files)
- Functions > 80 LOC or > 4 nesting levels
- Classes with > 15 methods or > 400 LOC
- Import cycles (A → B → A)
- Dead exports: function/class defined but never imported elsewhere (CodeGraph: `codegraph_callers`)
- Commented-out code blocks (>3 consecutive consecutive lines)

### 2. Consistency Rot

#### Standard (always run)
- `ast_grep_search(pattern="import axios|import fetch|import got|import superagent", lang="typescript")` — multiple HTTP clients
- `grep("console.log|console.error|console.warn")` — direct console use vs logger
- `ast_grep_search(pattern="try { $$$ } catch ($$$) { $$$ }", lang="typescript")` — error handling patterns
- `grep("as any|@ts-ignore|@ts-expect-error|as unknown")` — type escapes
- `grep("eslint-disable|prettier-ignore")` — lint suppressions

#### What to flag
- 3+ ways of doing the same thing (HTTP, logging, validation, config)
- Mixed naming conventions (camelCase + snake_case + PascalCase)
- Multiple date/time handling libraries
- Mixed error response shapes across modules

### 3. Type & Contract Debt

#### Standard (always run)
- `ast_grep_search(pattern="as any", lang="typescript")` — runtime type escapes
- `ast_grep_search(pattern="@ts-expect-error", lang="typescript")` — suppressed errors
- `ast_grep_search(pattern="@ts-ignore", lang="typescript")` — suppressed errors (legacy)
- `ast_grep_search(pattern=": any", lang="typescript")` — typed as any
- `lsp_diagnostics(filePath="<src-dir>")` — current type errors

#### What to flag
- `any` types on public APIs and exported interfaces