richkuo/rk-skills/app-prd

app-prd

Turn a raw idea dump into a complete, implementable PRD committed to the target repo. 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. 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).
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. Never paraphrase pricing tables or lifecycle windows.
• 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)

• 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.
• Spec pull requests get the same review gate as code pull requests.

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

For each user 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. Do not recap 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, after the review gate above (a fix-pr-review-loop run to LGTM on the PRD PR) — typically once the prd-questions stage empties the Open Questions section.

Failure modes