{"slug":"tech-debt-audit","title":"tech-debt-audit","summary":"Thorough, file-cited technical debt audit across 9 dimensions using AST-grep (tree-sitter), grep, language-native tooling, and optionally CodeGraph knowledge graph. Produces TECH_DEBT_AUDIT.md with severity, effort estimates, and prioritized fixes. Use when asked for codebase hea","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-23T08:58:13.721935Z","repo":{"url":"https://github.com/code-yeongyu/oh-my-openagent","stars":69391,"forks":5715,"license":null,"updatedAt":"2026-09-24T23:30:44Z"},"bodyHtml":"<hr>\n<h2>name: tech-debt-audit\ndescription: \"Thorough, file-cited technical debt audit across 9 dimensions using AST-grep (tree-sitter), grep, language-native tooling, and optionally CodeGraph knowledge graph. 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'.\"</h2>\n<h1>Tech Debt Audit Protocol</h1>\n<p>Model-agnostic technical debt audit for oh-my-openagent (OMO). Uses OMO's built-in tools (<code>grep</code>, <code>glob</code>, <code>bash</code> with <code>sg</code>, <code>read</code>, <code>lsp_diagnostics</code>, <code>task</code>) plus <strong>optional CodeGraph MCP</strong> for enhanced code graph analysis when available. Produces a grounded, citable <code>TECH_DEBT_AUDIT.md</code> artifact.</p>\n<h2>CodeGraph Enhancement (Optional)</h2>\n<p>If you have <a href=\"https://github.com/colbymchenry/codegraph\">CodeGraph</a> installed (check with <code>codegraph status</code>), its MCP tools (<code>codegraph_search</code>, <code>codegraph_callers</code>, <code>codegraph_callees</code>, <code>codegraph_impact</code>, <code>codegraph_explore</code>, etc.) can supersede or augment the standard tool searches in the dimensions marked below. CodeGraph gives you:</p>\n<ul>\n<li><strong>Symbol search</strong> — instant by-name lookup via FTS5</li>\n<li><strong>Call graph analysis</strong> — callers/callees for any function</li>\n<li><strong>Impact analysis</strong> — blast radius before changing any symbol</li>\n<li><strong>Smart context building</strong> — entry points, related symbols, and snippets in one call</li>\n<li><strong>Framework-aware routes</strong> — URL patterns linked to their handlers</li>\n</ul>\n<p>To use CodeGraph, ensure the <code>codegraph</code> MCP server is configured in your project's <code>.mcp.json</code> or global MCP config. The skill will auto-detect CodeGraph by checking if <code>codegraph</code> MCP tools are available. Sub-agents spawned via <code>task()</code> cannot use CodeGraph — they use the standard tool fallback.</p>\n<hr>\n<h2>Output</h2>\n<p>Write results to <code>TECH_DEBT_AUDIT.md</code> in the repo root with:</p>\n<ol>\n<li><strong>Executive Summary</strong> — 3-5 sentences: overall health, worst dimension, quick wins count</li>\n<li><strong>Mental Model</strong> — the repo's architecture in 1 paragraph (what it does, stack, module boundaries)</li>\n<li><strong>Findings Table</strong> — columns: ID, Category, File:Line, Severity (Critical/High/Medium/Low), Effort (Hours), Description, Recommendation</li>\n<li><strong>Top 5 Priorities</strong> — ranked by impact/effort ratio</li>\n<li><strong>Quick Wins Checklist</strong> — items under 30 minutes each</li>\n<li><strong>\"Looks Bad But Is Fine\"</strong> — patterns that look like debt but are intentional</li>\n<li><strong>Open Questions</strong> — things the maintainer should clarify</li>\n</ol>\n<h2>Phase 0: Orient</h2>\n<h3>Standard (always run)</h3>\n<ol>\n<li><code>glob(\"**/*.ts\")</code> / <code>glob(\"**/*.py\")</code> / etc — map the language stack</li>\n<li><code>glob(\"**/package.json\")</code> + <code>read()</code> — dependencies and build tooling</li>\n<li><code>bash(\"git log --oneline -200\")</code> — churn: find highest-change files</li>\n<li><code>glob(\"**/*\")</code> + basic math — find largest files (&gt;300 LOC are candidates)</li>\n<li>Cross-reference high-churn + large = debt hot zones</li>\n<li>Write the mental model paragraph in your own working context</li>\n</ol>\n<h3>CodeGraph Enhancement (if available)</h3>\n<p>Instead of guessing module boundaries, query the code graph:</p>\n<pre><code>codegraph_explore(query=\"architecture overview and main modules\")\n</code></pre>\n<p>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.</p>\n<pre><code>codegraph_explore(query=\"main entry points and execution flow\")\n</code></pre>\n<p>This surfaces entry points and call chains. Use these to understand how the code actually flows vs how the directory layout suggests it flows.</p>\n<h2>Phase 1: Audit Across 9 Dimensions</h2>\n<p>Use OMO tools for each dimension. Run parallel tool calls within each dimension. Every finding MUST cite <code>file:line:col</code>.</p>\n<h3>1. Architectural Decay</h3>\n<h4>Standard (always run)</h4>\n<ul>\n<li><code>bash(\"sg -p \\\"import { $$$ } from '$SRC'\\\" -l ts .\")</code> — map module graph, look for circular patterns</li>\n<li><code>bash(\"sg -p \\\"class $NAME { $$$ }\\\" -l ts .\")</code> — check for god classes</li>\n<li><code>grep(\"TODO|FIXME|HACK|XXX|WORKAROUND|TEMP\")</code> — tagged debt markers</li>\n<li><code>grep(\"async|await\")</code> on sync-looking files — misplaced async boundaries</li>\n<li><code>bash(\"wc -l &lt;file&gt;\")</code> on each large file found in Phase 0</li>\n</ul>\n<h4>CodeGraph Enhancement (if available)</h4>\n<p><strong>Dead code detection:</strong></p>\n<pre><code>codegraph_callers(symbol=\"&lt;suspected-dead-function&gt;\")\ncodegraph_callers(symbol=\"&lt;suspected-dead-class&gt;\")\n</code></pre>\n<p>Run <code>codegraph_callers</code> on suspected dead exports found via grep/glob. If the result shows zero callers (excluding test files), it's dead code.</p>\n<p><strong>Circular dependency detection:</strong></p>\n<pre><code>codegraph_impact(target=\"&lt;module-or-file&gt;\", direction=\"upstream\")\n</code></pre>\n<p>Use <code>codegraph_impact</code> on key modules to trace their dependents. If A depends on B and B depends on A, that's a cycle.</p>\n<p><strong>Architecture boundaries:</strong></p>\n<pre><code>codegraph_explore(query=\"module dependencies and architecture boundaries\")\n</code></pre>\n<p>Use <code>codegraph_explore</code> to survey actual module structure.</p>\n<h4>What to flag</h4>\n<ul>\n<li>Files &gt; 500 LOC (god files)</li>\n<li>Functions &gt; 80 LOC or &gt; 4 nesting levels</li>\n<li>Classes with &gt; 15 methods or &gt; 400 LOC</li>\n<li>Import cycles (A → B → A)</li>\n<li>Dead exports: function/class defined but never imported elsewhere (CodeGraph: <code>codegraph_callers</code>)</li>\n<li>Commented-out code blocks (&gt;3 consecutive consecutive lines)</li>\n</ul>\n<h3>2. Consistency Rot</h3>\n<h4>Standard (always run)</h4>\n<ul>\n<li><code>bash(\"sg -p \\\"import $CLIENT from '$PKG'\\\" -l ts .\")</code> — multiple HTTP clients</li>\n<li><code>grep(\"console.log|console.error|console.warn\")</code> — direct console use vs logger</li>\n<li><code>bash(\"sg -p \\\"try { $$$ } catch ($$$) { $$$ }\\\" -l ts .\")</code> — error handling patterns</li>\n<li><code>grep(\"as any|@ts-ignore|@ts-expect-error|as unknown\")</code> — type escapes</li>\n<li><code>grep(\"eslint-disable|prettier-ignore\")</code> — lint suppressions</li>\n</ul>\n<h4>What to flag</h4>\n<ul>\n<li>3+ ways of doing the same thing (HTTP, logging, validation, config)</li>\n<li>Mixed naming conventions (camelCase + snake_case + PascalCase)</li>\n<li>Multiple date/time handling libraries</li>\n<li>Mixed error response shapes across modules</li>\n</ul>\n<h3>3. Type &amp; Contract Debt</h3>\n<h4>Standard (always run)</h4>\n<ul>\n<li><code>bash(\"sg -p \\\"$VALUE as any\\\" -l ts .\")</code> — runtime type escapes</li>\n<li><code>grep(\"@ts-expect-error\")</code> — suppressed errors</li>\n<li><code>grep(\"@ts-ignore\")</code> — suppressed errors (legacy)</li>\n<li><code>bash(\"sg -p \\\"$NAME: any\\\" -l ts .\")</code> — typed as any</li>\n<li><code>lsp_diagnostics(filePath=\"&lt;src-dir&gt;\")</code> — current type errors</li>\n</ul>\n<h4>What to flag</h4>\n<ul>\n<li><code>any</code> types on public APIs and exported interfaces</li>\n<li>Untyped function parameters</li>\n<li>Missing schema validation at API/IO boundaries</li>\n<li>LSP type errors grouped by file</li>\n</ul>\n<h3>4. Test Debt</h3>\n<h4>Standard (always run)</h4>\n<ul>\n<li><code>glob(\"**/*.test.ts\")</code> — find all test files</li>\n<li><code>bash(\"bun test 2&gt;&amp;1 | grep -E '(fail|skip|todo)'\")</code> — current test health</li>\n<li>Cross-reference Phase 0 high-churn files with test existence</li>\n</ul>\n<h4>What to flag</h4>\n<ul>\n<li>Critical-path files with zero tests</li>\n<li>Skipped tests (<code>test.skip</code>, <code>describe.skip</code>)</li>\n<li>Tests asserting implementation details vs behavior</li>\n<li>Slow tests (&gt;1s each)</li>\n</ul>\n<h3>5. Dependency &amp; Config Debt</h3>\n<h4>Standard (always run)</h4>\n<ul>\n<li><code>bash(\"npm audit --omit=dev 2&gt;&amp;1 | head -40\")</code> — known CVEs (if node_modules present)</li>\n<li><code>read(\"package.json\")</code> — check dependency count and stale deps</li>\n<li><code>grep(\".env|process.env|Bun.env\")</code> — env var usage</li>\n<li><code>grep(\"API_KEY|SECRET|PASSWORD|TOKEN\")</code> in non-config files — hardcoded config</li>\n</ul>\n<h4>CodeGraph Enhancement (if available)</h4>\n<p><strong>Blast radius of core dependencies:</strong></p>\n<pre><code>codegraph_impact(target=\"&lt;core-utility-function&gt;\", direction=\"upstream\")\n</code></pre>\n<p>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.</p>\n<h4>What to flag</h4>\n<ul>\n<li>Outdated major-version deps</li>\n<li>Dependencies that do the same thing (duplicate libraries)</li>\n<li>Referenced env vars not documented in README</li>\n<li>Hardcoded environment-specific values</li>\n</ul>\n<h3>6. Performance &amp; Resource Hygiene</h3>\n<h4>Standard (always run)</h4>\n<ul>\n<li><code>bash(\"sg -p \\\"for ($$$ of $$$) { $$$ await $$$ }\\\" -l ts .\")</code> — async-in-loop</li>\n<li><code>grep(\"await.*map|await.*filter|await.*forEach\")</code> — sequential async iteration</li>\n<li><code>grep(\"Promise\\\\.all|Promise\\\\.allSettled\")</code> — existing parallel patterns (good signal)</li>\n<li><code>grep(\"addEventListener|on\\\\(|subscribe\")</code> without <code>removeEventListener|off\\\\(|unsubscribe</code> nearby — listener hygiene</li>\n</ul>\n<h4>What to flag</h4>\n<ul>\n<li><code>await</code> inside <code>for/of</code> loops (sequential when parallel possible)</li>\n<li>N+1 query patterns</li>\n<li>Missing cleanup on event listeners, intervals, handles</li>\n<li>Unnecessary serialization/deserialization</li>\n</ul>\n<h3>7. Error Handling &amp; Observability</h3>\n<h4>Standard (always run)</h4>\n<ul>\n<li><code>bash(\"sg -p \\\"catch ($$$) { $$$ }\\\" -l ts .\")</code> — catch blocks</li>\n<li><code>grep(\"catch.*{}|catch.*{\\\\s*}\")</code> — empty catch blocks</li>\n<li><code>grep(\"console.error|logger\\\\.error|log\\\\.error\")</code> — actual error logging</li>\n<li><code>bash(\"sg -p \\\"throw new $ERR($$$)\\\" -l ts .\")</code> — error types used</li>\n</ul>\n<h4>CodeGraph Enhancement (if available)</h4>\n<p><strong>Trace error propagation through call chains:</strong></p>\n<pre><code>codegraph_callers(symbol=\"&lt;key-error-handler-or-middleware&gt;\")\ncodegraph_explore(query=\"how errors propagate through &lt;key-error-handler&gt;\")\n</code></pre>\n<p>Use <code>codegraph_callers</code> to find who calls your error handlers. If errors are caught and swallowed at multiple levels, that's a finding.</p>\n<p><strong>Impact of changing error types:</strong></p>\n<pre><code>codegraph_impact(target=\"&lt;error-class-or-interface&gt;\", direction=\"upstream\")\n</code></pre>\n<p>Check the blast radius of custom error classes. If changing an error type would break 20+ consumers, the error contract is too tight.</p>\n<h4>What to flag</h4>\n<ul>\n<li>Empty catch blocks (worst offense)</li>\n<li>Generic <code>catch (e) { console.error(e) }</code> without recovery</li>\n<li>Inconsistent error shapes across modules</li>\n<li>Missing structured logging on critical paths</li>\n<li>Errors swallowed in promise chains (<code>.catch(() =&gt; {})</code>)</li>\n</ul>\n<h3>8. Security Hygiene</h3>\n<h4>Standard (always run)</h4>\n<ul>\n<li><code>grep(\"api[Kk]ey|api_secret|password|secret|token|credential\")</code> in source files (not config or env)</li>\n<li><code>grep(\"SELECT .* FROM|INSERT INTO|UPDATE.*SET|DELETE FROM\")</code> — SQL construction</li>\n<li><code>grep(\"innerHTML|dangerouslySetInnerHTML\")</code> — XSS vectors</li>\n<li><code>grep(\"eval\\\\(|Function\\\\(|setTimeout\\\\(.*string|setInterval\\\\(.*string\")</code> — code injection</li>\n</ul>\n<h4>What to flag</h4>\n<ul>\n<li>Hardcoded secrets in source</li>\n<li>String-concatenated SQL</li>\n<li><code>innerHTML</code> / <code>dangerouslySetInnerHTML</code> usage</li>\n<li><code>eval()</code> or string-based <code>setTimeout</code>/<code>setInterval</code></li>\n<li>Permissive CORS or auth middleware</li>\n</ul>\n<h3>9. Documentation Drift</h3>\n<h4>Standard (always run)</h4>\n<ul>\n<li><code>read(\"README.md\")</code> — check if claims match reality</li>\n<li><code>grep(\"@param|@returns|@throws\")</code> — docstring coverage</li>\n<li><code>grep(\"FIXME|TODO|HACK|XXX|WORKAROUND\")</code> — fixme density</li>\n<li>Compare README API examples with actual signatures</li>\n</ul>\n<h4>What to flag</h4>\n<ul>\n<li>README claiming features that don't exist</li>\n<li>Public functions without any doc comment</li>\n<li>Comments that contradict the code</li>\n<li>Stale architecture decision records (ADRs) if present</li>\n</ul>\n<h2>Phase 2: Deeper Dives (Parallel Sub-Agents)</h2>\n<p>For large codebases (&gt;50k LOC), delegate heavy dimensions to parallel sub-agents. Sub-agents CANNOT use CodeGraph — they use standard tools only:</p>\n<pre><code>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.\")\ntask(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.\")\n</code></pre>\n<p>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.</p>\n<h2>Phase 3: Synthesize &amp; Deliver</h2>\n<ol>\n<li>Collect all findings from direct tool calls, CodeGraph queries (if available), and sub-agent results</li>\n<li>Deduplicate — same issue mentioned by multiple dimensions</li>\n<li>Classify severity:\n<ul>\n<li><strong>Critical</strong> — Causes incorrect behavior, data loss, or security vulnerability</li>\n<li><strong>High</strong> — Will cause problems in production; blocks maintenance</li>\n<li><strong>Medium</strong> — Reduces maintainability; violates conventions</li>\n<li><strong>Low</strong> — Cosmetic; should fix when in the area</li>\n</ul>\n</li>\n<li>Estimate effort in hours per finding (conservative)</li>\n<li>Write <code>TECH_DEBT_AUDIT.md</code> with all required sections</li>\n<li>Report summary to the user</li>\n</ol>\n<h2>Severity Rubric</h2>\n<pre><code>Critical = actively causing bugs or security holes\nHigh     = will cause problems under normal operation; blocks changes\nMedium   = reduces maintainability; inconsistent; violates team conventions\nLow      = cosmetic; would be nice to fix when nearby\n</code></pre>\n<h2>Quick Checks Before Finishing</h2>\n<ul>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Every concrete finding has <code>file:line:col</code> citation</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> No generic claims without evidence</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> \"Looks Bad But Is Fine\" section explains at least 2-3 patterns</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Top 5 priorities ranked by impact/effort</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Quick wins are things that can be fixed in &lt;30 minutes each</li>\n</ul>\n","files":[{"path":"SKILL.md","sizeBytes":9613,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"notes-only","suspicious":0,"notes":2,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-03T16:37:27.860999Z","sha256":"551EC95C9D650B5275CB2B1B60FFF2C61136037686EB07094D87D104BC9BA003","sizeBytes":4307},"review":null,"source":{"repositoryUrl":"https://github.com/code-yeongyu/oh-my-openagent","path":".agents/skills/tech-debt-audit","license":null,"commit":"05dcba64b749e7666dcd0296c079d31cf3c298f1","subtreeSha":"CB4F460704E8459A888FE1D17A1AAC18306BD2225139B218A0EB590754797C3F","lastSyncedAt":"2026-09-25T07:37:33.26442Z"},"reviewedAt":"2026-09-03T16:37:45.944933Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/code-yeongyu/oh-my-openagent/tree/dev/.agents/skills/tech-debt-audit"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install code-yeongyu-oh-my-openagent@llmmart"},{"target":"git","command":"git clone https://github.com/code-yeongyu/oh-my-openagent.git"}]}