--- name: check description: Scan the project for stale and bloated documentation and write a hygiene report. Runs the deterministic scanner, dispatches a Sonnet subagent to classify only the signal-bearing candidates, finalizes/validates the machine report deterministically, then writes the report pair and stamps `last_check`. Invoked by `/os-doc-hygiene:check [--scope ] [--category ]`. --- # Hygiene Check Skill Orchestrates one documentation-hygiene check: **scan → classify → finalize → validate → write → stamp**. The scan, finalize, validation, write, and stamp are deterministic scripts (invariant #6 — no model). Only the per-file classification is a model step, dispatched to a **Sonnet** subagent. All scripts live under `${CLAUDE_PLUGIN_ROOT}/scripts/`. Run them with `python3` from the user's project directory (`cwd`), which is where the project root is resolved. Use the session scratchpad directory for all intermediate artifacts — **never** write to `.dochygiene/` until the validated write step. > **Precondition:** this skill requires the `CLAUDE_PLUGIN_ROOT` environment > variable to be set (Claude Code sets it at runtime). Every script path and the > Step 6/7 `python3 -c` invocations resolve against it; if it is unset, abort the > run rather than guessing a path. > Pick a scratch dir once and reuse it for the whole run, e.g. > `SCRATCH="$(mktemp -d)"`. The scan artifact, the subagent proposals, and the > *unvalidated* report pair all live there. ## Arguments Passed through from `/os-doc-hygiene:check`: - `--scope ` — narrow the scan. A glob (contains `*`) maps to the scanner's `--globs`. A **bare path** does NOT map cleanly to a `--globs` value (the scanner's glob matcher is unreliable for mid-pattern `**`), so for a bare path run the scanner unscoped (default `**/*.md`) and then **drop shortlist and `signals` entries whose path does not start with `/`** before Step 2. Record the effective scope in your Step 8 summary. - `--category ` — filter which **entries** are produced. The scanner is **category-agnostic** — a signal like `version_skew` can map to several classes/subtypes — so this filter is applied **after classification**, at the entry stage (Step 3.5), NEVER at candidate selection. `class` is `stale` or `bloat`; `subtype` is one of the closed enum values below. If no arguments are given, the scan uses defaults (`**/*.md`, default excludes). ## Workflow ### Step 0 — (D / M-GATE) Gitignore preflight Check whether `.dochygiene/` is already git-ignored, and offer to add it if not. ```bash ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || ROOT="" ``` Three cases: - **No git root** (`ROOT` empty — project is not a git repo): skip silently. `resolve_project_root` falls back to cwd; no `.gitignore` offer is meaningful. - **Already ignored** (`git -C "$ROOT" check-ignore -q .dochygiene` exits `0`): silent no-op. Proceed to Step 1. - **Not ignored** (exit `1`): present the one-line offer: > `doc-hygiene` stores its state and report under `.dochygiene/` at the project root. Per invariant #3, this directory should be gitignored so it doesn't appear as untracked in your repo. Shall I append `.dochygiene/` to `/.gitignore`? (yes/no) **Only on explicit confirmation ("yes"):** append as follows — never reorder or rewrite existing entries: ```bash if [ -s "$ROOT/.gitignore" ] && [ -n "$(tail -c1 "$ROOT/.gitignore")" ]; then printf '\n' >> "$ROOT/.gitignore" fi printf '.dochygiene/\n' >> "$ROOT/.gitignore" ``` (Creates `.gitignore` if absent; appends with a leading newline only when the file is non-empty and doesn't already end in one.) **If the user declines:** proceed without editing. Note that `.dochygiene/` may appear as untracked/dirty in `git status` until ignored. > **Do NOT append without explicit user confirmation.** (Invariant #3.) ### Step 1 — (D) Scan Run the scanner, capturing its stdout artifact to the scratch dir: ```bash python3 "${CLAUDE_PLUGIN_ROOT}/scripts/scanner.py" [--globs ...] > "$SCRATCH/scan.json" ``` - Omit `--globs` when there is no `--scope`. - The scanner auto-resolves the project root from `cwd` and applies default excludes (incl. `.dochygiene/`). Do not pass `--root`. The artifact is `{ project_root, scope_globs, excluded_dirs, files_scanned, shortlist, signals }`. `signals` is an object keyed by project-root-relative path: `{ "": [ { "name": "", "detail": "" }, ... ] }`. ### Step 2 — (D / logic) Select candidates Candidates = **the keys of `signals`** (signal-bearing paths only). Paths that are in `shortlist` but absent from `signals` have **zero signals**: they are **presumptively cleared** — they are NOT read by the model and produce no entries. - Do **NOT** filter candidates by `--category` here. The scanner is category-agnostic; you cannot know a file's class/subtype until the model has read it. `--category` is applied later, at Step 3.5. - (If a bare-path `--scope` was given, the shortlist/`signals` were already narrowed to that prefix in the Arguments step.) - **If there are zero signal-bearing candidates**, skip the model step (Step 3) entirely. Set the proposals array to `[]` and go straight to Step 4 — an empty-entries report is still written and `last_check` is still stamped. ### Step 3 — (M) Classify candidates — **Sonnet subagent** Dispatch ONE subagent (Agent tool) to classify all signal-bearing candidates. Use **Sonnet** (`model: sonnet`). The subagent reads each candidate file and its scanner signals and returns a SLIM proposal per file (judgment only — no computed fields). ``` Agent tool parameters: - subagent_type: "general-purpose" - model: sonnet - description: "Classify doc-hygiene candidates" - prompt: | Read and follow the workflow at: ${CLAUDE_PLUGIN_ROOT}/skills/check/workflows/classify-candidates.md Project root: Classify exactly these candidates (path → scanner signals, verbatim): [For each signal-bearing path, paste: - path: signals: ] Return ONLY the JSON array of proposals specified in the workflow. ``` **LOOP GUARD:** the subagent prompt MUST point to `workflows/classify-candidates.md`, NEVER to this SKILL.md (prevents recursive skill invocation, per the `commit` skill precedent). **SUBAGENT AUTHORIZATION:** the subagent is the executor — authorization is terminal. It MUST NOT re-ask for approval or wait for a confirmation that cannot arrive. If it believes it should not proceed, it MUST return its objection as its final result and stop immediately (REPORT-AND-EXIT). The human confirm gate lives upstream in the orchestrator, never inside the subagent. Wait for the subagent's JSON array. Write it verbatim to `"$SCRATCH/proposals.json"`. **Model escalation:** if the subagent flags a file as low-confidence on a *hard distinction* (stale-vs-bloat; destructive `delete-range` vs a generative rewrite of the same contradicted/superseded content), re-dispatch **only that file** to an **Opus** subagent (`model: opus`) with the same workflow, and substitute its proposal. Do not escalate the whole batch. ### Step 3.5 — (logic) Apply `--category` filter — entry stage If `--category` was given, drop every proposal whose `category` does not match, BEFORE finalizing. This is deterministic orchestrator logic (no model, no script): - `--category stale` / `--category bloat` → keep proposals whose `category.class` equals it. - `--category ` (e.g. `superseded`, `distill`) → keep proposals whose `category.subtype` equals it. Rewrite `"$SCRATCH/proposals.json"` with the filtered array. Files removed here are not errors — they simply produce no entry and will appear under "Cleared" in the human report (`cleared = shortlist − entries`). `report_builder.py` has no `--category` flag; the filter lives here. With no `--category`, pass all proposals through unchanged. ### Step 4 — (D) Finalize via `report_builder.py` Hand the scan artifact and the proposals to the model-free assembler. It fills the four guardrail fields the model must not author (`expected_sha256`, `safety_tier`, `is_destructive`/`is_reversible`, `raw_tokens`) and emits a schema-valid machine report plus a human-report skeleton, writing both to the **scratch** dir: ```bash python3 "${CLAUDE_PLUGIN_ROOT}/scripts/report_builder.py" \ --scan "$SCRATCH/scan.json" \ --proposals "$SCRATCH/proposals.json" \ --out-json "$SCRATCH/report.json" \ --out-md "$SCRATCH/report.md" ``` - Exit `0` — built. (`--out-json`/`--out-md` write files and suppress the stdout bundle, which is exactly what we want for scratch validation.) - Exit `1` — a **malformed proposal**. A structured error is on stderr: `{"error":"malformed proposal","detail":{"index":I,"field":F,"message":M}}`. Map `index` back to the offending candidate, re-prompt the subagent (Step 3) to fix only that proposal (or drop it), rewrite `proposals.json`, and re-run Step 4. - Exit `2` — usage / IO error (bad input path or unreadable JSON). Internal bug: stop and report. For an empty proposals array (`[]`), this still produces a valid empty-entries report — proceed normally. ### Step 5 — (D) Validate BEFORE writing — on the SCRATCH path `StateStore.write_report` deletes the prior report pair *first*, so validating after a write would destroy the last good report (invariant #4). Validate the scratch machine report first: ```bash python3 "${CLAUDE_PLUGIN_ROOT}/scripts/validate_report.py" "$SCRATCH/report.json" ``` - Exit `0` — valid. Proceed to Step 6. - Exit `1` — invalid. The validator prints all violations (each with a `field` path like `entries[2].exact_edit.anchor`). Map each violation back to its entry index, re-prompt the classification subagent (Step 3) to fix **only** the offending proposals — or drop an unfixable entry — rewrite `proposals.json`, re-run Step 4 (finalize) and Step 5 (validate). **NEVER write an invalid report.** Repeat until exit 0. - Exit `2` — usage error (internal bug, e.g. the report file is missing or not JSON). Stop and report. ### Step 6 + 7 — (D) Write report pair (rollover) AND stamp `last_check` Only after Step 5 returns exit 0. `StateStore` has no CLI; do the write **and** the stamp in one `python3 -c` so the `last_check` timestamp is the report's own envelope `generated_at` (design step 7 — same run instant, read back from the validated report, not a fresh `now()`): ```bash python3 -c ' import sys, os, json from datetime import datetime from pathlib import Path sys.path.insert(0, os.environ["CLAUDE_PLUGIN_ROOT"] + "/scripts") from state_store import StateStore, resolve_project_root scratch = os.environ["SCRATCH"] json_blob = Path(scratch + "/report.json").read_text() md_blob = Path(scratch + "/report.md").read_text() report = json.loads(json_blob) store = StateStore(resolve_project_root(Path(os.getcwd()))) store.write_report(json_blob, md_blob) # rollover: keeps exactly one pair store.set_last_check(datetime.fromisoformat(report["generated_at"])) print("wrote .dochygiene/report.json + report.md; last_check=" + report["generated_at"]) ' ``` (`SCRATCH` must be exported so the `-c` process can read it.) This writes `.dochygiene/report.json` and `.dochygiene/report.md` (atomic, one pair) and stamps `last_check`. ### Step 8 — Surface the result Print the human-report summary plus the two report paths. Read the written human report and show its header + group summary: ``` doc-hygiene check complete scope: category: Reports written: /.dochygiene/report.json /.dochygiene/report.md Run /os-doc-hygiene:clean to act on these (Phase 4), or /os-doc-hygiene:status for timestamps. ``` The human report header renders `scope_globs` but has no category field (the frozen `report_builder.py` does not take one), so surface the active `--category` here in the skill output rather than expecting it in the report. ## Closed enums (for reference — the subagent enforces them) - `category.class` ∈ { `stale`, `bloat` } - stale `subtype` ∈ { `contradicted`, `orphaned`, `superseded`, `provisional`, `completed-in-place`, `duplicated` } - bloat `subtype` ∈ { `distill`, `split`, `freeze` } - `op_type` ∈ { `deterministic`, `generative` } - `exact_edit.kind` ∈ { `delete-range`, `move-to-archive`, `insert-frontmatter`, `replace-text`, `dedupe` } ## Invariants - Step 0 check is deterministic (`git check-ignore`); the offer/confirm is a user gate (M-GATE). The append is deterministic and runs only on explicit confirmation. - Steps 1, 2, 4, 5, 6, 7 are deterministic scripts — **no model** (invariant #6). - Classification = **Sonnet**; single-file Opus escalation only on low confidence for hard distinctions. - The subagent supplies judgment only. It never authors `expected_sha256`, `safety_tier`, `is_destructive`, `is_reversible`, or `raw_tokens` — those are owned by `report_builder.py`. - **Validate on a scratch path BEFORE `write_report`** (write_report is destructive-first; invariant #4). Never write an invalid report. - `last_check` = the validated report's envelope `generated_at` (same run instant), not a fresh clock read. - Empty shortlist / zero signal-bearing candidates → still write an empty-entries report and still stamp `last_check`. - **LOOP GUARD:** the classification subagent prompt MUST point to `workflows/classify-candidates.md`, NEVER to this SKILL.md. - **SUBAGENT AUTHORIZATION:** the classify subagent is the executor; it MUST NOT block waiting for approval. If it objects, REPORT-AND-EXIT — the orchestrator adjudicates. The confirm gate never lives inside the subagent.