Brummel
832375f2ac
All 176 files in the four accumulating directories now use a zero-padded 4-digit counter prefix that reflects creation order (`NNNN-slug.md`). The counter is assigned per directory in strict git-log creation order; ties broken alphabetically by original name. The old `YYYY-MM-DD-` prefix on docs/specs/ and docs/plans/ files is dropped — the date is recoverable from git log and the counter carries the ordering. A file's counter is stable for the life of the file: never reassigned, never reused, never compacted. Deleted files retire their counter; subsequent files do not fill the gap. This is the property that lets cross-references stay literal — refs use the full filename including the counter (`design/contracts/0007-honesty-rule.md`) so they grep cleanly and resolve directly without a glob step. 313 cross-references updated across .md/.rs/.toml/.c/.json files (test pins, include_str! paths, design-INDEX entries, baseline notes, runtime C comments, inter-contract markdown links incl. bare basename and `../models/foo.md` forms). CLAUDE.md gets a new "File-naming convention" section spelling out the rule and rationale. skills/brainstorm/SKILL.md and skills/planner/SKILL.md updated so new spec/plan creation produces counter-prefixed names from the start. The full test suite (cargo test --workspace) passes.
267 lines
12 KiB
Markdown
267 lines
12 KiB
Markdown
# 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:
|
|
|
|
```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 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**
|
|
|
|
```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 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**
|
|
|
|
```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.
|