mobile-prototype

# Mobile Prototype Work out **what the screens are and how they connect** before anyone designs or builds them, working like a UX designer would. The prototype is a rough draw.io sketch on purpose: it keeps the discussion on features, states and branches, not on colours and spacing. ``` documents → proposals (gate A) → open questions (gate B) → draw.io sketch, flow locked (gate C) → optional: design system + final-look screens (gates D1, D2) → handoff ``` Paths in this file are relative to this skill's directory (`scripts/…`, `references/…`, `assets/…`). The user's project is the current working directory. ## Non-negotiables 1. **Documents propose, the user decides.** An answer found in a document is a *proposal* until the user approves it. Record who decided what. 2. **Ask only what changes the experience.** Conflicts between documents and unknowns that change a journey, a state or navigation get asked. Cosmetic choices you decide yourself and record. 3. **The flow lives in one file.** `docs/prototypes/flow.json` is the source of truth; the draw.io file and the final-look screens are generated from it by scripts. Never hand-write draw.io XML or HTML, and never place shapes or route arrows yourself. 4. **Rough on purpose.** The sketch uses plain boxes in a hand-drawn style. No brand colours, no real components, no pixel decisions before the flow is locked. 5. **Numbered and untangled.** Every screen frame carries a serial number (S1, S2, … in flow order), and people refer to screens by it everywhere. Review markup (numbers, remarks) stays outside the phone frame or in the frame's `note`. `sketch.mjs` refuses to draw crossing or shared arrows, arrows over screens, overlapping screens or labels in the way: never show a sketch that didn't pass `--check`, and fix a failure in `flow.json` (see "When the check fails" in `references/sketch-spec.md`), not in the diagram. 6. **Stop at every gate, and say what to read.** At each stop, end your turn: don't start the next phase ahead of the approval. Follow *Stops* below. 7. **Stop at a locked flow.** Deliver the sketch and a handoff package. Do not build a clickable app, and do not generate Compose, SwiftUI, Kotlin, Swift or production web code. 8. **Each platform behaves like itself.** The sketch is one flow for every platform in scope (P5); where Android and iOS differ (back, dialogs versus sheets, permission rules) say so in the frame's `note`. Follow `references/platforms/<platform>/conventions.md`. 9. **Everything lands in files** in one prototype folder inside the project, chosen by the user before the first file is written, so a fresh session can resume. 10. **First how it works, then how it looks.** The design phase is optional, starts only after the flow is locked (gate C) and only when the user chooses it, and never blocks the handoff. 11. **draw.io tooling helps; it never blocks.** If the draw.io MCP tools aren't loaded, say so in one line and carry on: the scripts write and open the diagram without them. ## Workspace (in the user's project) This document calls the prototype folder `docs/prototypes/` (the recommended location); wherever you read that path, use the folder the user chose in Phase 1. It must be inside the project: if the user names a path outside it (another repository, the home folder, `/tmp`), say the files have to stay in this project so they travel with it, and ask again. `scaffold.mjs` refuses such a path too. ``` docs/prototypes/ ├── README.md ← the reading guide for the user ├── flow.json ← journeys, screen states, transitions (you edit this) ├── flow.drawio ← the sketch, generated from flow.json ├── HANDOFF.md ← final deliverable for the native team ├── look/ ← design phase only: generated final-look screens └── notes/ ├── STATE.md ← phase, gates passed, next step (resume point) ├── INPUTS.md ← document inventory + fact register with citations ├── CLARIFICATIONS.md ← every question: source, proposal, status, decision ├── DECISIONS.md ← approved decisions and recorded assumptions └── DESIGN.md ← the visual direction (design phase only) + THEME-REPORT.md ``` `node scripts/scaffold.mjs --out <folder> --name "<App>"` creates `README.md`, `flow.json` and the four notes from templates, and never overwrites. Fill in what it creates; don't invent other files. The other scripts find the folder by its `notes/STATE.md`, so they need no `--out` unless the project holds more than one prototype folder. ## Stops The work pauses for the user only at these stops: **Inputs** (Phase 1), **gate A** (Phase 2), **gate B** (each Phase 3 round), **gate C** (Phase 4), **D1 / D2** (Phase 5) and the **handoff** (Phase 6). At every stop from gate A on, before ending your turn: 1. update `docs/prototypes/README.md` — *Where we are*, *Read now*, and each new file marked **you**, **reference** or **agent**; 2. record the stop in `STATE.md` under *Waiting on user*; 3. end the message with the short reading guide. Read `references/stops-and-reading-guide.md` at the first stop: it has what the user reads at each stop and the exact form of the guide. Everything the user must decide goes in the message. ## Phase 0 — Setup and resume 1. Look for an existing prototype folder: `docs/prototypes/notes/STATE.md`, the older default `prototype/notes/STATE.md`, or a `notes/STATE.md` next to a `flow.json` elsewhere in the project. If there is one, that is the prototype folder: don't ask for it again. Read `STATE.md` and every file in `notes/`, tell the user in two lines where things stand, and continue from the recorded next step; if that stop still waits on the user, repeat what it needs. 2. Check whether the draw.io MCP tools are available **in this session**: a tool whose name ends in `open_drawio_xml` (for example `mcp__drawio__open_drawio_xml`). 3. If they are missing, run `node scripts/check-drawio-mcp.mjs --host <this agent>` and show the result. **Ask** before changing the user's configuration, then run `--configure --host <this agent>` (without `--host` it configures every agent installed). A new server loads only after a restart: say so, record it in `STATE.md`, and **carry on**. Details: `references/drawio-setup.md`. ## Phase 1 — Discover the inputs 1. If the user named files, use those. Otherwise run `node scripts/discover-inputs.mjs --root .` to find specs, architecture, design, API contracts and images, plus **platform signals** with a suggestion. This step only reads; nothing is created yet. 2. **Ask where the prototype files should go** (the *Inputs* stop), unless the user already named a folder or Phase 0 found one: > Where should I put the prototype files? I recommend `docs/prototypes` (created if it > doesn't exist). Reply "ok" for that, or give another folder in this project. In the same message show the **availability table** — Spec / Architecture / Design / API / Other, plus the platform suggestion — with the files found for each. Ask the user to confirm the **target platform** (don't assume both), which documents are authoritative, which to ignore, and whether anything is missing (a design folder, a Figma link). Leave the table out when the user named the files and there is nothing to ask about them. End your turn. 3. "ok", "yes" or no preference means `docs/prototypes`. A relative path is relative to the project root; an absolute one must be inside the project (see *Workspace*). Then run `node scripts/scaffold.mjs --out <folder> --name "<App>"` and record the folder in `notes/STATE.md`. 4. Read every confirmed document in full (images too — look at them). Record the inventory and a fact register (ID, fact, source file § section) in `notes/INPUTS.md`. 5. Adjust for what is missing (`references/document-intake.md`). Without a spec, get at least a written feature description from the user before going on. ## Phase 2 — Answer from the documents → approval gate A Work through `references/question-bank.md`. For each question in scope, try to answer it from the fact register and classify it (full rules in `references/clarification-protocol.md`): | Class | Meaning | What happens | |---|---|---| | **A — Documented** | a document states it | propose it, with a citation | | **B — Inferred** | follows from documents but isn't stated | propose it as an assumption, with reasoning | | **C — Conflict** | documents disagree | must ask | | **D — Open, blocking** | unknown and changes a journey, state or navigation | must ask | | **E — Open, cosmetic** | unknown, low impact | pick a sensible default, record it | Write every item to `notes/CLARIFICATIONS.md`. Then present **A and B items** to the user as one compact table (question · proposed answer · source · confidence) and ask them to approve all, or correct by ID. Only approved items move to `DECISIONS.md`. Mention the E defaults in one line so the user can object. If there are C/D items, say how many questions will follow at gate B. Two things are always settled here or in Phase 3, and recorded in `STATE.md`: - **Target platforms (P5)**: Android, iOS or both. Propose it from the platform signals with citations; if there are none, or they disagree, ask. Never assume both. - **Sketch style (P6)**: ask in one line under the table — it is the user's preference, not something the documents answer: **wireflow** (the whole flow on one page per journey), **click-through** (a map, then one page per screen with clickable buttons) or **both**. With no preference, use the wireflow; the same `flow.json` produces all three. **Stop here (gate A).** Don't write `flow.json` or draw anything yet, even as a draft: the flow depends on the scope the user is about to approve or correct. ## Phase 3 — Close the gaps with the user → gate B Ask the **C and D questions**, most blocking first, **at most four per round**. Each question gives the evidence from the documents, two to four concrete options, and your recommended option first with a one-line reason. Use the host's structured-question tool when there is one (for example `AskUserQuestion` in Claude Code); otherwise ask as a numbered list in chat. Record each answer immediately. Answers can raise new questions — classify and queue them the same way. If the user says "you decide" or defers, record your choice as an assumption flagged for review. Gate B passes when no blocking (C/D) item is open. After three rounds, offer to proceed with the remaining items as flagged assumptions rather than keep asking. Each round is a stop. Once gates A and B have both passed (B passes at once when there are no C/D items), go straight on to Phase 4. ## Phase 4 — Sketch the flow → gate C 1. **Write the flow** in `docs/prototypes/flow.json` (format and element list: `references/sketch-spec.md`): - one **journey** per user goal in scope; - one **frame per screen state** the decisions require — the content state, and also empty, loading, error, offline, permission denied, validation error, and each dialog or sheet. Main path first, in the order the user meets the screens; a branch (a dialog, an error) names the screen it hangs under; - one **flow** per transition, labelled with what the user does ("tap Save", "Back with changes"), starting from the control that triggers it. Use realistic copy from the documents, not lorem ipsum. 2. **Generate and check**: `node scripts/sketch.mjs --style <wireflow|click-through|both>` writes `docs/prototypes/flow.drawio`; `node scripts/sketch.mjs --check` must pass. Then go through `references/sketch-review.md`. Fix `flow.json` and generate again; don't show a sketch with warnings you haven't looked at. 3. **Show it**: `node scripts/sketch.mjs --style <style> --open`, and give the user the file path (other viewers: `references/drawio-setup.md`). 4. **Stop (gate C).** In chat, give a short text outline of the journey (S-numbers and the arrows), the decisions you made on the user's behalf and the flagged assumptions, and ask them to lock the flow or say what to change. 5. **Changes**: treat feedback as new clarifications — record, change `flow.json`, regenerate, show again. If the user edited `flow.drawio` by hand, the script refuses to overwrite it: read their version (it is XML), carry every change into `flow.json` (ask if one is unclear), then run `sketch.mjs --force` (it keeps their version as `flow.drawio.bak`). Gate C passes only on an explicit approval; record it in `STATE.md` and `DECISIONS.md`. 6. After the approval, offer the design phase in **one line** (design system and final-look screens, or go straight to the handoff). Don't push it. ## Phase 5 — Optional design phase (only if the user chooses it) Read `references/design-phase.md` and follow it. The locked `flow.json` is the input; the user picks a direction from style tiles (gate D1) and approves the final-look screens (gate D2). The design phase changes how screens look, never the flow. If it is skipped or stopped, go to Phase 6. ## Phase 6 — Handoff and stop Write `docs/prototypes/HANDOFF.md` following `references/handoff-package.md`, with the sketch as visual reference. Update `STATE.md` to `complete`, and `README.md` so *Read now* is `HANDOFF.md` alone. Tell the user where everything is and stop — native implementation is a separate task. ## When guidance conflicts 1. The user's explicit decisions (in `DECISIONS.md`). 2. The supplied documents — the spec decides *what* the product does; the architecture decides what is *feasible*. Conflicts between them are class C and go to the user. 3. The platform conventions (`references/platforms/<platform>/conventions.md`). 4. The approved visual direction (`DESIGN.md`), for the look only; it never changes the flow or overrides the platform conventions. 5. Your own taste.