05 — The product doc (PRD)

When to read this: Before you run prd-grill for the first time, or whenever you suspect your existing PRD is too vague to actually constrain the agent.

What a PRD is for, in this kit#

In an enterprise setting, a Product Requirements Document is a multi-stakeholder negotiation artifact. It exists to capture agreement.

In this kit, the PRD has a different job. It exists to constrain the agent's downstream behavior. Specifically:

• It's the input architecture-md-builder reads before asking about the stack. Architecture without product context produces wrong choices.
• It's the input design-md-builder reads before asking about brand. Brand without product context produces generic-SaaS aesthetics.
• It's what /backlog-triage checks against when classifying inbox items, so the kit can reject items that don't trace to the PRD.
• It's what prd-revise compares shipped reality against to detect drift.

A vague PRD doesn't just fail to constrain. It misleads. The agent reads "users want a productivity tool" and confidently fills the gap with the average productivity tool from its training data. By week 4, you've shipped half a Notion clone you didn't want.

The six sections#

The kit's PRD has six sections. Each one captures a decision that, if missing, lets the agent drift in a specific direction.

The single longest section is non-goals. That's the one most worth getting specific on. Everything you don't write down as "out of scope" is something the agent might silently build.

What good vs. bad sections look like#

The clearest way to learn what a good PRD reads like: compare ❌ vague drafts to ✅ specific ones.

§1 — Primary user#

❌ "The user is a busy professional who wants to save time."

Demographic with no situation. Could describe anyone. Agent has no shape to constrain output.

✅ "Maya, 34, solo founder of a 2-person consultancy. Lives in her inbox + Notion. At 7pm Sunday she sits down to plan the week and spends ~40 minutes copy-pasting follow-ups from 5 client threads into a status doc. She has no PM, no CRM budget, and won't adopt anything that takes more than 10 minutes to set up."

Named archetype, trigger moment, current workaround, hard adoption constraint. Agent (and you) can ask "would Maya use this?" and get a real answer.

§2 — Problem#

❌ "Users need a better way to organize tasks across projects."

Solution-shaped (organizing tasks isn't a problem, it's a feature). Aspirational ("better"). Doesn't describe lived experience.

✅ "When Maya sits down Sunday night to plan her week she has no single view of what each client is owed. She rebuilds the picture from scratch every week out of email threads. She missed two deliverables last quarter because a follow-up was buried in a thread she didn't reopen."

Concrete moment, real consequence, current behavior. The user could read this and say "yes, that's me."

§3 — V1 capabilities#

❌ "Users can manage their tasks. The system supports tagging, filtering, and search."

Noun-led. Grouped vague verbs. An agent reading this fills the shape from training-data defaults.

✅

1. Paste an email-thread URL → system extracts open commitments.
2. Sunday 6pm cron generates a per-client status doc with open / closed / blocked items.
3. One-tap nudge: sender of any open commitment can be nudged via pre-drafted email.

Verb-led, atomic, each independently testable. Ordered by load-bearing weight (the first one is the one without which the product makes no sense).

§4 — Non-goals#

❌ "Mobile app is probably out of scope for now. We may add team features later. Real-time is a stretch goal."

Soft language ("probably," "may," "stretch"). Agents read soft language as permission to attempt. No reasons attached, so future-you can't tell what would change the decision.

✅

- ❌ Mobile app. *Reason: target user works at a desk; mobile-responsive is enough until usage data says otherwise.*
- ❌ Multi-user / sharing / permissions. *Reason: single-tenant data model only — multi-tenant is a 2-month rewrite.*
- ❌ AI-generated reply content. *Reason: system surfaces commitments; human writes the reply. We don't want to own hallucinated client communication.*

Hard exclusions, one-sentence reason each. The reason is what lets future-you (and future agents) decide whether to revisit.

§5 — Success metrics#

❌ "Grow weekly active users. Increase engagement. Hit 1,000 signups in Q1."

Vanity metrics — signups go up regardless of whether the product works. No threshold tied to user behavior. No counter-metric.

✅

- Primary: % of paying users who generate a Sunday digest 3+ consecutive weeks. Target: 60% by week 8.
- Secondary: Median minutes from "paste thread" to "first digest." Target: <10 min.
- Counter-metric: Support-ticket rate per active user must not exceed 1 per 20 users/week.

Behavioral, threshold + timeframe, plus a counter-metric so the team can't goose the primary by hurting something else.

§6 — Anti-patterns#

❌ "Build it well. Don't over-engineer. Follow best practices."

Tells an agent literally nothing. Agents fill silence with training-data defaults — auth pages, dashboards, refactors of adjacent code, "while I'm at it" features.

✅

- ❌ NOT a CRM. No contact records, no pipeline stages, no deal sizes.
- ❌ NOT a project manager. No Gantt, no dependencies, no assignees.
- ❌ NOT an AI assistant. No chat UI, no "ask me anything," no agent loop in the product surface.
- ❌ NOT a Notion competitor. No rich docs, no databases, no embeds.

Names the comparison product, then enumerates the specific UI/data-model artifacts that would signal drift toward it. An agent can scan this and check its own work against it.

The unifying test#

Read each finished section aloud and ask: "could this describe a different product I've seen before?"

If yes, it's too generic. Run another prd-grill pass on that section to pull out the specific detail that makes this product this product.

