Repo Doctor

Repo Doctor

Scores a repository against the agentic-quality doctrine — the cross-repo standard in rules/agentic-quality.md for code, comments, docs, and structure that a cold agent session can navigate. The rule says what good looks like; this skill measures a repo against it and maps each gap to its fix.

Read-only. The scorer never writes; remediation is always a separate, deliberate step.

Quick start

python scripts/repo-doctor.py                          # audit cwd, human panel
python scripts/repo-doctor.py --repo X:/path/to/repo   # audit another repo
python scripts/repo-doctor.py --json | jq .data.grade  # machine-readable
python scripts/repo-doctor.py --strict                 # CI gate: exit 10 below B

Six dimensions, 0–5 each, weighted into a letter grade:

Full rubric — what each check means, thresholds, and the fix for every finding: references/scoring-rubric.md.

Audit workflow

1. Run the scorer on the target repo. On cp1252/plain terminals it degrades to ASCII automatically; nothing is written.
2. Read findings top-down — they're sorted crit → warn → info. Facts (monster-file list, pairing ratio, entry-doc age) ride in --json under .data.facts.
3. Verify before acting. The scorer is heuristic: a flagged 900-line file may be a justified single-writer module (then it needs the guard comment + section map + gate, not a split); a "stale" AGENTS.md may describe code that genuinely didn't change. Confirm each finding against the repo before proposing work.
4. Remediate via the owning skill (below) — repo-doctor diagnoses, it does not operate. Batch fixes into small commits: entry-doc fixes first (highest leverage), then indexes, then guard comments, then splits.
5. Re-run to confirm the grade moved. For fleets, loop the scorer over repo roots with --json and tabulate grades.

Remediation map — who owns each fix

Boundary: repo-doctor audits repo-level conventions; techdebt scans code-level debt; review/code-review judge diffs. Don't blur the three.

Interpreting the two entry-doc questions

AGENTS.md vs CLAUDE.md — AGENTS.md is the single source of truth (open standard, read by all agent tooling). CLAUDE.md is legitimate only as a pointer or as Claude-specific deltas maintained in lockstep. The scorer flags apparent duplication; the decision tree and the one known-good dual-file pattern are in references/entry-docs.md.

Nested entry docs — nest only where a subsystem has its own contract (design-system package, determinism-bound engine, per-tool CLI); root file carries an ownership table linking each. Anatomy, length budgets, Landmines guidance, freshness discipline: same reference.

Monorepos

For large multi-subsystem repos the audit shifts: the root entry doc is judged as a router (invariants + ownership table), each contracted package needs its own entry doc and check, and cross-package invariants need mechanical gates, not prose. The full playbook — boundaries, navigation aids, extraction signals, parallel-agent (worktree) interplay, and the split-the-repo decision — is references/monorepo-structure.md. Run the scorer per-package as well as at root; a healthy root with a failing core package is the common monorepo blind spot.

Resources