# iter cadence — audit/fieldtest/docwriter cadence restructure

**Date:** 2026-05-11
**Branch:** main
**Status:** DONE
**Tasks completed:** 5 of 5

## Summary

This iter sorts the milestone-close stretch of the pipeline into
three cadence buckets, packaged by stability-window rather than by
milestone-grain:

1. **Per-milestone-mandatory — `audit`.** Runs every milestone close.
   Architect drift review against DESIGN.md plus the three regression
   scripts (`bench/check.py`, `bench/compile_check.py`,
   `bench/cross_lang.py`). Step 3 ("Optional rustdoc audit") and the
   `ailang-docwriter` cross-reference are removed; the rustdoc
   warning line is gone from the Handoff Contract and the Common
   Rationalisations table. Audit is now purely drift + bench.
2. **Boss-judgment post-audit — `fieldtest`.** Fires only when the
   orchestrator decides the iteration is correct and wants a field
   test, after audit closes clean (or with `ratify`-d drift only).
   Trigger is reframed from "audit closes" to "Boss judgment call";
   the expected finding shape (simple bugs route via `debug`,
   catastrophic architecture problems route via next `brainstorm`)
   is named explicitly. Cross-references add the ordering rule:
   fieldtest runs *before* docwriter.
3. **Boss-judgment post-fieldtest — `docwriter`.** New skill at
   `skills/docwriter/SKILL.md`. Boss-dispatched only, never
   triggered by audit closing. Pre-condition is clean audit plus any
   pending fieldtest. The agent (`ailang-docwriter`) carries the
   substantive rustdoc rules; the SKILL.md only governs trigger and
   dispatch. Symlinks added at `.claude/skills/docwriter` and
   `.claude/agents/docwriter`.

`skills/README.md` is the one place that visibly mirrors the new
three-bucket taxonomy: the skill table grew from six rows to seven,
the pipeline diagram extends past `audit --(clean)-->` into
fieldtest and docwriter as two distinct Boss-decision points, and
the agent roster moves `ailang-docwriter` into its own dispatch
group.

## Per-task subjects

- iter cadence.1: skills/docwriter — new Boss-dispatched skill (split from audit)
- iter cadence.2: skills/audit — drop docwriter step (now own skill)
- iter cadence.3: skills/fieldtest — Boss-dispatched framing + ordering note
- iter cadence.3-fix: address quality-review minors (frontmatter desc + cross-ref path)
- iter cadence.4: skills/README — three-bucket cadence taxonomy
- iter cadence.4-fix: drop stale audit-dispatches-docwriter parenthetical (README Conventions)
- iter cadence.4-fix: address quality-review importants + German-loanword sweep (English-only in-tree)
- iter cadence.5: per-iter journal + INDEX

## Lesson

**Packaging cadence by stability-window outperforms packaging by
milestone-grain.** The previous arrangement bundled rustdoc cleanup
into `audit` as an "optional Step 3", which papered over the real
mismatch: rustdoc rot is a *post-stability* concern (documenting
something that gets rewritten three iterations later is waste),
while drift review and bench regression are per-iteration concerns
(letting them slip even one milestone compounds). Bundling those
two cadences inside one skill made the optional step easy to skip
on every milestone, which is exactly the failure mode the skill
discipline exists to prevent. Splitting docwriter out into its own
Boss-dispatched skill makes the cadence honest: audit is
non-negotiable per milestone, docwriter is non-negotiable per
*stability window*. The fieldtest framing flip — from "fires when
audit closes" to "Boss judgment after audit closes" — is the same
refactor at a smaller scale: the milestone clock was not the right
trigger; the orchestrator's judgement that the iteration is
*complete* is.

## Concerns

None worth carrying forward. Three quality-review-fix follow-ups on
cadence.3 and cadence.4 (frontmatter description drift, stale
audit-dispatches-docwriter parenthetical, one German-loanword in
in-tree text) — all caught by the standard implement-skill
two-stage review and resolved inline.

## Known debt

- The agent file `skills/docwriter/agents/ailang-docwriter.md` was
  moved from `skills/audit/agents/` by the user before this iter
  began. Its standing reading list still names `skills/audit` as
  its home in one or two phrasings; a sweep of the agent's
  cross-references is a candidate tidy iteration but did not
  block this iter's narrower SKILL.md reshuffle.
- `docs/specs/2026-05-11-audit-fieldtest-docwriter-cadence.md` is a
  dated artefact — the spec describes the design at time of
  writing and is not retroactively updated as the implementation
  shipped. Per the or.1 convention, the per-iter journal is the
  running annotation.

## Blocked detail

N/A — DONE.

## Commits

`e351969^..HEAD` (8 commits including 3 quality-review-fix
follow-ups across cadence.3 and cadence.4).
