Docs Retention Index

---
name: docs-retention-index
description: Design the numbered retention index governing every workflow/process doc's LIFECYCLE — each doc gets a retention category, a reason-to-keep, a superseded-by pointer, and a cleanup rule, mirrored by per-doc retention frontmatter, so doc retirement becomes an explicit, approvable operation instead of silent rot or hoarding. Runs the reverse-reference sweep before retiring a doc, stages retirement (mark → redirect → remove) with human approval for deletion, and keeps the index the source of truth for what's kept, why, and until when. The DOC-lifecycle counterpart to skill-deprecation-planner (which retires a library SKILL) — pinned both ways. Use when governing doc retention/retirement, building a doc index with lifecycle metadata, or deciding which docs to keep, supersede, or delete. Do NOT use to retire a library SKILL (skill-deprecation-planner), sunset a PRODUCT feature/API to users (sunset-deprecation-communicator), or organize docs by type (diataxis-doc-organizer).
---

# Docs Retention Index

**Reading key:** frontmatter is the metadata block at the top of a Markdown
file; API means application programming interface.

## Purpose

Workflow and process docs accumulate in two failure modes at once: rot
(stale session reports, superseded plans, and dead runbooks nobody
removes because nobody's sure it's safe) and hoarding (keep everything
forever, just in case, until the folder is archaeology). Both come from
the same gap — no doc ever declared how long it should live or why. This
skill designs the numbered retention index that closes it: every governed
doc gets a retention category, a reason-to-keep, a superseded-by pointer,
and a cleanup rule, mirrored by per-doc frontmatter so each doc declares
its own lifecycle. Retirement becomes an explicit, approvable operation —
a reverse-reference sweep, then mark → redirect → remove, with deletion
human-approved. It is the DOC-lifecycle counterpart to
`skill-deprecation-planner`, which retires a library SKILL; the two are
pinned against each other in both directions.

## Use When

- Use when: governing the retention/retirement of workflow, process,
  session, or operational docs — deciding what to keep, supersede, or
  delete, and why.
- Use when: building a doc index with lifecycle metadata (retention
  category, reason-to-keep, review date, superseded-by).
- Use when: docs have rotted (stale/superseded docs nobody removed) or
  been hoarded (keep-everything with no reason), and retention needs a
  governing rule.
- Use when: a doc is being retired and needs the reverse-reference sweep
  and a staged, approvable removal.
- Do NOT use when: the object being retired is a library SKILL (its
  mark→redirect→remove lifecycle, neighbor trigger-eval sweep, catalog/
  README rows) — that is `skill-deprecation-planner`; different object,
  and it already references this seam.
- Do NOT use when: the task is communicating a PRODUCT feature/API sunset
  to external users (migration path, timeline, comms) — that is
  `sunset-deprecation-communicator`.
- Do NOT use when: the task is organizing docs by TYPE (tutorials/how-to/
  reference/explanation) — that is `diataxis-doc-organizer`; this governs
  lifecycle, not taxonomy.

## Inputs to Inspect

1. The doc corpus in scope: the workflow/process/session/operational docs
   this index governs, where they live, and their age/last-touched dates.
2. Existing lifecycle signals: any current index, frontmatter, or naming
   convention indicating retention or supersession (usually none — that's
   the gap).
3. Supersession relationships: docs clearly replaced by newer ones but
   never marked/removed, and canonical source-of-truth docs everything
   else defers to.
4. The reverse-reference graph: what links to each doc — other docs, code,
   READMEs, decision logs — so retiring one doesn't create dangling
   references.
5. The repo's removal mechanics and approval path: how deletions are made
   and approved, and whether a squash-merged removal must be reverted as one
   ordinary commit, so retirement rollback is correct.

## Workflow

1. **Define retention categories.** A small, clear set — e.g. permanent/
   canonical (source of truth, never auto-cleaned), reference-until-
   superseded, time-boxed (expires after a stated date/event), and
   transient/disposable (safe to remove after its purpose). Every governed
   doc gets exactly one.
2. **Assign per-doc lifecycle fields.** For each doc: retention category,
   a REASON-TO-KEEP (not "just in case" — a concrete why), superseded-by
   (if any), a cleanup rule, and a review/expiry date where applicable.
   Retention without a reason is hoarding; a reason makes keep-or-remove
   decidable.
3. **Mirror it in per-doc frontmatter.** Each doc declares its own
   lifecycle in frontmatter so the metadata travels with the doc and the
   index can be regenerated/checked against it. The doc and the index
   agree; drift between them is a finding.
4. **Build the numbered index.** A single numbered index listing every
   governed doc with its retention fields — the source of truth for what's
   kept, why, and until when. New docs are entered on creation.
5. **Make retirement an approvable operation.** Before retiring a doc, run
   the REVERSE-REFERENCE sweep (everything that links to it) and give each
   a disposition (relink, redirect, or accept removal). Then stage: mark
   (superseded/expired, successor named) → redirect for a grace window →
   remove. DELETION is human-approved — this skill plans and recommends;
   it does not delete.
   Before asking the owner to choose or approve retirement, explain the terms:
   **keep** retains the doc with a reason and review date; **redirect** marks
   it superseded and points readers to its successor during a grace window;
   **remove** deletes it only after the reference sweep, staging, and explicit
   approval. For each viable option, state why it fits, its benefits and
   drawbacks, setup work and ongoing maintenance cost (including any money),
   and how to reverse it. Recommend one option for this doc and explain why;
   state what the owner is actually authorizing before asking. Then ask
   exactly one atomic owner question; the answer sets the retirement plan
   (including any approved removal stage) only, and this skill still deletes
   nothing itself. When several documents have open retirement choices, ask
   only about the most blocking one this turn (for example, the one whose
   disposition other relinks depend on) and list the others as pending for a
   later turn.
