debt-ops-metrics

name	debt-ops-metrics
description	Print a debt-ops health summary from the metrics log, covering registration rate, feedback action rate, ADR creation, and AI-authored share. Use when the user asks for "debt-ops metrics", "debt health", "registry stats", or a tech-debt health summary. Read-only, never writes the log.

debt-ops-metrics

Read the hidden metrics log and tell the user whether the tripwires are tripping.

1. Find the log

The repo-hash is computed in Python (not shasum) so this is identical across macOS, Linux, and Windows — no BSD/GNU coreutils dependency.

REPO_HASH=$(python3 -c "import hashlib,subprocess;t=subprocess.run(['git','rev-parse','--show-toplevel'],capture_output=True,text=True).stdout.strip();print(hashlib.sha1(t.encode()).hexdigest()[:12] if t else '')")

# Hooks and skills share one deterministic cache base. Override with
# DEBT_OPS_CACHE; default is ~/.cache/debt-ops.
CACHE_DIR="${DEBT_OPS_CACHE:-$HOME/.cache/debt-ops}/cache/$REPO_HASH"

LOG="$CACHE_DIR/metrics.jsonl"
if [ -n "$REPO_HASH" ] && [ -f "$LOG" ]; then
  tail -n 500 "$LOG"
else
  echo "MISSING: no metrics.jsonl found for repo hash ${REPO_HASH:-<not-a-git-repo>}"
fi

If the file is missing or empty, tell the user no debt-ops activity has been logged for this repo yet and stop. On a skills-only tool (no hook adapter), only register and review events are logged — the per-edit edit/feedback/session events come from the hook adapter, so feedback metrics will be absent. Say so rather than reporting them as zero.

2. The log format

One JSON object per line. Event shapes:

• {"event":"register","slug":"...","ai_authored":bool,"letter":"...","ts":"..."} — each capture
• {"event":"review","total":N,"stale":N,"cold":N,"active":N,"ts":"..."} — each review
• {"event":"edit","file":"...","registry_count":N,"ts":"..."} — every agent edit (hook adapter only)
• {"event":"feedback","file":"...","result":"pass|fail","ts":"..."} — every quality-check fire (hook adapter only)
• {"event":"session","registry_count":N,"adr_count":M,"ai_authored_count":K,"ts":"..."} — start of each session (hook adapter only)

Timestamps are ISO-8601 UTC.

3. Compute the tripwires

Filter to the last 7 days. Then compute what the available events support:

• Captures / reviews — counts of event:register and event:review.
• AI-authored share — share of register events with ai_authored:true.
• Edits / sessions (hook adapter only) — counts of event:edit and event:session.
• Registry growth (hook adapter only) — last registry_count minus first.
• Feedback pass rate (hook adapter only) — count(result:pass) / count(event:feedback).
• FAIL → PASS rate (hook adapter only) — for each feedback with result:fail, look at the next feedback for the same file; count those that flipped to pass; divide by total fails. Below 50% means the agent isn't reliably acting on hook output — the architectural alarm bell.

If there are fewer than 5 data points in the window, say "need more data" and skip the verdict.

4. Report

One screen. No padding. Use → and ↑/↓ for trends. Mark adapter-only rows as n/a (skills-only) when those events are absent. Example shape:

debt-ops metrics — last 7 days
─────────────────────────────────
captures        : 7
reviews         : 2
ai-authored     : 57%

edits           : n/a (skills-only)
feedback ran    : n/a (skills-only)

verdict: ok

End with one judgment line:

• ok — captures >0 (and, when available, fail→pass rate ≥50%).
• investigate: — name the specific tripwire that tripped.

Don't

• Don't write to the log.
• Don't compute metrics not listed above.
• Don't report adapter-only metrics as 0 on a skills-only tool — mark them n/a.
• Don't guess at health when data is thin — say "need more data" instead.