docs: enforce design invariants via a critical-design-review skill and checklist #128

Merged

marco merged 1 commit from chore/critical-design-review-skill into main

2026-07-22 08:16:12 +02:00

marco commented

2026-07-22 08:15:21 +02:00

Owner

Summary

I kept forgetting our own agreed rules during design discussions, and machine-local memory doesn't help because it isn't shared across my PCs. This makes the rules persistent (in git) and enforced at design time, so they can't be silently skipped.

New critical-design-review skill (.claude/skills/, committed → travels to every machine): before any implementation code, a feature/design change (a proposal, an imperative task, or a mid-conversation pivot) must produce a review whose core is a mandatory Invariants Check — one verdict per invariant, each justified by a concrete element of this design, no line skippable or rubber-stampable.
New ## Design checklist in CLAUDE.md: the single runnable index of design-time invariants (server-authority, both HARD GATEs, protocol versioning, string catalog, single-thread sim, act-on-instance, persistence, identity/GM auth, process separation, AoI, multi-platform, …). The skill points at it; it is not duplicated.
Single-source hygiene: removed rule/DoD/section duplication that had already drifted (base-DoD was enumerated in three places and disagreed on multi-platform); gave "act-on-instance / no side-collection" and "extend-by-type, not switch" a canonical prose home; game-design now references this skill by slug.

This is a process/docs change only — no code touched.

How it was tested

Adversarial self-review: ran a parallel multi-agent critical-review panel over the two artifacts across six rounds (forcing-function effectiveness, invariant coverage completeness, DRY/drift, artifact correctness, cross-machine persistence, concision). Iterated fixes until the panel reported 0 HIGH findings for two consecutive rounds and coverage was declared complete. HIGH count per round: 3 → 1 → 3 → 2 → 0 → 0.
Cross-machine persistence verified: .claude/ is not git-ignored, both artifacts are tracked and committed, no absolute-path/OS coupling.
Gates run locally: just lint (build succeeded, 0 warnings) and just test (all suites green — 184 GameServer, 72 Client.Core, 54 Shared, 12 Auth, 14 AssetExtractor, 4 Assets).

Checklist

just lint passes (CSharpier + analyzers, zero warnings)
just test is green
The whole solution builds (client and tools included)
Multi-platform preserved (server on Win/macOS/Linux, client on Win/macOS) — docs-only; verified no OS/path coupling in the artifacts
Tests added/updated for this change — N/A: process/docs change, no code
Linked issue — none; this skill will be exercised next on #112 and #18

## Summary I kept forgetting our own agreed rules during design discussions, and machine-local memory doesn't help because it isn't shared across my PCs. This makes the rules **persistent (in git) and enforced at design time**, so they can't be silently skipped. - **New `critical-design-review` skill** (`.claude/skills/`, committed → travels to every machine): before any implementation code, a feature/design change (a proposal, an imperative task, or a mid-conversation pivot) must produce a review whose core is a **mandatory Invariants Check** — one verdict per invariant, each justified by a concrete element of *this* design, no line skippable or rubber-stampable. - **New `## Design checklist` in `CLAUDE.md`**: the single runnable index of design-time invariants (server-authority, both HARD GATEs, protocol versioning, string catalog, single-thread sim, act-on-instance, persistence, identity/GM auth, process separation, AoI, multi-platform, …). The skill points at it; it is not duplicated. - **Single-source hygiene**: removed rule/DoD/section duplication that had already drifted (base-DoD was enumerated in three places and disagreed on multi-platform); gave "act-on-instance / no side-collection" and "extend-by-type, not switch" a canonical prose home; `game-design` now references this skill by slug. This is a process/docs change only — no code touched. ## How it was tested - **Adversarial self-review**: ran a parallel multi-agent critical-review panel over the two artifacts across six rounds (forcing-function effectiveness, invariant coverage completeness, DRY/drift, artifact correctness, cross-machine persistence, concision). Iterated fixes until the panel reported **0 HIGH findings** for two consecutive rounds and coverage was declared complete. HIGH count per round: 3 → 1 → 3 → 2 → 0 → 0. - Cross-machine persistence verified: `.claude/` is not git-ignored, both artifacts are tracked and committed, no absolute-path/OS coupling. - Gates run locally: `just lint` (build succeeded, **0 warnings**) and `just test` (**all suites green** — 184 GameServer, 72 Client.Core, 54 Shared, 12 Auth, 14 AssetExtractor, 4 Assets). ## Checklist - [x] `just lint` passes (CSharpier + analyzers, zero warnings) - [x] `just test` is green - [x] The whole solution builds (client and tools included) - [x] Multi-platform preserved (server on Win/macOS/Linux, client on Win/macOS) — docs-only; verified no OS/path coupling in the artifacts - [ ] Tests added/updated for this change — N/A: process/docs change, no code - [ ] Linked issue — none; this skill will be exercised next on #112 and #18

marco added 1 commit

2026-07-22 08:15:21 +02:00

docs: enforce design invariants via a critical-design-review skill and checklist

ci / Lint & Test (pull_request) Successful in 2m48s

Details

3b1b63fb76

marco merged commit e4b8b70223 into main

2026-07-22 08:16:12 +02:00

marco deleted branch chore/critical-design-review-skill

2026-07-22 08:16:13 +02:00

marco referenced this pull request from a commit

2026-07-22 08:16:14 +02:00