clay-borg/workplans/CB-WP-0022-the-design-instrument.md

id	kind	title	status
CB-WP-0022	product	The design instrument: findings about the game, with their reproductions	ready

Purpose

structural tier  L   (named a high-leverage pass by the maintainer, and it
                      amends INTENT — clay-borg gains a stated aspect)
chaos            d8 = 6  → no override
declared tier    L

Declaration 5 of chaos window 2. Tier L: separate survey, adversarial review, ADR, then spec, then code.

The insight, in the maintainer's words

"We should consider ourselves testing the game and document inconsistencies to report them back to the ground-game repo, so that the game designer can improve the rules accordingly… We should have the rigorous game simulation engine and a meta scope to capture notes about game design flaws, questions, results and protocols about trial games… This will provide clay-borg an additional aspect as a valuable game design tool."

This is already happening and has no home. In five passes the engine has produced, as a by-product of being rigorous:

finding	how it surfaced
ten underdetermined rules points (U1–U10)	formalizing the dataset into testable rules
SOLVE offered on a face-down Problem, always inert	a human dragging it three rounds running
GR-A13 "wasted SOLVE" on a claimed Problem	a scenario that had to pick a default
GR-E01 unreachable below 5 seats	arithmetic over the deal count
six provisional scenario defaults	scenarios that could not be written without deciding something
GR-E03 / GR-E04 never played to the end	nobody noticed for nineteen passes

Every one was found by building the simulator, not by playing. That is the thing worth naming: a simulator rigorous enough to refuse ambiguity is a design instrument, because it cannot proceed past a rule that does not decide.

And every one of them has been carried in prose, in six different places, and one sat unread in an inbox for four days.

The load-bearing rule this must have

The project's standing failure is unexecuted verification. A design register that collects opinions would reproduce it in a new medium.

A design finding is not admissible without its reproduction.

Concretely: a scenario that fails, an arithmetic check that prints the contradiction, a recorded game the reader can replay, or a named test. "This feels unbalanced" is a note, not a finding. GR-E01 is admissible because 4/6/9 against 5/7/9 is a computation anyone can rerun; the SOLVE inertness is admissible because a recorded session shows three no-ops.

This is what would make clay-borg a design tool rather than a suggestion box, and it is the one part of this proposal that must not be traded away for convenience.

The judgment I want reviewed, not assumed

The maintainer asked whether this should extend to "a meta about the clay-borg engine evolution itself."

My answer is no, and it should be argued rather than accepted. That register already exists and is load-bearing: evidence/CB-EV-* records what each pass found, decisions/ADR-* records what was decided and what was rejected, gates.toml records what every control has caught and what would retire it, and workplans record what was attempted. Nineteen passes of engine evolution are already captured, with dates, costs and falsifiers.

Building a second register for the same subject would be ceremony, and this project has a standing rule that a gate must cash out. The asymmetry is the point: engine evolution has a home and game design does not.

If the adversarial review disagrees, that is exactly the kind of thing tier L exists to surface.

Task: survey how this is done elsewhere, and what we already have

id: CB-WP-0022-T01
status: todo
priority: high

research/CB-RES-0007-*.md.

Do not survey issue trackers. The question is narrower and more interesting: how do rigorous rule systems record the ambiguity they found? Candidates worth a benchmark-to-beat:

• Errata and rulings practice in published games (Magic's comprehensive-rules + rulings split, Netrunner's NAPD card rulings) — what makes a ruling findable years later.
• Formal-methods counterexample traces — a model checker's output is precisely a reproduction attached to a claim, which is the shape wanted here.
• Conformance-suite provisional behaviour — how W3C/WHATWG mark "implementation-defined" and how a spec later absorbs it.
• What this repo already has: provisional: true scenarios, §Underdetermined, gates.toml's caught/retire_if shape, and the hub message that went unread. The register must reuse the provisional machinery rather than compete with it.

Name, per dimension, the property to beat — findability, reproducibility, and whether a ruling can close a finding mechanically.

Task: adversarial review

id: CB-WP-0022-T02
status: todo
priority: high

Tier L requires it. Give the reviewer the survey and the §judgment above, and require an attempt at:

• that the engine-evolution register is redundant — the strongest counter is that ADRs record decisions and evidence records findings, but nothing records what we learned about building engines, which is a third thing;
• that "carries its reproduction" is affordable — if half the real findings cannot be reproduced cheaply, the rule will be quietly dropped and the register becomes a suggestion box anyway;
• that a register is needed at all, rather than one more section in GroundRules.md §Underdetermined, which already exists and already works.

Record the trail in history/, unpolished.

Task: decide

id: CB-WP-0022-T03
status: todo
priority: high

decisions/ADR-0012-*.md. At minimum:

• whether clay-borg's INTENT gains a stated aspect as a design instrument, and in what words — this is the change with the longest half-life in the pass;
• the finding taxonomy, and it should be grounded in the six findings above rather than invented: underdetermined (rules do not say), inconsistent (rules disagree with each other or the data), inert (a rule that cannot fire), degenerate (fires, but collapses play), unplayed (implemented, never played);
• the lifecycle and who owns each state: raised → reported → ruled → applied, or withdrawn;
• whether a finding without a reproduction is rejected or admitted as a note — and if admitted, how it is prevented from aging into an apparent finding.

Task: specify

id: CB-WP-0022-T04
status: todo
priority: high

specs/GameDesign.md, with metrics, because a spec without them is prose.

Candidate measures, to be argued not adopted:

• findings with a runnable reproduction — target 100%, and the denominator includes withdrawn ones;
• time from raised to reported — the U-items took four days to be read; that is the number this exists to fix;
• findings closed by a ruling vs findings still open, with age.

Also specify the trial protocol, which is the part with no precedent here: a trial game is a --recorded session plus an observation log, so "we played it and X happened" is replayable rather than remembered. The engine already records sessions as scenarios; a trial is that plus notes, and it must cost almost nothing or it will not be done.

Task: build it, and backfill what is already known

id: CB-WP-0022-T05
status: todo
priority: high

The register, the tool, and then the six findings above entered into it — backfilling is the test. A register that cannot express findings the project already has is the wrong register, and discovering that after designing it is the point of doing it in this order.

make design (or equivalent) must report: open findings by kind, those without a reproduction, and those never reported to their owner.

Task: report to ground-game, mechanically

id: CB-WP-0022-T06
status: todo
priority: high

Generate the report and send it. The message that sat unread for four days is the baseline to beat, and the failure was not the message — it was that nothing pointed at it and nothing tracked whether it was answered.

So the report must land somewhere that persists: a file in ground-game under its own workplan, not only an inbox entry. GROUND-WP-0002 already holds the ten U-items; this should extend it rather than duplicate it.

Include the two sharpened findings this pass has already produced:

• GR-E01 vs GR-S01 — the deal count puts 4/6/9 points in play against thresholds of 5/7/9, so either the count or the thresholds are wrong and no dataset reconciles them;
• SOLVE's legality against a face-down Problem or an unmatchable suit.

Task: evidence

id: CB-WP-0022-T06B
status: todo
priority: high

evidence/CB-EV-0020-*.md.

• Whether backfilling changed the design — if all six findings fit the first taxonomy, say so and be suspicious of it.
• What tier L cost against what it caught, since this is the second full-weight L pass and CB-WP-0012's deleted its own structural trigger.
• The engine-evolution question, as the review left it.
• Quote CB-WP-0021's cost by re-running the instrument.