# App Prd

> Use when the user wants an app idea turned into a Product Requirements Document (PRD) committed to a repo — "create a PRD", "/app-prd", "turn this idea into a PRD", or a raw idea dump ending with "save it to this repo". Produces a complete, section-numbered PRD.md landed via worktree + PR, bootstrapping an empty repo if needed. Stage 1 of the new-app-pipeline.

- Skill: `richkuo/app-prd` (Agent Skill)
- Install (CLI): `npx skillmds@latest add richkuo/app-prd`
- Raw SKILL.md: https://api.skillmd.com/api/skills/richkuo/app-prd/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: richkuo (https://skillmd.com/u/richkuo)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/richkuo/app-prd

---


# app-prd

Turn a raw idea dump into a complete, implementable PRD committed to the target repo. The PRD is the single source of truth every later stage (question refinement, issue filing, workflow execution) builds on — write it so a cold agent could implement from it plus nothing else.

## Input

- An idea dump: features, pricing, constraints, platform choices — usually messy prose. Optionally a target repo (defaults to the current checkout).
- If no repo exists yet and the user named one, offer `gh repo create <name> --private` before proceeding.

## Steps

### 1. Check repo state

`git status`, `git log --oneline -3`, `git remote -v`, `git ls-remote origin`. Three cases:

- **Normal repo**: proceed with the standard worktree + PR flow.
- **Empty repo with remote** (no commits anywhere): bootstrap first — create `main`, one **empty** initial commit (`git commit --allow-empty -m "Initial commit"` + attribution footer), push. A PR needs a base branch to exist; never put the PRD itself in the bootstrap commit.
- **No repo/remote**: confirm repo creation with the user.

### 2. Draft `PRD.md`

Structure (adapt section names to the product, keep the skeleton):

1. Header table — product name, repo, platforms, status (**mark the MVP scope explicitly**, e.g. "Draft v0.1 — MVP scope"), last-updated date.
2. **Product Overview** — what it does, for whom, the emotional/business core in plain language.
3. **Goals** — 3-5 bullets.
4. **Platforms & Technology** — a table: each app surface, domains, payments, database, storage, email, auth. Record deferred infrastructure explicitly ("to be provisioned later; design compatible from day one").
5. Feature sections — accounts, core domain objects, creation flows, privacy rules. **Number every section** (§4.2 style); later stages and issues cite these numbers.
6. **Pricing** — exact rates in tables, worked examples labeled *illustrative*, discount rules with the user's own example numbers preserved.
7. Lifecycle/operations sections — storage tiers, scheduling windows with computed buffers (show the arithmetic: base time + buffer = trigger point).
8. **Notifications** — every trigger, plus the implied supporting set (invites, receipts, warnings) marked as implied.
9. Per-platform parity section when there are multiple surfaces.
10. **Open Questions** — numbered; see rule below.
11. **Out of Scope (MVP)**.
12. **Post-MVP Roadmap** — everything the user flagged as later.

### 3. Faithfulness rules (integrity-critical)

- Transcribe every stated number, rate, duration, and rule **exactly** — pricing tables and lifecycle windows are contract text, not paraphrase.
- Garbled or ambiguous input: make the best-effort interpretation in place **and** file the ambiguity in Open Questions. Never silently guess; never ask about things a sensible default covers.
- Anything you inferred rather than were told (e.g. an implied App Store policy, an implied email type) — say so inline.

### 3b. Executable-spec rules (apply to every PRD edit)

- A spec is executable: agents implement its lines literally. Every normative line must survive a literal reading. Ask whether an agent can follow the line exactly as written and still produce the wrong thing.
- **Verify API claims against the installed SDK or type definitions.** Before the spec names a property, type, or signature, read the declaration at the deployment target (`*.swiftinterface` under `xcrun --sdk iphoneos --show-sdk-path`, or the package's own `.d.ts`). Web documentation alone is insufficient evidence. A sample written against a legacy API (for example the `VN*` Vision types) proves nothing about its modern replacement.
- **In-repo evidence outranks external documentation.** A code comment that records a compile failure is ground truth. Contradict it only by reproducing the compile.
- **Terminology edits sweep every dependent.** After the spec renames or forbids a mechanism, search the spec and all open issues for each remaining mention: implementation orders, tables, checklists, acceptance criteria.
- **Realtime-path lines name the mechanism per component.** When components differ in units, coordinate spaces, or timelines, give each its own explicit statement. A shared phrase that groups them invites a wrong literal reading.
- Spec pull requests get the same review gate as code pull requests. A spec error multiplies across every issue that cites the section.

### 4. Land it

Worktree off latest `origin/main`, branch `cc/prd`, commit `PRD.md`, push, open a PR. Attribution footer on the PRD file itself, the commit, and the PR body (`Created`).

### 5. Iterate on the same PR

The user will refine in bursts ("change X", "add Y", "rename call date to unseal date"). For each revision:

- Edit, commit, push to the **same branch** — one PR accumulates the whole draft history.
- Rename sweeps: `grep -c` first, replace all occurrences and casing variants, fix grammar fallout (a/an).
- Flip the PRD file's footer verb to `Updated` on first revision; commits use `Updated` thereafter.
- Reply with what changed in one or two sentences, not a recap of the document.

## Output

PR URL plus a one-line summary of coverage and where the open questions are listed. The PR merges when the user says so — typically after the `prd-questions` stage empties the Open Questions section.

## Failure modes

| Situation | Do this |
|---|---|
| Empty repo, no base branch | Bootstrap `main` with an empty commit first — never commit the PRD directly to main |
| User's numbers seem inconsistent (e.g. discount examples) | Record them verbatim, add an Open Question showing the inferred rule |
| User states requirements mid-iteration contradicting earlier ones | Latest wins; update every section it touches, not just the nearest one |
| Tempted to fill a spec gap with a plausible invention | Open Question instead |