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:

Dimension	Measures	Weight
entry_docs	AGENTS.md/CLAUDE.md present · Landmines section · length budget (~250 lines) · freshness in commits-since-touched	2.0
docs_health	README · docs/ index when >6 files · ghost links in the index	1.5
comments	contract blocks on the largest source files · section markers in files >400 lines	2.0
structure	monster files (>800 warn, >1500 crit; generated exempt) · repo-root junk	2.0
enforcement	tests · CI · single check entry point · invariant gate scripts	1.5
doc_pairing	fraction of recent feat/fix commits touching a *.md in the same commit	1.0

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

Finding	Owner
Missing/weak AGENTS.md, multi-platform doc mess	doc-scanner (generate/consolidate), template: assets/AGENTS-template.md
Missing docs index	Write from assets/docs-index-template.md
Monster file needs splitting	refactor-ops (extract-module patterns, circular-dep cautions)
Monster file is justified	Guard comment + section map + a scripts/check-* invariant gate (pattern in references/comment-doctrine.md)
Missing/weak comments	references/comment-doctrine.md — contract blocks, WHY-only, guard comments, citations
Decisions undocumented	adr-ops
Stale PLAN/roadmap	project-planner
Code-level debt (duplication, dead code, security)	techdebt — deliberately NOT scored here
New repo from scratch	scaffold + the two templates in assets/

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

Resource	What it owns
scripts/repo-doctor.py	The scorer: six dimensions, findings, grade; --json envelope claude-mods.repo-doctor/v1; --strict CI gate
references/scoring-rubric.md	Every check: what it measures, threshold, why, and the fix
references/comment-doctrine.md	Contract blocks, WHY-only inline, guard comments, section markers, format-at-site, citations — with good/bad examples
references/entry-docs.md	AGENTS.md anatomy + Landmines, AGENTS-vs-CLAUDE decision, nesting policy, freshness discipline
references/monorepo-structure.md	Structuring very large monorepos for agentic development
assets/AGENTS-template.md	Entry-doc skeleton with mandatory Landmines section
assets/docs-index-template.md	docs/00_INDEX.md skeleton with the two anti-rot rules baked in