melodic-software · kyle-sexton · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026
diff --git a/docs/CATALOG.md b/docs/CATALOG.md
@@ -67,7 +67,7 @@ plugin manifests and kept in sync by CI — never hand-edit it; the category voc
 
 - [`bug-report`](../plugins/bug-report) — Produces a structured five-field bug report — title, steps to reproduce, expected vs actual, severity with justification, and suggested fix location — from an informal defect description. Read-only by default: it emits the report and never edits code, opens a PR, or files an issue on its own.
 - [`debugging`](../plugins/debugging) — Debug observed failures via a disciplined six-phase loop: build a fast deterministic reproduction signal, reproduce, rank falsifiable hypotheses, instrument, fix with a regression test, then clean up and post-mortem.
-- [`docs-hygiene`](../plugins/docs-hygiene) — Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), audit-derivability (classify whether a whole document earns its existence — could a fresh agent re-derive it from the code?), and audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects).
+- [`docs-hygiene`](../plugins/docs-hygiene) — Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), audit-derivability (classify whether a whole document earns its existence — could a fresh agent re-derive it from the code?), audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects), and write-for-agents (authoring-time doctrine that fires while agent-consumed markdown is being written).
 - [`code-tidying`](../plugins/code-tidying) — Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps recently changed files through grouped, dependency-ordered simplification waves with a never-drop deferred-items contract; /code-tidying:dissolve-comments enforces self-describing expressive code over a diff — deletes zero-information comments, dissolves code-expressible ones into names and structure behind a tests gate (safe mode restricts applied edits to removals), and keeps only terse load-bearing comments code cannot express; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill.
 - [`coupling`](../plugins/coupling) — Iteratively reduces coupling in any repository at any altitude — documents, code modules, applications, or repositories: scans for change-transmitting dependencies typed against a coupling model (strength ladder, connascence, volatility weighting), verifies every finding, applies a budgeted batch of safe behavior-preserving reductions, and keeps a durable ledger so structural candidates route to design lanes and repeated runs continue where the last stopped.
 - [`repo-hygiene`](../plugins/repo-hygiene) — Repo hygiene action-router: /repo-hygiene:clean sweeps reclaimable caches, build artifacts, and stale git metadata, and can realign the working tree to a fresh-pull state — dry-run-first, with destructive tiers gated behind explicit confirmation and a session-scoped destructive-command guard. Ecosystem targets are detected at runtime; secrets, runtime dependencies, and skill data are preserved by default.

diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/PLUGIN-PHILOSOPHY.md
@@ -567,7 +567,9 @@ without the instruction, delete it or convert it to a hook"
 applied the same doctrine to Claude Code itself, removing over 80% of its system prompt for the
 Opus 5 / Fable 5 generation with no measurable loss on its coding evaluations
 ([The new rules of context engineering for Claude 5 generation models](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models),
-verified 2026-08-08). Four rules follow:
+verified 2026-08-08). Context load is not the only budget: the human maintainer's cognitive load
+is its sibling constraint, and the write-time doctrine budgeting both lives in
+`docs-hygiene:write-for-agents`. Four rules follow:
 
 - **Evidence-gated additions.** A new standing instruction requires observed, repeated stumble
   evidence against the current model — the same failure seen more than once — never anticipation

diff --git a/docs/SKILL-CHEAT-SHEET.md b/docs/SKILL-CHEAT-SHEET.md
@@ -184,6 +184,7 @@ owned by [docs/CATALOG-TAXONOMY.md](CATALOG-TAXONOMY.md).
 | [`/docs-hygiene:compress`](../plugins/docs-hygiene/skills/compress/SKILL.md) | `docs-hygiene` | Tighten markdown by dropping flavor while preserving every directive |
 | [`/docs-hygiene:extract-ssot`](../plugins/docs-hygiene/skills/extract-ssot/SKILL.md) | `docs-hygiene` | Deduplicate repeated prose into one named source of truth |
 | [`/docs-hygiene:rename-references`](../plugins/docs-hygiene/skills/rename-references/SKILL.md) | `docs-hygiene` | Sweep stale references after renames, including forms grep misses |
+| [`/docs-hygiene:write-for-agents`](../plugins/docs-hygiene/skills/write-for-agents/SKILL.md) | `docs-hygiene` | Authoring-time doctrine for agent-consumed markdown |
 | [`/education:explain`](../plugins/education/skills/explain/SKILL.md) | `education` | Explain any concept or the last response in genuinely plain words |
 | [`/education:quiz-me`](../plugins/education/skills/quiz-me/SKILL.md) | `education` | Generate a post-change report with a quiz verifying you absorbed the work |
 | [`/education:teach`](../plugins/education/skills/teach/SKILL.md) | `education` | Multi-session learning coach for general topics or repo-grounded concepts |

