Build Dod

Build DoD

A DoD converts a spec into pass/fail gates. Its power is in integration tests — scenarios that prove the deliverable works by exercising it the way a user would.

Core Principle

Tests aren't there to be passed. They're there to prove results. Verify the deliverable through integration scenarios that exercise it end-to-end, not through unit tests that verify internals.

Process

1. Read the full spec
2. List deliverables — the artifacts that exist when done
3. If a digraph/flow diagram is provided, extract intended user journeys, decision points, and outcomes from it
4. Write acceptance criteria — one observable assertion per row
5. Inventory every user-facing message surface from the spec
6. Write integration test scenarios that prove the deliverable works end-to-end
7. Map each AC and each message to the scenario(s) that prove it
8. Crosscheck — confirm every AC and every message is covered and every scenario is sound

When this skill is used inside an Attractor run, scratch outputs should be written under .ai/runs/$KILROY_RUN_ID/.... Root .ai is not implicitly ingested.

If a digraph is provided

Use the graph in two passes:

1. Intent pass (primary): Treat the graph as a map of product intent and user flow. Use it to identify the major journeys, decisions, and failure/recovery paths that matter to users.
2. Flow sanity pass (secondary): Do lightweight topology checks only to catch intent-breaking issues (for example, a required outcome has no reachable path).

Acceptance Criteria

Each AC is a single, testable assertion using observable language: "exists", "returns", "displays", "produces", "exits 0".

Group by concern (e.g. Build, Output, Behavior, Integration). Number hierarchically: AC-1.1, AC-1.2, AC-2.1.

ACs describe what must be true. They are proven by integration test scenarios, not by individual unit tests.

Integration Test Scenarios

Integration tests are the primary verification mechanism. Each scenario exercises the delivered artifact directly, proving multiple acceptance criteria simultaneously.

When a digraph exists, write scenarios around high-level intent coverage, not exhaustive graph traversal. Prefer:

• Primary happy paths
• High-risk branches and decision outcomes
• Critical error/recovery paths
• Mode transitions that change user experience (for example first run vs returning user)

Test the delivered artifact in its delivery form. At least one scenario must exercise the full delivery path:

• Browser app → serve it in a browser, confirm it loads and runs
• CLI tool → invoke the binary, check exit code and output
• Library → import it and call its public API
• Data file → consume it with its intended reader

If the deliverable is a browser app and no scenario loads it in a browser, the DoD is incomplete.

Validate every user-facing message. Help text, error messages, status displays, feedback strings, prompts, and warnings are promises to the user. Inventory all of them from the spec, then ensure each one is triggered and validated in at least one scenario:

• Trigger the condition that should display it
• Confirm the message appears
• Confirm what the message says is true (if help says "press ? for help", pressing ? must show help)

This means all messages, not a sample. If the spec describes 20 distinct message surfaces, 20 must be tested.

When one artifact references another, verify both. A source file that references an output is evidence of intent; confirm the output itself is present and valid.

For each primary way the deliverable is used, write a scenario with:

• Starting state — deterministic inputs (fixed seed, known data, clean environment)
• Actions — a sequence of operations a real user or consumer would perform
• Expected outcomes — observable results after each action

Scenarios should cross multiple AC groups. A browser app scenario might cover loading, display, input, and state persistence in one flow.

Each scenario is self-contained — it sets up its own preconditions within the test rather than depending on externally pre-computed inputs or manual preparation.

Each scenario becomes a named automated test in the DoD, with test exits 0 as its verification.

For checks that require judgment, write a concrete semantic verification with:

• The question to answer
• The expected answer
• The evidence to examine (file paths, commands, artifacts)