/prototype/`.
### 7. New risks may surface
If a new empirical question emerges during prototyping that was not on the original `R-NN` list, surface it in § 6 New Risks Discovered with the same shape as a SPEC_REVIEW `R-NN` (assumption, why-not-readable, suggested prototype, materiality). Do not silently expand prototype scope to chase the new question; the new risk becomes input to the next SPEC_REVIEW round (or escalates to human if the prototype budget is exhausted).
### 8. Verdict discipline
The verdict is computed from per-`R-NN` verdicts mechanically:
```
all in {resolved} → go
at least one resolved-with-caveats; none unresolved or new-risk → go-with-caveats
at least one unresolved (material) OR
at least one new-risk-discovered (material) → abort
```
Materiality test: a per-risk verdict is **material** if its consequence affects the SPEC's stated approach (wire shape, behavioral path, library choice, performance budget, error code). Non-material `unresolved` or `new-risk-discovered` items are surfaced in § 6 and the overall verdict may still be `go-with-caveats`.
The verdict drives orchestrator behavior:
- `go` → SPEC regenerates with PROTOTYPE.md added to its inputs; the approach stands.
- `go-with-caveats` → SPEC regenerates with PROTOTYPE.md as input; § 5 Caveats are encoded into the SPEC.
- `abort` → SPEC must regenerate with a fresh approach (the current approach cannot work as-described). If the prototype round count has reached 2 (per ADD convergence cap), the orchestrator escalates to human instead.
There is no subjective override. A reviewer who believes a risk is acceptable downgrades it to `resolved-with-caveats` with an explicit caveat — not by overriding the verdict.
### 9. Risk-driven scope
The prototype tests only what the `R-NN` entries demand. Do not pad with generic edge-case tests, bench suites, or coverage exploration. Specifically:
- § 3 Edge Cases Tested includes only edge cases the prototype actually exercised in service of an `R-NN`, not a generic checklist.
- § 4 Performance Findings is included only when at least one `R-NN` has a performance dimension; otherwise it carries the omission stub.
- § 8 Recommendations is grounded in evidence captured during § 2 experiments, not general advice.
### 10. Single YAML frontmatter block
Exactly one YAML frontmatter block at the top of PROTOTYPE.md, containing the universal fields (`skill`, `date`, `status`) plus the prototype-specific fields. Never two blocks. Counts match the body exactly.
### 11. Precision over vagueness
No "appropriate", "relevant", "as needed", "etc.", "various", "reasonable", "best practice", "industry-standard". Use exact library names with versions, exact file paths, exact line numbers, exact field names, exact configuration values. Unresolvable ambiguity surfaces in § 9 Open Questions with options, tradeoffs, and a recommendation.
---
## Output Format
The template below is wrapped in a 4-backtick fence so that the inner 3-backtick blocks (the Reproduce shell block under § 1 and the evidence code blocks under § 2) render correctly. PROTOTYPE.md itself uses standard 3-backtick fences for those inner blocks.
````markdown
---
skill: PROTOTYPE.md
date: {YYYY-MM-DD}
status: {complete | has_open_questions | blocked}
unit: {U-NN}
verdict: {go | go-with-caveats | abort}
risks_addressed: {N}
risks_resolved: {N}
risks_unresolved: {N}
caveats_surfaced: {N}
new_risks_discovered: {N}
prototype_runtime_min: {N}
open_questions: {N}
---
# PROTOTYPE: {U-NN} — {Unit Name}
> Empirical validation of the `R-NN` risks surfaced by `add/{U-NN}/SPEC_REVIEW.md`.
> Scratch code retained at `add/{U-NN}/prototype/`. Verdict (`go`, `go-with-caveats`,
> `abort`) drives orchestrator branching back to `/SPEC.md` regeneration.
## § 1. Setup
- **Scratch directory:** `add/{U-NN}/prototype/`
- **Toolchain:**
- `{tool 1 name and version — e.g., "Node.js v22.9.0"}`
- `{tool 2 name and version — e.g., "tsx 4.19.0"}`
- `{...}`
- **Dependencies installed:**
| Package | Version (pinned) | Purpose |
|---------|------------------|---------|
| `{name}` | `{semver}` | `{which R-NN this supports}` |
(Repeat per dependency.)
- **Reproduce:**
```bash
cd add/{U-NN}/prototype/
{install command — e.g., "npm install"}
{run command 1 — e.g., "npx tsx experiment-r01.ts"}
{run command 2 — ...}
```
---
## § 2. Risks Addressed
For each `R-NN` from SPEC_REVIEW.md § 5:
### R-{NN}: {short title — copy from SPEC_REVIEW.md § 5}
- **Question (verbatim from SPEC_REVIEW § 8):** `{exact question}`
- **Approach:** `{one paragraph — what files in prototype/ contain the experiment, what they test, what assertions they make}`
- **Findings:** `{concrete factual answer — data, output, error messages, raw token-tree dumps, timing measurements. Use code blocks for evidence.}`
```
{captured terminal output, JSON dump, error trace, timing measurement, etc.}
```
- **Implication for SPEC:** `{specific claim or constraint the SPEC must now reflect, with proposed wording for the SPEC section — e.g., "Replace § 6 'shiki returns serializable token trees' with 'shiki returns token trees containing function references for theme application; serialization requires a custom toJSON conversion (see units//u03/prototype/serializer.ts)'."}`
- **Code link:** `prototype/{filename}` (relative to the scratch dir)
- `prototype/{filename-1}` — `{what it tests}`
- `prototype/{filename-2}` — `{what it tests}` (if multi-file)
- **Library source consulted (if any):** `{e.g., "node_modules/marked/src/Tokenizer.ts:142–156"}`
- **Verdict:** `{resolved | resolved-with-caveats | unresolved | new-risk-discovered}`
(Repeat for each `R-NN`. Every `R-NN` from SPEC_REVIEW.md § 5 must appear here. If SPEC_REVIEW had no risk surface, do not run this skill.)
---
## § 3. Edge Cases Tested
Risk-driven only — only edge cases the prototype actually exercised in service of an `R-NN`. Do not include a generic checklist.
| Case | Expected | Actual | Verdict | Driving R-NN |
|------|----------|--------|---------|--------------|
| `{specific input or scenario}` | `{expected output}` | `{actual output}` | `{pass \| fail \| quirk}` | `R-{NN}` |
(Repeat per case. If none: "No edge cases tested beyond the primary R-NN experiments.")
---
## § 4. Performance Findings
(Include this section only if at least one `R-NN` has a performance dimension. Otherwise: "No performance dimension in any R-NN; section omitted.")
- **Baseline (current SPEC approach):** `{timing — e.g., "1240ms per 100-token tree, n=10"}`
- **Alternative tested (if any):** `{timing}`
- **Bottleneck identified (if any):** `{specific operation and its share of total time}`
- **Implication for SPEC:** `{specific budget or strategy the SPEC must encode}`
---
## § 5. Caveats and Constraints
Every constraint the SPEC must encode for the implementation to succeed. Each entry is paired with the `R-NN` that surfaced it.
#### {Caveat title}
- **Driving R-NN:** `R-{NN}`
- **Type:** `{configuration | version pin | error-path | order-of-operations | limitation}`
- **Constraint (exact wording for the SPEC):** `{e.g., "shiki must be initialized with codeToTokens (not codeToHtml) when rendering inside react-diff-view; see prototype/serializer.ts"}`
- **What breaks if missing:** `{specific implementation failure — e.g., "react-diff-view re-tokenises and discards shiki's theme metadata; the production code will render unstyled tokens."}`
(Repeat per caveat. If none: "No caveats — every R-NN resolved without constraints.")
---
## § 6. New Risks Discovered
Empirical questions that surfaced during prototyping but were not on the original `R-NN` list. These become input to the next SPEC_REVIEW round (or escalate if material and the prototype budget is exhausted).
#### {Short title}
- **Surfaced by:** `R-{NN} experiment in prototype/{filename}`
- **Assumption (newly identified):** `{exact statement of what was implicitly assumed}`
- **Why it cannot be answered by reading:** `{specific reason — same shape as SPEC_REVIEW R-NN justification}`
- **Suggested prototype:** `{one-line scope of what to test}`
- **Materiality:** `{material | non-material — and why}`
(Repeat per new risk. If none: "No new risks discovered.")
---
## § 7. Verdict
**verdict: `{go | go-with-caveats | abort}`**
{One paragraph. Begin with what was empirically validated (name the strongest finding — e.g., "shiki's token trees survive round-trip through react-diff-view's diff hunks when codeToTokens is used"). Then summarise: what caveats apply (point at § 5), what new risks surfaced (point at § 6), what the SPEC author must update before the unit can proceed. If `abort`, name the unresolved risk and the reason the current approach cannot work as-described. If `go`, conclude that the SPEC may regenerate with PROTOTYPE.md as input and proceed to /PLAN.md.}
---
## § 8. Recommendations for Production Implementation
Concrete, evidence-grounded advice for the SPEC author. Each recommendation cites the `R-NN` (and § 2 finding) that supports it.
#### {Recommendation title}
- **Driving R-NN(s):** `R-{NN}`
- **Recommendation:** `{exact API shape, exact strategy, exact infrastructure addition — e.g., "Use shiki.codeToTokens() and feed tokens to a self-recursive renderToken function that walks react-diff-view hunks; do not pass through codeToHtml() because react-diff-view re-tokenises HTML."}`
- **Final API/struct shape (if applicable):**
```
{exact type signature or struct definition}
```
- **Quirks the production code must handle:** `{specific quirk and how — e.g., "Empty hunks with line:0 do not produce output; guard with `if (hunk.lines.length === 0) return null;`."}`
- **Graceful degradation needed (if any):** `{when and how — e.g., "Inputs > 1MB exceed react-diff-view's default chunking; fall back to plain rendering."}`
(Repeat per recommendation. If none: "No production recommendations beyond § 5 caveats.")
---
## § 9. Open Questions
Genuinely unresolved review-level questions where empirical evidence was contradictory, insufficient, or would require infrastructure beyond the scratch directory.
- [ ] `{Question — e.g., "Behavior under sustained load (10⁴ token trees / sec) was not measurable in a single-process prototype; do we need a load-test rig before SPEC?"}`
- **Option A:** `{interpretation}` — `{tradeoff}`
- **Option B:** `{interpretation}` — `{tradeoff}`
- **Recommendation:** `{suggested resolution or "escalate to human"}`
(If none: "All questions resolved.")
````
---
## Scope
### In scope
- Reading SPEC_REVIEW.md § 5 Risk Surface and § 8 Prototype Brief end-to-end
- Reading the unit's SPEC.md for context
- Reading the 1–2 design artifacts cited by `R-NN` reference materials
- Tool-driven access to the codebase (read-only) and web sources
- Initialising a scratch project at `units//u/prototype/` with appropriate toolchain
- Installing dependencies inside the scratch directory at versions pinned by the SPEC
- Writing throwaway code, fixtures, scripts, and tests inside the scratch directory
- Running experiments iteratively, capturing output, dumps, timings, and errors as evidence
- Reading installed library source when documentation diverges from reality
- Producing PROTOTYPE.md with per-`R-NN` findings, caveats, recommendations, and a mechanically-computed verdict
- Surfacing newly discovered empirical risks in § 6 for the next SPEC_REVIEW round
- Retaining the scratch directory as a permanent artifact for reproducibility
### Out of scope
- Authoring or modifying SPEC content — owned by `/SPEC.md` (G1) on regeneration. PROTOTYPE proposes constraints and recommendations; the SPEC skill encodes them.
- Re-running spec-review or recomputing the risk surface — owned by `/SPEC_REVIEW.md` (G2).
- Modifying production code, sibling units' prototype directories, or repository-root configuration files — strict read-only outside the scratch directory.
- Implementation of the unit — owned by `/IMPLEMENTATION.md` (G5) after the SPEC is final.
- Cross-unit risk analysis — every unit's prototype is independent; risks for one unit do not leak across units.
- Long-running experiments (> 1 hour wall-clock) — surface as a § 6 New Risk and escalate; the prototype budget is for fast empirical answers, not extended benchmarking.
- Polishing prototype code, adding test coverage beyond what an `R-NN` demands, or refactoring scratch experiments — the prototype is throwaway.
- Resolving the SPEC's own open questions — owned by the cross-cutting `/decide` skill before SPEC_REVIEW runs.
- Fetching live data from production external systems — use staging endpoints or recorded fixtures inside the scratch directory.
---
## Quality Checklist
Before considering PROTOTYPE.md complete, verify:
- [ ] Output file has valid YAML frontmatter with all required fields (`skill`, `date`, `status`, `unit`, `verdict`, `risks_addressed`, `risks_resolved`, `risks_unresolved`, `caveats_surfaced`, `new_risks_discovered`, `prototype_runtime_min`, `open_questions`)
- [ ] Single YAML frontmatter block at the top — never two
- [ ] No placeholders, TODOs, or vague language ("appropriate", "relevant", "as needed", "etc.", "various", "reasonable", "best practice", "industry-standard")
- [ ] § 9 Open Questions is present (empty with "All questions resolved." or with genuine review-level ambiguities only)
- [ ] Output is self-contained — readable and actionable without re-opening SPEC_REVIEW.md, the SPEC, or the prototype scratch code
- [ ] Every `R-NN` from SPEC_REVIEW.md § 5 appears in § 2 with a per-risk verdict (`resolved`, `resolved-with-caveats`, `unresolved`, or `new-risk-discovered`)
- [ ] Every § 2 finding cites concrete evidence (terminal output, JSON dump, error verbatim, timing measurement, screenshot path, test runner output, library source path) — no findings rest on agent reasoning alone
- [ ] § 1 Setup lists exact toolchain versions and exact pinned dependency versions; the Reproduce block contains commands that recreate the experiments end-to-end
- [ ] Scratch directory exists at `units//u/prototype/` and is not empty — every § 2 finding's Code link resolves to a file inside it
- [ ] § 5 Caveats and Constraints names every constraint the SPEC author must encode; each caveat is paired with the `R-NN` that surfaced it and states exactly what breaks if missing
- [ ] Verdict is computed mechanically from per-`R-NN` verdicts: `go` iff every per-risk verdict is `resolved`; `go-with-caveats` iff at least one is `resolved-with-caveats` and none are materially `unresolved` or `new-risk-discovered`; `abort` iff at least one is materially `unresolved` or `new-risk-discovered`
- [ ] § 6 New Risks Discovered is present (empty with "No new risks discovered." or with newly-surfaced empirical questions in the same shape as SPEC_REVIEW `R-NN` entries — assumption, why-not-readable, suggested prototype, materiality)
- [ ] No production-code modifications occurred — every file edit during this skill landed inside `units//u/prototype/`
- [ ] § 8 Recommendations are concrete (exact API shapes, exact struct definitions, exact strategies) and grounded in § 2 evidence — no vague "consider X" or "use the right Y" advice
- [ ] § 4 Performance Findings is present iff at least one `R-NN` had a performance dimension; otherwise it carries the omission stub
- [ ] § 7 Verdict paragraph names the strongest empirical validation finding and connects it to § 5 caveats and § 6 new risks
- [ ] Frontmatter counts match the body exactly: `risks_addressed` equals the count of § 2 entries; `risks_resolved` equals the count of per-risk verdicts in `{resolved, resolved-with-caveats}`; `risks_unresolved` equals the count of per-risk verdicts in `{unresolved, new-risk-discovered}`; `caveats_surfaced` equals the § 5 entry count; `new_risks_discovered` equals the § 6 entry count; `open_questions` equals the unresolved checkbox count in § 9
- [ ] `status` is `complete` if § 9 reads "All questions resolved.", `has_open_questions` if any unresolved checkbox remains, `blocked` only when a missing input prevented prototyping (Phase 1 abort)