/omh-tech-debt-audit

name: "omh-tech-debt-audit"
description: "[omh] Accumulated tech debt to rank: 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."
metadata:
  hermes:
    tags: [workflow, oh-my-hermes, maintenance]
    category: maintenance
    phase: tech-debt-audit
    role: reviewer
    quality_tier: finding-evidence-gated

Tech Debt Audit

This is a Hermes-native `tech-debt-audit` workflow skill.

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.

Workflow Lane

• Current lane: **Coding handoff** (`idea-to-deploy`, `llm-app-dev`, `cto-loop`, `deploy-and-monitor`, `code-review`, `build-failure-triage`, `verification-gate`, `security-safety-review`, `+28 more`) - coding owners, handoffs, review, CI, and merge evidence.
• If intent belongs to another lane, hand back to `oh-my-hermes` or name the adjacent workflow.
• Shared product, routing, compatibility, and evidence rules: `omh-routing/references/skill-common-rail.md`.

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` Hermes role: `reviewer` 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.

Handoff policy:

Hermes owns the orientation, the dimension audit, and the ledger; detection commands run through the operator's terminal and stay prepared_not_observed until their output is seen, and every fix the ledger recommends is coding work for the selected executor lane, never part of the audit.

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:

• orient