In this method a product feature is first written as a short spec, then built as an interactive simulation (SIM): a single-file app where you can see the screens, play each use case, and watch the state, API calls and events behind them. Before anyone writes production code, the SIM goes through a feasibility gate. Every decision is logged with its reason, and rejected ideas are kept together with the conditions under which they could come back. After release, an AI drives the shipped app and the docs are corrected to match reality. An AI assistant helps at every step. People make the decisions.
The demo app, ShelfShare (a neighbourhood book-swap app), its company and everything in it are invented. The method comes from real product work; none of that work's content appears here.
A product loop, plus two loops that keep the knowledge alive. The walkthrough below applies all 14 steps, in order, to one feature.
What happens: one sentence of idea, then the problem in numbers, the outcome we want, and what each stakeholder wants or worries about. The result is a short list of initial use cases.
Why: the PRD starts from the problem, not a screen. Tensions between stakeholders are written down early, because they decide the design later.
FACT61% of agreed swaps never happened: "couldn't agree where/when" 38%, "no-show" 27%.
HYPOTHESISIf the app arranges where and when, and confirms the handoff, completion rises.
| Stakeholder | Wants | Worries |
|---|---|---|
| Community lead | Fast, friendly swaps | Bureaucracy |
| Trust & safety | Public places, reporting | Location leaks |
| Platform eng | Reuse existing services | New real-time infra |
AITension logged as Q1: live proximity vs location privacy.
What happens: a one-page outline. It lists the use cases (each with a SIM scenario ID and a status), the technical interactions as currently imagined, the assumptions and the open questions.
Why: the first PRD is a hypothesis. It only has to be concrete enough to build a SIM from. Each assumption is written down so the next stage can test it.
| ID | Use case | SIM | Status |
|---|---|---|---|
| UC-1 | Browse nearby, sorted by metres, "nearby now" dot | browse | Proposed |
| UC-4 | Meet now: both members see a live map | meetnow | Proposed |
| UC-5 | Handoff code, books change shelves | handoff | Proposed |
Assumption A1: members accept sharing live location during a swap.
API: location.stream.publish/subscribe: NEEDS ENG DEFINITION
What happens: the outline becomes a single-file interactive app. It shows both members' phones, a use-case driver, a state matrix (empty, loading, error, timeout), a live server-state panel, an API & event log, and per-element rationale (Inspect mode).
Why: playing a use case shows what a document hides. In this case the server-state panel shows two members' coordinates being exchanged every 5 seconds, which nobody had noticed in the text.
API log while two members walk towards each other:
16:40 → maya location.stream.publish NEEDS ENG DEFINITION
{"lat":51.512,"lon":-0.1118}
16:40 → tom location.stream.publish NEEDS ENG DEFINITION
16:40 ⚡ location.updated {"swapId":"sw1","members":2}
Server state: member_positions (shared between members) → both rows filled.
What happens: the SIM, including its API log, is checked against the existing architecture, policies, other in-flight PRDs and other products. Each finding is labelled as fact, AI analysis or hypothesis.
Why: this is the cheapest moment to find out the core idea can't ship. Here four findings combine into one serious issue.
| # | Finding | |
|---|---|---|
| F2 | No real-time channel; 9–12 weeks to build | FACT |
| F3 | Policy P-7: coordinates never sent to another member | FACT |
| I1 | "Nearby now" dot conflicts with the in-flight Quiet profile PRD | AI |
| I4 | Home location inferable after ~3 swaps | AI |
What happens: 2–3 comparable products are studied for how they solve the same problem: what works, what users complain about, and what not to copy.
Why: it comes after the gate, so it shapes the restructured version rather than polishing a version that can't ship. The lessons become element rationale inside the SIM.
| Learned | From | Became |
|---|---|---|
| Credits break the "nothing I want" deadlock | PageTrade | UC-2b credits |
| Fixed public places feel safe | BookBench | Swap Spots |
| "Box was empty when I got there" | BookBench | Hold after accept |
Not copied: live location (SwapCircle: safety reviews), public star ratings (risk of retaliation), postage.
All three competitors are fictional.
What happens: the decision is logged with who, when, why, the rejected alternatives and the conditions for revisiting it. Then PRD v2 and SIM v2 are written. v1 is not edited; it stays readable as a superseded version.
Why: a year from now someone will say "why don't we just show who's nearby?" The answer, and the conditions under which it could become yes, are already written down.
DECISIONDL-1, week 4: replace live location with Swap Spots, 1-hour windows and boolean check-in. Keep the handoff code.
Rejected: blurred live location (still triangulates); live location only near venues (same infrastructure cost); chat only (doesn't fix the failure rate).
HISTORYRevisit v1 when all are true: (1) a real-time channel exists for other reasons, (2) legal approves a consented P-7 exception, (3) proximity can be computed without exchanging coordinates, (4) Swap Spots miss the 70% target.
What happens: reviewers play SIM v2 and comment against a named scenario. An AI reviewer goes first. Each piece of feedback becomes a tracked change, a new use case or an explicit "build last".
Why: comments tied to a scenario are concrete and quick to check. Engineering receives behaviour, not drawings: the API log and server state show exactly what the system has to do.
| # | From | Change |
|---|---|---|
| R1 | AI | Code expires after 10 min |
| R2 | Trust & safety | New UC-9: private Report a problem |
| R3 | Platform | Reuse the existing one-time code service |
| R4 | Design | Code shown as 482 · 913 to read aloud |
| R7 | Platform | Counter-offer marked "build last" |
Handoff: PRD 2.0.1 + SIM v2 + decision log. Two APIs left for engineering to define: slot capacity and check-in radius.
What happens: after release, an AI agent drives the real app on a test device with two test accounts. It runs every use case and compares screens and network calls with the PRD, the SIM, the engineering docs and the ticket history.
Why: what ships always differs a little from what was specified. The aim isn't to blame anyone; it's to find out what actually exists.
| Finding | Class |
|---|---|
| V1 · 30-min slots instead of 1-hour windows | 🔁 intentional change |
V2 · No counter-offer (swaps.counter → 404) | ⛔ omitted |
| V3 · "Want list" ♡ on book cards: in no document | ➕ undocumented addition |
AIHYPOTHESISV3 pushes at listing time may reveal when a neighbour is active, the same concern as I1.
What happens: each difference is reconciled. Nothing is silently deleted, so the docs end up describing reality and how it got that way.
Why: the next person to read the PRD sees what is really live, what is still wanted, and which ideas are waiting for their conditions to change.
| Ver | Change |
|---|---|
| 1.0 | Live "Meet now" (superseded, kept) |
| 2.0 | Swap Spots, credits, holds |
| 2.0.1 | Review changes |
| 2.1 | Reconciled with release |
Both SIMs are fully interactive and run offline. Pick a use case on the left; it plays on both phones while the server state and the API & event log update on the right. Turn on 🔍 Inspect elements and tap anything on a phone to see why it exists. In v2, Changes vs v1 lists every difference with its reason.
v1 was not wrong to build. It was the fastest way to find out the core idea couldn't ship. Keeping it, together with the reason it was replaced, turns a dead end into knowledge someone can reuse.
arrived:true only482 · 913, 10-min expirysim-v1.html is frozen; the build script refuses to overwrite it