---
name: hygiene
description: Manage stale and bloated docs. `/hygiene check` scans the project for stale/bloated documentation and writes a report; `/hygiene clean` applies documented findings; `/hygiene sweep` runs check then clean; `/hygiene status` shows the last check/clean/reminded timestamps and whether a report exists.
argument-hint: "[check [--scope <glob-or-path>] [--category <class|subtype>] | status | clean [--scope <glob-or-path>] [--category <class|subtype>] | sweep [--scope <glob-or-path>] [--category <class|subtype>]]"
---

# /hygiene — Documentation Hygiene

Single entry point for the doc-hygiene plugin. Dispatch on `$ARGUMENTS`.

Parse the first token of `$ARGUMENTS` as the subcommand; everything after it is
passed through. Scripts live under `${CLAUDE_PLUGIN_ROOT}/scripts/` (mirrors
`hooks/hooks.json`).

## `check [--scope <glob-or-path>] [--category <class|subtype>]`

Invoke the **`hygiene-check`** skill (Skill tool, `skill: "hygiene-check"`),
passing the `--scope` and `--category` arguments through verbatim. The skill owns
the full workflow — scan → classify → finalize → validate → write report → stamp
`last_check`. Do not scan or classify here; just route to the skill and surface
its summary.

## `status`

Read-only. No skill, no model, no scan. Run the state store directly and report
the three lifecycle timestamps plus whether a report exists. `state_store.py` is a
module (no CLI), so call it via `python3 -c`:

```bash
python3 -c '
import sys, os
sys.path.insert(0, os.environ["CLAUDE_PLUGIN_ROOT"] + "/scripts")
from state_store import StateStore, resolve_project_root
from pathlib import Path
s = StateStore(resolve_project_root(Path(os.getcwd())))
def fmt(dt): return dt.isoformat() if dt else "never"
print("last_check:    " + fmt(s.get_last_check()))
print("last_clean:    " + fmt(s.get_last_clean()))
print("last_reminded: " + fmt(s.get_last_reminded()))
print("report:        " + ("present" if s.read_report() else "none"))
'
```

Present the output as a short human summary, for example:

```
doc-hygiene status for: <project-root>

  last check     2026-06-20T14:03:11+00:00
  last clean     never
  last reminded  2026-06-24T09:00:00+00:00
  report         present  (run /hygiene check to refresh)
```

Do not classify or distill anything — these are timestamp reads only.

## `clean [--scope <glob-or-path>] [--category <class|subtype>]`

Invoke the **`hygiene-clean`** skill (Skill tool, `skill: "hygiene-clean"`),
passing the `--scope` and `--category` arguments through verbatim. The skill owns
the full workflow — load report → gate confirm-tier entries → apply deterministic
ops → dispatch generative ops → commit → stamp `last_clean`. Do not apply any
edits here; just route to the skill and surface its summary.

A report must exist before running `clean`. If the user has not yet run
`/hygiene check`, the skill will stop and instruct them to do so.

## `sweep [--scope <glob-or-path>] [--category <class|subtype>]`

`sweep` is check-then-clean: a convenience that runs both skills in sequence,
passing the same `--scope` and `--category` through to each.

1. **First**, invoke the **`hygiene-check`** skill (Skill tool,
   `skill: "hygiene-check"`), passing `--scope` and `--category` verbatim.
   Surface the check summary to the user.

2. **Then**, invoke the **`hygiene-clean`** skill (Skill tool,
   `skill: "hygiene-clean"`), passing the same `--scope` and `--category`
   verbatim.

The confirm gate in `hygiene-clean` applies identically under `sweep` — sweep
does **not** auto-approve any confirm-tier or generative entries. The user will
still be prompted to approve any entries that require it before any file
mutation occurs (invariant #7).

`sweep` produces at most one cleanup commit (the clean step); the check step
writes only to the gitignored `.dochygiene/` and does not commit.

## No arguments or unrecognized subcommand

Print usage, then run the `status` block above and show current state:

```
/hygiene — documentation hygiene

  check [--scope <glob-or-path>] [--category <class|subtype>]
                 scan for stale/bloated docs and write a report
  status         show last check/clean/reminded timestamps + report presence
  clean [--scope <glob-or-path>] [--category <class|subtype>]
                 apply documented findings (requires a report; run check first)
  sweep [--scope <glob-or-path>] [--category <class|subtype>]
                 check then clean in sequence (confirm gate still applies)
```