2 +name: prototyping-spec
3 +description: Use after an approved spec, before roadmaps/plans, when spec size or quality makes assumptions risky and temporary prototypes can verify claims against reality.
8 +Verify an approved spec against reality before planning.
10 +This phase uses temporary prototypes to prove or falsify spec claims, assumptions, integrations, data shapes, and logical consistency.
11 +Prototype tech does not matter.
12 +Use project tech, throwaway scripts, mocked fixtures, real APIs, or tiny harnesses as needed, as long as the proof is definite.
14 +**Announce at start:** "I'm using the prototyping-spec skill to verify the spec with temporary prototypes."
18 +Offer this phase after user approval of the written spec and before `/skill:writing-roadmaps` or `/skill:writing-plans` when either condition is true:
20 +- the spec is >250 lines
21 +- spec review flags assumptions, ambiguity, integration risk, or logical gaps
23 +Skip it for small, concrete specs with no risky assumptions unless the user asks for it.
27 +- Do not implement production code.
28 +- Do not start roadmap or plan writing during this phase.
29 +- Keep prototypes temporary unless the user explicitly asks to promote an artifact.
30 +- Prefer self-verifying commands over visual inspection or vibes.
31 +- Every claim checked must end as `supported | falsified | inconclusive`.
32 +- Delete temporary artifacts before handing back the report.
36 +###
Step 1: Load the Spec 38 +Read the spec and identify claims that must be true for implementation to work.
40 +Classify claims by risk:
42 +- **Architecture:** component boundaries, data flow, ownership, lifecycle
43 +- **Existing APIs:** real signatures, behavior, errors, extension points
44 +- **New APIs:** proposed shapes, call order, serialization, compatibility
45 +- **Data:** file formats, schemas, migrations, persistence, generated output
46 +- **Runtime:** platform behavior, dependency behavior, performance, concurrency
47 +- **Logic:** contradictions, impossible states, missing transitions
49 +###
Step 2: Pick Prototype Targets 51 +Prototype only claims where uncertainty can damage the plan.
53 +For each target, write a short verification card before coding:
57 +Hypothesis: if ... then ... because ...
58 +Falsifier: false if ...
59 +Prototype: temp path and tech
60 +Command: exact command to run
61 +Proof: observable output/assertion
62 +Cleanup: exact temp paths to delete
65 +Unfalsifiable claims are not ready for prototyping.
66 +Rewrite them into observable claims or flag them as spec ambiguity.
68 +###
Step 3: Build Temporary Prototypes 70 +Use the smallest prototype that can answer the claim.
79 +- generated sample data
80 +- microbenchmarks when performance is the claim
82 +Default location is outside the repo.
83 +If repo context is required, use one contained ignored directory such as `.pi/tmp/<slug>/` or `tmp/<slug>/` and record it.
84 +Never scatter scratch files.
88 +Run the command and record evidence.
90 +Use at least two independent checks when practical:
94 +- assertion failure on wrong output
95 +- rerun for determinism
96 +- compare with existing tests/docs/source
97 +- inspect generated output against expected shape
101 +- **supported:** evidence backs the spec claim
102 +- **falsified:** evidence contradicts the spec claim
103 +- **inconclusive:** prototype cannot decide the claim cleanly
105 +###
Step 5: Report Spec Improvements 107 +Do not silently edit the spec.
108 +Report suggested changes with rationale and evidence.
110 +Use this report shape:
115 +**Spec:** `path/to/spec.md`
125 +| Claim | Result | Evidence | Notes |
126 +| ----- | --------- | --------------------------- | ----- |
127 +| ... | supported | `command` + observed output | ... |
129 +### Suggested spec changes
137 +- Deleted temporary artifacts: ...
139 +### Remaining questions
144 +###
Step 6: Clean Up 146 +Delete temporary artifacts before final response.
148 +Required cleanup checklist:
150 +- stop started processes
151 +- delete temp dirs, scripts, outputs, logs, generated fixtures
152 +- keep only explicitly promoted artifacts
153 +- run `git status --short` if the repo was touched
154 +- explain any remaining dirty paths
158 +After reporting, ask the user whether to apply suggested spec changes or proceed to planning.
160 +If the user applies spec changes, update the spec and repeat the normal spec review gate before planning.
161 +If the user proceeds without changes, use `/skill:writing-roadmaps` for large/multi-phase specs or `/skill:writing-plans` for single-plan specs.