# 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 field test 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 complete"**: 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 field test". 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.