docs-lifecycle-sweep
Docs lifecycle sweep — Tier-B classification with evidence for stale docs. Use when user says doc sweep, clean up stale docs, compact audits, doc janitor, or promote/lift/retire a doc.
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 5
- Forks
- 0
01 前言 Front Matter
- name
- docs-lifecycle-sweep
- description
- Docs lifecycle sweep — Tier-B classification with evidence for stale docs. Use when user says doc sweep, clean up stale docs, compact audits, doc janitor, or promote/lift/retire a doc.
02 资源文件 1
- 参考文档WORKFLOW.md8.3 KB
03 SKILL.md 正文
Docs lifecycle sweep — the doc janitor
docs-governance defines what every doc should be (lifecycle types, existence test, closing prescriptions, cross-reference discipline). This skill is the how — it walks the repo-wide docs/ surface, applies the spec mechanically, and produces a per-file action plan the user approves before anything is touched.
The promise: at the end of a sweep, every remaining file passes the existence test, every closed plan is lifted, every closed audit is either kept-with-justification or deleted-with-knowledge-lifted, every cross-reference still resolves, and there is no dead weight.
When to fire
User intent (any phrase is enough):
- "clean up stale docs" / "doc janitor" / "doc sweep"
- "audit docs lifecycle" / "compact audits" / "compact plans"
- "are these audits still earning their keep"
- "what's gone stale in
docs/" - "delete tombstones" / "no tombstones, please"
- "promote / lift / retire
<doc>" - "is this audit closed properly"
- After landing a substantive PR, asking "did anything in docs go stale because of this?"
Also fire proactively when:
- Closing a Plan, Audit, or Research file via
improve-codebase-architectureor any normal commit that ships a trackedroadmap.mditem — the closure is a natural sweep trigger for that file's neighbours. - A PR adds a new
docs/audits/<topic>.md— sweep the rest ofdocs/audits/to catch anything the new audit just superseded. - A repo-wide refactor changes paths or symbol names cited from docs (cross-reference rot risk).
Scope (which surfaces this skill walks)
This repo is Tier B only — one repo-wide docs/ surface, no per-feature subtrees, no per-shared-component READMEs. Two surfaces:
| Tier | Substrate | Sweep scope |
|---|---|---|
| B — repo-wide | docs/ at repo root |
All 5 lifecycle types: architecture.md, roadmap.md, glossary.md, audits/, plans/, research/ |
| 0 — per-tooling-area | .agents/, .cursor/ |
Each rule + skill — apply existence test; check Tier-1 always-on cost still earns its keep |
Default: the user names a surface (e.g. "sweep docs/audits/"), and we walk just that one. If they say "sweep docs" without scope, walk all of docs/.
Procedure: WORKFLOW.md — enumerate → existence test → classify → report → execute on approval.
Hooking the sweep into normal workflows
The skill is discoverable (Tier 3) — it fires on user intent. To make it run more automatically:
- End of every PR-closing commit — when an agent closes a Plan or Audit (e.g. via
improve-codebase-architecture), it should call this skill on the affectedaudits/orplans/directory as the final step. - End of every material refactor — when
src/files move or symbols rename, run this skill ondocs/to catch cross-reference rot. - Pre-merge hygiene — before merging a long-lived branch, sweep the
docs/surfaces it touches so stale claims don't land onmain.
Anti-patterns
- ❌ Deleting without surfacing the classification first. The user owns the call. The skill produces evidence; it does not unilaterally decide.
- ❌ Slimming without grepping for cited rule numbers / section anchors. Anchor breakage is silent and degrades over time.
docs-governance§ 6 is non-negotiable. - ❌ Leaving tombstones. A "this audit was closed and deleted, see commit X" pointer file IS the dead weight the sweep is supposed to eliminate. Trust
git log --follow. A singleroadmap.mdline under "Closed audits (pointers)" is the maximum allowed surface for "this used to exist." - ❌ Lifting trivia. Not every closed audit has knowledge worth lifting. If the audit's findings are 100% mechanical ("rename X to Y, delete dead file Z") and the result is visible in source, lift nothing, delete the file.
- ❌ Reformatting "while we're here." A sweep edits structure (delete / slim / lift / pointer-update). Cosmetic re-flowing of unrelated docs is a separate PR.
- ❌ Sweeping Tier-1 rules without checking the always-on cost ledger. A Tier-1 rule that no longer earns its always-on cost should demote to Tier 2 / Tier 3 (per
agents-tier-system), not get deleted outright. - ❌ Leaving enumerated cross-reference indexes inline after a slim or delete. A line like "Cited from
architecture.md,glossary.md" in any doc is a hand-maintained index that goes stale every time the sweep runs. When you encounter one, replace it with the lookup command (rg "<anchor>" docs/) — the command IS the index. Seedocs-governance§ 6. - ❌ Citing specific audit / plan / research filenames as canonical examples in skills or rules. Skills are durable; the docs they describe are mortal under this very lifecycle. Use shape placeholders (
<YYYY-MM-DD>-<topic>.md,docs/audits/<topic>.md) and describe the shape of what to look for, not which file does it today. Same hazard in rules — see authoring-discipline +authoring-discipline/PROSE.md(no mortal filename anchors).
Reference
docs-governance— the spec this skill operationalises (lifecycle types, existence test, closing prescriptions, cross-reference discipline).docs-governance-priming— Tier 2 priming; cites docs-governance + this skill on doc edits.improve-codebase-architecture— natural caller; closes plans and triggers a sweep on the surroundingplans/folder.- WORKFLOW.md — 5-step procedure + output substrate.
agents-tier-system— applies when sweeping Tier 0 (.agents/rules/,.agents/skills/).
04 同仓库更多 Skills
vue-persist
Gate Vue 3 UI on Persist hydration with useHydrated (shallowRef). Use in setup/effectScope when avoiding flash of default state on async backends.
svelte-store-persist
Gate Svelte store-based UI on Persist hydration with hydratedStore (Readable). Use for Svelte 3–4 or Svelte 5 apps that still use stores; runes UI → svelte-persist.
svelte-persist
Gate Svelte 5 runes UI on Persist hydration with hydratedRune (.current). Use for Svelte 5; for stores / Svelte 3–4 use svelte-store-persist.
solid-persist
Gate Solid UI on Persist hydration with useHydrated (Accessor). Use when avoiding flash of default state on async backends; read hydrated() in reactive scopes.
react-persist
Gate React UI on Persist hydration with useHydrated + toHydrationSignal. Use when avoiding flash of default state on async backends (IndexedDB), SSR snapshot true, or wiring HydrationSignal into React 18/19.
preact-persist
Gate Preact UI on Persist hydration with useHydrated (preact/compat useSyncExternalStore). Use when avoiding flash of default state on async backends or wiring HydrationSignal into Preact.