/repo-doctor

name: repo-doctor
description: >
  USE WHEN inheriting a legacy repo, when user asks "what's missing for
  AI-first work here?", "is this repo agent-ready?", "audit my repo",
  "is anything out of sync with the code?", or when the
  bare-repo-nudge / cheatsheet hook suggests a checkup. Read-only
  AI-readiness audit — scores ~24 dimensions across Foundation
  (AGENTS.md / CLAUDE.md / per-dir AGENTS.md), Why (ADRs + session
  logs), What (GLOSSARY.md + architecture.yml), In-code (AIDEV
  anchor density + overdue), Hygiene (tests, LOC ratio, structured
  logging, .gitignore, README, manifest, CI config, .env.example,
  repro env, secret guardrails), AND Sync (code↔docs
  drift: arch-map vs disk, glossary vs code, per-dir AGENTS.md vs
  dir activity, CHANGELOG vs version, README slash-refs). Each gap
  → concrete fix action. Reports a readiness level L0-L4 (gated, ADR
  0012) + local score trend; --fix walks the top gaps; --semantic adds
  an advisory truthfulness review via the readiness-reviewer subagent.
  Differentiated from /init-repo (one-shot bootstrap, writes files)
  and /stack-check (time-based freshness) — this skill answers
  completeness, drift AND (opt-in) truthfulness in one pass. See ADR
  0006 (initial design), ADR 0007 (Sync addition), ADR 0012 (levels +
  deterministic core) for rationale.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Task
  - Bash(git rev-parse:*)
  - Bash(git ls-files:*)
  - Bash(git log:*)
  - Bash(test:*)
  - Bash(ls:*)
  - Bash(wc:*)
  - Bash(stat:*)
  - Bash(date:*)
  - Bash(find:*)
  - Bash(tail:*)
  - Bash(grep:*)
  - Bash(head:*)
  - Bash(cat:*)
argument-hint: "[--score] [--json] [--fail-on missing|todo|stale|semantic] [--scope foundation|why|what|incode|hygiene|sync|all] [--semantic] [--fix N] [--quiet] [--no-history] [--no-recommend]"

/repo-doctor

What it does

Reads the current repo and answers the question prose `AGENTS.md` doesn't cheaply answer per session: **what's missing for AI-first work here?** Output is a Markdown report scored across ~24 dimensions, with a concrete fix action per gap (often "invoke `/X`").

Read-only on the repo; writes only local state (see Hard rules). The skill is an audit, not a bootstrap.

This skill complements three existing ones with clean differentiation:

| Skill | Question it answers | |-------|---------------------| | `/init-repo` | "Set this fresh repo up." *(writes files)* | | `/stack-check` | "What I have — is it stale?" *(freshness audit)* | | `/repo-doctor` | "What I *don't* have — what's missing?" *(presence + drift + opt-in truthfulness; guided handoff via `--fix`)* | | `/security-review` | "Is this diff safe to commit?" *(orthogonal — code-level scan)* | | `/dynamic-check` | "Do the declared commands actually run?" *(executes code — opt-in, separate skill per ADR 0013)* |

When to invoke

• Inheriting an existing repo (legacy or new-to-you) and wondering

what's missing for AI-first development.

• After `/init-repo` ran, to see what *else* the bootstrap didn't

cover.

• Periodically (every few months) to catch drift.
• When the `skill-cheatsheet` SessionStart hook suggests a checkup.
• Before pitching a "make this repo agent-ready" piece of work to a

client — output is a ready-made list of concrete improvements.

Do NOT invoke for:

• Day-to-day "is this stale" checks — that's `/stack-check`.
• Security audit of changes — that's `/security-review`.
• One-shot setup — that's `/init-repo`.

Output format

# Repo Doctor — <repo-name> — <YYYY-MM-DD>

## Summary

✅ 11 pass · ⚠️ 8 attention · ❌ 5 missing · **Score: 63/100** ·
**Level: L1 Instructed (L2 blocked by Hygiene: deficit 2.5 > 2.0)**

## Foundation (loaded every session)

| Check | Status | Fix |
|---|---|---|
| AGENTS.md (root) | ✅ 4.2 KiB | — |
| CLAUDE.md (one-line `@AGENTS.md` import) | ✅ present | — |
| Per-dir AGENTS.md | ⚠️ 3 source dirs >500 LOC missing | drop `templates/AGENTS.md.example` into `src/billing/`, `src/auth/`, `src/api/` |

## Why (load-bearing decisions)

| Check | Status | Fix |
|---|---|---|
| ADRs (docs/adr/) | ❌ directory absent | next load-bearing decision → invoke `/adr-new` |
| Session logs (docs/sessions/) | ⚠️ last entry 47 days old | end of next substantial session → `/session-log` |

## What (domain + structure)

| Check | Status | Fix |
|---|---|---|
| GLOSSARY.md | ❌ missing | invoke `/glossary-init` (auto-surfaces candidates) |
| architecture.yml | ❌ missing | invoke `/arch-map` |

## In-code discoverability

| Check | Status | Fix |
|---|---|---|
| AIDEV anchors | 12 anchors / 4823 LOC = 2.5/KLOC | typical (target 1–5/KLOC) |
| Overdue anchors | ⚠️ 2 past deadline | see `/stack-check` for detail |

## Engineering hygiene

| Check | Status | Fix |
|---|---|---|
| Tests present | ✅ 28 test files | — |
| Test/source LOC ratio | ⚠️ 0.18 (target 0.5–1.0) | `src/billing` largest, fewest tests — add coverage there first |
| Structured logging | ❌ `print(` 14×, no structured logger detected | invoke `/log-structured` |
| .gitignore (claude-leverage state) | ✅ present | — |
| README quickstart | ✅ present | — |
| Language manifest | ✅ pyproject.toml | — |
| CI config | ✅ .github/workflows/ci.yml | — |
| .env.example | ⚠️ env usage in 3 files, no example | add `.env.example` with the required keys |
| Reproducible env | ✅ poetry.lock (lockfile-level) | — |
| Secret guardrails | ⚠️ only `.env` gitignored | add gitleaks to pre-commit or CI |

## Sync (code ↔ docs drift)

| Check | Status | Fix |
|---|---|---|
| `architecture.yml` ↔ disk | ⚠️ 2 drifts: `public_surface: [LegacyClient]` not in code; `src/old/` orphan (on disk, not in YAML) | invoke `/arch-map` to refresh |
| `GLOSSARY.md` ↔ code | ⚠️ term `Lead` no longer ref'd in code (last seen 4 months ago) | edit `GLOSSARY.md` or `/glossary-init --add` |
| Per-dir `AGENTS.md` staleness | ✅ all in sync | — |
| `CHANGELOG` ↔ version | ❌ `plugin.json` says 1.6.0, `CHANGELOG` top is 1.5.0 | add a `## [1.6.0]` entry to `CHANGELOG.md` |
|