AILang/docs/plans/0031-audit-fieldtest-docwriter-cadence.md

Audit / fieldtest / docwriter cadence restructure — Implementation Plan

Parent spec: docs/specs/0012-audit-fieldtest-docwriter-cadence.md

For agentic workers: REQUIRED SUB-SKILL: use skills/implement to run this plan. Steps use - [ ] checkboxes for tracking.

Goal: Move docwriter into its own Boss-dispatched skill; shrink audit to architect+bencher; sharpen fieldtest framing as Boss-dispatched post-audit field test; refresh skills/README.md cadence taxonomy.

Architecture: Pure config/docs reshuffle, no code. Three Boss-orchestrated buckets: per-milestone-mandatory (audit), Boss-judgment post-audit (fieldtest), Boss-judgment post-fieldtest (docwriter). The sequence forms audit → (Boss: ready?) → fieldtest → (Boss: stable?) → docwriter.

Tech Stack: Markdown only. Files under skills/ and .claude/.

---

Files this plan creates or modifies

• Create: skills/docwriter/SKILL.md — short SKILL.md pointing at the agent's own carrier contract; Boss-dispatched trigger criteria; no mandatory schedule.
• Create: .claude/skills/docwriter (symlink → ../../skills/docwriter).
• Create: .claude/agents/docwriter (symlink → ../../skills/docwriter/agents).
• Modify: skills/audit/SKILL.md — drop Step 3, drop docwriter from agents-dispatched, drop the rustdoc Common-Rationalisation row, update cross-references.
• Modify: skills/fieldtest/SKILL.md — sharpen trigger to Boss-dispatched; name the expected finding-shape (simple bugs or catastrophic architecture problems).
• Modify: skills/README.md — skill table: refine audit row, add docwriter row, refine fieldtest row; pipeline diagram extended with the late → docwriter branch; agent roster moves ailang-docwriter into a new docwriter group.

Already-present (no action): skills/docwriter/agents/ailang-docwriter.md (user-moved from skills/audit/agents/).

---

Task 1 — Create skills/docwriter/SKILL.md + symlinks

Files:

• Create: skills/docwriter/SKILL.md

• Create: .claude/skills/docwriter (symlink)

• Create: .claude/agents/docwriter (symlink)

• Step 1: Write skills/docwriter/SKILL.md with the structure below (frontmatter + body). Length target ≤ 90 lines.

Frontmatter:

---
name: docwriter
description: Use when the API surface of one or more crates has stabilized across recent milestones and rustdoc lag is suspected (cargo doc --no-deps shows accumulated warnings, or a newcomer would not be able to navigate the crate from `cargo doc --open` without DESIGN.md). NOT a per-milestone step; Boss-dispatched only, after audit closes clean and after any pending fieldtest has run.
---

Body must cover, in order:

1. > Violating the letter of these rules is violating the spirit. lead-in.

2. Overview — one paragraph naming the cadence question this skill answers: rustdoc rot accumulates silently; documenting unstable code is waste; the right moment is post-stability. Reference the cadence taxonomy (3 buckets) without re-explaining it.

3. When to Use / Skipping — Boss-dispatched only. Trigger conditions: (a) cargo doc --no-deps shows accumulated warnings across multiple crates after a stability window, (b) a roadmap entry like "Rustdoc warning sweep" has matured, (c) onboarding-readability check. Explicitly: NOT triggered by audit closing.

4. The Iron Law — code-fenced:

   DOCWRITER IS POST-STABILITY, NOT PER-MILESTONE.
   NO API CHANGES — DOCS ONLY.
   IF THE CODE STILL FEELS LIKE IT MIGHT GET REWRITTEN, DON'T DOCUMENT IT YET.
   

5. Dispatch — one paragraph: orchestrator dispatches ailang-docwriter with crate_scope, warning_target, optional priority_items. The agent carries the rules; this SKILL.md only governs trigger + dispatch.

6. Handoff Contract — table mirroring the agent's carrier (crate_scope, warning_target, priority_items as in / Status, files_touched, warnings_cleared, findings as out).