diff --git a/docs/upstream/mattpocock-skills.md b/docs/upstream/mattpocock-skills.md
@@ -86,8 +86,8 @@ design-locked as `docs-hygiene:write-for-agents`
 (contract: `docs/specs/write-for-agents-brief.md`; build:
 [#2962](https://github.com/melodic-software/claude-code-plugins/issues/2962) +
 [#2963](https://github.com/melodic-software/claude-code-plugins/issues/2963), the audit-side
-completion-criteria criterion). The GAP/PARTIAL verdict cells below flip to ADOPTED when #2962
-merges.
+completion-criteria criterion). **#2962 built (docs-hygiene 0.17.0)**: the gap-1/2 verdict
+cells below are ADOPTED; #2963's audit-side criterion remains the one open follow-on.
 
 **Lane 8 closed 2026-08-17**: gap 3 (invocation) is decided — invocation-mode rubric homed at
 `docs/conventions/invocation-mode/README.md` (model-invoked default + three exception classes;
@@ -97,12 +97,12 @@ flip as [#2969](https://github.com/melodic-software/claude-code-plugins/issues/2
 
 | Upstream section | Our surface | Verdict |
 |---|---|---|
-| Context pointers (wording-as-trigger, branches, front-loaded leading word) | `docs-hygiene:audit-progressive-disclosure` (blind-pointer finding + six pointer-quality criteria in its tier model) — audit-time; `playbooks:skill-authoring` description-as-trigger — skills only | PARTIAL — no authoring-time home for non-skill agent docs (gap 1 → #2909) |
-| The two loads (context load / cognitive load) | PLUGIN-PHILOSOPHY Instruction economy (context load only) | GAP — cognitive-load-as-budget doctrine absent (→ #2909) |
-| Information hierarchy (steps vs reference, ladder, co-location, sprawl) | three-tier load-cost model ≈ the ladder | PARTIAL — co-location and steps-vs-reference distinction absent (→ #2909) |
-| Steps and completion criteria (clarity, demand, premature completion, post-completion steps, legwork) | none — the prior mapping was silent on this section (oversight, not a decision) | GAP (gap 2 → #2909) |
-| When to split (by sequence / by invocation) | tier-model split triggers are size/concern-based only; invocation axis now owned by the rubric | PARTIAL — sequence half rides #2962; invocation half ADOPTED (lane 8: `docs/conventions/invocation-mode/`) |
-| Leading words + negation | tracked strand (below) | TRACKED — disposition path #2909 |
+| Context pointers (wording-as-trigger, branches, front-loaded leading word) | `docs-hygiene:write-for-agents` (authoring-time, branch-covering front-loaded pointer doctrine) + `audit-progressive-disclosure` (audit-time criteria) + `playbooks:skill-authoring` (skills) | ADOPTED (adapted; #2962, docs-hygiene 0.17.0) |
+| The two loads (context load / cognitive load) | `write-for-agents` "Budget both loads" + PLUGIN-PHILOSOPHY Instruction-economy cross-reference | ADOPTED (adapted; #2962) |
+| Information hierarchy (steps vs reference, ladder, co-location, sprawl) | `write-for-agents` steps-vs-reference + co-location doctrine; three-tier load-cost model carries the ladder | ADOPTED (adapted; #2962) |
+| Steps and completion criteria (clarity, demand, premature completion, post-completion steps, legwork) | `write-for-agents` "Give every step a completion criterion" (write-side); audit-side criterion rides #2963 | ADOPTED (adapted; #2962 — audit-side pending #2963) |
+| When to split (by sequence / by invocation) | `write-for-agents` split-by-sequence; invocation axis owned by the rubric (`docs/conventions/invocation-mode/`), pointed at, never restated | ADOPTED (both halves; #2962 + lane 8) |
+| Leading words + negation | `write-for-agents` "Prompt the positive" | ADOPTED (adapted; #2962 — tracked strand retired below) |
 | Pruning: single source of truth | `docs-hygiene:extract-ssot` + the topic-docs single-home rule | PARITY+ |
 | Pruning: environment-as-truth ("cache") | `docs-hygiene:audit-derivability` (keep-as-derivation-cache verdict + drift control) | PARITY+ (stronger — cache without drift control is not a cache) |
 | Pruning: relevance / sediment | `claude-config:audit-instructions`, `session-flow:reanchor`, `docs-hygiene:rename-references`, `review` doc-drift-detector | PARITY |
@@ -126,9 +126,9 @@ triggers stand until the owning lane records the disposition:
   negation/negative-space port deferred from that session's gap scan) — this record
   cross-links that deferral rather than opening a second ledger entry. Trigger: a
   mattpocock/skills release whose changeset names `writing-for-agents`.
-  **Disposition (lane 7, 2026-08-17): adopted into the `docs-hygiene:write-for-agents` design
-  (#2962) — this row retires when that implementation merges; the release trigger stands until
-  then.**
+  **RETIRED (2026-08-18): adopted as `write-for-agents` "Prompt the positive"
+  (docs-hygiene 0.17.0, #2962). The release-named recheck trigger now applies only as an
+  ordinary attribution-table row concern, not an open strand.**
 - **Invocation-reach invariant** (upstream `SKILL-MECHANICS.md:10`: a user-invoked skill —
   `disable-model-invocation: true` — can be invoked by no other skill).
   **Disposition (lane 8, 2026-08-17): CONFIRMED against current official docs**

diff --git a/plugins/docs-hygiene/.claude-plugin/plugin.json b/plugins/docs-hygiene/.claude-plugin/plugin.json
@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "docs-hygiene",
-  "version": "0.16.1",
-  "description": "Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), audit-derivability (classify whether a whole document earns its existence \u2014 could a fresh agent re-derive it from the code?), and audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects).",
+  "version": "0.17.0",
+  "description": "Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), audit-derivability (classify whether a whole document earns its existence \u2014 could a fresh agent re-derive it from the code?), audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects), and write-for-agents (authoring-time doctrine that fires while agent-consumed markdown is being written).",
   "author": {
     "name": "Melodic Software",
     "email": "info@melodicsoftware.com"

diff --git a/plugins/docs-hygiene/CHANGELOG.md b/plugins/docs-hygiene/CHANGELOG.md
@@ -1,5 +1,27 @@
 # Changelog — docs-hygiene plugin
 
+## [0.17.0]
+
+### Added
+
+- New skill `write-for-agents`: the write-side complement to the audit skills —
+  authoring-time doctrine firing while agent-consumed markdown is written
+  (CLAUDE.md/AGENTS.md content, `.claude/rules` files, agent-loaded reference/context
+  docs, navigation-pointer lines, doc-plus-pointer extractions). Inlines the adapted
+  doctrine (two-loads budgeting, branch-covering front-loaded pointers,
+  steps-vs-reference separation with co-location, observable completion criteria with
+  premature-completion/post-completion/legwork guards, split-by-sequence,
+  positive-form prompting) and points at the audit siblings, the invocation-mode
+  rubric, and `curate-language` rather than restating them; the
+  restructure-before-pointer caveat is stated inline pending its audit-side home
+  (#2987). Ships `reference/agent-doc-surfaces.md`
+  (docs-verified auto-read surface table, Claude Code v2.1.233 baseline, plus
+  other-ecosystem analogues) and a 9-case eval suite gating trigger reliability
+  (5 positive writing-moment cases, 3 negative route-away controls, 1 doctrine
+  behavior case). Route-away fence: SKILL.md authoring, audit requests, and
+  human-facing docs stay with their incumbent owners. Design contract:
+  `docs/specs/write-for-agents-brief.md` (course lane 7, #2909); build issue #2962.
+
 ## [0.16.1]
 
 ### Changed

diff --git a/plugins/docs-hygiene/README.md b/plugins/docs-hygiene/README.md
@@ -3,8 +3,8 @@
 A Claude Code plugin bundling documentation-hygiene skills — one cohesive
 capability: keeping a repository's tracked markdown lean, deduplicated, and
 free of decayed references. Each skill is invocable on its own; together they
-cover the flavor, noise, duplication, boundary, rename, worth, and loading
-axes of doc upkeep.
+cover the flavor, noise, duplication, boundary, rename, worth, loading,
+and authoring axes of doc upkeep.
 
 ## The skills
 
@@ -17,6 +17,7 @@ axes of doc upkeep.
 | `/docs-hygiene:rename-references` | Sweeps stale references after renames — the forms plain token grep misses: slash-command tokens, relative paths from moved files, frontmatter chains and globs — via a 12-form pattern library with audit, half-rename detection, and apply modes. |
 | `/docs-hygiene:audit-derivability` | Read-only, document-level worth classifier: could a fresh agent re-derive this whole document from the code, config, and structure? Weighs derivability, re-derivation cost, drift risk, and fact ownership into a verdict (delete, convert-to-pointer, keep-as-derivation-cache, keep-owns-facts), splits it by audience, and confirms load-bearing deletions with a fresh-context spot-test. Where the other five trim *inside* a doc, this decides whether the doc should exist. |
 | `/docs-hygiene:audit-progressive-disclosure` | Read-only progressive-disclosure classifier: grades agent-facing instruction markdown against a three-tier load-cost model (always-loaded / invocation-loaded / on-demand) and emits seven finding shapes in two lanes — split opportunities (oversize, mixed-concerns, tier-mismatch) and hub/spoke structure defects (blind-pointer, orphan-spoke, deep-nesting, missing-toc) — with tiered treatment guidance. Thresholds are advisory and Anthropic-prescribed; a deterministic `detect.sh` emits the facts, the judgment layer adjudicates. |
+| `/docs-hygiene:write-for-agents` | The write-side complement to the audit skills: authoring-time doctrine that fires while agent-consumed markdown is being written (CLAUDE.md/AGENTS.md content, rules files, agent-loaded reference docs, pointer lines, doc-plus-pointer extractions) — two-loads budgeting, branch-covering pointers, steps-vs-reference separation, observable completion criteria, split-by-sequence, positive-form prompting — with a verified auto-read surface reference and a trigger-reliability eval suite. |
 
 ## Requirements