| name | nw-test-design-mandates |
| description | Design mandates for acceptance tests - hexagonal boundary, business language abstraction, user journey completeness, pure function extraction, 3 Pillars (domain language / chained narrative / production composition), and the layered ATD discipline (Universe-bound assertion, layer-dependent PBT mode, two-tier acceptance, example-based sad paths). Lean recomposing core - routes to three narrow mandate modules. |
| user-invocable | false |
Acceptance Test Design Mandates (recomposing core)
This skill is the Single Source of Truth (SSOT) for every acceptance-test-design mandate. All mandates are enforced during peer review and must pass before handoff to software-crafter.
This core holds the cross-cutting concerns (numbering, registry, language-convention frame, compliance-verification handoff) and COMPOSES three narrow mandate modules. The canonical mandate definitions live in the modules — this core does not re-inline them.
Assertion failure messages state WHAT / WHY / HOW (STANDING)
Every AT assertion's failure message MUST state WHAT observable failed (the specific
expected-vs-actual), WHY it matters (the contract it breaks), and HOW to fix (what
the implementation must make true / the concrete remediation). A bare assert x == y with
no message — or a message that only restates the code — is itself a defect: a RED must TEACH
the crafter exactly what to make true, not force them to reverse-engineer the intent. Same
what/why/how rule the product's own error surfaces obey.
Durable outcome naming (STANDING)
Every acceptance-test identifier must name the durable observable value it
protects. Delivery bookkeeping is not value: never put slice_NN or
slice-NN in a test file/function name. Do not create a ledger, delivery
narrative or execution plan to preserve that bookkeeping; Git owns change
provenance. Before RED, derive
the identifier from the charter's value statement; a reader must understand
what is protected without opening delivery bookkeeping. Scenario titles and
parametrization IDs follow the same naming rule. The acceptance designer and
reviewer validate the observable meaning at authoring time; no language-specific
post-hoc naming gate is part of the delivery spine.
Closure obligations — COUNT / PARTITION / SILENCE (STANDING)
Three generative obligations. They fire at AUTHORING time, on the shape of what an AT (or the
artifact it certifies) asserts — not as a gate that fires after the error. They are
domain-agnostic: a validator checks the obligation is DISCHARGED without understanding the
subject. Whenever a scenario, a charter oracle, or a design artifact emits one of these
shapes, the matching cell is filled inline while writing:
- Emit a COUNT → name the POPULATION. A number ("3 consumers wired", "0 findings", "5
slices") is meaningless without its denominator: 3 of WHAT total, 0 out of a set that was
actually enumerated. An AT asserting a count MUST also pin the population it was drawn from,
and assert the count against that population — never a bare integer.
- Emit a PARTITION → assert CONSERVATION. When a whole is split into parts (buckets,
statuses, refused/accepted halves, per-category verdicts), the parts MUST sum back to the
whole. Assert the conservation law, not just the individual buckets — a partition whose
pieces silently drop members is the exact defect this catches.
- Declare SILENCE/ABSENCE → name the DISCRIMINATOR. A "clean / nothing found / no-op /
not-applicable" result MUST carry what distinguishes looked-and-genuinely-absent from
never-actually-looked (no capable tier, unparseable input, swallowed error). The AT
proves the discriminator by constructing the empty case AND a broken/incapable case and
asserting their outputs DIFFER — the negative test no positive test can replace (Vera's
absence ≠ incapacity,
nw-user-examiner §8). A silence indistinguishable from a swallowed
error is a false negative wearing a degraded alibi, never a PASS.
Why here, why inline: the obligation is SEEDED mechanically from what the design already
states — a Reuse Analysis EXTEND row that names a field ("binding_name plus template_parts")
already implies the population; the charter's negative oracle already implies the
discriminator. Filling the cell while authoring costs the system, not a gate firing after a
wrong path is taken (GDP-2 inline-at-authoring + GDP-5 cost-on-system). The denominator is not
documentation — it is the falsifier made mechanical.
Composition (load by trigger)
| Module | Kind | Trigger — load when... | Covers |
|---|
nw-test-design-mandates-scenario-design | KNOWLEDGE | shaping/judging a scenario's SHAPE — boundary, language, journey, fixtures, style | Mandates 1-4, the 3 Pillars, Walking Skeleton Strategy |
nw-test-design-mandates-layered-mechanics | KNOWLEDGE | choosing test MECHANICS for a layer + adapter-realness — assertion style, PBT mode, tier, sad-path treatment | Mandates 8-11, Layered Test Discipline table, Polyglot Adapter Matrix |
nw-test-design-mandates-composition-contract | KNOWLEDGE | composing the AT's DRIVING SURFACE + code contract — SSOT-via-types, driving-port-only, contract-shape tag, dormant-seam | Mandates 12-15 |
Load path: ~/.claude/skills/nw-test-design-mandates-{module}/SKILL.md. Load the module whose trigger matches your current moment; load more than one when a task spans moments. The three triggers partition the mandate-space — every mandate lives in exactly one module.
Numbering Convention (read before citing any mandate)
Mandate numbers are an SSOT-internal index, defined in exactly one place — this registry. They may be re-indexed at will when the registry is reorganized.
- Inside the modules: each mandate carries a number for ordering and cross-reference.
- Everywhere else (agents, other skills, tasks, docstrings, ADRs, tests): refer to a mandate by its stable descriptive name plus a pointer to this SSOT — e.g. "the Driving-Port-Only Boundary mandate (SSOT:
nw-test-design-mandates)". Do NOT hard-code the number in external references; the number is not a contract and external code must not lock onto it.
- Existing numeric labels in test docstrings (
Mandate-12, Mandate-13, ...) are legacy shorthand for the named rules; treat them as references to this SSOT, not as independent definitions.
Mandate Registry (canonical names → module)
| # | Name | Module |
|---|
| 1 | Hexagonal Boundary Enforcement | scenario-design |
| 2 | Business Language Abstraction | scenario-design |
| 3 | User Journey Completeness | scenario-design |
| 4 | Pure Function Extraction Before Fixtures | scenario-design |
| — | The 3 Pillars (style backbone) | scenario-design |
| — | Walking Skeleton Strategy | scenario-design |
| 8 | Universe-bound assertion at layers 1-3 | layered-mechanics |
| 9 | PBT input mode is layer-dependent (+ v2 mock-status driver) | layered-mechanics |
| 10 | Two-tier acceptance for rich journeys | layered-mechanics |
| 11 | Integration sad paths stay example-based | layered-mechanics |
| — | Layered Test Discipline table + Polyglot Adapter Matrix | layered-mechanics |
| 12 | SSOT + Zero Duplication via Types + Services + DSL | composition-contract |
| 13 | Driving-Port-Only Boundary | composition-contract |
| 14 | Contract Shape Classification | composition-contract |
| 15 | Dormant-Seam Reconciliation | composition-contract |
| 16 | Algebraic Analysis Before the Scenario | scenario-design |
LANGUAGE CONVENTION FRAME (read FIRST — overrides all examples in the modules)
Code examples in the modules use Python syntax for illustration only. They are NOT prescriptive about target language. nWave is language-agnostic per the "genericity and agnosticism" mandate (2026-05-24).
Before applying mandates, detect the target project's language from manifest files: package.json → TypeScript/JS; Cargo.toml → Rust; go.mod → Go; pyproject.toml/setup.py/Pipfile → Python; pom.xml/build.gradle → Java/Kotlin; *.csproj/*.fsproj → C#/F#; Gemfile → Ruby; Package.swift → Swift.
When the target language is NOT Python: adapt EVERY code example — replace Python imports (from pytest_bdd import ..., from hypothesis import ...), type hints, class/function syntax, test-framework idioms, directory conventions (tests/ vs test/ vs __tests__/) with target equivalents. Project conventions ALWAYS WIN over skill examples — if the user's repo has 50 TS files and zero Python files, mandates apply via TypeScript test framework, never Python pytest.
Empirical anchor: 5 of 5 Python code blocks in the original skill, zero TS/Go/Rust — root-cause for language-leak per F-SKILL-EXAMPLES-LANGUAGE-LEAK. Connects [[feedback_language_adapter_plugin_architecture_2026_05_24]] (genericity mandate).
Mandate Compliance Verification
Handoff to software-crafter includes proof all mandates pass (definitions per the cited module):
- CM-A (Mandate 1 — scenario-design): All test files import entry points (driving ports), zero internal component imports
- CM-B (Mandate 2 — scenario-design): Gherkin uses business terms only, step methods delegate to services
- CM-C (Mandate 3 — scenario-design): Scenarios validate complete user journeys with business value
- CM-D (Mandate 4 — scenario-design): Business logic extracted to pure functions. Impure code isolated behind adapters. Fixture parametrization applies only to adapter layer.
- CM-E (Mandate 8 — layered-mechanics): Every step-method at layers 1-3 uses
assert_state_delta(before, after, universe, expected) with port-exposed universe entries
- CM-F (Mandate 9 — layered-mechanics): the representative layer 3+ wiring/sad-path test is example-only; for every declared broad-input/state/failure law (e.g.
BROAD_INPUT_DOMAIN), the smallest sufficient set of separate, budgeted semantic-PBT tests exists instead — normally one property per distinct law, combined only when one generated observation honestly falsifies all combined laws — each sited at a deterministic, replayable, law-bearing surface (real I/O not required, but the generated observation carries an explicit preservation map to the promised real-port observation), proving the SAME promised observation as the representative example — never a proxy, never a replacement for it. When no such surface exists, the result is EVIDENCE_GAP back to DESIGN before authoring — DESIGN names the surface and preservation map or corrects the law; the obligation is never silently downgraded to example-only
- CM-G (Mandate 10 — layered-mechanics): If journey is ≥3 chained scenarios with rich input space → Tier B
test_<feature>_state_machine.py exists alongside Tier A .feature; Tier B's optionality is independent of the CM-F carve-out
- CM-H (Mandate 11 — layered-mechanics): Layer 3+ sad paths are named example-based tests; no PBT machinery imported into that sad-path set — the CM-F carve-out's semantic-PBT test(s) live in their own file(s), never merged into these examples
Evidence: import listings, grep for technical terms, walking skeleton identification, focused scenario count, pure function extraction inventory, universe-entry audit (grep for _ prefix in universe names → flag internal-field leakage), tier-B file presence check.
