App requirements document template: from a one-page PRD to your first feature spec

The product requirements document has one job: to hold the decisions that no template, agency or agent can make for you. Everything else — architecture, screens, data model, timeline — follows from these, so they come first and they stay short. Five sections, one page, plain sentences.

1. Who it's for, and the moment they need it. One or two sentences. Not a persona with a stock photo — a person in a situation. "Runners in a weekly club who need to check in at the start line in the thirty seconds before the run begins, often with cold hands and no signal." The situation carries more design information than a demographic ever will.

2. What it does — the job, in one sentence, then the three core flows. The sentence is the app's reason to exist. The three flows are the things a user does most, each written as "user does X, sees Y": "Runner opens the app at the start line, sees this week's run, taps once to check in." If you cannot write three, you are not ready to build; if you want to write nine, you are describing version four.

3. What v1 deliberately leaves out. The most valuable section, and the one every long-form template lacks. List the features you thought of and are not building first — accounts, payments, social, notifications, the admin panel — with one clause on why they wait. This is the section that saves you from the week-three collapse where the app tries to be everything.

4. How you'll know it worked. One or two measurable signals, observable within the first weeks — not "10,000 downloads" but "the organiser stops using the paper list" or "eight of ten club members check in through the app on week two." This tells you and the builder what to optimise, and it tells you when to stop.

5. What must never break — and what the app must not do. Constraints that are true from day one: the data must work offline; nothing is stored about minors; it must run on last year's phones; it must not require an account to use the core flow. Each of these changes the architecture, so the builder needs them before the first screen is written.

That is the whole document. Add a line for platform (iPhone first, Android at launch, both from day one) and a line for the backend you already have, if any. Everything a long-form template asks for beyond this either belongs in a feature spec, or belongs to a later version, or is something you will only learn by shipping. Modaal's own quickstart puts the preparation the same way: "A clear app idea in 3–5 sentences, a short PRD, or one core user flow to ship first." The word to notice is or — any one of those is enough to begin.

A feature spec answers a narrower question than the PRD: for this one piece of the app, what does finished look like, and how will we check? It is short because a feature is small, and it is written late — right before building — because by then you know things you did not know when you wrote the PRD.

The structure below is the one Modaal's agent produces when you turn the Plan toggle on and ask for a feature; our documentation lists the sections as: Overview, User Scenarios, Technical Approach, Implementation Steps, Files to Modify, Risks & Open Questions, Testing Strategy. Three of them are yours to write or approve; the rest a builder fills in.

Overview. Two sentences: what the feature is and which PRD flow it serves. If it serves none, it is a v2 feature wearing a v1 badge.

User scenarios. The heart of the spec, and the section that most templates get wrong by writing "user stories" that describe wishes rather than outcomes. Write each scenario as Given a starting state, When the user does something, Then a specific, observable result — and write one scenario per way the feature can end. A check-in feature has a happy ending (checked in), an already-checked-in ending, a no-signal ending, and a run-not-open-yet ending. Four scenarios, four endings, nothing vague left for the builder to guess. Modaal's cross-platform framework, Duet, uses exactly this rule for its feature one-pagers — "the states, the transitions, and a row per ending the feature can reach" — because the endings are what get tested.

Technical approach. How it will be built: which screens, what data, what the app needs from a backend, what is reused from features that already exist. If you're not technical, this section is the builder's; your job is to read it and ask about anything that surprises you.

Implementation steps. An ordered list. Its value is not the ordering; it's that a numbered list becomes a checklist a builder ticks off — and that you can see when step three is "add an account system" for a feature that shouldn't need one.

Files to modify. Builder's section. For an AI agent this is what keeps feature twenty from quietly rewriting feature three.

Risks and open questions. The honest list: what's unknown, what depends on a decision not yet made, what might not work on older phones. Empty risk sections are the most reliable sign of a spec nobody thought about.

Testing strategy. One line per scenario: how each ending will be checked. If a scenario cannot be tested, it was not a scenario; it was a hope.

That is about a page for a small feature and two for a large one. Written just-in-time, one at a time, in the order the PRD's core flows dictate.

If you take a single technique from this page, take this one. The difference between a requirements document that gets built correctly and one that gets built approximately is almost always in the scenarios — specifically, whether they cover the endings.

"The user can check in to a run" is a feature description. It leaves the builder to decide what happens when the run hasn't opened, when the phone has no signal, when the user taps twice, when the run was cancelled. Each of those decisions will be made — by an engineer at 6 pm, or by an agent in the moment — and none of them will be made the way you'd have made them. Now the same feature as scenarios:

Given this week's run is open and I haven't checked in, when I tap Check in, then I see a green confirmation with my name and the time, and the organiser's list shows me within a minute.

Given I've already checked in, when I open the app, then I see my check-in time and no button.

Given I have no signal, when I tap Check in, then the app records it locally, shows "will sync", and syncs when signal returns.

Given the run is cancelled, when I open the app, then I see the cancellation and no way to check in.

Four short lines. Every one of them is testable; every one of them removes a decision from the builder; and together they are the feature. Modaal's Duet framework takes this further than paper can: scenarios are written "Given / When / Then — a branch per ending", recorded into fixtures that "are never edited by hand, and they win any disagreement with the prose", and replayed on both iPhone and Android in the build. The written scenario becomes the thing the code is checked against. You don't need Duet to get most of the benefit; you need the habit of writing the endings.

