playbooks/docs-hygiene: aihero course lane 7: authoring-time steering doctrine (writing-for-agents re-decision)

[kyle-sexton]

Context

Steering-section extension of the AI Hero course vetting effort — contract in docs/topics/pocock-course-lanes/PLAN.md (branch claude/plan-mode-discussion-55kszx); lanes 1–6 are #2899–#2904. This lane was filed from the steering-section session (branch claude/pocock-steering-course-00zkvd), which covered the course's nine steering lessons and re-evaluated the SSOT's writing-for-agents rejection.

The re-evaluation (2026-08-17, recorded in docs/upstream/mattpocock-skills.md) found the "rejected at parity or stronger" claim holds only for the audit/pruning half (docs-hygiene, claude-config, unhobble machinery). Two authoring-side gaps belong to this lane:

1. Authoring-time trigger gap. Upstream writing-for-agents fires at the writing moment ("Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md"). Our coverage is audit-shaped — read-only classifiers that fire on audit phrasing. Only skills have an authoring-moment home (playbooks:skill-authoring). No surface triggers on "write a doc the agent will consume", "add a pointer line to CLAUDE.md", or doc-plus-pointer extraction — the course's central exercise.
2. Completion-criteria doctrine has no home. Upstream's "Steps and completion criteria" section (clarity vs demand, premature completion, post-completion steps, legwork, split-by-sequence) maps to nothing in our surfaces, and the prior mapping row was silent on it — an oversight, not a recorded decision.

Also in scope: the "two loads" doctrine (cognitive load as a legitimate budget — "the human is the index... the price of human agency" — absent from our doctrine; PLUGIN-PHILOSOPHY's Instruction economy covers context load only), and the SSOT's tracked leading-words + negation strand (this lane is its disposition path; the event trigger stays until then).

Session decision (user-confirmed 2026-08-17): a NEW authoring skill — adapted and made our own, not vendored or wrapped — model-invoked on the writing moment, scope = any agent-consumed doc, pointing at existing audit skills rather than restating them. Recorded user concern: enforcement/triggering — the skill only helps if it actually fires at the writing moment; a hook that forces the load is probably overengineering, but trigger reliability must be a first-class design constraint with evals.

Proposed work

• Open with /planning:interview me per contract; lane discusses and decides — implementation leaves as filed work items
• Decide the skill's home plugin, name (naming grammar per PLUGIN-PHILOSOPHY), and description wording (description-as-trigger; trigger-phrase evals via evals:design + skill-quality:check validate-evals)
• Decide inline-vs-point boundaries against the incumbent surfaces (playbooks:skill-authoring, docs-hygiene:audit-progressive-disclosure tier model + pointer-quality criteria, claude-memory:audit) — encapsulation rules apply; ADRs 0004/0005/0008 constrain where doctrine may live
• Adapt: context-pointer wording doctrine (branches, front-loaded leading word), information hierarchy (steps vs reference, co-location, sprawl), completion criteria, when-to-split, leading words + negation (retires the tracked strand), two loads
• Coordinate the cross-skill invocation-phrasing finding (upstream .agents/invocation.md, PRs feat(planning): route incumbency-driven plan-review findings to incumbent mode #878/feat(typos-format): per-file typos autofix hook plugin #880) with lane 6's candidate — one owner, no duplication

Acceptance criteria

• Adopt/reject-with-reason/track-on-event decision rows in docs/upstream/aihero-course.md for lessons 1 (The Steering Map), 2 (Steering With A Pointer), 4 (Write A Skill — authoring half), 7 (Pruning — parity confirmations)
• Skill design decided (home, name, description, inline-vs-point map) with work items filed for implementation
• Trigger-reliability concern addressed in the design: an eval plan for the writing-moment trigger phrases
• Tracked leading-words strand disposition recorded in the SSOT
• docs/upstream/mattpocock-skills.md decomposition-table verdicts updated

References

• docs/upstream/mattpocock-skills.md — writing-for-agents section-by-section decomposition (added in the steering-section session)
• Upstream: skills/productivity/writing-for-agents/SKILL.md + SKILL-MECHANICS.md (v1.2.3 @ 84fdeff; verified current 2026-08-17)
• docs/topics/pocock-course-lanes/PLAN.md (contract; claim ladder; lane outputs)
• docs/topics/context-engineering-claude-5/ (prior art to reconcile, not duplicate)
• ADRs 0004, 0005, 0006, 0007, 0008 (docs/adr/)

Metadata

Field	Value
Category	unspecified
Area	playbooks, docs-hygiene, skill-quality, docs/upstream
Ecosystem	unspecified

[kyle-sexton]

Lane 7 closed (2026-08-17, session chain on claude/pocock-steering-course-00zkvd). Interview-first per contract: 2 rounds, 12 questions, register gate clean, user confirmed.

Decisions (rows in docs/topics/pocock-course-lanes/STEERING.md for lane 6's harvest): new skill docs-hygiene:write-for-agents — model-invoked, write-side complement to the audit siblings; scope generalized to any agent-consumed markdown (user-widened); completion criteria adopted at both moments; two-loads doctrine in the skill body + philosophy cross-ref; leading-words strand folded in; forcing hook REJECTED (trigger reliability gated by a shipped eval suite instead); vendoring REJECTED (adapted house skill).

Acceptance criteria: ☑ decision rows recorded (STEERING.md, pending lane 6's aihero-course.md collection per the round-1 Q3 decision) · ☑ skill design decided — Brief locked at docs/topics/authoring-steering-skill/PLAN.md, build filed as #2962 + #2963 · ☑ trigger-reliability eval plan in the design (plugin-eval suite gates the implementation PR) · ☑ leading-words strand disposition recorded in the SSOT (retires on #2962 merge; release trigger stands) · ☑ decomposition-table annotation landed (verdict cells flip to ADOPTED on merge).

Beyond the filed scope: the trigger-boundary question produced a docs-verified enumeration of 25 Claude Code instruction surfaces + 13 ecosystem analogues (docs/topics/authoring-steering-skill/design/agent-doc-surfaces.md), including changelog-falsified confirmation that Claude Code does not read AGENTS.md natively through v2.1.233.

Commits: de338ea4, 16f60ca4.

---

Generated by Claude Code