repo-doctor diagnoses README "shape problems" — the hero never lands, install-to-first-success buries the lede, the "what is this" sentence assumes prior context, the badge row is louder than the content — and produces a prioritized punch list a maintainer can act on in an afternoon. Read-only by default; opens a PR only when the user explicitly asks. Key features: - 9-criterion rubric scored 1–5 with cited line numbers and one-line fixes - Rubric weighting adapts to inferred repo category: library, CLI, framework, app, spec, or personal project - Audience inference (working developers, newcomers, maintainers, mixed) — catches the most common shape problem: README pitched at the wrong audience for its category - Punch list grouped P0 (blocking) / P1 (high-leverage) / P2 (nice-to-have) - Three operating modes (Auto / Semi-auto / Manual) with the same conversational density tradeoff as repo-visuals - Optional upstream PR with the punch list as the description; never auto-applies edits