18 KiB

Raw Blame History

PRD: `doc-hygiene` plugin

Status: shipped · Built at plugins/os-doc-hygiene/ in cc-os, not the cc-plugins target/marketplace named below. Historical design doc — kept as-is except this note and the location/marketplace corrections below.

Problem Statement

When I work intensively in a project, documentation accumulates two distinct defects that both degrade how usefully an AI agent (and I) can read the repo:

Stale docs — content that is now wrong: it contradicts the running system, references files/symbols/paths that no longer exist, is pinned to an old tool version, claims "in progress" for shipped work, or duplicates a fact that has since drifted. Trusting it causes wrong actions. This is the high-severity class because agents read confidently and don't sanity-check.
Bloated docs — content that is still true but mostly irrelevant: long debugging narratives, resolved-problem detail at full fidelity, decisions recorded without distillation, append-only growth. It doesn't lie; it dilutes attention and burns context-window budget, and buries the one live caveat in archaeology.

Severity scales with injection frequency: a stale line in a doc nobody opens is annoying; the same line in an auto-injected file (CLAUDE.md, memory index) misleads every session unprompted.

Today I notice this only incidentally, have no systematic way to find it across projects, and cleaning it up by hand wastes both my time and AI tokens. I also don't want a tool that interrupts my flow or silently rewrites my repos.

Solution

A Claude Code plugin, installed globally but operating per-project, that:

Reminds, doesn't nag. A deterministic SessionStart hook checks an in-project timestamp and, only if the last hygiene check is older than a threshold, injects a noticeable reminder telling me how many days it's been and which command to run. Zero AI tokens unless I act. Snoozes so it reminds at most once per day while stale.
Checks on demand. A check skill runs a deterministic scan that gathers objective signals and a candidate shortlist, then an AI classification pass that reads candidates, categorizes them (stale vs bloat, by sub-type), assigns each a concrete operation tagged by op-type (deterministic | generative) and safety tier (auto | confirm), and estimates context-weight savings. It produces a human report (what to clean and why) and a machine report (structured ops for the cleaner to consume).
Cleans, git-safely and scoped. A clean skill consumes the machine report. For each op it checks an mtime guard (file unchanged since the check); deterministic ops are applied mechanically with no model; generative ops are delegated to Sonnet subagents. auto-tier ops run without fuss; confirm-tier ops escalate into an approval list. Cleanup runs only on a clean/committed tree (or after an auto-checkpoint) and lands as a single reviewable commit. The user can scope a run to specific categories or files.
Composes. A sweep entry runs check-then-clean in one go, still surfacing the report and gating confirm-tier ops.

The design leads with deterministic code (scan, signals, state, patch-apply, token estimate) and reserves AI for the genuine judgment (classification and prose distillation). This keeps it fast, cheap, and trustworthy.

User Stories

As a developer, I want a deterministic SessionStart reminder when a project's docs haven't been checked in over a threshold, so that I'm nudged without spending any AI tokens.
As a developer, I want the reminder to be visually noticeable and to name the exact command to run, so that acting on it is one step.
As a developer, I want the reminder to snooze (at most once/day while stale), so that it doesn't nag me every session for a week.
As a developer, I want hygiene state stored per-project in a gitignored dot directory, so that there is no global index to corrupt, race, or itself go stale.
As a developer, I want to run a check manually with a slash command, so that after a heavy context-building session I can clear what accumulated.
As a developer, I want the check to deterministically scan scoped files and compute objective signals (broken references, version skew, edit-recency vs git churn, location, append-only growth, archive-to-live ratio, frontmatter markers), so that the AI pass starts from facts, not a blank read.
As a developer, I want the AI pass to classify each candidate as stale (contradicted, orphaned, superseded, provisional, completed-in-place, duplicated) or bloat (distill, split, freeze), so that the right remedy is chosen per file.
As a developer, I want each recommended operation tagged with an op-type (deterministic | generative) and a safety tier (auto | confirm), so that the cleaner knows what it can apply mechanically and what needs a model or my approval.
As a developer, I want a human-readable report describing what should be cleaned and why, grouped by category, so that I can decide at a glance.
As a developer, I want a machine-readable report the cleaner consumes directly, so that the cleanup step doesn't re-derive the analysis.
As a developer, I want only the single most-recent report kept (rollover deletes prior reports), so that the tool's own artifacts don't become bloat.
As a developer, I want the check to estimate context-weight savings per file, summed into categories and a total (bottom-up), so that I can prioritize.
As a developer, I want savings honestly framed and weighted by injection frequency (auto-injected files counted as real per-session savings, on-demand docs as theoretical-max), so that the numbers aren't misleading.
As a developer, I want the cleaner to apply deterministic+auto ops (move-to-archive, freeze-stamp, known-target link fix, exact-dup dedupe) with no model and no prompt, so that no-brainer cleanup just happens.
As a developer, I want every destructive, subjective, or generative op to be confirm-tier and escalated for my approval, so that nothing surprising happens to my repos.
As a developer, I want a per-op mtime guard so that if a file changed since the check, its cached edit is skipped (and re-analysis recommended) rather than blindly applied.
As a developer, I want generative cleanup (distilling narrative into live constraints) delegated to a Sonnet subagent, so that distillation quality is high and doesn't drop the constraint that mattered.
As a developer, I want cleanup to run only on a clean/committed tree, or to auto-commit a WIP checkpoint first, so that my uncommitted work is never lost.
As a developer, I want each cleanup run to land as a single reviewable commit, so that I can inspect or revert the whole sweep trivially.
As a developer, I want to scope a cleanup to specific categories or files (e.g. "only the orphaned-reference fixes"), so that I stay in control of how much changes at once.
As a developer, I want a sweep command that runs check-then-clean, so that when I already trust the project I can do both in one step.
As a developer, I want sweep to still surface the report and gate confirm-tier ops, so that the convenience path isn't a foot-gun.
As a developer, I want a status command that reports last-check and last-clean timestamps for the current project, so that I can see where it stands without running anything.
As a developer, I want to protect files from being flagged via hygiene: frozen frontmatter or a .dochygiene-ignore file, so that deliberately-frozen records and append-only logs aren't repeatedly flagged.
As a developer, I want sensible scope defaults (markdown + known doc locations; excluding build/vendor/archive/graphify-out dirs) with per-project overrides, so that the scan targets docs and nothing irrelevant.
As a developer, I want the check and clean steps to update their own timestamps (last_check, last_clean) and the reminder to track last_reminded, so that the lifecycle is observable and the snooze works.
As a developer, I want the plugin to work in any project where it's enabled without per-project setup beyond enablement, so that adoption is frictionless.
As a developer, I want classifier behavior protected by golden examples and invariants, so that future edits to the plugin don't silently regress what counts as stale vs bloat.
As a developer, I want decisions (especially confirm-tier approvals) recorded, so that there's an audit trail of what was changed and why.
As a developer, I want the deterministic scripts to emit structured JSON and correct exit codes, so that they're independently testable and composable.

