/doctor

name: doctor
description: >
  Run a read-only hygiene + documentation audit on the current repo.
  TRIGGER when the user says "is this repo healthy", "check hygiene",
  "audit this repo" (when they mean inspect, not remediate), "what's
  drifted", "run doctor", "run a health check", "audit docs", "check
  for doc drift", "what's broken in this project", "are the hooks
  still installed", "/nyann:doctor".
  Do NOT trigger on "fix this repo" / "remediate" / "bring it into
  compliance" — those are retrofit (audit + fix). doctor
  reports, never writes. Do NOT trigger on "what does this repo do"
  (that's a docs pointer, not a hygiene audit).

doctor

Read-only audit. Never mutates the filesystem. Wraps `bin/doctor.sh`, which internally runs `bin/retrofit.sh --report-only`.

1. Resolve the profile

`doctor.sh` requires `--profile <name>`. The skill's job is to pick the right one without pestering the user:

1. Look for a `.nyann/profile` or equivalent profile hint in the repo. 2. If the repo's CLAUDE.md declares an active profile, use that. 3. If neither exists, ask the user which profile to audit against (`default`, `nextjs-prototype`, `python-cli`, or any user/team profile they've installed). Don't silently pick `default` — the audit is only meaningful against an intended baseline.

2. Invoke

bin/doctor.sh --target <cwd> --profile <name> [--json] [--scope <csv>]

`--profile` takes a **bare profile name** (e.g. `python-cli`, `nextjs-prototype`), not a filesystem path. The script resolves the name to the profile JSON internally.

Pass `--json` when the user says "machine-readable", "as JSON", "pipe this", or similar — otherwise emit the human-readable report.

Pass `--scope <csv>` when the user wants to inspect only a subset of the audit — e.g. "just check my docs", "are my hooks healthy". Accepts any of `docs`, `hooks`, `branching`, `gitignore`, `editorconfig`, `github`, `history`, `all`, comma-separated. When narrower than `all`, the rendered output gains a `Scope: <csv>` line and `--persist` is auto-disabled (a partial-scope health score would corrupt the trend series in `memory/health.json`).

3. Interpret the exit code

| Code | Meaning | What to tell the user | |---|---|---| | 0 | clean | "No drift. Hygiene and docs look healthy." | | 4 | warnings only | "Not failing, but some things have drifted. Here's the list." Offer to remediate via `retrofit`. | | 5 | critical | "Missing required files or broken internal links. Run `retrofit` to fix." |

4. Sections in the report

The output has several blocks. When the user asks "what does each section mean?", explain in terms of the repo, not nyann internals:

• **MISSING:** files the profile expects but the repo lacks (e.g. no

`.husky/pre-commit` when the profile declares husky hooks).

• **MISCONFIGURED:** files present but content doesn't match (e.g. a

`.husky/pre-commit` exists but doesn't actually run the expected linter).

• **NON-COMPLIANT HISTORY:** last N commit subjects that don't match

Conventional Commits. Informational — nyann never rewrites history.

• **DOCUMENTATION:** CLAUDE.md size vs budget, internal link resolution,

MCP link reachability (when MCP connectors are available), orphan files under `docs/` / `memory/`, and misplaced docs (files at non-canonical paths that could be reorganized via retrofit).

• **GITHUB PROTECTION:** branch protection per strategy, tag-protection

rulesets (when `.github.tag_protection_pattern` is declared in the profile), CODEOWNERS-required gate (when a CODEOWNERS file exists or `.github.require_code_owner_reviews=true`), and repo-security settings (Dependabot, secret scanning, push protection, code scanning). Soft-skips when `gh` is missing or unauthenticated. Driven by `bin/gh-integration.sh --check` under the hood. Critical drift here bumps the exit code to 5; warn drift bumps it to 4.

• **DOC STALENESS:** doc files under `docs/` whose correlated source

paths have changed substantially since the doc itself was last touched. Heuristic-based (`bin/docs-staleness.sh`); thresholds configurable via the profile (`documentation.staleness_threshold_*`). Informational — never affects exit code.

• **PUBLIC-DOC DRIFT:** README/CONTRIBUTING/SECURITY/docs/*.md scanned

for version-ref drift (semver older than latest tag), broken markdown link targets, missing `npm run` / `make` script references, and count-claim drift (opt-in per profile). Driven by `bin/docs-drift-scan.sh`. Critical/high findings escalate the exit code (mirrors GitHub protection); medium/low are advisory.

• **IAC DRIFT:** IaC source (`*.tf`, `Chart.yaml`, `Pulumi*.yaml`,

`*.tfvars`, Ansible vars) scanned for committed secrets (critical), unpinned module refs / providers / deps (high), missing lockfiles and Helm `appVersion` lag (medium). Filesystem + git only — no `terraform plan`, no cloud calls. Driven by `bin/iac-drift-scan.sh`, gated per profile via `iac.drift_check.{enabled, unpinned_refs, missing_lockfile, secrets_in_vars, version_lag}`. Critical/high findings escalate the exit code (mirrors public-doc drift); medium/low are advisory. Silent on non-infra repos. Like public-doc drift, this is score-isolated — it shapes the exit code but not the numeric health score.

The protection block respects nyann's gh-best-effort invariant — it never prompts for credentials and never blocks the audit. When `gh` isn't reachable, the section reports `skipped` and contributes no drift to the exit code.

5. Surface health trend (when available)

After showing the audit report, check whether `memory/health.json` exists in the target repo. If it does:

1. Run `bin/health-trend.sh --target <cwd> --last 10`. 2. Show the sparkline and summary: "Health trend: ▃▄▅▆▇ — 72→85 over last 10 checks (↑ improving)." 3. If any `category_deltas` show worsening (delta < 0 in the breakdown), call them out: "⚠ `missing` got worse (−3 over the window)." 4. If