DayZ Feature Spec

The DayZ-adapted spine of spec-driven development: define what done means and how it will be verified before touching code, then gate the artifacts for consistency before spending an in-game test cycle.

This is the local adaptation of GitHub's spec-kit specify → clarify → analyze → implement flow. The generic app scaffolding (TDD red-green, contract tests, user-story-as-independent-MVP slicing, the specify CLI, GitHub-issue export, extension marketplace) is intentionally dropped — see "What this drops" below. What is kept is the discipline that already maps to R7/R8/R8-extended and G1–G3, plus one thing they lack: an explicit artifact-level consistency gate.

When to use / when to skip

Use before implementing:

• a new mod feature, or any change touching >1 file (aligns with R3),
• anything data-critical (persistence, progression) — then also invoke rigorous-data-audit,
• anything where "done" is not self-evident, or where a later phase/consumer reads this phase's output (R8-extended forward contract).

Skip for: 1-line typos, trivial reversible tweaks (default keybind, stringtable key, path slash). R3's small-reversible-changes-go-direct rule wins — a spec here would be ceremony.

The flow

Plan mode ─► dayz-feature-spec                       ─► [code] ─► dayz-feature-spec        ─► dayz-mod-workflow ─► R5 batched
            Step 1 spec + Step 2 checklist  (GATE)              Step 3 analyze gate (GATE)     (implement)          in-game test

The two gates are where this skill earns its place: nothing goes to the expensive in-game cycle (R5) with an unmeasurable criterion, an unverified cross-file reference, or a spec↔code contradiction.

Step 1 — Write the feature spec

Fill references/spec-template.md. It is deliberately short. Four sections carry the DayZ-specific weight:

• Acceptance Scenarios — Given/When/Then, each with concrete in-game repro steps (spawn what, do what, observe what). "It works" is not a scenario.
• Success Criteria — measurable and, where possible, technology-agnostic. DayZ examples: "bolt moves when firing", "0 Error lines in script_*.log post-test", "hands within <0.5 cm of grip", "car reaches ≥X km/h on flat ground". Vague adjectives ("looks good", "works") are not criteria. Event position is mandatory covariate of spec (LL-427): recorded and reported with result, and proof of mechanism is stratifying by it and checking that within the stratum treatment ceases to matter.
• Assumptions — every guess marked ASSUMED. If an assumption decides whether the work is correct (path, classname, version, format), resolve it with AskUserQuestion now, not after coding (G1: verbalizing a risk is not managing it).
• Forward Contract (R8-extended) — list every symbol the next phase or consumer reads: config.cpp classnames, model.cfg selections/bones, .p3d proxy paths, hiddenSelections, stringtable keys, layout names. Each MUST carry a verify status — path:line (verified per G2/R2) or [UNVERIFIED]. An [UNVERIFIED] ref is a coverage gap the analyze gate treats as CRITICAL. This is exactly the LFQuad Phase B P1 class of bug (proxy path to a non-existent file, missing selections model.cfg needs). Before spending an arm on a field, grep readers discounting declaration/default/clamp/serialization (LL-428): without readers it is placebo, and if reader is conditional one must prove on flown data that condition is reached.

Step 2 — Spec quality checklist ("unit tests for English")

Before writing any code, run references/spec-checklist.md against the spec. It checks the spec itself the way tests check code: is every criterion measurable, every scenario reproducible, every ASSUMED resolved-or-flagged, every cross-file ref verified, scope boundary explicit. A spec that fails the checklist is not ready to implement. This is a gate on the English, complementary to rigorous-data-audit, which is a gate on the code.

Step 3 — Analyze gate (after code/tasks, before the in-game test)

Run references/analyze-gate.md — a read-only cross-artifact pass over spec ↔ plan ↔ HANDOFF/tasks ↔ code ↔ CLAUDE.md. It reports coverage gaps, contradictions, terminology drift, duplicate/near-duplicate requirements, unverified forward-contract refs, and constitution (R1–R9 / G1–G6) violations, each with a severity (CRITICAL/HIGH/MEDIUM/LOW). The gate MUST NOT modify files; it produces a report and offers remediation for explicit approval.

Key DayZ adaptation: coverage means every acceptance criterion has a verification path — either an offline check (grep / python / py3d / RPT scan) or an assignment to the batched in-game session (R5). A criterion with no verification path is a CRITICAL coverage gap. CRITICAL findings block the in-game cycle.

This is the artifact-level complement to R7 (trace invariants to all call-sites, code-level) and R8 (end-to-end mental walk).

What this drops from spec-kit (and why)

• TDD / red-green / contract tests — DayZ has no unit-test harness; the acceptance test is the in-game gate (R5). The verification-path concept replaces test-first.
• User-story-as-independent-MVP slicing — DayZ features are often monolithic (a vehicle drives or it does not; a grip pose is right or wrong). Priorities/scenarios are kept; the MVP-per-story ceremony is not.
• The specify CLI, uv scaffolding, tech-stack research phase — the stack is fixed (Enforce Script, config.cpp, model.cfg, .p3d) with a fixed toolchain (AddonBuilder, DayZDiag). No scaffolding needed.
• /taskstoissues, extensions/presets/bundles marketplace — solo dev; overkill.

If a future task tempts you to re-add generic app cruft here, don't — that was the reason to adapt rather than adopt.

Relationship to existing rules and skills

