write-a-prd

This skill will be invoked when the user wants to create a PRD. You may skip steps if you don't consider them necessary.

Default to an interview-driven PRD when the user is still shaping the idea. If the current conversation already contains a concrete problem, proposed solution, prototype, bug report, or prior codebase analysis, switch to context-first mode: synthesize what is already known, verify it against the repo, and ask only blocking questions instead of restarting the interview.

Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions. Skip this if context-first mode applies and the existing context is enough to proceed.
Explore the repo to verify their assertions and understand the current state of the codebase. Use the project's domain vocabulary consistently, and respect any existing ADRs or architecture docs in the area being changed.
Interview the user relentlessly about every aspect of this plan until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. In context-first mode, replace this with a short list of assumptions and ask only about assumptions that would materially change the PRD.
Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation.

A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes.

Check with the user that these modules match their expectations. Check with the user which modules they want tests written for.

Once you have a complete understanding of the problem and solution, use the template below to write the PRD. Save the PRD as a Markdown file at docs/prds/<slug>.md in the project root (create the directory if it doesn't exist). Use a descriptive kebab-case slug for the filename (e.g. docs/prds/user-authentication.md). Tell the user the path of the created file.

The PRD must be junior-developer-ready: explain the implementation path step by step, define unfamiliar terms, make dependencies explicit, and avoid assuming the implementer knows the hidden context from the conversation. A junior developer should be able to turn the PRD into issues and implementation work without asking what order to do things in.

Problem Statement

The problem that the user is facing, from the user's perspective.

Solution

The solution to the problem, from the user's perspective.

User Stories

A LONG, numbered list of user stories. Each user story should be in the format of:

As an , I want a , so that

This list of user stories should be extremely extensive and cover all aspects of the feature.

Implementation Decisions

A list of implementation decisions that were made. This can include:

The modules that will be built/modified
The interfaces of those modules that will be modified
Technical clarifications from the developer
Architectural decisions
Schema changes
API contracts
Specific interactions

Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.

Exception: if a prototype, state machine, reducer, schema, type shape, or API contract snippet encodes a decision more precisely than prose can, inline only the decision-rich part and explain why it is included. Do not paste full demos or implementation scaffolding.

Step-by-Step Implementation Plan

A numbered implementation plan written for a junior developer. Each step should explain:

What to change
Why that step comes at this point in the sequence
Which module, interface, API contract, schema, or workflow it affects
What to verify before moving to the next step
Common pitfalls or assumptions to avoid

The plan should be concrete enough to execute, but durable enough that it does not depend on brittle line numbers or code snippets.

Testing Decisions

A list of testing decisions that were made. Include:

A description of what makes a good test (only test external behavior, not implementation details)
Which modules will be tested
Prior art for the tests (i.e. similar types of tests in the codebase)

Out of Scope

A description of the things that are out of scope for this PRD.

Further Notes

Any further notes about the feature.