gz-tech-debt-review

name: gz-tech-debt-review persona: quality-reviewer description: Survey scoped technical debt across existing gzkit probes and render a prioritized, line-grounded report with route recommendations. Use for tech-debt review requests across touched files, paths, ADRs, OBPIs, or the whole repo. Produces diagnosis only; findings route to chores, in-flight fixes, or at most one GHI per run, never directly to OBPI. category: code-quality lifecycle_state: active owner: gzkit-governance last_reviewed: 2026-04-29 metadata: skill-version: "1.2.1" model: sonnet

gz-tech-debt-review

Survey the codebase for technical debt across multiple debt classes, synthesize the findings into one prioritized report, and recommend a resolution path for each finding.

This skill is a synthesizer, not a new analyzer. The gzkit surface already runs the analyses (chores, validators, ruff, ty, xenon, radon). The skill's job is to wield those tools, normalize their outputs, rank by impact, and produce one operator-facing report — so debt findings end up in GHIs, OBPI briefs, or chore runs instead of dying on a terminal scrollback.

Position in the gzkit surface

Invocation

/gz-tech-debt-review                          # default: touched-files scope
/gz-tech-debt-review --scope all              # whole repository sweep
/gz-tech-debt-review --scope touched          # current branch's diff vs main
/gz-tech-debt-review --scope adr ADR-0.1.0    # ADR-scoped paths
/gz-tech-debt-review --scope obpi OBPI-0.1.0-01  # brief Allowed Paths
/gz-tech-debt-review --scope path src/gzkit/commands  # explicit subtree
/gz-tech-debt-review --draft-ghis             # also draft GHI bodies for High/Critical

The first positional token after --scope selects scope mode. The --draft-ghis flag is opt-in: by default the skill diagnoses only. With the flag it drafts gh issue create --label tech-debt bodies for Critical and High findings the operator can route as a follow-up.

Scope resolution

Resolve the file list before running any analysis. The scope mode determines how:

If the resolved file list is empty, abort with a clear message rather than scanning the whole repo silently.

The file list is the audit scope. Findings outside it are noted but not graded.

Debt classes (binding)

A "debt class" is a named family of failure shapes with one or more signal sources. The skill surveys all classes by default. Operators can narrow with --class <name> (repeatable) when they want a focused read.

Adding a class is additive: extend the table, add a probe in Step 2, extend the severity matrix below.

Severity rubric (binding)

Every finding is graded Critical / High / Medium / Low. Severity is a function of (a) blast radius and (b) reversibility — never of how big the diff is to fix.

If a finding could be graded two ways, grade up — debt's main failure mode is being underweighted and ignored.

Step 1: Resolve scope

1. Parse the invocation: scope mode, classes, flags.
2. Resolve the file list per the table above.
3. Save the file list to .gzkit/audits/tech-debt/<YYYY-MM-DD>/scope.txt. This makes the audit replayable; an operator running the same scope later can diff the lists.
4. If git diff --name-only returns nothing on --scope touched, fall back to the most recent commit's files and tell the operator you did so.

Step 2: Run the probes

Run probes for every class in scope. Wield existing tools — do not re-implement analysis. Each probe writes its raw output to .gzkit/audits/tech-debt/<YYYY-MM-DD>/probes/<class>.txt so the report can cite line-grounded evidence.

For each class, the canonical probe:

Wrap probes that produce attestable output under ARB so the report can cite receipts: uv run gz arb step --name <class> -- <command>. This is required when --draft-ghis is set, optional otherwise.

If a probe errors (tool not installed, scope empty, etc.), record "probe-error: " as a Medium finding under a probe-health class — never silently drop it. A missing probe is itself debt.

Step 3: Synthesize and rank

For every probe hit, produce a finding record:

finding_id: <class>-<short-slug>
class: <one of the debt classes>
severity: <Critical|High|Medium|Low>
location: <file>:<line> (or <file> for whole-file findings)
evidence: <one or two lines of probe output, verbatim>
recommendation: <fix shape — see § Recommendation discipline>
route: <one of: in-flight | GHI | OBPI | chore | discard>

Save the full finding list to .gzkit/audits/tech-debt/<YYYY-MM-DD>/findings.json.

Recommendation discipline

The recommendation field names the fix shape, not the code. Diagnose, don't write the patch. Phrase as imperative:

• "Split _render_table (87 LOC) into _format_rows and _emit_table."
• "Replace # type: ignore[union-attr] at status.py:412 with # ty: ignore[unresolved-attribute] per .claude/rules/pythonic.md."
• "Drop the Strategy class in cli/parser_artifacts.py:64 to a module-level dispatch dict."
• "Doc example at docs/user/runbook.md:148 shows gz status output that drifted from current rendering — paste fresh output."

Anti-patterns:

• Recommendations that say "improve" / "clean up" / "make better" without naming the fix shape
• Recommendations that propose adding a feature (debt review never expands scope — that's gz-plan or ghi-author's job)
• Recommendations that route to "discuss with the team" — operator attention is the scarce resource; route concretely or downgrade

Route discipline

GHI budget — one per skill run (binding)

A debt-review run produces at most one GHI recommendation, regardless of how many High/Critical findings surface. This is binding, not a heuristic.

