.agents/skills/tech-debt-audit/SKILL.md
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.
If you have 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:
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.
Write results to TECH_DEBT_AUDIT.md in the repo root with:
glob("**/*.ts") / glob("**/*.py") / etc — map the language stackglob("**/package.json") + read() — dependencies and build toolingbash("git log --oneline -200") — churn: find highest-change filesglob("**/*") + basic math — find largest files (>300 LOC are candidates)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.
Use OMO tools for each dimension. Run parallel tool calls within each dimension. Every finding MUST cite file:line:col.
ast_grep_search(pattern="import { $$$ } from '$SRC'", lang="typescript") — map module graph, look for circular patternsast_grep_search(pattern="class $NAME { $$$ }", lang="typescript") — check for god classesgrep("TODO|FIXME|HACK|XXX|WORKAROUND|TEMP") — tagged debt markersgrep("async|await") on sync-looking files — misplaced async boundariesbash("wc -l <file>") on each large file found in Phase 0Dead 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.
codegraph_callers)ast_grep_search(pattern="import axios|import fetch|import got|import superagent", lang="typescript") — multiple HTTP clientsgrep("console.log|console.error|console.warn") — direct console use vs loggerast_grep_search(pattern="try { $$$ } catch ($$$) { $$$ }", lang="typescript") — error handling patternsgrep("as any|@ts-ignore|@ts-expect-error|as unknown") — type escapesgrep("eslint-disable|prettier-ignore") — lint suppressionsast_grep_search(pattern="as any", lang="typescript") — runtime type escapesast_grep_search(pattern="@ts-expect-error", lang="typescript") — suppressed errorsast_grep_search(pattern="@ts-ignore", lang="typescript") — suppressed errors (legacy)ast_grep_search(pattern=": any", lang="typescript") — typed as anylsp_diagnostics(filePath="<src-dir>") — current type errorsany types on public APIs and exported interfacesglob("**/*.test.ts") — find all test filesbash("bun test 2>&1 | grep -E '(fail|skip|todo)'") — current test healthtest.skip, describe.skip)bash("npm audit --omit=dev 2>&1 | head -40") — known CVEs (if node_modules present)read("package.json") — check dependency count and stale depsgrep(".env|process.env|Bun.env") — env var usagegrep("API_KEY|SECRET|PASSWORD|TOKEN") in non-config files — hardcoded configBlast radius of core dependencies:
codegraph_impact(target="<core-utility-function>", direction="upstream")
Run this on a few key internal modules (logger, config loader, HTTP client) to see how widely they're used. A widely-depended-on module with poor error handling or type safety is a high-priority refactor target because changes to it ripple everywhere.
ast_grep_search(pattern="for ($$$ of $$$) { $$$ await $$$ }", lang="typescript") — async-in-loopgrep("await.*map|await.*filter|await.*forEach") — sequential async iterationgrep("Promise\\.all|Promise\\.allSettled") — existing parallel patterns (good signal)grep("addEventListener|on\\(|subscribe") without removeEventListener|off\\(|unsubscribe nearby — listener hygieneawait inside for/of loops (sequential when parallel possible)ast_grep_search(pattern="catch ($$$) { $$$ }", lang="typescript") — catch blocksgrep("catch.*{}|catch.*{\\s*}") — empty catch blocksgrep("console.error|logger\\.error|log\\.error") — actual error loggingast_grep_search(pattern="throw new $ERR(", lang="typescript") — error types usedTrace error propagation through call chains:
codegraph_callers(symbol="<key-error-handler-or-middleware>")
codegraph_explore(query="how errors propagate through <key-error-handler>")
Use codegraph_callers to find who calls your error handlers. If errors are caught and swallowed at multiple levels, that's a finding.
Impact of changing error types:
codegraph_impact(target="<error-class-or-interface>", direction="upstream")
Check the blast radius of custom error classes. If changing an error type would break 20+ consumers, the error contract is too tight.
catch (e) { console.error(e) } without recovery.catch(() => {}))grep("api[Kk]ey|api_secret|password|secret|token|credential") in source files (not config or env)ast_grep_search(pattern="SELECT .* FROM|INSERT INTO|UPDATE.*SET|DELETE FROM", lang="typescript") — SQL constructionast_grep_search(pattern="innerHTML|dangerouslySetInnerHTML", lang="typescript") — XSS vectorsgrep("eval\\(|Function\\(|setTimeout\\(.*string|setInterval\\(.*string") — code injectioninnerHTML / dangerouslySetInnerHTML usageeval() or string-based setTimeout/setIntervalread("README.md") — check if claims match realitygrep("@param|@returns|@throws") — docstring coveragegrep("FIXME|TODO|HACK|XXX|WORKAROUND") — fixme densityFor large codebases (>50k LOC), delegate heavy dimensions to parallel sub-agents. Sub-agents CANNOT use CodeGraph — they use standard tools only:
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. The main agent handles CodeGraph queries itself while sub-agents run the standard tool passes.
TECH_DEBT_AUDIT.md with all required sectionsCritical = 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
file:line:col citation