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.
124 lines
4.9 KiB
Markdown
124 lines
4.9 KiB
Markdown
# 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.
|