jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/plugins/os-doc-hygiene/CLAUDE.md

3.0 KiB
Raw Blame History

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.