Implementation Decisions

Distribution & activation

New plugin os-doc-hygiene in the cc-os marketplace (built at plugins/os-doc-hygiene/; see migration note above). Installed globally, operates per-project. No global state index — the question of "how to key projects globally" is dissolved by per-project storage.
Marketplace registration deferred until the plugin is functional (documented as a build-completion step, not done now).

State & artifacts (in-project)

A gitignored .dochygiene/ directory at the project root (resolved via git root, fallback cwd) holds:
- state.json — last_check, last_clean, last_reminded timestamps.
- the single most-recent report (human .md + machine .json).
Rollover: each new check deletes the prior report before writing the new one.
.dochygiene/ must not be tracked. The tool does not silently edit the user's .gitignore (that would itself be an outward mutation, against the non-intrusive premise). Instead: on first check it detects whether the dir is ignored and, if not, surfaces a one-line offer to add the entry — applied only on confirmation (or noted in the report). The scanner always self-excludes .dochygiene/ regardless.

Components / modules (described abstractly; see CLAUDE.md for the build map)

State store (deterministic): reads/writes state.json; atomic writes; resolves project root.
Scanner (deterministic): walks scoped files, computes signals, emits a candidate shortlist with attached signals. Respects scope config + ignore markers + frozen frontmatter + append-only detection.
Reminder hook (deterministic, SessionStart): reads state, compares to staleness threshold, applies once/day snooze via last_reminded, emits a noticeable notice. No model.
- Mechanism (confirmed): plugins declare hooks in hooks/hooks.json at the plugin root (not under .claude-plugin/). The visible, zero-token notice is emitted via the hook's JSON systemMessage field (a user-facing banner) — NOT additionalContext (which is silent to the user). The command names the slash command to run. matcher is startup|resume.
- Snooze is load-bearing, not polish: SessionStart also fires on resume, clear, and compact. The once/day last_reminded snooze is what prevents the banner re-firing after every compaction within a single working session.
- Constraints to respect: keep timeout low (≤5s); exit 0 (never block the session); the script must be fast and side-effect-free beyond reading state.
Classifier / report builder (AI — the check skill): consumes the shortlist, reads candidates, assigns category + op-type + safety tier, writes exact edits for deterministic ops, and calls the token estimator. Emits human
- machine reports. Updates last_check.
Token estimator (deterministic helper): counts tokens of removed/reduced spans with a local tokenizer approximation (no API call); weights by injection frequency; rolls up file → category → total. Framed as "context weight reduced," splitting injected vs on-demand.
Cleanup executor (the clean skill + deterministic patch-applier): consumes the machine report; mtime-guards each op; applies deterministic ops mechanically; delegates generative ops to Sonnet subagents; runs auto freely and escalates confirm; enforces git checkpoint + single-commit; scopable by category/file. Updates last_clean.
Sweep (composition): invokes check then clean, preserving the report surface and confirm gate.