• Plan mode produces the plan this spec references; run this skill right after.
• G1 / R3 — clarify before assuming; plan+approval for big changes. Step 1's ASSUMED-resolution is G1 applied at spec time.
• G2 / R2 — cite-then-verify. Every forward-contract ref and cross-file symbol is verified path:line.
• G3 — honest verification. Success Criteria say what will be checked and how.
• R7 / R8 / R8-extended — the analyze gate is the artifact-level layer above R7's code-level invariant tracing and R8's end-to-end walk; the Forward Contract section is R8-extended made explicit.
• rigorous-data-audit — for data-critical mods, this skill precedes it; the spec's crash-recovery/admin scenarios feed that audit.
• dayz-mod-workflow — consumes the approved spec and implements.
• pre-output-discipline — the discovery→generation gate; writing the spec is a generation step, so validate discovery first. Optional external skill, not included in this pack. Without it, apply the gate by hand: every discovery claim carries a verified path:line before any spec text is written.
• Pre-code ceremony routing (SP-050) — which gate applies when is fixed by the single source: <system-notes>\workflow.md §Árbol de decisión pre-código. This skill is Step 2 of that tree; Grill A precedes it, Grill B and dayz-mod-workflow follow.

Provenance

Adapted from github/spec-kit, reviewed 2026-07-01. Sources: templates/spec-template.md, templates/commands/analyze.md, templates/commands/clarify.md, templates/checklist-template.md. Generic scaffolding excluded by design.

Forward Contract for injected objects

[EXACT][CLAIM-R21-FEATURE-INJECTED-CONTRACT] When a plan injects an object that replaces another implementation (planner, bridge, transport, repository), the Forward Contract MUST enumerate every field and method the consumer reads, not only the field that motivates the test double. Grep all accesses on the injected value and prefer the existing result type over a partial look-alike. The generator applies consumer clamp rules before declaring treatment, and manifest records effective value, not requested one (LL-429): what collapses to control is mislabeled control.

The failure mode is concrete: a consumer can read .status.value, .proposal and .source even when a plan mentions only .proposal; the partial object then fails at runtime despite satisfying the prose spec. Verified example: GameMaster_dev/tools/gm/service.py:209-218; the complete existing result contract is GameMaster_dev/tools/gm/ollama_planner.py:43-50.

Eligibility symmetry across push and pull (LL-269)

Before a Forward Contract says “use the same bound or rule as X,” enumerate every existing predicate that answers the same eligibility, visibility, or authorization question. If full sync, incremental broadcast, and request handling disagree, the contract names the chosen invariant and justifies it; it does not copy one route by convenience.

When the server pushes notice of data and also serves that data on request, pull must not be stricter than push unless the contract defines a recoverable exception. Add an acceptance case where direct player-to-object distance fails but eligibility through a connected endpoint passes: a pushed notice must lead to a successful pull. If the defect was in the contract, amend the contract with a changelog alongside the code; a code-only fix leaves the trap for the next phase.

API-index liveness boundary

[EXACT][CLAIM-R21-FEATURE-API-INDEX-LIVENESS] A zero-record result from dayz-api-index v1 does not prove that a declaration is absent: v1 strips comments, so commented-out and genuinely missing declarations both yield zero active records. Until v2 reports active|commented|missing, the parent chain, compile guards and config namespace, open the cited source, record the source path:line, and inspect the surrounding #ifdef state before recommending an API.

The v2 index is supporting evidence, not an implementation gate for unrelated work. In particular, it does not block the .layout viewer or the UI evidence loop defined by the r21 product spec.

Rules promoted from lessons corpus (added 2026-07-27)

Promoted from AI/20_Knowledge/lessons-learned.md so they arrive via trigger instead of depending on someone remembering to search for them. Each rule cites its origin LL-NNN; the complete entry (symptom, origin, evidence) lives there.

• LL-017 — Every decision test defines PASS, FAIL, and INCONCLUSIVE/setup-failed, with an explicit precondition separating the third. Fix metrics and matching before executing.
• LL-116 — Every probe used to decide architecture maintains inputs during window, uses mechanically complete fixture, and validates fail-closed before side effect. If a null result admits more than one plausible cause, classify it INCONCLUSIVE.

Rules promoted from lessons corpus (added 2026-07-27)

Promoted from AI/20_Knowledge/lessons-learned.md so they arrive via trigger instead of depending on someone remembering to search for them. Each rule cites its origin LL-NNN; the complete entry (symptom, origin, evidence) lives there. Do not remove the citation: the index lessons-index.md detects promotion by searching for that reference inside skills.

• LL-040 — Do not close or dismiss a criterion based on log silence until executing interaction that can reveal failure. If condition is not yet reproducible, keep gate or demonstrate structural parity with a functional baseline.

(added 2026-08-31, SP-239) Separate raw producer records from canonical derived records

When the runtime producer cannot derive a canonical output enum because an offline verifier owns that decision, the Forward Contract defines two record types from the start:

• X_RAW is emitted by the runtime producer. Its fields and enums contain only facts that actor can observe directly.
• X is the canonical record emitted by the named offline derivation step. Its contract owns the derived enum such as GREEN, RED, or INCONCLUSIVE.

Name the emitter for both records and state the transformation from X_RAW to X. Never make the raw producer satisfy the canonical enum by inventing an out-of-contract sentinel such as RAW-DATA-ONLY; that guarantees an enum violation rather than representing a third verdict. The analyze gate treats one record name shared by two emitters, or a derived field assigned to the raw producer, as a Forward Contract contradiction.