Dayz Feature Spec

---
name: dayz-feature-spec
description: >
  Define and quality-gate a non-trivial DayZ feature before implementation.
  Produces measurable Success Criteria, Given/When/Then scenarios with in-game
  repro, resolved ASSUMED markers, and a Forward Contract for every classname,
  model.cfg selection, .p3d proxy, stringtable/layout key or injected object the
  next phase consumes. Then runs a spec checklist and a read-only
  spec↔plan↔tasks/HANDOFF↔code consistency gate for coverage gaps,
  contradictions, terminology drift and unverified references. Use for "spec
  de la feature", "definición de done", "criterios de aceptación", "antes de
  implementar", acceptance criteria, consistency/analyze gate, spec checklist
  or "¿está listo para codear?". Run after planning and before
  dayz-mod-workflow; compose with rigorous-data-audit for data-critical work.
---

# 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](https://github.com/github/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.