spec+plan: audit/fieldtest/docwriter cadence restructure

docs/specs/2026-05-11-audit-fieldtest-docwriter-cadence.md

@@ -0,0 +1,123 @@
+# Audit / fieldtest / docwriter cadence restructure — 2026-05-11
+
+**Status:** Approved (orchestrator + user, chat-derived)
+**Scope:** skill-system reshuffle; no code touched
+
+## Motivation
+
+Today `audit/SKILL.md` bundles three checks under one milestone-close
+trigger:
+
+1. **architect** drift review
+2. **bencher** regression check
+3. **docwriter** rustdoc cleanup (Step 3, "optional")
+
+Fieldtest is a separate skill but is described as following audit by
+default for any milestone that touched user-visible surface.
+
+The trio mixes three different cadence-needs:
+
+- **drift** and **regression** are intrinsic to a milestone close —
+  they compound silently across milestones if deferred, so they
+  *must* run at every close.
+- **fieldtest** measures usability-belief — it's a Praxistest run when
+  the orchestrator believes the iteration is correct. Findings are
+  either simple bugs or catastrophic architecture problems; both
+  decay slowly, so the cadence doesn't have to be per-milestone.
+- **docwriter** documents stable API surface. Writing rustdoc onto
+  code that the next iteration may rewrite is wasted work. The right
+  cadence is *post-stability*, not *per-milestone*.
+
+The current packaging forces these three different cadences into one
+mandatory pipeline step. This spec splits them.
+
+## Decision
+
+Three Boss-orchestrated buckets:
+
+1. **Per-milestone, mandatory (audit)**: architect + bencher only.
+2. **Boss-judgment, post-audit, "the iter is fertig"**: fieldtest.
+3. **Boss-judgment, post-fieldtest, "API surface has settled"**:
+   docwriter.
+
+Sequence: `audit → (Boss: ready?) → fieldtest → (Boss: stable?) →
+docwriter`. The two Boss-gated steps share the same "don't produce
+output for code that may still be rewritten" principle; their
+stability windows differ (iter-stable vs. surface-stable).
+
+## Concrete changes
+
+### docwriter becomes its own skill
+
+- Create `skills/docwriter/SKILL.md` (new).
+- `skills/docwriter/agents/ailang-docwriter.md` already exists
+  (moved by user from `skills/audit/agents/`).
+- Frontmatter description: "Use when API surface has stabilized
+  across one or more milestones and rustdoc lag is suspected. NOT a
+  per-milestone step; Boss-dispatched only."
+- The SKILL.md body is short — mostly a pointer to the agent's own
+  carrier contract plus the trigger criteria. No mandatory schedule.
+- Symlinks: add `.claude/skills/docwriter → ../../skills/docwriter`
+  and `.claude/agents/docwriter → ../../skills/docwriter/agents`.
+
+### audit shrinks
+
+- `skills/audit/SKILL.md`: remove "Step 3 — Optional rustdoc audit".
+- Remove `ailang-docwriter` from the "Agents dispatched" list.
+- Remove the "Rustdoc warnings are just style" row from Common
+  Rationalisations.
+- Frontmatter description: now reads "architect drift review +
+  three regression scripts" — already correct since the
+  user-applied tweak.
+
+### fieldtest framing sharpened
+
+- `skills/fieldtest/SKILL.md`: trigger section reframes from "after
+  audit closes cleanly" (which sounded automatic) to "Boss-dispatched
+  after audit closes cleanly, when the orchestrator believes the
+  iteration is correct and wants a Praxistest". The pre-condition is
+  still a clean audit; the trigger is the Boss's judgment-call.
+- Add a one-line note on what kind of findings to expect: either
+  simple bugs (→ debug → implement mini) or catastrophic
+  architecture problems (→ next brainstorm). Friction items are
+  also possible; the routing table stays.
+
+### skills/README.md updated
+
+- Skill table: change audit row's description; add docwriter row;
+  refine fieldtest row to mention Boss-dispatch explicitly.
+- Agent roster: move `ailang-docwriter` from the audit group to a
+  new docwriter group.
+- Pipeline diagram: extend with the late `→ (Boss judgment) →
+  docwriter` branch.
+
+### CLAUDE.md cross-ref check
+
+- `Roles of docs/...` table mentions audit / journals / specs /
+  plans / WhatsNew — does not name docwriter or rustdoc
+  scheduling. No edit needed.
+- Skill system overview: see if docwriter is mentioned. If yes,
+  refresh the wording. If no, no edit.
+
+## Out of scope
+
+- Any change to the agents' own behaviour (architect, bencher,
+  fieldtester, docwriter agent files).
+- Code changes. This is a config/docs restructure only.
+- The `Rustdoc warning sweep` P2 roadmap item — it stays where it
+  is; in fact this restructure makes it the canonical example of
+  "Boss-dispatched docwriter".
+
+## Acceptance
+
+- `skills/docwriter/SKILL.md` exists and is reachable via
+  `.claude/skills/docwriter`.
+- `skills/audit/SKILL.md` no longer mentions docwriter or Step 3.
+- `skills/fieldtest/SKILL.md` describes Boss-dispatch trigger
+  language.
+- `skills/README.md` reflects the new three-bucket cadence.
+- `git grep -n "Step 3 — Optional rustdoc"` in `skills/` returns
+  nothing.
+- `git grep -n "docwriter" docs/CLAUDE.md skills/README.md
+  skills/audit/SKILL.md skills/fieldtest/SKILL.md` only matches
+  the new wording, not orphans from the old packaging.