tech-debt-audit

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

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 (confirm with lsp_find_references)
• Commented-out code blocks (>3 consecutive consecutive lines)

2. Consistency Rot

Standard (always run)

• bash("sg -p \"import $CLIENT from '$PKG'\" -l ts .") — multiple HTTP clients
• grep("console.log|console.error|console.warn") — direct console use vs logger
• bash("sg -p \"try { $$$ } catch ($$$) { $$$ }\" -l ts .") — 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)

• bash("sg -p \"$VALUE as any\" -l ts .") — runtime type escapes
• grep("@ts-expect-error") — suppressed errors
• grep("@ts-ignore") — suppressed errors (legacy)
• bash("sg -p \"$NAME: any\" -l ts .") — typed as any
• lsp_diagnostics(filePath="<src-dir>") — current type errors

What to flag

• any types on public APIs and exported interfaces
• Untyped function parameters
• Missing schema validation at API/IO boundaries
• LSP type errors grouped by file

4. Test Debt

Standard (always run)

• glob("**/*.test.ts") — find all test files
• bash("bun test 2>&1 | grep -E '(fail|skip|todo)'") — current test health
• Cross-reference Phase 0 high-churn files with test existence

What to flag

• Critical-path files with zero tests
• Skipped tests (test.skip, describe.skip)
• Tests asserting implementation details vs behavior
• Slow tests (>1s each)

5. Dependency & Config Debt

Standard (always run)

• bash("npm audit --omit=dev 2>&1 | head -40") — known CVEs (if node_modules present)
• read("package.json") — check dependency count and stale deps
• grep(".env|process.env|Bun.env") — env var usage
• grep("API_KEY|SECRET|PASSWORD|TOKEN") in non-config files — hardcoded config

What to flag

• Outdated major-version deps
• Dependencies that do the same thing (duplicate libraries)
• Referenced env vars not documented in README
• Hardcoded environment-specific values

6. Performance & Resource Hygiene

Standard (always run)

• bash("sg -p \"for ($$$ of $$$) { $$$ await $$$ }\" -l ts .") — async-in-loop
• grep("await.map|await.filter|await.*forEach") — sequential async iteration
• grep("Promise\\.all|Promise\\.allSettled") — existing parallel patterns (good signal)
• grep("addEventListener|on\\(|subscribe") without removeEventListener|off\\(|unsubscribe nearby — listener hygiene

What to flag

• await inside for/of loops (sequential when parallel possible)
• N+1 query patterns
• Missing cleanup on event listeners, intervals, handles
• Unnecessary serialization/deserialization

7. Error Handling & Observability

Standard (always run)

• bash("sg -p \"catch ($$$) { $$$ }\" -l ts .") — catch blocks
• grep("catch.{}|catch.{\\s*}") — empty catch blocks
• grep("console.error|logger\\.error|log\\.error") — actual error logging
• bash("sg -p \"throw new $ERR($$$)\" -l ts .") — error types used

What to flag

• Empty catch blocks (worst offense)
• Generic catch (e) { console.error(e) } without recovery
• Inconsistent error shapes across modules
• Missing structured logging on critical paths
• Errors swallowed in promise chains (.catch(() => {}))

8. Security Hygiene

Standard (always run)

• grep("api[Kk]ey|api_secret|password|secret|token|credential") in source files (not config or env)
• grep("SELECT . FROM|INSERT INTO|UPDATE.SET|DELETE FROM") — SQL construction
• grep("innerHTML|dangerouslySetInnerHTML") — XSS vectors
• grep("eval\\(|Function\\(|setTimeout\\(.string|setInterval\\(.string") — code injection

What to flag

• Hardcoded secrets in source
• String-concatenated SQL
• innerHTML / dangerouslySetInnerHTML usage
• eval() or string-based setTimeout/setInterval
• Permissive CORS or auth middleware

9. Documentation Drift

Standard (always run)

• read("README.md") — check if claims match reality
• grep("@param|@returns|@throws") — docstring coverage
• grep("FIXME|TODO|HACK|XXX|WORKAROUND") — fixme density
• Compare README API examples with actual signatures

What to flag

• README claiming features that don't exist
• Public functions without any doc comment
• Comments that contradict the code
• Stale architecture decision records (ADRs) if present

Phase 2: Deeper Dives (Parallel Sub-Agents)

For large codebases (>50k LOC), delegate heavy dimensions to parallel sub-agents. Each sub-agent runs the standard tool passes for its dimensions:

task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 1 (Architecture) and 2 (Consistency). [REQUEST] Run ast_grep and grep searches for dimensions 1-2 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity: Critical/High/Medium/Low.")
task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 3 (Type debt) and 7 (Error handling). [REQUEST] Run searches for dimensions 3 and 7 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity.")

Spawn 2-3 sub-agents for the heaviest dimensions, collect results in parallel, then synthesize.

Phase 3: Synthesize & Deliver

1. Collect all findings from direct tool calls and sub-agent results
2. Deduplicate — same issue mentioned by multiple dimensions
3. Classify severity:

• Critical — Causes incorrect behavior, data loss, or security vulnerability
• High — Will cause problems in production; blocks maintenance
• Medium — Reduces maintainability; violates conventions
• Low — Cosmetic; should fix when in the area

1. Estimate effort in hours per finding (conservative)
2. Write TECH_DEBT_AUDIT.md with all required sections
3. Report summary to the user

Severity Rubric

Critical = actively causing bugs or security holes
High     = will cause problems under normal operation; blocks changes
Medium   = reduces maintainability; inconsistent; violates team conventions
Low      = cosmetic; would be nice to fix when nearby

Quick Checks Before Finishing

• [ ] Every concrete finding has file:line:col citation
• [ ] No generic claims without evidence
• [ ] "Looks Bad But Is Fine" section explains at least 2-3 patterns
• [ ] Top 5 priorities ranked by impact/effort
• [ ] Quick wins are things that can be fixed in <30 minutes each