AILang/docs/specs/0012-audit-fieldtest-docwriter-cadence.md

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.