60 lines
3.0 KiB
Markdown
60 lines
3.0 KiB
Markdown
# doc-hygiene
|
||
|
||
Claude Code plugin that monitors and manages **stale** and **bloated** project
|
||
documentation. Installed globally, operates per-project. Reminds (deterministic,
|
||
zero-token) on `SessionStart`; checks and cleans on demand via skills.
|
||
|
||
> `PRD.md` is the historical source-of-truth design doc (see its top-of-file
|
||
> migration note for current location). This file is a current-state index,
|
||
> not a build map — the plugin is fully built (5 skills, tests passing).
|
||
|
||
> Vault user guide (nuance/mental-model, not a how-to):
|
||
> `~/Documents/SecondBrain/user-guide/os-doc-hygiene-user-guide.md`.
|
||
|
||
## Core distinction (do not conflate)
|
||
|
||
- **Stale** = the doc is *wrong* (contradicted, orphaned, superseded,
|
||
provisional, completed-in-place, duplicated). Remedy: fix or remove.
|
||
- **Bloat** = the doc is *true but mostly irrelevant* (distill, split, freeze).
|
||
Remedy: change its altitude, almost never delete history.
|
||
|
||
Severity scales with **injection frequency** — a stale line in `CLAUDE.md` (auto
|
||
-injected every session) is worse than the same line in a doc nobody opens.
|
||
|
||
## Component map
|
||
|
||
- `skills/` — five skills: `check`, `clean`, `status`, `sweep`, `calibrate`
|
||
(each `SKILL.md` + `workflows/`); see `skills/CONTEXT.md` for the index.
|
||
- `scripts/` — deterministic Python core (scanner, state store, reminder,
|
||
report builder, validator, patch applier, token estimator, rulebook,
|
||
calibrate helpers); see `scripts/CONTEXT.md`.
|
||
- `hooks/hooks.json` — `SessionStart` → `scripts/reminder.py` (banner only,
|
||
no analysis, no mutation beyond `last_reminded`).
|
||
- `tests/` — pytest suite covering every deterministic seam; see
|
||
`tests/CONTEXT.md`.
|
||
- `invariants.md` — the reversion-protection contract (numbered behavioral
|
||
invariants); read before changing scanner, state, or safety-tier logic.
|
||
- `examples/golden/` — golden classifier fixtures (Layer 2 of reversion
|
||
protection, paired with `invariants.md`).
|
||
- `lifecycle-spec.md` — the rulebook layer (global `rulebook.json` +
|
||
per-project `.dochygiene-rules.json`) feeding tier derivation and the
|
||
`calibrate` skill; decisions are ADR-0038–0041.
|
||
- `openspec/` — this plugin's own OpenSpec changes/specs tree (archived
|
||
changes correspond to shipped features).
|
||
|
||
## Conventions
|
||
|
||
- **Language**: Python, OOP — small single-responsibility classes, dependency
|
||
injection, immutable transforms where possible. See
|
||
`../cc-architect/references/tool-patterns/deterministic-scripting.md`.
|
||
- **Model routing**: scripts = no model; classification = Sonnet (hard cases →
|
||
Opus); generative distillation = Sonnet (NOT Haiku).
|
||
- **Reversion protection**: `invariants.md` + `examples/golden/` + human gate
|
||
for changes to either. See
|
||
`../cc-architect/references/tool-patterns/reversion-protection.md`.
|
||
- Read a directory's `CONTEXT.md` before its source files (progressive
|
||
disclosure).
|
||
|
||
Changing any invariant requires updating `invariants.md` and the golden
|
||
examples, with explicit human approval — do not restate the invariants here.
|