skills/docs/engineering/to-prd.md

Quickstart:

npx skills add mattpocock/skills --skill=to-prd

npx skills update to-prd

Source

What it does

to-prd turns the current conversation and your codebase understanding into a product requirements document, then publishes it to your issue tracker.

The load-bearing constraint: it does not interview you again. By the time you reach for it, the alignment work is done — to-prd synthesises what is already known rather than asking a fresh round of questions.

When to reach for it

You invoke this by typing /to-prd — the agent won't reach for it on its own.

Reach for it once a change has been talked through and the domain language is settled, and you want that shared understanding written down as a spec before any code is written. If you haven't aligned yet, grill first — for that, use grill-with-docs. To split the finished PRD into tickets, use to-issues.

Prerequisites

to-prd publishes into your issue tracker, so setup-matt-pocock-skills must have configured the tracker and triage labels for this repo first. It applies the ready-for-agent label itself — no separate triage pass needed.

What the PRD includes

• Problem statement — what is broken or missing, and why it's worth solving, in the project's own vocabulary.
• Solution — the shape of the fix at a high level, before any implementation detail.
• User stories — an extensive, numbered list of the concrete behaviours the change must support, each one independently checkable.
• Implementation decisions — the choices already settled during the conversation, so they aren't relitigated later.
• Testing decisions — the seams the feature will be tested at, and what "done" looks like.
• Out-of-scope items — what this change deliberately does not cover, to keep the ticket bounded.
• Further notes — anything else worth carrying forward that doesn't fit the sections above.

Deep modules

Before writing the PRD, to-prd sketches the seams at which the feature will be tested and looks for deep module opportunities — a lot of functionality hidden behind a small, stable interface. It prefers existing seams to new ones and the highest seam possible, ideally just one across the whole change.

That matters for agentic development: a good interface gives tests something durable to target, so the code underneath can change without the tests moving.

It's working if

• It starts writing the PRD instead of asking you a fresh round of questions.
• It checks the seams with you before writing, and proposes as few as possible.
• The PRD comes back in your project's domain vocabulary, not generic boilerplate.

Where it fits

to-prd is a step in the main build chain:

grill-with-docs → to-prd → to-issues → tdd

Reach for it after the plan and domain language are resolved, and before you break the work into implementation tickets. Its key neighbours are grill-with-docs, which sharpens the context so the PRD is precise, and to-issues, which turns the PRD into independently-grabbable issues for tdd to implement. When you're unsure which skill or flow fits, ask-matt routes you.