Authoring Round

Authoring round: 6 terms per category

One round takes the site up to 54 terms forward: roster from the pool, briefs with demo hints, one parallel author agent per category plus one verify agent, then e2e centrally, then a single commit. Eleven rounds have run this way; the process below is the distilled shape, including every failure mode they taught.

A round is 6 per category only while every category still has 6. The pool is now uneven and draining unevenly: interaction was exhausted before round 16, and round 16 emptied color and aesthetic (1 candidate each) while authoring 6 apiece elsewhere, for 38 terms across 8 agents. Take the whole of a nearly-empty category rather than skipping it, size the agent list to the categories that still have terms, and tell a 1-term agent it has one term so it does not pad. Check the real shape with pool-remaining.ts before promising the user a number.

Files in this skill directory:

• pool-remaining.ts: lists the unauthored pool per category
• make-briefs-template.ts: briefs generator to copy and fill
• workflow-template.js: the two-phase agent orchestration to copy and fill

0. Preconditions

• Read SPEC.md and AGENTS.md first if this session has not.
• Clean git tree, on main (commits go directly to the current branch; never branch).
• The USER runs the dev server on port 4321. Confirm with a GET request to http://localhost:4321/ (Astro dev answers HEAD with nothing, so a HEAD probe looks exactly like a server that is down). Never start, stop, or restart any dev server; if it is down, ask the user rather than launching one.
• Agent quirk: Astro 7.2 force-backgrounds astro preview when it detects an agent, so Playwright aborts with "webServer exited early" and runs nothing. playwright.config.ts now sets ASTRO_PREVIEW_BACKGROUND=1; set it by hand for any ad-hoc playwright run. Piped through a buffering pipeline this reads as a HANG with an empty log, because the orphaned preview holds stdout open. Run e2e detached to a log file and never under a tool timeout: the full suite is ~18 min and a 10 min cap kills it mid-run.

1. Roster (main session, ~15 min)

1. bun .claude/skills/authoring-round/pool-remaining.ts for the per-category pool AND the stub backlog, which it now prints as its own list. Stubs outrank the pool. A stub is a published page carrying a definition and nothing else, already linked to by six to nine articles, so promoting one repays a debt the site is already visibly carrying. If the stub list is non-empty, the round is a promotion round (see §6) unless the user asked for new terms specifically.

2. Pick 6 per category, or the whole remainder where fewer are left. Selection principles, in priority order:

   • Pay prose IOUs: grep recent articles for "enumerated separately" and named cross-references to unauthored terms; an on-site article that NAMES a candidate is a debt the candidate's article repays by linking back.
   • Prefer head/core priority; take tail terms when they complete a family or pair.
   • Build contrast pairs into one round (fake-urgency/fake-scarcity, frame-rate/jank): round-mates get told to contrast each other in one sentence each way, and the demos must look different. Only where the pair is REAL, and that is a decision made at roster time, not at batching time: batching terms together for coordination (shared context, one owner for both sides of an edge, lookalike avoidance) must never come with an instruction to write an edge between them. Round 23 batched trace-viewer with diff-viewer purely because both are dense developer views, told the agent to author them "as a pair, one edge between them written on both sides", and got exactly that: a seeAlso each way plus a sentence in each article inventing a kinship ("both are dense two-pane developer views", "a list beside a detail is what they have in common"). The agent had already half-caught it, downgrading contrastWith to seeAlso because nobody describing a trace viewer reaches for the word diff viewer, which is the discrimination test correctly applied and should have ended in NO edge at all. The user caught the rest. Say "these two are yours, keep them from looking alike" and let the relation earn its place or not exist.
   • Avoid near-duplicates of existing specimens (a demo that would look like an existing one is a smell even when the term is distinct).
   • Rotate and >2-contact terms wait: the stage speaks single-contact touch (data-touch persona, hold step, pressure; STAGE_NEWS law 17) and the two-contact pinch (pinch step, pinchSpread, Ctrl+drag takeover; law 21), so pressure, long-press, tap, swipe, and pinch terms are authorable. Rotate and gestures past two contacts stay out of rosters until the vocabulary grows them (the fake-touch entry in the specimen-sweep ledger tracks it).

