spec: agent-doc register detectors — three cut classes routed through the findings relay

[kyle-sexton]

Brief

TLDR

Three cut classes for agent-facing markdown — content the model already knows, coercive emphasis, and negation without a positive — have official backing, no current detector, and no route to a remediation surface. Add them as finding shapes on the audits that already own their territory, each emitting a type: review-findings file the existing review:fanout fix relay applies behind a human gate. No new skill.

A fourth candidate (ceremonial-section removal) is rejected as a change and filed as a question instead — see "Rejected".

Authoring surface: docs/specs/agent-doc-register-detectors-brief.md.

How this brief replaced its predecessor

The first draft proposed a new apply-side skill, docs-hygiene:rewrite-for-agents. A fresh-context plan review returned three CRITICALs, all verified against source:

1. Its flagship cut targeted headings audit-noise/SKILL.md explicitly protects — "Section EXEMPTIONS never flagged: ## Recheck triggers, ## Cross-references, ## Sources / ## History / ## External authority footers". Two skills in one plugin, opposite verdicts, same headings.
2. Its evidence was one external repo (0/36) against 199 of 224 (88.8%) of this fleet's own SKILL.md files — the same upstream whose premises docs/conventions/invocation-mode/README.md already inverted once, for documented reasons.
3. The apply-side shape it described is the fixed verb realign (docs/PLUGIN-PHILOSOPHY.md:62) — "Consumes a findings artifact a sibling audit produced… never re-judges the surface itself" — which the draft violated by re-deriving its own classification.

Chasing (3) surfaced the decisive fact, stated by docs/conventions/detector-findings/README.md: "the fleet's gap is detectors, not apply capability. Deterministic detectors exist and produce real findings; what they lack is a route to a remediation surface. Conforming to a file format is that route."

The gap analysis that motivated the original draft still holds — every one of upstream's seven writing-for-agents levers landed on the authoring side or the audit side, and nothing retrofits an existing file. The remedy was mis-specified, not the gap.

Goal

Each of the three officially-backed cut classes has a detector in the audit that owns its territory, emitting findings that reach review:fanout's apply relay through the documented producer contract — so a verbose agent-facing file can be corrected without a human hand-copying findings into edits.

The premise correction (load-bearing)

"Shorter" is not the goal and is not officially endorsed. Skill docs say cut explanation of what Claude already knows ("Default assumption: Claude is already very smart"). Prompt-engineering docs say be explicit and specific ("The more precisely you explain what you want, the better the result"), with worked examples that fix problems by adding words.

No detector may target length. Each targets a named content class. Word count is a reported side effect, never an objective and never a threshold.

The three detectors

ID	Class	Home	Why that home
D1	Content the model already knows — an instruction carrying no proper noun, path, threshold, version, or repo-specific fact	claude-config:audit-instructions	Already owns "prior-model workarounds, over-prescriptive scaffolding"; its empirical half already routes to claude-config:unhobble
D2	Coercive emphasis — CRITICAL:, You MUST, all-caps imperatives, blanket "if in doubt, use X"	claude-config:audit-instructions	Official re-baselining guidance is exactly this scope
D3	Negation with no positive alternative in the same sentence	docs-hygiene:audit-noise	Shape-classification against a fixed taxonomy is what it does; write-for-agents already carries the write-side rule

Protected content — no detector may flag it

Directives, thresholds, numeric bounds, qualifiers, version pins; proper nouns, paths, file names, command strings, env vars; quoted 'trigger phrase' strings in a description; motivating context where rationale changes behavior; completion criteria; worked examples that disambiguate a fragile task.

A change that makes an instruction more specific is a legitimate outcome even though it adds words.

The hard constraint on D1/D2 findings

plugins/skill-quality/scripts/check-skill.sh:414 hard-FAILs a dropped 'trigger phrase' versus the base ref ("dropped trigger keyword(s) vs HEAD (auto-invocation regression)"). The script's own header calls check 3 "the regression-critical net: a rewrite that silently drops a description trigger phrase degrades…".

Therefore: no detector emits a finding whose remediation edits a description, when_to_use, or any quoted trigger phrase. Detectors are body-scoped. A description-level concern is reported to the human, never routed to the apply relay.

Producer contract

Per docs/conventions/detector-findings/README.md. Each detector writes a file conforming to the shape owned by plugins/review/skills/fanout/context/default-mode.md "Findings-file shape" — frontmatter type: review-findings, date, branch, tier. Producer obligations:

• Run the full topic-docs rung order, not only its last rung — writing to the documented default when a higher rung resolved puts the file where fix never scans, and nothing reports the miss.
• Take the non-interactive collapse; a headless detector cannot ask or persist config.
• branch: frontmatter proves ownership, never the directory.
• The self-ignore guard is owed, not re-derived, including its invalid cases.
• Emit final values — normalization and ranking are fanout's internal pipeline, not producer input.

Today's producers are ai-slop, overengineering, review, testing. Neither audit-instructions nor audit-noise emits a findings file yet, so the first detector in each plugin carries the wiring.

Rejected: ceremonial-section removal

Cutting standalone ## Purpose / ## Why this file exists / ## What this skill is NOT / ## Sources / ## Cross-references / ## When NOT to use.

Rejected on three verified grounds: it contradicts audit-noise's protected-headings hard rule; it rests on a single external corpus against 88.8% house adoption; and those headings carry load-bearing boundary-fence prose in this fleet (compress and audit-noise both use "What this skill is NOT" for exactly that), where upstream's solo-operator premises differ.

The divergence is still real and unexplained, so it is filed as a question — answerable only by house-corpus content review, never by heading-name grep.

Out-of-scope

• Any new skill. The apply relay exists.
• Any detector that edits a description, when_to_use, or quoted trigger phrase.
• Length or token-count targets of any kind.
• Human-facing prose (docs-hygiene:write-for-humans).
• Word-level flavor trimming (docs-hygiene:compress), cross-file duplication (docs-hygiene:extract-ssot), whole-document worth (docs-hygiene:audit-derivability).
• Whether a detector should exist at all as a promoted routine — the autonomy plugin's routine-catalog concern.

Acceptance criteria

• D1, D2 shapes exist in claude-config:audit-instructions with tier assignments arguable from review's severity.md test.
• D3 shape exists in docs-hygiene:audit-noise's shape table.
• Each detector emits a findings file that review:fanout fix locates and applies on a test branch — verified end-to-end, not by inspection.
• No detector emits a finding whose remediation touches a description, when_to_use, or quoted trigger phrase; covered by a negative test.
• Protected-content list has one test per protected category proving no-flag.
• skill-quality:check passes for every modified skill, run against the source checkout.

Captured assumptions

• The 1024-char description cap is documented as enforced at package/upload on the API path; whether Claude Code validates filesystem/plugin skills against it locally is not stated, so the gate breach may be latent rather than live.
• disable-model-invocation: true skills are excluded from the shared listing budget.

Deferred questions

• Whether review:fanout fix handles prose-rewrite findings as well as it handles code findings. If it does not, a docs-hygiene:realign following the PLUGIN-PHILOSOPHY:62 verb contract becomes justified — but only then, and it would consume findings, never re-judge.
• Whether D1's "no proper noun, path, threshold" heuristic is precise enough to run deterministically, or whether it is inherently a judgment shape belonging in the audit's model-graded lane. Filed as its own investigation.

Execution shape: per-item PRs