Why. A debt skill that emits 9 GHIs from one scan turns the skill into a GHI-spammer: the operator's queue floods with debt items the skill graded itself, the triage signal-to-noise ratio collapses, and the operator's tracking surface stops reflecting work-they-decided-to-do and starts reflecting work-the-skill-decided-was-important. That's the exact governance inversion the MAKE LLM STOCHASTIC VIBES INERT mantra defends against — the operator's typing budget and queue attention are the scarce resources, and a skill that converts them at 9× per run is exfiltrating attention, not preserving it.

How to pick the one GHI. From the full finding set, choose the finding that:

1. Is Critical if any Critical surfaced; otherwise the highest-severity single finding the operator could not cleanly route to a chore.
2. Is scoped — a single named module/function/surface, not a cluster.
3. Has no existing chore home — if the finding fits an existing chore, route to chore instead and pick a different GHI candidate.
4. Has no existing GHI open against the same surface (check gh issue list --search '<surface>' --state open).

If no finding meets all four, emit zero GHIs and route everything else to chore / in-flight / discard. Zero GHIs is the right answer more often than agents instinctively believe.

Everything else routes to chore. Bulk debt is a chore-runner problem, not a GHI problem. Chores already aggregate scope, schedule the work under a maintenance lane, and emit the receipts the operator wants — without polluting the issue queue.

Tidying-class only — do not route to OBPI. This skill surfaces quality-of-implementation defects, not new capability work. OBPI ceremony exists for planned increments under an active ADR; debt findings are remediation, not new scope. Even when a finding cluster is large enough that a refactor brief feels appealing, the right operator response is "file the one GHI; if the refactor merits an ADR, the operator opens one through gz-plan or gz-design" — not "the debt skill drafts an OBPI." Routing debt findings to OBPI shifts capability-planning authority from operator to skill, which is the wrong governance shape.

Step 4: Render the report

Two-section render. Save to .gzkit/audits/tech-debt/<YYYY-MM-DD>/report.md. Print path to chat along with the table summary; do not dump the full report into chat — operators review the file.

Section A — Table summary (top)

One table grouping by class, one row per finding, columns: Severity | Class | Location | Recommendation | Route. Sort by severity descending, then by class. Counts at the bottom: Critical: N | High: N | Medium: N | Low: N | Total: N.

Section B — Per-finding detail

For each finding (Critical and High only in the body; Medium and Low collapsed under a <details> block), one subsection:

### [Severity] <class>: <location>

**Evidence**
> <verbatim probe excerpt>

**Why this is debt**
<one paragraph: which rule / invariant / contract this drift violates,
grounded in a citation to AGENTS.md §, a rule under .gzkit/rules/, or
the chore's CHORE.md>

**Recommended fix**
<imperative fix shape>

**Route:** `<route>` — <one-line rationale>

If --draft-ghis is set, append a § Draft GHI bodies section with ready-to-paste gh issue create --label tech-debt bodies for every Critical and High finding routed to GHI.

Step 5: Operator handoff

After rendering, print to chat:

1. The report path
2. The Critical/High/Medium/Low counts
3. The top three findings by severity (one line each)
4. The single GHI candidate, if any (per § GHI budget). If no finding meets the four selection criteria, say so explicitly: "No GHI recommended; everything routes to chore or in-flight."
5. The recommended next operator action — one of:
   • "File the one GHI: <title>" (if a GHI candidate was selected)
   • "Run chore X on the size-cap cluster" (if a chore-routable cluster dominates)
   • "Bundle Low findings into the next opportunistic commit" (if all-Low)
   • "Apply the in-flight fixes now" (if the highest-severity finding meets in-flight thresholds)

Do not auto-execute the next action. The skill diagnoses; the operator routes.

Constraints

• Diagnose, do not patch. Per the user's choice (option A on recommendation style): name the fix shape, do not write the code. gz-obpi-simplify is the patching skill; this one is the surveying skill. The boundary is intentional.
• Wield existing tools. Do not re-implement complexity scoring, coverage measurement, or pattern detection. The chore/validator surface is canonical; the skill's value is synthesis.
• Cite line-grounded evidence. Every finding has a probe output excerpt. No narrative-only findings — that's the MAKE LLM STOCHASTIC VIBES INERT failure.
• Severity grade-up on ambiguity. Underweighting is the dominant failure mode for debt review.
• Save artifacts under .gzkit/audits/tech-debt/<date>/. The audit must be replayable without re-running the model.
• Respect simplify-ignore annotations (same convention as gz-obpi-simplify). Code in protected regions is excluded from review and reported separately.

Common rationalizations

These thoughts mean STOP — you are about to ship a hollow review:

Red flags

• Report rendered without any line:column references — synthesis without evidence
• More than one finding routed to GHI in a single run — the skill became a GHI-spammer; the one-per-run budget is binding (§ GHI budget)
• Multiple findings routed to GHI because they "feel important" rather than because they meet all four selection criteria
• No Critical findings ever surface — severity grade-up rule is not being applied
• Report rendered before all probes completed — partial audits are not audits
• Recommendations that read "review this" or "consider X" — diagnostic discipline broken

Related skills