3. Collision-check every pick AND its likely aliases against src/content/terms/ (name: lines catch both term names and alias names). A candidate whose name is already an alias of an existing term is DEAD: swap it and note nothing. Claimed aliases a surviving pick must not take become fences in its brief hint.

   This is now the highest-value step in the roster, not a formality. Do it as a script over the whole pool rather than per pick: slugify every alias name in every term file into a claimed-slug map, then test each candidate slug against it. Round 16 found 19 dead candidates in a 214-term pool, and they cluster in exactly the wrong place: both of accessibility's core candidates (landmark-region, tab-order) and two of motion's three head/core (shared-element-transition, layout-animation). Priority is no defence. Also eyeball the survivors for near-duplicates the slug test cannot see: a candidate whose display name equals an existing term's name is just as dead (motion's reduced-motion is the on-site prefers-reduced-motion), and the pool's own notes field often flags merge candidates. The dead list is worth reporting to the user, since candidates.json still carries them.

   Round 17 found 20 dead this way, then found four more the slug test cannot see and one that escaped the roster entirely. Two failure modes to add to the sweep, both cheap:

   • Affix variants. A candidate that is an existing term plus or minus a trailing noun shares no slug with it: back-to-top-button against the published back-to-top. This one reached an author agent, which refused it as a duplicate and cost the round a slot. Test each candidate slug with its trailing -button, -bar, -menu, -view, -pattern stripped, and with the existing slugs' own affixes added.
   • Definition duplicates. Read the DEFINITION of the nearest existing term, not just its name. bulk-action-bar died because bulk-actions' definition already says "a bar that appears once a selection exists and reports its count"; session-timeout died to timeout-warning, slash-command-menu to slash-command, color-alone to use-of-color. Four picks, all with distinct slugs, all already written. Grep the candidate's own definition keywords against existing definitions before promising the pick.

2. Briefs (main session, ~30 min)

Copy make-briefs-template.ts to a scratch directory, fill PLAN with the round's slugs and hints (hint anatomy is documented in the template; drop the key for any category with no terms left), set OUT to an absolute scratch path, run it with bun from the repo root. It hard-fails on any slug already on site or missing from the pool.

It also prints a const ROSTER = {...} line. Keep that output: it goes into the workflow script in step 3 verbatim, and it is what lets the verify gate tell a finished round from an interrupted one.

3. Author + verify (agents, ~30-45 min)

Copy workflow-template.js, fill the placeholders:

• BRIEFS: the absolute path from step 2.
• ROSTER: the line step 2 printed, pasted verbatim. It is the round's contract in three places: each author is told its exact slugs and refuses to guess if its briefs disagree, the log names any slug no agent reported, and the verify gate is told the shape of the round rather than inferring it from what survived. A workflow script has no filesystem access, so this literal is the only way the script can know it.
• CATEGORY_GUIDANCE: per-category exemplars, IOUs, and alias fences (anatomy documented in the template). This is where roster knowledge becomes agent knowledge; skimping here costs e2e failures later.
• Never trim STAGE_NEWS; append new laws as rounds teach them, and mirror any mechanically-checkable new law into scripts/validate-terms.ts as a gate.

Smoke-test the filled script before running it, because a script that fails to parse burns the whole launch and reports it as a bare SyntaxError with no round attached:

node -e 'const s=require("fs").readFileSync(process.argv[1],"utf8").replace(/^export const meta/m,"const meta");new Function(`return (async () => {${s}})()`);console.log("parses")' -- /abs/path/to/rN.js

node --check is the wrong tool here, and worse than nothing. A workflow script's real evaluation context is an async function body: top-level await and a top-level return are both legal in it, and both are errors to --check (as CJS it rejects the await, as .mjs it rejects the return). So --check fails on every correct script, which trains you to dismiss its output, which is how round 25 launched a script whose prompt strings contained unescaped backticks. Wrapping the source in a function body parses it the way the runner will and reports only real faults. It earned its keep immediately: the first run of it over the edited template caught a missing comma in a prompt array.

Run it with the Workflow tool if available (one author agent per stocked category, in parallel, then the verify agent). Without a Workflow tool, run the same prompts as parallel subagents and the verify prompt as one subagent after all authors return. Authors do their own visual pass against the user's dev server; the verify agent runs validate/typecheck/biome once and fixes what fails. Nobody runs e2e but you.

