readme-doctor

# readme-doctor Most README problems aren't typos or missing sections — they're 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. This skill audits a README against patterns that consistently correlate with maintainer outcomes (stars, contributor onboarding, issue quality) and produces a punch list a maintainer can act on in an afternoon. The skill's quality comes from the **rubric being grounded in the repo's actual audience and category**, not from a generic checklist. A README for a 50K-star framework needs different things than a personal-project utility. ## Phases 1. **Discovery** — pick operating mode (Auto / Semi-auto / Manual, §1.1), input the README, infer the repo's category and audience from the scan, agree on what "good" looks like for this specific repo. 2. **Audit** — walk the rubric, score each criterion, gather evidence (cite line numbers). 3. **Punch list** — prioritize findings P0 (blocking) / P1 (high-leverage) / P2 (nice-to-have), each with a one-line fix. 4. **Optional output** — read-only summary by default; on user request, open a PR with concrete edits. --- ## Phase 1 — Discovery ### 1.1 Operating mode (ask first) Same three modes as `repo-visuals` — Auto, Semi-auto (recommended), Manual. Use `AskUserQuestion`. Mode affects how many decisions are silent vs surfaced; it does not skip rubric checks. ### 1.2 Input User may p...