rubenglez Prototype
Step 1: Define the question
Before writing any code, state the design question in one sentence:
"Can [approach] handle [constraint] at [scale]?" "Which of [option A] / [option B] produces [outcome]?" "What does the state machine look like when [edge case] happens?"
If the question can't be written in one sentence, the prototype is too broad — narrow it first.
Read the relevant .harness/engineering/features/[slug].md to understand the full feature context, then surface the specific uncertainty that needs answering.
Confirm the question with the user before proceeding.
Step 2: Choose the approach
| Question type | Approach |
|---|---|
| Logic / state machine / business rules | Interactive terminal app — simulate inputs, display full state after each action |
| Visual / UX / layout | Multiple UI variations on one route, toggled via ?variant=a / ?variant=b |
| Library / external integration | Minimal single-file script that exercises the specific capability |
| Performance / data volume | Benchmark harness with representative data sizes |
Step 3: Build it
Rules — these are not optional:
- Mark as temporary: name files
_prototype-[slug]or place in a_spike/folder near the target location - Single entry point: one command to run, matching the project's existing conventions
- In-memory state: no persistence unless the prototype specifically tests database behaviour
- Speed over quality: no tests, no abstractions, minimal error handling
- Expose state changes: display full state after every action so every finding is visible
- No shared code: do not extract from or integrate into production code
Do not refactor the prototype. Do not make it "production-ready." It exists only to answer the question.
Step 4: Run and observe
Run the prototype. Work through the scenarios that exercise the question. Note:
- The answer to the design question
- What surprised you (constraints, edge cases, or behaviour that wasn't obvious from the spec)
- Whether the approach is viable
Share findings with the user before writing anything to .harness/.
Step 5: Capture and clean up
Approach is viable:
- Update the feature spec's Technical approach section in
.harness/engineering/features/[slug].mdwith what the prototype revealed — be specific about what works and any constraints discovered - If the finding resolves a genuine architectural trade-off (hard to reverse + surprising without context + real alternatives existed): write an ADR to
.harness/adr/NNNN-[slug].md - Delete ALL prototype code — including
_spike/folders and_prototype-*files - If the prototype revealed reusable patterns, describe them in prose in the ADR or feature spec — do not keep the prototype code as a reference
- Commit the spec/ADR updates:
git add .harness && git commit -m "docs: capture prototype findings"— worktrees and future sessions only see committed.harness/content
Approach is not viable:
- Update the feature spec: document what was tried and why it failed
- Propose an alternative approach to the user
- Delete ALL prototype code
- Commit the spec update:
git add .harness && git commit -m "docs: capture prototype findings"
After cleanup, confirm:
- What was written to
.harness/ - That prototype code has been deleted (list the deleted paths)
- What the recommended next step is:
/prototypeagain with a new question, or/implementif the design is now clear