Writing PRDs That AI Agents Can Execute

Product-Level, Not Implementation-Level

A PRD describes what the user experiences and what the business needs. It does not describe tables, API signatures, or file paths. Those belong in the phase plan (Part 6). This separation is deliberate: the PRD is the "what" and the phase plan is the "how."

Why this matters for AI agents: if the PRD includes implementation details, the phase plan generator will defer to them even when they are suboptimal. The PRD should describe the desired outcome. The phase plan generator should derive the best implementation from the codebase's current state, patterns, and constraints.

The PRD Template

14 Common Sections (All PRDs)

Every PRD, regardless of category, has these 14 sections:

1. Purpose: Why this unit exists. What happens if it does not exist? What user pain does it solve?
2. Scope: In scope and out of scope. Every out-of-scope item references which unit handles it.
3. Dependencies: Which units must be complete before this one starts.
4. Test Pair: Which unit verifies this one (backend units are tested by their frontend counterpart).
5. Related Units: Four relationship types: depends on, test pair, composes into, shares pattern with.
6. Success Signals: Observable behaviors that indicate this feature is working. Not metrics, behaviors.
7. Metrics to Track: Quantifiable measurements with targets and measurement methods.
8. Cross-Unit Integration Points: What this unit sends to other units and what it receives. Triggers and data shapes.
9. Tier and Metering Constraints: Which features are available at each pricing tier. User experience at each limit.
10. Configuration Surface: What is configurable, default values, where configuration lives.
11. Assumptions: Things assumed to be true. Documented, not implicit.
12. Open Questions: Unresolved items with a resolution path. Allowed in PRDs. Zero allowed in phase plans.
13. Cross-Cutting Features: Audit logging, search indexing, notifications: follows defaults or custom behavior?
14. Changelog: Date, change, reason. Tracks evolution.

Frontend Additions (F1-F13)

Frontend and full-stack PRDs add 13 sections that define the user experience in exhaustive detail:

Backend Additions (B1-B9)

The Brainstorming Process

PRDs are created through structured conversations with AI, not written from scratch. The AI acts as a senior product manager who leads with recommendations, not open-ended questions.

Six Rules for the Brainstorming Session

1. Never generate the document until explicitly told. Brainstorm all sections first. Generate last. This prevents premature commitment.
2. Never start web research until explicitly told. The founder's domain knowledge comes first. Research fills gaps, it does not drive the conversation.
3. One conversation per PRD. Context must stay in one place. No "continue from where we left off."
4. No implementation details. If tables or APIs creep in, redirect: "That belongs in the phase plan."
5. Every template section must be filled. No skipping. If a section does not apply, explicitly state why.
6. One section at a time. The AI presents a recommendation for one section. The founder refines. Move to the next. This prevents overwhelm and ensures depth.

The Session Flow

Start: The AI reads the unit from the Master PRD Index, identifies the category, pulls related unit context, and presents a recommendation for the Purpose section.

Middle: Section by section, the AI leads: "For the User Journeys, I recommend these four scenarios based on the personas in your Company Overview: morning triage, first-time setup, power-user bulk action, and error recovery. Here is my draft for each. What would you change?"

End: After all sections are brainstormed, the AI generates the full PRD as a structured document (markdown or docx). The founder reviews the complete document, makes final edits, and saves it to the docs folder.

UI Mocks as First-Class Artifacts

Every frontend and full-stack PRD includes an interactive UI mock (F13). The mock is an HTML file with inline React or plain HTML/CSS/JS that renders every state defined in F4, with a state switcher panel.

What the Mock Includes

• Every state from F4 (empty, loading, loaded, error, dense) as switchable views.
• Every interaction from F3 rendered as clickable elements (even if they do not have real behavior).
• Responsive breakpoint toggle (desktop, tablet, mobile).
• Brand tokens applied (colors, typography, spacing from tokens.css).

Why Mocks Matter for AI Agents

The mock is a visual contract. The phase plan references specific mock states. The spec references mock states for visual tests. The executing agent can open the mock side-by-side with its implementation and compare. Without a mock, "the list should look right" is subjective. With a mock, "the list should match mock state: loaded-standard at desktop breakpoint" is verifiable.

Automated PRD Verification

After a PRD is written, it passes through an automated verification command that runs 18 checks against all existing PRDs and foundation documents.

The 18 Checks

Each finding is categorized as Critical (blocks phase plan generation), Recommended (should fix), or Informational (awareness). Every finding includes: what is wrong, where the conflict is, and a specific recommendation for how to fix it.

What You Leave With

For each unit: one PRD (5-15 pages) and one UI mock (HTML file). Both saved to the unit's folder in the docs directory. Both verified by the 18-check automated verification command.

The PRD is now ready for Part 6: Orchestration, where it gets translated into implementation-level phase plans and execution specs.