# Omh Tech Debt Audit > [omh] Hermes Tech Debt Audit workflow: build the severity-by-effort debt ledger from observed repo evidence - orient, audit the named dimensions with file:line citations, rank fixes and quick wins - and reconcile RESOLVED/NEW/CARRIED against the previous ledger on rerun. Use when the user says: tech-debt-audit, tech debt, tech debt audit, technical debt, technical debt audit, tech debt ledger, debt ledger, audit our tech debt. - Skill: `rlaope/omh-tech-debt-audit-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add rlaope/omh-tech-debt-audit-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/rlaope/omh-tech-debt-audit-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: rlaope (https://skillmd.com/u/rlaope) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/rlaope/omh-tech-debt-audit-2 --- # Tech Debt Audit This is an OMH `tech-debt-audit` workflow skill, projected for Agent Skills hosts (Claude Code, Codex, Cursor, opencode, OpenClaw, pi). ## Why This Exists `tech-debt-audit` exists so accumulated debt becomes a ranked, reconcilable ledger instead of a one-off complaint: findings cite file:line, severity and effort make the trade-off explicit, quick wins are separated from big fixes, and reruns mark what was resolved instead of rediscovering it. ## Do Not Use When - The target is one diff, PR, or claim rather than the codebase's accumulated state; use `code-review`. - The user wants the debt removed now, behavior preserved; use `ai-slop-cleaner` for deletion-first cleanup. - A boundary-changing fix from the ledger needs its execution shaped into phases; use `refactor-plan`. - The question is release risk for a specific deploy rather than source quality; use `production-audit`. ## Examples Good example: - Prompt: Audit our tech debt and tell me what to fix first - we have maybe two weeks of cleanup budget. - Expected behavior: Orientation from manifests and churn, dimension-by-dimension findings with file:line citations, the severity-by-effort ledger with top fixes and quick wins sized to the budget, and the looks-bad-but-fine list. - Why: A budgeted what-to-fix-first question is exactly the ranked ledger this workflow produces. Bad example: - Prompt: This module is a mess, rewrite it properly. - Expected behavior: Refuse the rewrite framing: audit the module into ledger findings with bounded fixes, or route a decided restructure to `refactor-plan`. - Why: A rewrite recommendation is the failure mode the ledger exists to replace with bounded, ranked fixes. ## Completion Checklist - Orientation evidence is observed: manifests, churn ranking, and largest files are named, not assumed. - Every finding has id, dimension, file:line, severity, effort, and a bounded recommendation. - Quick wins and top fixes are ranked, and the looks-bad-but-is-actually-fine section is present. - On rerun, every prior finding is reconciled RESOLVED, CARRIED, or superseded - none silently dropped. ## Recovery Notes - If the stack is unrecognized, orient from the manifests first and say which dimensions lack detection commands rather than guessing. - If a finding cannot be cited to file:line, demote it to an open question and keep it out of the ranked table. - If the previous ledger's ids no longer match the tree, map them by dimension plus path before declaring anything RESOLVED. ## Use When Use when the codebase's accumulated debt should be measured and ranked as a ledger - findings with file:line, severity, and effort, quick wins separated from big fixes - rather than judged as a diff or cleaned up on the spot. Strong routing signals: `tech-debt-audit`, `tech debt`, `tech debt audit`, `technical debt`, `technical debt audit`, `tech debt ledger`, `debt ledger`, `audit our tech debt`, `tech debt report`, `code debt audit`, `where is our tech debt`, `기술부채`, `기술 부채`, `기술부채 감사`, `기술부채 감사해줘`, `기술부채 점검`, `기술부채 장부`, `부채 원장` ## Catalog Metadata Category: `maintenance` Phase: `tech-debt-audit` Quality tier: `finding-evidence-gated` Reasoning demand: `heavy` Quality bar: - Orient before auditing: read the manifests, rank churn from the git log, and name the largest and most-changed files - observed evidence, never memory of the tree. - Audit dimension by dimension from the named list - architectural decay, consistency rot, type and contract gaps, test debt, dependency and configuration debt, performance and resource debt, error-handling and observability debt, security hygiene, documentation drift; the full contract is `omh-tech-debt-audit/references/debt-dimensions.md`. - Every finding row carries a stable id, its dimension, a file:line citation, a severity, an effort class (S/M/L), and a bounded recommendation - never a rewrite. - Close with the mandatory looks-bad-but-is-actually-fine section: deliberate patterns that pattern-match to debt stay off the ledger, with the reason recorded. - On rerun, reconcile against the previous ledger before writing a new one: every prior finding is marked RESOLVED with the evidence gone, CARRIED with its age, or superseded by a NEW finding - a rerun that restarts from zero loses the ledger's point. Required inputs: - the repo root or the scoped path list the audit is confined to - the stack truth from manifests (package/build files), not from memory of the tree - the previous ledger when one exists, so the rerun can reconcile instead of restart Expected outputs: - orientation summary: manifests read, churn ranking, largest files, test and CI entry points - findings table per `tech_debt_ledger/v1`: id, category, file:line, severity, effort, recommendation - top fixes ranked by severity and the quick wins ranked by payoff-per-effort - the looks-bad-but-is-actually-fine list, and the RESOLVED/NEW/CARRIED reconciliation on rerun Artifact expectations: - debt ledger per `omh-tech-debt-audit/references/debt-dimensions.md` - prepared detection commands named per stack, marked observed only after their output is seen Safety rules: - Never recommend a rewrite; the ledger names bounded fixes or it names nothing. - A finding without a file:line citation is an open question, not a finding. - Detection commands are prepared context until their exit status and output are observed. - A scoped path list is a boundary: out-of-scope findings are reported as out of scope, never audited silently. ## Runtime Evidence Use the current host's own tools and subagent/task mechanism when available; otherwise run the same lanes sequentially or name the unavailable capability. A prepared plan, handoff, checklist, or skill installation is not execution, review, CI, merge-readiness, or merge evidence. Report actual tool results or `not_observed` / `not_available`; never invent dispatch or host accounting. Treat supplied context as advisory, not proof of hidden memory reads or writes. State scope, constraints, verification, and the stop condition before work. Supporting paths are relative to this skill directory; sibling skill paths are relative to its parent. Resolve them from the host-provided skill base directory (`{baseDir}` on hosts that provide it), never a hardcoded install location. A named workflow not installed here is unavailable, not permission to emulate its host-specific capabilities. Verify through the real surface before done.