# The method: AI-assisted PRDs with executable simulations

**In one line:** the product spec is a playable single-file app (the SIM). The written PRD is derived from it.
Every decision, rejected idea and version is kept. An AI assistant does the research, builds the SIM and keeps
the SIM and the PRD consistent.

## Why
- A static PRD hides gaps. When a reviewer can click through a SIM, missing states, races and contradictions show up in minutes.
- Feasibility problems found after design or build are expensive. This method checks feasibility while the SIM is still cheap to change.
- Teams forget why a decision was made, then argue it again. Here every decision has a date, an owner and a source.
- An AI assistant makes the cost of a new SIM version close to zero. The method relies on that.

## Stages

| # | Stage | Output | Gate |
|---|---|---|---|
| 1 | **Intake.** Research tickets, earlier PRDs, chats, code and docs. Old PRDs count as context, not requirements. | `notes.md` with sources and open questions | Open questions answered |
| 2 | **Surface matrix.** List which roles use which app on which platform. | App × Role × Platform table | Confirmed by the PM |
| 3 | **As-is SIM** (optional). Simulate today's behaviour. The SIM flags gaps by itself. | `current-sim.html` | Matches the shipped reference |
| 4 | **PRD v1 outline + SIM v1** | `prd-v1.md`, `sim-v1.html` | Scripted run passes with 0 console errors |
| 5 | **Feasibility and impact.** Check the SIM's assumptions against the real architecture and code. | `analysis.md` | **A serious issue forces a restructure, or a fork into v1/v2 alternatives** |
| 6 | **Competitive and standards research** | Matrix: products × behaviours, with confidence and sources | Shows what to copy and what to avoid |
| 7 | **Refine loop.** Collect changes, preview them, apply them as one batch, then version-stamp. | New SIM file per version. Old versions are never edited. | Every use case reaches *Decided* |
| 8 | **Use-case PRD.** Generate per-use-case pages from a catalogue. | Index, use-case pages, Mock page, versions table | Each use case links to a SIM scenario |
| 9 | **Review and handoff.** Answer reviewer questions inline against a named SIM version. | Answered questions, change requests, engineering tickets | Sign-off |
| 10 | **Release validation + reconciliation** (proposed). An AI drives the released app and compares it with the PRD and the SIM. | Reconciliation report | Each difference is classified, nothing is silently dropped |

## Three loops
- **Product loop:** idea → stakeholders → PRD outline → SIM → feasibility → impact → competitors → detailed PRD → review → design/engineering → release → AI validation → reconciliation → next iteration.
- **Validation loop:** an AI drives the released product and compares it with the PRD and the SIM. Each difference is classified as an intentional change (update the docs), an omission (move it to the backlog, never delete it) or an undocumented addition (document it).
- **Knowledge loop:** rejected and superseded ideas are archived with their reasons and the conditions for revisiting them. A periodic review asks which constraints are no longer true.

## SIM anatomy
- **One HTML file.** No network access, state lives in memory, refresh resets it. The version is in both the file name and the header.
- **Centre:** the app inside a realistic device frame that uses native platform patterns. Browser `alert()` is never used.
- **Driver controls:** a scenario or use-case selector, roles, device and surface, state matrix (happy, empty, loading, error, timeout, validation, permission), time and speed controls, environment toggles (API OK/error, client version).
- **World state panel:** the state of the backend, devices or other systems that the UI depends on.
- **Event log:** every simulated API call, broadcast, push and external signal, with its exact name. APIs that do not exist yet are marked.
- **"Changes vs current" overlay:** for each change it shows *current*, *proposed*, *logic*, *why*, *source* and *try it* (which loads the scenario).
- **Element rationale:** tapping an element shows why it exists, its pattern or inspiration, the requirement behind it, the technical reason, whether it is a new idea and the alternatives considered.
- **Element documentation:** a Description panel lists the elements on screen with their action and use-case ID. Rationale is shown through "Why" buttons. `[assumption]` tags appear inline.
- **Deep links:** the URL hash stores role, viewport and state, so a reviewer can open one exact case.

## PRD ⇄ SIM links
- Each use case has: situation, trigger, what happens, how each component behaves, today's behaviour, **SIM scenario ID**, sources, open questions and a status (*Proposed / Open / Decided*, with date).
- Each SIM change cites the PRD use case or decision that caused it. The Mock page lists the current SIM, the previous SIM and the as-is SIM.

## History rules
- Versions are never overwritten. v1 stays readable next to v2.
- Rejected ideas stay as pages marked *removed*, with the date and the reason. "Possible later" notes are kept.
- Different approaches can live as parallel PRDs (v1 "simple now" vs v2 "better, needs engineering").
- The decision log records who decided, when, why and the conditions under which the decision would be reopened.

## Kinds of statement (kept separate)
Every statement is labelled as one of: source fact, AI analysis, human decision, hypothesis, recommendation or historical rationale.

## Where AI helps
It reads and summarises sources, flags conflicts, drafts use cases, builds and patches SIMs, runs headless checks, researches competitors and standards, regenerates the PRD from the catalogue, answers reviewer questions against a specific SIM version and (proposed) validates the released app.

**Human gates.** Only the PM decides. Nothing is published without approval. Only engineering owns implementation.