Authors also run AUDIT_PASS: vd-stage.audit() plays a specimen's choreography through the real attract player on the dev server and reports the same triple e2e/choreography.e2e.ts asserts (no failures, exactly one subject, not interrupted). Round 17 is why it is in the template: three of seven agents found the API unprompted, audited their own specimens, and the round came back 96/96 green on the first test:e2e:new, with zero behavioral fixes needed for the first time in the process. The other four flew blind and got lucky. It is a dev-server pre-check, not the gate (dev injects CSS through JS, so a specimen can mount before the stage has its height), so a failure there is always real while a pass is only very likely: you still run the full suite.

Refused terms (STAGE_NEWS law 18): an author who finds a term needs input or stage machinery the player does not have returns it unauthored with needs stage primitive: <what> instead of faking it with a simulation control. Collect these in the report, tell the user (building the primitive is a main-session or dedicated-session job, like hold and the touch persona were), and keep the term out of rosters until the primitive lands. Faking the player is exactly what the fake-touch sweep is un-doing; never mint new offenders.

Interrupted-agent recovery (three times now: twice a spend limit, once an API connection lost mid-response): inventory which slugs have all three files (terms/<slug>.mdx, demos/<slug>/demo.ts, demos/<slug>/choreography.ts), then relaunch a finish variant: per-category agents get only their REMAINING slugs, are told which batch-mates are DONE (read them for idiom, do not rewrite), treat partial files as drafts from their earlier self, and run the visual sweep over the WHOLE category batch (dead agents may not have visually checked their own later terms; the sweep has caught real overflow bugs in "complete" specimens every time). The verify agent then gates the whole round.

An agent that dies mid-response returns NOTHING, so its finished terms are absent from completed and invisible to anything reading only the agents' reports. That is what the ROSTER fill is for. Round 25 is the worked example: an author died having written wireframe of a three-term fidelity ladder, and the verify gate, told only what the surviving agents reported, found a published term contrasting two slugs that did not exist. It did the SPEC 2.3-sanctioned thing and minted mockup and prototype as STUBS, which is right in isolation and is exactly the debt the family was batched whole to avoid. The gate now knows the roster and is told the opposite rule for slugs on it: leave the dangling relation dangling, let bun validate fail, and report the gap in its incomplete field, because a stub there converts a recoverable interruption into published debt signed by the gate. A stub is still correct for a slug the round never planned, and the gate says so explicitly when it mints one.

4. e2e and commit (main session, ~30 min)

1. bun run test:e2e:new plays only specimens without a committed subject snapshot; first run fail-writes the new snapshots. Ask before starting it, and never run the full bun run test:e2e unasked: nothing runs it automatically any more (ci.yml is static gates only, e2e is manual in e2e.yml), so a 45-minute pass is 45 minutes of the user's session. Fix behavioral failures and re-run targeted until green.

   Run it in the round that authored the specimens, even if the round is otherwise done. The gate finds its work by the ABSENCE of a snapshot, so skipping it leaves no trace of the omission: nothing fails, nothing warns, and the round commits looking complete. Round 24 shipped 38 specimens with no record anywhere of what any of them identifies as, and the only reason anyone found out is that round 25's run came back reporting 47 new specimens instead of nine, at four times the wall clock. If the user declines the run, say in the report that the round's specimens are unproven and that the next round will pay for it.

   The failure taxonomy so far, most common first:

   • an assert timed to the edge of a state window (give it room, aim mid-window)
   • an assert on evidence inside a popup the action just closed (mirror onto trigger)
   • a mount-time assert with no room for kit fades (open with a wait)
   • invalid selector syntax and hairline subjects (now validate-gated)
   • an assert on a wrapper with no box: a group whose children are all absolutely positioned, or one held at height: 0 to overlay without shifting, measures zero and reads as absent just like a hairline does
   • a demo that answers input by synthesizing more input (btn.click() inside a click handler): the choreography passes and the TAKEOVER pass fails, because it counts the clicks reaching the specimen and wants exactly one
   • a mid-flight assert on an element that is fading OUT (STAGE_NEWS law 28). The tell is an identical claim passing inbound and failing outbound, so it reads as flake rather than as a rule; it is not one, and widening the window cannot fix it. Claim the exit through something that stays visible.
   • an assert whose meaning does not match the element's (STAGE_NEWS law 29): a cumulative claim aimed at a "last event" readout. Look for its twin while fixing it, an assert that passes for a reason the demo's state axis never touched, which is invisible precisely because it is green.

