Generating PRDs
Relevant source files
The following files were used as context for generating this wiki page:
Generating a Product Requirements Document (PRD) is the process of synthesizing conversation context and codebase understanding into a formal specification for a new feature or system change. This process avoids interviewing the user and instead leverages existing project knowledge to define the problem statement, user stories, and implementation decisions.
In this project, PRD generation is a governed step often associated with the to-prd skill. It serves as a precursor to Execution Planning and large-scale implementations, ensuring that all technical and user-facing requirements are documented before code is written.
Sources: skills/to-prd/SKILL.md:1-10, skills/repo-large-implementation/SKILL.md:14-25
PRD Generation Workflow
The generation process follows a structured sequence to ensure the document accurately reflects the current state of the repository and the user's requirements.
1. Repository Exploration
The agent explores the repository to understand the current codebase state. This involves using the project's domain glossary and respecting any existing Architectural Decision Records (ADRs) in the relevant area.
2. Module Sketching
The agent identifies major modules required for the implementation. It prioritizes "deep modules," which encapsulate high functionality within simple, stable interfaces. The agent then presents these modules to the user to confirm expectations and determine testing priorities.
3. Synthesis and Publishing
The agent writes the PRD using a standard template and publishes it to the configured issue tracker. The needs-triage label is applied to the resulting issue to initiate the standard triage flow.
Sources: skills/to-prd/SKILL.md:12-30
The diagram above illustrates the step-by-step logic used by the agent to move from raw conversation context to a published PRD.
Sources: skills/to-prd/SKILL.md:12-30
PRD Structure and Content
Every generated PRD follows a standardized Markdown template to ensure consistency across the project.
| Section | Description | Requirement |
|---|---|---|
| Problem Statement | The problem from the user's perspective. | Required |
| Solution | The proposed solution from the user's perspective. | Required |
| User Stories | Extensive, numbered list in "As an , I want... so that..." format. | Required |
| Implementation Decisions | List of modules, interfaces, technical clarifications, and schema changes. | No file paths/code snippets |
| Testing Decisions | Description of testable behavior, target modules, and prior art. | Required |
| Out of Scope | Clear boundaries of what the PRD does not cover. | Required |
Sources: skills/to-prd/SKILL.md:32-75
Implementation vs. Procedural Details
PRDs must describe behavior, not procedure. For example, a PRD should specify that a type accepts an optional field rather than instructing the agent to open a specific file and edit a specific line. This ensures the document remains durable as files are moved or refactored.
Sources: skills/triage/AGENT-BRIEF.md:16-25, skills/to-prd/SKILL.md:52-53
Integration with Project Systems
PRD generation relies on proper repository configuration, typically established via the setup-matt-pocock-skills command.
Issue Tracker Integration
The agent must know the target issue tracker to publish the PRD. Supported trackers include:
- GitHub: Uses the
ghCLI for issue creation. - GitLab: Uses the
glabCLI. - Local Markdown: Creates files under
.scratch/<feature-slug>/PRD.md.
Sources: skills/setup-matt-pocock-skills/SKILL.md:41-55, skills/setup-matt-pocock-skills/issue-tracker-local.md:1-10
Triage and Governance
Once published, a PRD enters the project's triage state machine. This involves the application of canonical labels like needs-triage. In larger implementations, the PRD serves as the "authority" that guides the repo-production-workflow.
Sources: skills/setup-matt-pocock-skills/SKILL.md:65-75, skills/repo-production-workflow/SKILL.md:1-10
This sequence shows the interaction between the agent and the external project management tools during the final stages of PRD generation.
Sources: skills/to-prd/SKILL.md:28-30, skills/setup-matt-pocock-skills/SKILL.md:41-75
Governance in Large Implementations
For major features or refactors, PRD generation is a mandatory precursor to Execution Planning. The generated PRD acts as the source of truth for:
- Defining Scope: Explicitly stating what is in and out of scope.
- PR Ownership: Determining which behaviors belong to which pull requests.
- Verification: Setting the success conditions for the implementation.
Sources: skills/repo-large-implementation/SKILL.md:60-70, skills/execution-planning/SKILL.md:120-135
PRD generation ensures that technical decisions are recorded as "durable governing designs" rather than ephemeral chat history, facilitating handoffs between different agent sessions or human reviewers.
Sources: skills/execution-planning/SKILL.md:25-35, skills/repo-large-implementation/SKILL.md:110-120