mostafa-drz/docs-doctor

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=<name> → 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=<name>: Read ~/.claude/skills/docs-doctor/templates/<name>.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 <repo>/.docs-doctor/ if missing. Ensure it's in .gitignore (offer to add if not).
2. Write markdown report to <repo>/.docs-doctor/report-<YYYY-MM-DD-HHMM>.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 <repo>/.docs-doctor/report-<ts>.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/<YYYY-MM-DD-HHMM>.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> mode on <N> files
  Errors: X · Warnings: Y · Info: Z
  Top issues: <one-liners for top 3>
  Report: .docs-doctor/report-<ts>.md
  Fixes applied: <count>  (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/<name>.md. Each template declares default flags as YAML frontmatter:

---
name: <template-name>
description: <one-liner>
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=<name> 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

# /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/<YYYY-MM-DD-HHMM>.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:

   ## <session slug> — <YYYY-MM-DD>
   - Mode: <mode>
   - Useful categories: <list>
   - Noisy categories: <list>
   - Severity calibration: <answer>
   - Auto-fix accuracy: <answer>
   - Output preference: <answer>
   - Signal: <one-line generalisation of the takeaway>
   

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 <signal>. 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 "<rule>" — contradicted by <session-1>, <session-2>.

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.