doc-triage

name	doc-triage
description	Route markdown into artifacts that can't lie — doc comments, ADRs, issues, archive — and execute the conversions. Use when the user says doc triage, docs cleanup, too many markdown files, or a design doc shipped.

Doc Triage

Reduce a repo's standalone markdown to a minimal set of living documents by routing every file's content to the artifact that can't drift: colocated doc comments, append-only ADRs, tracker issues, or the archive. The governing principle: a document that claims to describe current state will eventually lie; move its claims somewhere enforcement exists, or date-stamp it as history.

Do not use when

• The repo has ≤5 md files and they're current — nothing to triage.
• The user wants to write documentation — that's ordinary work, not triage.

Procedure

1. Inventory

List every *.md in the repo (excluding vendored/node_modules). For each, record: path, last-modified vs. last-modified of the code it describes, and a one-line summary of what it claims.

2. Classify (the "can it lie?" test)

Route each file to exactly one bucket:

• Doc-comment material: intent about a specific module — why, invariants, business constraints, rejected alternatives. → Moves onto the module it governs (@moduledoc/TSDoc). The file then deletes.
• ADR: a decision with cross-module scope and a why. → Becomes docs/adr/NNNN-<slug>.md, dated, append-only, from assets/adr-template.md. Never rewrite history into it; record the decision as-of its date.
• Backlog: aspirational design for unbuilt work. → Becomes tracker issues (or TODO.md entries if no tracker); the design file itself goes to archaeology, not the living tree.
• Archaeology: design-phase thinking for shipped or abandoned work. → docs/archive/<name>-<date>/, or design/ if still explicitly non-authoritative and in progress. Add a one-line header: "Archaeology — not current documentation."
• Delete: stale state-descriptions superseded by code, duplicates, scratch. Git keeps them; git rm in a commit is versioned removal and satisfies Trash-only rails.
• Living (the survivors): README, the architecture map, active ADRs. Target ≤5; each survivor must justify why it can't convert.

Ambiguous files: split them — most sprawl is part intent (→ comments), part decision (→ ADR), part stale (→ delete).

3. Execute

Perform the conversions: write the doc comments onto modules, create the ADRs, file the issues, move the archaeology, delete the dead. One commit per bucket keeps review sane.

4. Guard (offer, don't impose)

• scripts/md-budget.sh: deterministic allowlist check for CI (.md-allowlist, exit 1 on violation) or advisory mode.
• scripts/pre-push: advisory doc-drift margin note via claude -p; never blocks.
• scripts/doc-sweep.sh: scheduled full drift + archaeology-leak sweep with a dead-man's-switch status file.

Interview points (batch, don't dribble)

Before executing, batch the genuinely-owner calls into one question set: survivor list confirmation, contested buckets, tracker vs. TODO.md, and whether to install guards. Everything else is mechanical.