Adopt the documentation-existence admission test as a portable-baseline pre-check in doc-drift and declutter tooling

[kyle-sexton]

Context

melodic-software/standards PR #206 adds conventions/engineering/documentation-existence.md — an admission test governing whether a tracked page may exist at all: could a reader with repository search derive this content from the code itself? Yes → the page may not exist (deletion, not update). Admitted categories: decisions, domain language, thin navigation, policy and wiring.

The interview contract behind it lives at docs/topics/documentation-existence/PLAN.md in the standards repo.

Proposed work

Sharpen the charter of the documentation tooling in this repo so existence is judged before accuracy:

• review:doc-drift-detector agent — before asking "is this doc stale?", ask "may this doc exist?"; a page failing admission is drift by construction and the finding routes to deletion (after relocating anything admissible), not to an update.
• docs-hygiene:declutter skill — same pre-check on its classification pass.

Design decision to make first (why status: needs-decision)

Whether the admission test ships as the portable-baseline default (applied when a consuming repo declares no documentation conventions of its own) or engages only when the consuming org's declared standards contain it. The re-anchor:follow-our-standards resolution ladder is the governing seam: an org's own declared conventions always win; plugins must never hard-code melodic-software/standards (verified: zero runtime references today — keep it that way).

The test itself is org-agnostic, which argues for portable-baseline default with org-declared conventions overriding.

Related

No linked issue

🤖

[kyle-sexton]

This was generated by AI during triage. · Category: improvement (tooling charter + cross-repo policy) · Priority: priority: high (agnosticism/standards-seam significance per rule 5; note: tooling-quality, sub-sort below core north-star work-readiness items within high). Routed needs-human + wayfind: design.

Why needs-human

The author explicitly flagged needs-decision, and correctly: the fork is cross-repo policy, which the lane reserves for human judgment. The proposed work (teach review:doc-drift-detector and docs-hygiene:declutter to ask "may this doc exist?" before "is it stale?", routing admission-failing pages to deletion) is mechanical once the posture is set — but the posture itself is the open question:

Does the documentation-existence admission test ship as the PORTABLE-BASELINE DEFAULT (applied when a consuming repo declares no doc conventions of its own), or engage ONLY when the consuming org's declared standards contain it?

This is genuine cross-repo policy because:

• The test originates in melodic-software/standards PR fix(source-control): harden PR lifecycle guards #206 (conventions/engineering/documentation-existence.md; interview contract at docs/topics/documentation-existence/PLAN.md).
• The governing seam is the re-anchor:follow-our-standards resolution ladder — an org's own declared conventions ALWAYS win — and the hard constraint that plugins must never hard-code melodic-software/standards (verified: zero runtime references today; keep it that way). How a standards-repo convention becomes a plugin default without coupling is exactly the policy call.

Well-grounded recommendation (for the human to ratify)

Portable-baseline default, org-declared conventions overriding. The admission test is org-agnostic (the "derivable from code by a reader with search?" question is repo-shape-independent), so a portable default is defensible; the follow-our-standards ladder already provides the clean override seam so no coupling to melodic-software/standards is introduced. If accepted, the two tooling changes (doc-drift existence-before-accuracy pre-check; declutter classification pre-check) become straightforward implementations against that resolved posture.

Recommended human path

Ratify the posture (portable-baseline default + ladder override), then the doc-drift-detector + declutter changes are ready to spec. Depends on standards PR #206 landing the convention it consumes.

[kyle-sexton]

This was generated by AI (needs-human decision-brief pass).

Decision brief (2-minute read)

Problem. Should the documentation-existence admission test (from standards PR #206) ship as a portable-baseline default in the doc-drift-detector agent and the declutter skill, or engage only when a consuming org's declared standards contain it? The work itself (add a "may this doc exist?" pre-check ahead of "is it stale?", route admission-failures to relocate-then-delete) is mechanical once the posture is set.

Today (verified in repo):

• plugins/review/agents/doc-drift-detector.md judges accuracy/freshness only — categories are Stale / Missing / Aspirational (doc-drift-detector.md:57-59); "Aspirational" routes to clarify status, never delete. No admission pre-check exists.
• plugins/docs-hygiene/skills/audit-noise/SKILL.md — this is the declutter skill (frontmatter name: audit-noise; the catalog still surfaces a declutter entry). It classifies five in-page NOISE shapes (citation / ghost-ref / preamble / enum-list / scope-meta) into Tier 1-3 and is read-only. It has no whole-page admission test.
• Zero runtime references to melodic-software/standards in plugins (confirmed) — the re-anchor:follow-our-standards ladder is the existing override seam.

Options.

• RECOMMENDED — Portable-baseline default + org-declared override via the follow-our-standards ladder. The admission question ("could a reader with repo search derive this from code?") is repo-shape-independent, so a portable default is defensible, and the ladder already gives orgs a clean override with no hard-coding of standards. Reversibility: HIGH — this is classifier heuristic + prompt text; demoting to opt-in later is a default flip, no migration. Tradeoff: the deletion-routing reach expands to repos that never opted in, so the pre-check must only ever recommend relocate-then-delete (the agent already only reports; the skill is already read-only), never auto-delete.
• Opt-in only (engage when org standards declare it). Tradeoff: zero surprise for consumers, but the test's org-agnostic value is stranded until each org re-declares it — higher friction, lower reach. Reversibility: HIGH.
• Advisory tier now, promote later — surface admission findings as a SUGGESTION-level signal, never routing to deletion, and flip to default once trusted. Tradeoff: safest rollout, but adds a tier and defers the actual behavior change. Reversibility: HIGH.

Cross-links.

• standards PR fix(source-control): harden PR lifecycle guards #206 — the convention this consumes; must land first (the triage comment above already notes this dependency; building on it, not restating).
• source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440 (outward_write_mode) is non-binding here: both surfaces are already report-only / read-only, so the report-only default suppresses nothing new — no outward-write concern to resolve for this issue.

[kyle-sexton]

Operator decision (2026-07-19, decision-session batch 2; relayed).

ACCEPTED — the decision brief's RECOMMENDED option verbatim.

Re-intake: removing needs-human, adding priority: needs-triage for routing.

[kyle-sexton]

This was generated by AI during triage.

Cleanup, not re-triage. Already correctly carries status: needs-decision with the decision framed in its own body (portable-baseline default vs org-declared-only for the documentation-existence admission test). Only action here: clear the stale priority: needs-triage queue label left over from before this item's decision routing — item was never actually re-queued for triage.