How prd-grill works#

prd-grill is a skill, not a slash command. Invoke it by name:

prd-grill

The skill operates on six rules, in priority order:

1. One question at a time. Never five at once.
2. Recommend an answer with every question. You react instead of staring at a blank prompt.
3. Read the codebase before asking when the codebase can answer. If you have a package.json already, the skill won't ask what stack you're using. It'll read it.
4. Walk the dependency tree. It won't ask about non-goals before you've decided V1 capabilities.
5. Spend the most time on non-goals. Phase 4 is the longest by design. Solo founders want to skip it because every "no" feels like a loss. The "no" is the point.
6. Push past the first answer. Two pushes per vague answer. If you resist after two, the skill accepts your answer and moves on.

A typical run takes 20–45 minutes for a thin project, longer for something architecturally loaded. Output: docs/PRD.md plus a Revision log skeleton at the bottom.

Phase 0: diagnose#

Before asking anything, the skill checks:

• Does docs/PRD.md already exist? If yes, is it specific or vague?
• Does ROADMAP or ARCHITECTURE already exist? If yes, the PRD is being added retroactively — those constrain what the PRD can claim.
• Is there existing code? Treat partial implementation as evidence of intent.

If you have just an idea and nothing else, the skill starts at Phase 1 with the full interrogation.

Phases 1 through 6#

The phases mirror the section structure above. For each, the skill asks one open question with a recommended answer:

Phase 1 prompt: "Who is V1 for? Not 'everyone' or 'people who want X' — name a single archetype, ideally based on a real person. What do they do for work, what's the moment in their day they'd reach for this product, and what are they doing right now to solve the problem manually?"

If your first answer is vague ("entrepreneurs"), the skill pushes once: "Solo founders, small-team founders, or VC-backed founders? They have very different tools and budgets." If you resist a second time, it accepts what you have and moves on.

The skill watches for rubber-stamp acceptance. If you accept its recommendation verbatim with no edits, especially on Phase 1 (user) or Phase 4 (non-goals), it asks one targeted confirmation question to make sure you actually thought about it.

Phase 7: write the file#

After all six phases are answered, the skill writes docs/PRD.md using its internal template. Sections you decided are filled in. Sections you deferred read **Deferred** — see Revision log entry [date], so future-you knows it was a deliberate punt, not an oversight.

The file ends with an empty Revision log section ready for prd-revise to grow.

Why specificity matters more for AI-built products#

A human engineer asks "wait, do we actually want auth here?" before adding it. An agent ships it.

That's the central asymmetry. Negative space — what the product is not — has to be written down, not implied. Same for user definition, problem framing, capability scoping. Wherever the PRD is vague, the agent interpolates from the generic-product distribution in its training data. The output drifts toward "yet another SaaS."

If you're tempted to skip sections of the PRD because they "feel obvious," remember: they don't feel obvious to the agent. They aren't in its context. Write them down.

When to run prd-revise#

The PRD written in week 1 starts to lie by week 6. Capabilities ship that aren't documented. PRD items get silently descoped. Architectural decisions invalidate PRD assumptions.

prd-revise is the maintenance skill. Invoke it by name:

prd-revise

Run it when:

• A phase just shipped (a row flipped to [x]).
• A new entry in ARCHITECTURE.md Trade-off log materially affects scope.
• You're about to triage a fresh batch of inbox items and want them judged against current product intent.
• You notice your mental model has drifted from the written PRD.
• Cadence: every 5–10 shipped specs, or every phase boundary, whichever comes first.

Don't run it:

• Mid-spec execution. It produces context noise during implementation.
• More than once per phase under normal conditions. PRD churn is a smell. If your PRD changes weekly, the issue is upstream.
• On thin projects with <5 specs total. There's nothing to drift yet.

What prd-revise detects#

The skill looks for drift in three dimensions:

1. Shipped capabilities not in PRD. For each [x] spec, can it be traced back to a PRD capability? If not, was it scope creep that should be documented or reverted?
2. PRD capabilities not yet shipped or scheduled. Was the capability silently descoped? Forgotten? Or has the PRD over-promised relative to V1 reality?
3. Invalidated assumptions. Does anything in ARCHITECTURE.md §5 (Bets) or §6 (Trade-off log) contradict a claim in the PRD?

The skill surfaces findings as a structured table. You decide what to do for each finding — the skill never edits the PRD without your approval.

Approved updates land with an append-only Revision log entry at the bottom of the PRD:

### 2025-04-15 — Phase 1 revision pass
 
**Triggered by:** phase boundary
 
**Drift addressed:**
- Reaction emoji on tasks shipped (P0 #4) but wasn't in PRD §3 → added to capabilities
- "V1 includes shareable public profile pages" was in PRD §3 but no spec; user descoped → moved to non-goals
 
**Updates applied to PRD:**
- §3 — added "react with emoji on a task" as capability #4
- §4 — added "public profile pages" as non-goal with reason
 
**Carried forward:**
- (none)

After a revise pass, re-triage any open inbox items. They should be judged against the freshly-updated PRD.

Common stumbles#

Continue#

If your project has a database, auth, payments, queues, or cross-cutting concerns: Chapter 06: The architecture doc. Otherwise: Chapter 07: The design doc.