2. Review the new subject snapshots (e2e/__snapshots__/<slug>-subject.txt): every one should be scope: element with a sensibly narrow subject; every data-pose carrier must mount in a state satisfying its pose (the attributes in the snapshot show both). A whole scene scope withdraws identify: verify the agent noted that decision deliberately.

3. No full bun run test:e2e, locally or in CI. If the round's specimens should be proven before release, say so in the report and let the user trigger the manual Specimens workflow, scoped with grep if only some terms changed.

4. Check for stray files (authors sometimes leave shot-*.png or probe scripts at the repo root); move them out, never commit them.

5. bun run og --build shoots the share images (SPEC §10). It builds, then photographs every specimen that has no image yet, which after a round is exactly the new terms: seconds of shooting on top of the build. Not optional. A term page names /og/<slug>.png whether or not the file exists, so a new term without one ships a broken link preview, and nothing anywhere checks for it.

6. Commit everything as Author an Nth round of 6 terms per category. The tree must be clean after.

5. Report

Tell the user: terms count before/after (from bun validate's summary), e2e check count, behavioral failures found and how they were fixed (each is a candidate new law for STAGE_NEWS), notable agent decisions (subject choices, dropped aliases, deviations from briefs), and the remaining pool size.

The consolidated relations pass has run (2026-08-21), so a new term no longer ships with empty relations: author its edges in the round, against the discrimination test in SPEC §2.3, and give a term whose family already has a head term a variantOf rather than a new contrast. Tags are authored too, since the corpus backfill (2026-08-29): give every term the tags it belongs to FROM THE ENUM AS IT STANDS, read off how the same facet was applied to that term's own family rather than from the tag name alone. What a round may not do is grow the enum: a tag invented while authoring nine terms is a tag chosen without knowing who else wants it, so record the candidate in research/enumeration/canonicalize-notes.md and let it be settled by a pass over the whole vocabulary (SPEC §2.5).

6. Promotion rounds

A promotion round finishes stubs instead of authoring new terms. Everything above applies, with five differences that all come from the same fact: the term file already exists and is already linked to.

• Roster. The stub list from step 1 IS the roster, so there is no pool selection, but the collision sweep matters MORE rather than less: a stub written as a relation target a year of rounds ago may since have been authored under another name. Check each stub's definition against its nearest published neighbours, not just its slug, and be willing to return one as a merge (an alias on the neighbour) rather than force a page. The 2026-08-21 round checked 24 and merged none, but two (zero-state against empty-state, semantic-color against color-role) needed the existing graph consulted before they survived.
• Briefs. Per term they carry, beyond the usual: the MANDATORY reciprocations (every symmetric edge a published term already declares at the stub, which symmetry stopped requiring only because it was a stub, and which the gate demands the moment it publishes), the prose IOUs (the articles already linking in, which the new article must agree with and link back to), and a per-term lookalike fence naming the neighbour demo it must not duplicate. Compute the reciprocations mechanically; they are not guessable.
• Relations are declared one-sided, on purpose. Authors write relations ONLY in their own files and never touch another term's frontmatter, because seven agents editing shared neighbours is a lost-write race. bun validate then reports one symmetry error per new outbound edge, which is expected, not a failure: the main session closes them centrally afterwards (the closure script is trivial and worth keeping). Check the eight-contrast hub cap after closure, not before: the 2026-08-21 round pushed select to nine and had to drop its weakest new edge.
• Tags are the main session's, not the authors'. Assign them centrally, matching how the facet was applied to that term's own family (read the neighbours' tags), rather than letting each agent invent its own reading of the enum.
• Editing in place. Keep name, slug and category byte-identical: other pages link to that slug. A definition may be sharpened only after reading the articles that link in, because their prose was written against it, and a sharpening that makes them false is a regression. Have the verify agent diff all three fields against git show HEAD: and report drift.