To make the two layers concrete, here is a small real-shaped app carried through both documents. It is deliberately modest — that is the point of a v1.

PRD — RunClub Check-in (one page)

Who, and the moment: members of a weekly running club who need to check in at the start line in the thirty seconds before the run begins, often with cold hands and unreliable signal. The organiser currently uses a paper list.

The job: replace the paper list with a one-tap check-in the organiser can see live.

Three core flows: (1) member opens the app at the start line, sees this week's run, taps once to check in; (2) organiser opens the app, sees who's checked in, live; (3) organiser creates next week's run in under a minute.

v1 leaves out: accounts and passwords (members are identified by a club code plus their name — no sign-up); payments; route maps; push notifications; the history view; any admin website. All are plausible later; none is needed to retire the paper list.

How we'll know: the organiser doesn't bring the paper list on week three.

Must never break / must not do: check-in must work offline and sync later; the app must not require an account for the member flow; nothing about members is shown to other members except first names; runs on iPhones from the last four years.

Platform: iPhone first, Android at the club's request within the season. Backend: none yet; a hosted database is acceptable.

Feature spec — 001 Member check-in

Overview: the member's one-tap check-in for the current run; serves core flow 1.

User scenarios: the four scenarios from the previous section, verbatim.

Technical approach: one screen showing the current run (name, date, status); a check-in action that writes locally first, then to the shared list; club identity from a stored club code and name entered once; no login.

Implementation steps: (1) current-run screen with mock data; (2) local check-in state with the four endings; (3) shared list write with retry; (4) organiser-side read (feature 002 reuses it); (5) empty and cancelled states.

Files to modify: builder's section.

Risks and open questions: what identifies "this week's run" when two clubs share a code; whether the organiser needs to undo a check-in (deferred to 002); offline sync conflict when the same name checks in from two phones.

Testing strategy: one test per scenario; the no-signal scenario tested with networking disabled; the double-tap case tested explicitly.

Notice what the first version does not contain, and how much of the spec's value is in the endings and the risks. This is a v1 that can be built and put in a runner's hand within days — which is the only way to find out whether the organiser really does leave the paper list at home.

The order matters more than the effort.

Minutes 0–10: the situation and the job. Write PRD sections 1 and 2 without stopping to edit. If the one-sentence job takes more than three attempts, you have two apps; pick one.

Minutes 10–25: the three flows, then the cut list. Write the three "user does X, sees Y" flows. Then write everything else you thought of into section 3 — the v1 cut list. Most people find this is where the relief is: the ideas are kept, just not built yet.

Minutes 25–35: the signal and the constraints. One measurable sign of success within weeks. Then the must-never-break list — offline, privacy, old devices, no forced accounts. If you're unsure whether something is a constraint or a feature, ask: would violating it make the app wrong, or merely smaller? Wrong is a constraint.

Minutes 35–55: the first feature spec — scenarios first. Take core flow 1. Write its endings as Given/When/Then, one per ending, before anything else. Then the overview, then the risks you can already see, then one test line per scenario. Leave technical approach, steps and files for the builder unless you are the builder.

Minutes 55–60: read it as the builder. Where would you have to guess? That's a missing scenario or a missing constraint. Add it; don't add prose.

Two habits make this compound. Keep the PRD to one page — if it grows, something in it belongs in a spec or in v2. And write each spec just before its feature, not all of them up front: by feature four you'll know things about your app that would have made the feature-four spec wrong if you'd written it on day one. Whether you then hand the documents to an engineer, drop them into a prototype tool, or start describing to an AI agent, the input is the same — which is the whole argument of spec-driven development and of the from-scratch guide that this page slots into.

Since this structure is Modaal's, it's fair to show what it does with the documents — from our own docs, dated 8 September 2026.

The PRD goes into the new-project wizard. You describe the app on the home screen — and you can attach design docs, screenshots and Figma links alongside it — pick a template (iPhone and Android together, iPhone now and Android later, a quick prototype, a game, a watch app), confirm the name and identifiers, and press Create. Nothing is written to disk until then. Since version 1.8.0 the wizard explicitly takes "your PRD or a description of the first feature" — so the one page you just wrote is the input.

The first turn writes PRD.md and the first spec. The agent reads your description and attachments, confirms scope if something is ambiguous, writes a structured PRD.md at the root of the project, then plans the first feature and writes it to specs/001-\<feature\>/spec.md — the seven-section spec above. It does this in planning mode, without writing code, and it is prototype-first by default: the first iteration aims at a clickable prototype with realistic mock data, and defers accounts, backends and analytics unless you ask for them. That default is the v1 cut list, enforced by the tool.

Every later feature is the Plan toggle. Plan on, describe the feature, and the agent researches the codebase and writes its spec.md — scenarios, approach, steps, files, risks, tests — without touching source. You read it, correct it, approve it. Plan off, and it builds from that spec, compiling and fixing its own errors, running the app, committing. Your scenarios are what it implements against; on a Duet project they are also recorded and replayed on both platforms in the build, so the iPhone and Android apps are checked against the same endings.

The reason to write the documents this way, then, is not that Modaal requires it — it will write a PRD from three sentences if that's what you have. It's that a PRD with a real cut list and a spec with real endings turns a good agent into a precise one, and turns "review the code" — which most product people can't do — into "review the plan", which they can. Free plan: one project, unlimited prompts, no card; the details are on the pricing page.