cc-os/plugins/os-doc-hygiene/skills/check/SKILL.md

name	description
check	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 <glob-or-path>] [--category <class|subtype>]`.

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 <glob-or-path> — 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 <path>/ before Step 2. Record the effective scope in your Step 8 summary.
• --category <class|subtype> — 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.

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 <ROOT>/.gitignore? (yes/no)

  Only on explicit confirmation ("yes"): append as follows — never reorder or rewrite existing entries:

  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:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/scanner.py" [--globs <glob> ...] > "$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: { "<path>": [ { "name": "<signal>", "detail": "<text>" }, ... ] }.

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: <scan.project_root>

    Classify exactly these candidates (path → scanner signals, verbatim):
    <candidates>
    [For each signal-bearing path, paste:
       - path: <project-root-relative path>
         signals: <the JSON array from scan.json["signals"][path]>
    ]
    </candidates>

    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 <subtype> (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:

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:

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()):

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:    <effective scope, e.g. **/*.md or the bare-path prefix>
  category: <the --category filter, or "all">

<contents of .dochygiene/report.md, or its header + per-group bullet lines>

Reports written:
  <project-root>/.dochygiene/report.json
  <project-root>/.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.