6. **Detect rot AND hoarding.** Flag docs past their review/expiry,
   superseded-but-present, and orphaned; equally, flag "permanent" docs
   with no reason-to-keep (hoarding by default). Push both toward an
   explicit decision.
7. **Specify rollback.** State the rollback per retirement. Revert an isolated
   retirement commit when that would affect only the retirement; otherwise
   restore the targeted doc and references without reverting unrelated work.
8. **Deliver** the index, the frontmatter convention, and the per-doc
   dispositions in the Output Format — with deletions flagged for human
   approval.

Retention-category definitions, the per-doc frontmatter schema, the
reverse-reference sweep checklist, and the mark→redirect→remove staging:
[references/retention-index-sheet.md](references/retention-index-sheet.md).

## Output Format

```
DOCS RETENTION INDEX — <scope: workflow/process docs>
Categories:    permanent/canonical | reference-until-superseded | time-boxed | transient
Index (numbered):
  <row number | doc path | category | reason-to-keep | superseded-by | cleanup rule | review/expiry>
Frontmatter:   per-doc retention fields (mirrors the index; drift = finding)
Retirements (recommended):
  <doc>: reverse-ref sweep result; disposition (relink/redirect/remove);
         stage=mark→redirect→remove; rollback=<isolated revert or targeted restore>; DELETION = human-approved
Owner choice: <plain-language keep/redirect/remove terms; reason, pros/cons,
               setup and maintenance cost, reversibility for each viable option;
               recommendation and why; exact action needing approval>
Findings:      rotted (past expiry / superseded-present / orphan); hoarded (permanent, no reason)
Boundaries:    SKILL retirement → skill-deprecation-planner; product sunset →
               sunset-deprecation-communicator; corpus-by-type → diataxis-doc-organizer
```

## Validation Checklist

- [ ] A small, clear set of retention categories is defined; every
      governed doc has exactly one.
- [ ] Each doc has a concrete reason-to-keep (not "just in case"),
      superseded-by, cleanup rule, and review/expiry where applicable.
- [ ] Per-doc frontmatter mirrors the index; drift between them is flagged.
- [ ] A single numbered index is the source of truth for what's kept, why,
      and until when.
- [ ] Retirement runs a reverse-reference sweep and stages mark → redirect
      → remove; DELETION is human-approved, not executed here.
- [ ] Before an owner decision, keep/redirect/remove are explained with
      reasons, pros and cons, setup/maintenance cost and reversibility; one
      recommendation explains why and names the exact approval scope.
- [ ] Both rot (stale/superseded/orphan) and hoarding (permanent without a
      reason) are surfaced.
- [ ] Rollback is stated per retirement (isolated revert or targeted restore
      that preserves unrelated changes).
- [ ] SKILL-retirement, product-sunset, and corpus-by-type concerns are
      handed to their owning skills.

## Gotchas

- Rot and hoarding are the same disease: no doc ever said how long it
  should live. The reason-to-keep field is the cure for both — it makes
  "keep" a decision, not a default.
- "Permanent" with no reason is hoarding wearing a badge. Canonical
  source-of-truth docs earn permanence; a session report from last year
  doesn't. Demand the reason.
- Deleting a doc without the reverse-reference sweep breaks every link
  into it — a dead cross-reference in the README, a decision log pointing
  at nothing. Sweep first, disposition each reference, then remove.
- Retiring by editing history in place (or hard-deleting a superseded doc
  that others cite) destroys traceability. Mark and redirect through a
  grace window; supersede visibly.
- This skill plans retirement; it does not delete. Executing a deletion is
  a human-approved operation — quietly removing docs is exactly the silent
  behavior the index exists to prevent.
- Retiring a DOC is not retiring a SKILL. A skill's retirement sweeps
  neighbor trigger-evals and catalog rows and is `skill-deprecation-planner`'s
  job; conflating them applies the wrong reverse-link graph.
- An index that drifts from the docs' own frontmatter is two sources of
  truth. Mirror them and treat divergence as a finding, or the governance
  rots like the docs it governs.

## Stop Conditions

- The object being retired is a library SKILL → route to
  `skill-deprecation-planner` (it owns the skill lifecycle and already
  pins this seam from its side).
- The task is communicating a PRODUCT feature/API sunset to external users
  → route to `sunset-deprecation-communicator`.
- The task is organizing docs by type → route to `diataxis-doc-organizer`.
- A retirement recommendation would DELETE a doc → stop at the recommend
  stage and require explicit human approval for the deletion; this skill
  governs and plans, it does not execute removals.

## Supporting Files

- [references/retention-index-sheet.md](references/retention-index-sheet.md)
  — retention-category definitions, the per-doc frontmatter schema, the
  reverse-reference sweep checklist, and the mark→redirect→remove staging
  with rollback.
- `evals/evals.json` — behavior cases including the reason-to-keep
  discipline, the reverse-reference sweep, and the human-approved-deletion
  refusal.
- `evals/trigger-evals.json` — discrimination against `skill-deprecation-planner`
  (DOC vs SKILL — the pinned seam), `sunset-deprecation-communicator`, and
  `diataxis-doc-organizer`.