7. Cross-references — point at skills/docwriter/agents/ailang-docwriter.md for the substantive process; point at skills/audit/SKILL.md (the pre-condition: audit must have closed clean) and skills/fieldtest/SKILL.md (run any pending fieldtest first).

• Step 2: Create the symlinks

ln -s ../../skills/docwriter .claude/skills/docwriter
ln -s ../../skills/docwriter/agents .claude/agents/docwriter
ls -la .claude/skills/docwriter .claude/agents/docwriter

Expected output: both lrwxrwxrwx lines pointing at the right targets.

• Step 3: Commit

git add skills/docwriter/SKILL.md .claude/skills/docwriter .claude/agents/docwriter
git commit -m "iter cadence.1: skills/docwriter — new Boss-dispatched skill (split from audit)"

---

Task 2 — Shrink skills/audit/SKILL.md

Files:

• Modify: skills/audit/SKILL.md

• Step 1: Remove Step 3 ("Optional rustdoc audit") entirely. Renumber Step 4 → Step 3, Step 5 → Step 4.

• Step 2: Update "Combine architect drift items + bench results + rustdoc warnings" in the (now-Step-3) Classify-and-report paragraph: drop the + rustdoc warnings clause. The classification stays fix / ratify / carry-on.

• Step 3: Update the Handoff Contract table — remove the rustdoc_warnings row.

• Step 4: Remove the Common-Rationalisation row "Rustdoc warnings are just style, no real drift".

• Step 5: Update "Agents dispatched" cross-references — remove the skills/audit/agents/ailang-docwriter.md bullet entirely. The architect and bencher bullets remain.

• Step 6: Update the "Project source" cross-reference if it names rustdoc — re-read the paragraph and decide. Current wording mentions "Iter cycle / Tidy-iter at family boundaries" and "Performance regressions"; if neither names rustdoc, leave the paragraph as-is.

• Step 7: Sanity-grep

git grep -n "docwriter\|rustdoc" skills/audit/SKILL.md

Expected: no matches.

• Step 8: Commit

git add skills/audit/SKILL.md
git commit -m "iter cadence.2: skills/audit — drop docwriter step (now own skill)"

---

Task 3 — Sharpen skills/fieldtest/SKILL.md

Files:

• Modify: skills/fieldtest/SKILL.md

• Step 1: Rewrite the "When to Use / Skipping" trigger section to frame fieldtest as a Boss-dispatched field test. Replace the current "Triggers:" bullet "A milestone has just closed audit cleanly (or with ratify-d drift only)." with:

Boss-dispatched after audit closes cleanly, when the orchestrator believes the iteration is correct and wants a field test. The pre-condition is a clean (or ratify-d) audit; the trigger is the Boss's judgment-call that the iteration is complete.

Keep the other two trigger bullets ("A shipped feature is suspected of being LLM-hostile…" / "A user-facing surface change…") — they already match Boss-judgment.

• Step 2: Add a one-line note on expected finding shape, immediately after the trigger bullets. Wording:

Findings cluster around two shapes — simple bugs (route via debug → implement mini) or catastrophic architecture problems (route via next brainstorm). Friction and spec-gap items are also possible; the routing table below applies in all cases.

• Step 3: Add an explicit ordering note in the Cross-references or Overview section: fieldtest runs before docwriter; docwriter happens at a later, longer stability window. One line is enough.

• Step 4: Sanity-check the rest of the document — Iron Law, Process, Handoff Contract, Common Rationalisations should remain unchanged. The Boss-judgment framing is the only conceptual shift.

• Step 5: Commit

git add skills/fieldtest/SKILL.md
git commit -m "iter cadence.3: skills/fieldtest — Boss-dispatched framing + ordering note"

---

Task 4 — Refresh skills/README.md cadence taxonomy

Files:

• Modify: skills/README.md