Operation taxonomy

Op-type deterministic: exact, reversible edits the check pre-computes (delete/move/stamp/known-link-fix/exact-dedupe). Applied with no model.
Op-type generative: prose transformations (distill, split) requiring a model at clean time (Sonnet). Deferred — not pre-written at check time — so a check is cheap even when no clean follows.
Safety tier auto: deterministic + reversible + objective → runs without prompt.
Safety tier confirm: destructive (any delete), subjective, or generative → escalated for approval.

Git safety (reversion-protection vocabulary)

Cleanup requires a clean/committed working tree, or auto-commits a WIP checkpoint first.
Each cleanup run lands as one reviewable commit (the post-state).
confirm-tier approvals are logged to a decisions record.

Model routing (per the marketplace convention)

Deterministic scan/state/patch-apply/token-estimate: no model (scripts).
Writing those scripts: Haiku.
Classification / report building: Sonnet (reading comprehension + judgment). The hardest stale-vs-bloat distinctions may escalate to Opus.
Generative distillation at clean time: Sonnet (explicitly not Haiku — this is the highest-judgment task and Haiku produces lossy summaries).
Orchestration: Opus (the calling Claude).

Language

Python, OOP, small composable single-responsibility classes with dependency injection (per the deterministic-scripting reference), chosen for broad reach in a general-purpose plugin and for testability.

Report schema is the linchpin

The machine report schema (per-file: category, signals, recommended op, op-type, safety tier, optional exact-edit, token estimate) is the contract every other component consumes. It is designed and frozen first.

Testing Decisions

What makes a good test here: assert external behavior at the highest deterministic seam — given an input doc tree / state file / report, the script produces the correct structured output and exit code. Do not assert internal class structure. The AI classification layer is pinned by golden examples, not unit assertions.

Seams (highest first):

Scanner — input: a fixture doc tree; output: candidate shortlist JSON. Unit-tested against fixtures exercising each signal (broken ref, version skew, churn-vs-edit, location, append-only, frozen frontmatter, ignore file).
State store — timestamp read/write, rollover (only latest report kept), snooze logic. Unit-tested with an injected clock and temp dirs.
Reminder hook — given a state.json + injected clock + threshold, asserts notice / no-notice / snoozed. Unit-tested via the injected clock (no real time, no real session).
Token estimator — counts on known spans; injection-frequency weighting; bottom-up rollup. Unit-tested on fixed inputs.
Patch-applier + mtime guard — applies deterministic ops on fixtures; skips when fixture mtime is newer than the check timestamp. Unit-tested.
Classifier (AI) — golden examples (examples/golden/): input doc tree → expected report categorization, per the reversion-protection pattern. Run the check against each; flag mismatches for human review.

Prior art: the commit and cc-architect plugins pair deterministic scripts/ with skills and structured output; this plugin follows that split. The reversion-protection reference (cc-architect/.../reversion-protection.md) defines the golden-example + invariants approach used for the classifier.

Out of Scope

A global cross-project dashboard / index (dissolved by per-project storage).
Exact Claude token counting via API at check time (local approximation only; exactness isn't worth the latency/cost for a motivational estimate).
Non-markdown content analysis beyond known doc locations (e.g. linting source code comments). Scope defaults to docs.
Auto-running cleanup from the SessionEnd/SessionStart hook — the hook only ever reminds; all mutation is user-invoked.
Pushing commits or any outbound/network action — cleanup is local commits only; the user pushes.
Editing files outside the resolved project root.
v2 polish: richer per-category savings visualizations, configurable op taxonomies beyond the built-in set.

Further Notes

Build order (the report schema gates everything): (1) machine report schema; (2) deterministic scanner + state store + reminder hook; (3) check skill (scanner → AI classify → report); (4) clean skill (consume report, git-safe, scoped) + sweep; (5) bonus: deterministic patch-apply + token estimator. Patch-apply and token-estimate are explicitly v2 — they optimize a report format that must exist and be proven first.
Why deterministic-first matters here specifically: the check does the expensive cognition once (reading + deciding); cleanup executes. Pushing attribute-detection into the scanner and exact edits into the report means most cleanup needs no model at all, and a check is cheap even when no cleanup follows.
False-positive trust risk: without the frozen/ignore mechanism and append-only detection, the tool would re-flag deliberately-frozen records every week and lose the user's trust. This is treated as a correctness requirement, not a nicety.
The tool must not become bloat: report rollover (keep latest only) and the gitignored dot dir are deliberate guards against the plugin polluting the very repos it cleans.
Linchpin mechanism verified: the SessionStart systemMessage banner path was confirmed against the Claude Code hook docs before this PRD was finalized (no other plugin in the collection wires a CC hook, so it had no precedent). Build-spike #1 is still to stand up a trivial hooks/hooks.json emitting a systemMessage and confirm it renders visibly in a real session before building the deterministic core on top of it.

18 KiB Raw Blame History

PRD: doc-hygiene plugin