--- name: docs-doctor description: >- Audits a repository's documentation for unused docs, wrong details, missing coverage, inaccurate data, broken structure, and writing best-practices. Generates a markdown report (HTML optional) with severity ratings. Supports modes (main, comprehensive, focused, quick), per-profile templates (open-source, internal-docs, blog, nextjs-app), optional --fix for low-risk auto-fixes (broken links, frontmatter, stale dates), and a /feedback subcommand that promotes recurring signals into Learned defaults. Use when you want a "docs doctor" pass on a repo before a release, after a refactor, or as a recurring DX health check. argument-hint: "[--mode=] [--from-template=] [--category=] [--scope=] [--fix] [--html] [help|config|reset|feedback|templates|resume]" disable-model-invocation: true allowed-tools: - AskUserQuestion - Read - Write - Edit - Glob - Grep - Bash - WebFetch --- # Docs Doctor Audit a repository's documentation like a doctor: triage what's missing, wrong, stale, structurally broken, or written badly. Produce a severity-ranked report; optionally apply low-risk fixes. Configurable by mode, scope, and template profile. Learns from your feedback over time. ## Preferences _On startup, use the `Read` tool to load `~/.claude/skills/docs-doctor/preferences.md`. If missing, treat as "no preferences set" and continue with Defaults below._ ## Context _On startup, use the `Bash` tool to detect: git repo root (`git rev-parse --show-toplevel`), current branch, and whether `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` is present (for code-doc check selection). Use the `Glob` tool to list `**/*.md`, `**/*.mdx`, and any `CLAUDE.md` / `AGENT.md` files. Skip any detection step that fails — do not abort._ ## Command routing Check `$ARGUMENTS`: - **`help`** → display help, then stop - **`config`** → interactive setup, then stop - **`reset`** → delete `~/.claude/skills/docs-doctor/preferences.md`, `feedback-journal.md`, `sessions/`, `resume-state.md`, confirm, stop - **`feedback`** → run the feedback flow (see § Feedback & learning), then stop - **`templates`** → list available templates from `~/.claude/skills/docs-doctor/templates/`, then stop - **`resume`** → if `resume-state.md` exists, continue the last interrupted run; else say `No session to resume.` - **`--from-template=`** → load template, merge with flags, run - **anything else** (including empty) → run the audit ### Help ``` Docs Doctor — audits repository documentation and produces a severity-ranked report Usage: /docs-doctor Interactive audit (asks for mode) /docs-doctor --mode=main Default audit (6 core categories) /docs-doctor --mode=comprehensive Adds link-check, code-doc drift, freshness vs git /docs-doctor --mode=quick Smoke check (broken links + frontmatter + stale dates) /docs-doctor --mode=focused --category=missing-docs Run a single category /docs-doctor --from-template=nextjs-app Use a preset profile /docs-doctor --scope=markdown,frontmatter Limit doc types audited /docs-doctor --fix Apply low-risk auto-fixes after report /docs-doctor --html Also emit interactive HTML report /docs-doctor templates List available templates /docs-doctor feedback Rate the most recent session /docs-doctor resume Continue an interrupted run /docs-doctor config Set preferences /docs-doctor reset Clear preferences + journal + sessions /docs-doctor help This help Categories (for --category): unused-docs, wrong-details, missing-docs, inaccurate-data, missing-structure, best-practices Current preferences: (loaded from ~/.claude/skills/docs-doctor/preferences.md) ``` ### Config Use `AskUserQuestion` to collect: - **Q1** — Default mode: `main` / `comprehensive` / `quick` - **Q2** — Default scope (multiSelect): markdown, frontmatter, code-docs, agent-instructions - **Q3** — Default output: markdown / html / both - **Q4** — Severity threshold (what's shown in report): `info+` / `warn+` / `error-only` - **Q5** — Fix policy: `never` (report only) / `interactive` (ask per fix) / `auto-low-risk` (apply allowed fixes without prompt) - **Q6** — Ignored path globs (comma-separated, e.g. `node_modules/**, vendor/**, .next/**`) Write to `~/.claude/skills/docs-doctor/preferences.md` in the three-tier format (see § Preferences file format below). ### Reset Use the `Bash` tool to delete the skill's state files: - `~/.claude/skills/docs-doctor/preferences.md` - `~/.claude/skills/docs-doctor/feedback-journal.md` - `~/.claude/skills/docs-doctor/sessions/` - `~/.claude/skills/docs-doctor/resume-state.md` Confirm: `State cleared. Using defaults next run.` ## First-time detection If `preferences.md` does not exist: > First time using `/docs-doctor`? Run `/docs-doctor config` to set defaults, or continue with sensible defaults (mode=main, scope=markdown+frontmatter+agent-instructions, output=markdown, severity=warn+, fix=never). Then proceed. --- ## Defaults - mode: `main` - scope: `markdown, frontmatter, agent-instructions` - output: `markdown` - severity threshold: `warn+` - fix policy: `never` - ignored paths: `node_modules/**, vendor/**, dist/**, build/**, .next/**, .turbo/**, coverage/**` ## Workflow ### Step 0 — Load learning context 1. `Read` `~/.claude/skills/docs-doctor/preferences.md` — apply Defaults / Profile / Learned in that order (Learned wins). 2. `Read` `~/.claude/skills/docs-doctor/feedback-journal.md` — note any recurring `Signal:` lines to bias severity and category emphasis. 3. If either file is missing, continue silently with Defaults. ### Step 1 — Resolve run config 1. Parse flags from `$ARGUMENTS`. 2. If `--from-template=`: `Read` `~/.claude/skills/docs-doctor/templates/.md`, merge template values under flags (flags override template). 3. If `--mode` is unset and not in preferences: use `AskUserQuestion` to pick mode. Pre-select the `Learned` mode if one exists, else `main`. 4. If `--category` is set but `--mode` is not `focused`, set `--mode=focused`. 5. Compute final config object: `{ mode, scope, output, severity_threshold, fix_policy, ignored_paths, categories, target_files }`. ### Step 2 — Discover docs 1. Use `Glob` to enumerate candidate files based on scope: - `markdown`: `**/*.md`, `**/*.mdx` - `frontmatter`: subset of markdown that starts with `---` - `code-docs`: `**/*.{ts,tsx,js,jsx,py,rs,go}` (filter by detected project type) - `agent-instructions`: `**/CLAUDE.md`, `**/AGENT.md`, `**/AGENTS.md` 2. Remove anything matching `ignored_paths`. 3. If zero files: stop with `No docs found in scope. Check --scope or --ignored.` ### Step 3 — Run checks For each enabled category, run the corresponding checks defined in `reference/checks.md`. Categories enabled by mode: | Mode | Categories | |---------------|-----------------------------------------------------------------------------------------------------| | quick | wrong-details (broken-links subset), missing-structure (frontmatter only), inaccurate-data (dates) | | main | all 6 core: unused-docs, wrong-details, missing-docs, inaccurate-data, missing-structure, best-practices | | comprehensive | main + freshness-vs-git, external-link-check, code-doc-drift, onboarding-flow, search-ability | | focused | only the category passed via `--category` | Each check returns findings with: `{ file, line?, category, severity, rule, message, suggested_fix? }`. Run checks in parallel where independent (e.g. file-level reads can batch). Use `Grep` for pattern checks across files, `Read` for per-file inspection. Defer external network checks (`WebFetch`) to last; cap to 25 URLs per run unless `--mode=comprehensive`. ### Step 4 — Score and rank 1. Apply severity rules from `reference/severity.md`. 2. Filter out findings below `severity_threshold`. 3. Sort by severity (error → warn → info), then by category, then by file. 4. Compute summary counts: total, by severity, by category. ### Step 5 — Write report 1. Create `/.docs-doctor/` if missing. Ensure it's in `.gitignore` (offer to add if not). 2. Write markdown report to `/.docs-doctor/report-.md` with sections: - Header (mode, scope, severity threshold, ignored paths) - Executive summary (counts, top 5 issues) - Findings grouped by category, each with severity badge, file:line, rule, message, suggested fix - Fix plan (if `--fix` requested) 3. If `--html` or output preference is `html`/`both`, also write `/.docs-doctor/report-.html` — single-file HTML with chip filters per severity/category (matches Decision Report pattern: hero summary, inline JS filters, gray-out-on-change). 4. Save session log: `~/.claude/skills/docs-doctor/sessions/.md` with: config used, counts, top findings, decisions taken, follow-ups. ### Step 6 — Optional `--fix` pass If `--fix` was passed and `fix_policy ≠ never`: 1. Filter findings to those with `suggested_fix` AND rule in the auto-fixable allowlist: - `broken-internal-link` - `frontmatter-missing-required` (only safe defaults) - `frontmatter-key-disorder` - `stale-last-updated` 2. If `fix_policy = interactive`: for each fix, show diff via `AskUserQuestion` (Apply / Skip / Apply all remaining). 3. If `fix_policy = auto-low-risk`: apply all allowlisted fixes without prompting; record them in the report. 4. Use `Edit` for file changes. Never `Write` over a file unless creating a new doc the user approved. 5. After all fixes, re-run only the touched checks to confirm. 6. Append a "Fixes applied" section to the report. Destructive or wide-blast fixes (deleting whole docs, rewriting paragraphs) are never auto-applied — always require explicit confirmation. ### Step 7 — Final summary Print to chat: ``` Docs Doctor: mode on files Errors: X · Warnings: Y · Info: Z Top issues: Report: .docs-doctor/report-.md Fixes applied: (if --fix) ``` Then ask via `AskUserQuestion`: - **Open report?** Yes / Open in browser (HTML) / No ### Step 8 — Invite feedback End with one line: > Run `/docs-doctor feedback` — even one rating helps me sharpen severity and category emphasis for this repo. --- ## Templates Templates live in `~/.claude/skills/docs-doctor/templates/.md`. Each template declares default flags as YAML frontmatter: ```yaml --- name: description: inputs: { mode, scope, severity_threshold, fix_policy } tasks: [ordered-check-keys] constraints: [rules] ignored_paths: [globs] postProcesses: [open-report, append-to-changelog] --- ``` Loading: when `--from-template=` is passed, `Read` the file, parse the frontmatter, merge values under the workflow config (CLI flags still win). Shipped templates: - `open-source.md` — emphasises README, CONTRIBUTING, LICENSE, public API docs - `internal-docs.md` — emphasises onboarding, runbooks, ADRs - `blog.md` — content-first: frontmatter completeness, broken images, draft markers, dates - `nextjs-app.md` — Next.js conventions: route-level docs, app/page coverage, CLAUDE.md sanity To add a template: drop a new file in `templates/` matching the schema above. List them via `/docs-doctor templates`. ## Preferences file format ```markdown # /docs-doctor preferences Updated: YYYY-MM-DD ## Defaults - mode: main - scope: markdown, frontmatter, agent-instructions - output: markdown - severity_threshold: warn+ - fix_policy: never - ignored_paths: node_modules/**, dist/**, .next/** ## Profile (optional — edit freely) - (user-editable lines: bias which categories matter, custom severity per repo) ## Learned - (populated from feedback; promoted after 3+ consistent signals) ``` ## Feedback & learning When invoked as `/docs-doctor feedback`: 1. Find the most recent `~/.claude/skills/docs-doctor/sessions/.md`. If none, say `No recent session found.` and stop. 2. Print a one-line summary of that session (mode, file count, top issues). 3. Ask via `AskUserQuestion` in one batch (4 questions): - **Category usefulness** (multiSelect): which categories were signal vs noise? - **Severity calibration**: too strict / about right / too lenient - **Auto-fix accuracy** (only if `--fix` was used): all correct / some wrong / no fixes applied - **Output format preference**: keep markdown / prefer HTML / want both / want shorter summary 4. Append to `~/.claude/skills/docs-doctor/feedback-journal.md`: ``` ## — - Mode: - Useful categories: - Noisy categories: - Severity calibration: - Auto-fix accuracy: - Output preference: - Signal: ``` 5. **Promotion rule:** when 3+ sessions share the same `Signal:`, promote it to `## Learned` in `preferences.md` and tell the user once: `Noticed you consistently . Saved as standing default.` 6. **Drift correction:** when a `Learned` rule is contradicted in 2 newer sessions, demote it back to inactive and log the demotion in the journal as `Signal: demoted "" — contradicted by , `. ## Principles 1. **Manifest first** — every audit run produces a report file; the conversation is the index, not the source of truth. 2. **Graceful degradation** — missing preferences / journal / templates never block a run; fall back to Defaults silently. 3. **Learn quietly** — promote a rule only after 3+ consistent signals; mention once, never twice. 4. **No fabricated structure** — if scope or mode is ambiguous, ask via `AskUserQuestion` rather than invent. 5. **Destructive actions need confirmation** — auto-fix is gated to a strict allowlist; anything else asks first. 6. **Stop means stop** — if the user halts mid-audit, write `resume-state.md` with progress so `/docs-doctor resume` can continue. 7. **Skill orchestrates, does not re-judge** — when fixing, preserve user-authored content; never rewrite prose silently. 8. **Detail lives in reference/** — keep this SKILL.md under 500 lines; deep check definitions live in `reference/checks.md` and `reference/severity.md`.