• Step 1: Update the skill table ("The six skills" — note it's now seven; rename the section heading if appropriate).

  • audit row's Output and Mandatory? are correct; refine the description if it implies rustdoc. The audit description should mirror its frontmatter: "Architect drift review + three regression scripts."
  • Insert a new row for docwriter between audit and fieldtest:
    • Trigger: "API surface stabilized; rustdoc lag suspected"
    • Output: "rustdoc updates in /// and //!"
    • Mandatory?: "No — Boss-dispatched only"
  • fieldtest row description should explicitly say "Boss-dispatched post-audit field test", not "after audit closes".
  • Bump the heading from "The six skills" to "The seven skills".

• Step 2: Update the pipeline diagram to reflect the new sequence:

[new milestone]                                  [bug observed]
       |                                                |
       v                                                v
 brainstorm  ->  plan  ->  implement                  debug -> implement (mini)
       (per iteration loop)
                  |
       [milestone close]
                  |
                  v
                audit  --(drift)--> plan + implement (tidy iteration)
                       --(ratify)-> JOURNAL + --update-baseline
                       --(clean)-+
                                 |
                       [Boss: iter complete? if surface-touch:]
                                 v
                            fieldtest --(bug)------> debug -> implement (mini)
                                      --(friction)-> brainstorm OR plan (tidy)
                                      --(spec_gap)-> ratify OR tighten DESIGN.md
                                      --(clean)----+
                                                   |
                                       [Boss: surface stable across N milestones?]
                                                   v
                                              docwriter (rustdoc sweep)
                                                   |
                                                   v
                                            next milestone

(Keep the existing ASCII style; the diagram above is the target shape.)

• Step 3: Update the agent roster table — move the ailang-docwriter row out of the audit group into a new docwriter group (its Path becomes docwriter/agents/; Dispatched by skill becomes docwriter).

• Step 4: Discovery section — bump the symlink list under "Skills are reachable" and "Agents are reachable" to include docwriter (the symlinks were created in Task 1).

• Step 5: Commit

git add skills/README.md
git commit -m "iter cadence.4: skills/README — three-bucket cadence taxonomy"

---

Task 5 — Final cross-ref verification

Files:

• No new edits expected. Verification only; if a grep hits an orphan, fix inline.

• Step 1: Grep for orphaned docwriter references in audit

git grep -n "docwriter\|rustdoc" skills/audit/SKILL.md

Expected: zero hits.

• Step 2: Grep CLAUDE.md for docwriter wiring

git grep -n "docwriter" CLAUDE.md

If hits exist, evaluate whether the wording still applies under the new packaging. If not, fix inline.

• Step 3: Grep the symlinks

ls -la .claude/skills/docwriter .claude/agents/docwriter
test -L .claude/skills/docwriter && test -L .claude/agents/docwriter && echo OK

Expected: both symlinks present, "OK" printed.

• Step 4: Final read-through

Read skills/audit/SKILL.md, skills/fieldtest/SKILL.md, skills/docwriter/SKILL.md, and skills/README.md end-to-end. Confirm:

• audit no longer mentions docwriter

• fieldtest's trigger reads as Boss-dispatched

• docwriter's SKILL.md is reachable and complete

• README's skill table and pipeline diagram match the three-bucket cadence

• Step 5: Per-iter journal

Append docs/journals/2026-05-11-iter-cadence.md mirroring the per-iter journal style (or.1, fieldtest entries are templates). Include: per-task subjects, summary of the three-bucket cadence, one-line lesson on packaging cadence by stability-window rather than milestone-grain.

Update docs/journals/INDEX.md with one new line.

• Step 6: Commit

git add docs/journals/2026-05-11-iter-cadence.md docs/journals/INDEX.md
git commit -m "iter cadence.5: per-iter journal + INDEX"

---

Acceptance check (run at end)

git grep -nE "Step 3 — Optional rustdoc" skills/         # zero hits
git grep -nE "ailang-docwriter" skills/audit/             # zero hits
ls -la .claude/skills/docwriter .claude/agents/docwriter # both symlinks

All three expectations green → iter cadence is done.