Task: Generate PROTOTYPE.md — Empirical Validation of Risky SPEC Assumptions

Task: Generate PROTOTYPE.md — Empirical Validation of Risky SPEC Assumptions

Objective

Produce a PROTOTYPE.md that resolves every R-NN risk surfaced by G2 SPEC_REVIEW.md before the SPEC regenerates. Each risk is settled by writing scratch code in units/<area>/u<NN>/prototype/, running it, capturing concrete evidence, and translating the empirical findings into a constraint or caveat the SPEC must encode. The skill emits a machine-readable verdict (go, go-with-caveats, or abort) that the orchestrator branches on: go regenerates the SPEC unchanged in approach, go-with-caveats regenerates with the surfaced caveats encoded, abort regenerates with a fresh approach (or escalates to human if the prototype budget is exhausted). An agent reading PROTOTYPE.md alone — without re-reading the SPEC, the SPEC_REVIEW, or the prototype scratch code — can tell exactly what was empirically validated, what caveats apply, what new risks surfaced, and what specific edits the SPEC must apply on regeneration.

PROTOTYPE.md exists because real-world testing of the ADD pipeline showed SPECs frequently encoding silent assumptions about library behavior, runtime semantics, and integration friction — assumptions the SPEC author drew from documentation but never verified by running code. Implementations would discover the assumptions wrong only after a complete G5 implementation cycle, forcing expensive re-work. The defining discipline — and the commonest violation — is evidence over reasoning: every finding cites concrete output (a token-tree dump, a timing measurement, an error verbatim, a screenshot, a test runner pass/fail), not the agent's reasoning about what should happen. The commonest failure is declaring a risk "resolved" with no captured evidence — typically because the experiment was inconclusive but the agent moved on. If a finding cannot cite evidence, the experiment was not conclusive and must be iterated.

Inputs

1. SPEC_REVIEW.md (required, primary driver) — for the unit. Read § 5 Risk Surface (the R-NN entries) and § 8 Prototype Brief (the consolidated question-driven brief) end-to-end. These are the questions to answer; every R-NN becomes a § 2 entry in the output. Path: units/<area>/u<NN>/SPEC_REVIEW.md.
2. SPEC.md (required) — for the unit. Read for context — what the unit is meant to do, what the proposed approach is, what the risks relate to. Do not modify. Path: units/<area>/u<NN>/SPEC.md.
3. Design artifacts cited by R-NN entries (required, scoped per risk — typically 1–2) — usually a subset of INTERFACES.md (for wire-format risks), BEHAVIOR.md (for state/saga risks), DATA.md (for schema risks), or one of the surface IAs (for UI risks). Read only the artifacts named by the R-NN entries' reference materials; do not pre-load the full design suite.
4. Existing codebase (required, accessed via Grep, Glob, and Read) — for reading production code that the prototype will integrate with or mimic. Read-only. Do not modify production code under any circumstances.
5. Web (required, accessed via WebSearch and WebFetch) — for library documentation, GitHub source, npm/crates/PyPI registries, RFCs, and the literal source files of installed dependencies when documentation diverges from observed behavior.

Read-set size: 1 SPEC_REVIEW + 1 SPEC + 1–2 design artifacts + tool reads (codebase, web). Within ADD's 10-artifact budget.

Workflow

The skill is a focused, sequential, exploratory task — single-agent, no subagents. Five phases.

Phase 1: Read Inputs

Read SPEC_REVIEW.md § 5 Risk Surface and § 8 Prototype Brief end-to-end. Read SPEC.md end-to-end for context. Read the 1–2 design artifacts cited by R-NN reference materials.

For each R-NN, build an in-agent working list:

• The verbatim question from SPEC_REVIEW § 8.
• The verbatim assumption from SPEC_REVIEW § 5.
• The reason the question cannot be answered by reading.
• The suggested prototype scope and reference materials.

If any required input is missing — units/<area>/u<NN>/SPEC_REVIEW.md does not exist, has empty Risk Surface, or has no Prototype Brief — stop and emit a PROTOTYPE.md with status: blocked describing exactly which input is missing or empty. Do not invent risks to prototype. PROTOTYPE only runs when SPEC_REVIEW emitted verdict: prototype-needed.

Phase 2: Plan Prototypes