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 4. Estimate effort in hours per finding (conservative) 5. Write `TECH_DEBT_AUDIT.md` with all required sections 6. 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