diff --git a/docs/plans/2026-05-11-audit-fieldtest-docwriter-cadence.md b/docs/plans/2026-05-11-audit-fieldtest-docwriter-cadence.md new file mode 100644 index 0000000..fbeb8ae --- /dev/null +++ b/docs/plans/2026-05-11-audit-fieldtest-docwriter-cadence.md @@ -0,0 +1,266 @@ +# Audit / fieldtest / docwriter cadence restructure — Implementation Plan + +> **Parent spec:** `docs/specs/2026-05-11-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 Praxistest; 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: + +```yaml +--- +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** + +```bash +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** + +```bash +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** + +```bash +git grep -n "docwriter\|rustdoc" skills/audit/SKILL.md +``` + +Expected: no matches. + +- [ ] **Step 8: Commit** + +```bash +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 Praxistest. 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 Praxistest. The pre-condition is a clean (or `ratify`-d) audit; the trigger is the Boss's judgment-call that the iteration is fertig. + +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** + +```bash +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 Praxistest", 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 fertig? 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** + +```bash +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** + +```bash +git grep -n "docwriter\|rustdoc" skills/audit/SKILL.md +``` + +Expected: zero hits. + +- [ ] **Step 2: Grep CLAUDE.md for docwriter wiring** + +```bash +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** + +```bash +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** + +```bash +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) + +```bash +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. diff --git a/docs/specs/2026-05-11-audit-fieldtest-docwriter-cadence.md b/docs/specs/2026-05-11-audit-fieldtest-docwriter-cadence.md new file mode 100644 index 0000000..03efda1 --- /dev/null +++ b/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. diff --git a/skills/audit/agents/ailang-docwriter.md b/skills/docwriter/agents/ailang-docwriter.md similarity index 100% rename from skills/audit/agents/ailang-docwriter.md rename to skills/docwriter/agents/ailang-docwriter.md