prd-to-issues

Overview of prd-to-issues skill

prd-to-issues is a planning skill that turns a product requirements document into a set of small, independently useful GitHub issues built as vertical slices rather than layer-by-layer tasks. It is best for founders, product engineers, tech leads, and agent users who already have a PRD and want implementation-ready work breakdown without producing a backlog full of vague “build backend”, “build frontend”, and “write tests” tickets.

What prd-to-issues actually does

The core job of prd-to-issues is not “summarize a PRD.” It restructures a requirement into tracer-bullet issues: thin, end-to-end slices that cut through schema, API, UI, and tests so each ticket is demoable on its own.

Best fit for Requirements Planning

Use prd-to-issues for Requirements Planning when you need to move from product intent to an execution sequence. It is especially useful when a team wants:

• implementable GitHub issues
• dependency-aware sequencing
• a mix of autonomous work and human-decision checkpoints
• smaller tickets that reduce merge risk and coordination overhead

Why teams choose prd-to-issues over a generic prompt

A normal prompt often produces feature-component checklists. The prd-to-issues skill pushes toward vertical slices, explicit blockers, and ticket types:

• AFK: can be implemented without human input
• HITL: needs a human decision, review, or approval

That distinction is practically useful if you are planning agent-assisted delivery, async execution, or triage queues.

Biggest differentiator

The most important differentiator is the slice philosophy: each issue should be narrow but complete. That gives you tickets a developer or agent can actually pick up, finish, verify, and merge, instead of half-finished technical layers that only become useful after several more tasks land.

What this skill does not replace

prd-to-issues does not replace product discovery, architecture design, or roadmap prioritization. If your PRD is still ambiguous, politically contested, or missing scope boundaries, the output may look organized while still being wrong.

How to Use prd-to-issues skill

prd-to-issues install context

If you are using the Skills workflow, install prd-to-issues from the mattpocock/skills repository:

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

Then invoke it from your agent environment when you are ready to convert a PRD into implementation issues.

What to read first in the repository

This skill is lightweight. The main file to read is:

• SKILL.md

There are no extra helper scripts, reference docs, or rules folders surfaced here, so most of the real value comes from understanding the workflow in SKILL.md and supplying better inputs than the repository can provide on its own.

The minimum input prd-to-issues needs

At minimum, prd-to-issues usage works best when you provide:

• the PRD GitHub issue number or URL
• the product goal
• any hard constraints already known
• whether the agent should inspect the codebase first

If the PRD is not already in context, the skill expects the agent to fetch it, typically with gh issue view <number> including comments.

Strong inputs produce much better issue breakdowns

A rough request like “turn this PRD into issues” is usually not enough. Better input includes:

• target user or workflow
• known technical boundaries
• rollout constraints
• dependencies on existing systems
• whether to optimize for speed, low risk, or autonomy

A stronger prompt looks like:

“Use prd-to-issues on GitHub issue #123. Break it into thin vertical slices. Prefer AFK slices where possible. We already have auth and billing, but no notification system. Optimize for demoable increments and minimal cross-team coordination.”

That gives the skill planning constraints it cannot infer from the PRD title alone.

The practical workflow the skill follows

The prd-to-issues guide is straightforward:

1. Locate the PRD issue.
2. Pull the issue content into context if needed.
3. Optionally inspect the codebase to understand current implementation reality.
4. Draft thin vertical slices.
5. Mark each slice as AFK or HITL.
6. Show blockers between slices.
7. Present the breakdown for user review before creating tickets.

This review step matters. The skill is designed to propose a breakdown, not silently create a backlog without confirmation.

Why codebase exploration is optional but often worth it

The repository marks codebase exploration as optional, but in real use it often changes the quality of the output. Without codebase context, the skill may produce clean-looking slices that ignore:

• existing abstractions
• data model constraints
• naming conventions
• already-shipped partial implementations

If the PRD depends on current system behavior, inspect the codebase first.

What a good issue list should contain

When prd-to-issues is working well, each proposed slice should include:

• a short, clear title
• Type: HITL or AFK
• Blocked by: prior slices if sequencing matters

The best outputs also make it obvious why each ticket stands alone and what makes it verifiable.

How to turn a rough PRD into better prompts

If your PRD is broad, add planning instructions before invoking the skill:

• “Prefer many thin slices over a few large ones.”
• “Each slice must be demoable on its own.”
• “Avoid phase-based tickets like backend/frontend/testing.”
• “Call out any slice that needs product or design review as HITL.”
• “Flag sequencing only when a real blocker exists.”

These instructions reinforce the repository’s vertical-slice intent and reduce generic backlog output.

Common output pattern to expect

For a feature with UI, API, and persistence, the skill should lean toward slices like:

• a minimal end-to-end happy path
• a follow-up validation or permissions slice
• an edge-case handling slice
• an observability or reporting slice if required

It should not default to:

• database ticket
• API ticket
• frontend ticket
• QA ticket

That latter pattern is exactly what prd-to-issues is trying to avoid.

When to ask for HITL vs AFK explicitly

If your team uses agents or highly async execution, tell the skill to maximize AFK slices. If you know there are unresolved questions around UX, compliance, or architecture, ask it to isolate those as HITL tickets instead of burying uncertainty inside implementation work.

Best time to use prd-to-issues in the planning cycle

Use prd-to-issues skill after the PRD is concrete enough to describe user outcomes and constraints, but before engineers have started manually decomposing the work. Too early, and the tickets will be speculative. Too late, and the skill adds less value because the work breakdown already exists.

prd-to-issues skill FAQ

Is prd-to-issues good for beginners?

Yes, if you already have a reasonably clear PRD. It is beginner-friendly in format, but the output quality still depends on your ability to provide scope boundaries and review the resulting slices.

How is prd-to-issues different from asking an AI for tickets?

The difference is the planning model. prd-to-issues is biased toward independently grabbable tracer bullets, explicit blockers, and HITL/AFK labeling. A generic prompt often produces less actionable tickets and weaker sequencing.

When is prd-to-issues a poor fit?

It is a poor fit when:

• the PRD is mostly open questions
• the work is research-heavy
• success depends on unresolved architecture choices
• you need sprint estimation more than issue decomposition

In those cases, discovery or design review should happen first.

Do I need GitHub issues for this skill?

Practically, yes. The workflow is built around a PRD stored as a GitHub issue number or URL, and the output is intended to become GitHub issues. You can adapt it elsewhere, but GitHub is the natural fit.

Does prd-to-issues create issues automatically?

The source guidance focuses on drafting and presenting a numbered breakdown first. Treat it as a planning aid unless you explicitly wrap it in your own issue-creation workflow.

Should I use prd-to-issues if the codebase is unfamiliar?

Yes, but ask for codebase exploration first. If the repository is large or legacy-heavy, skipping that step increases the chance of unrealistic slices and hidden blockers.

How to Improve prd-to-issues skill

Give prd-to-issues sharper planning constraints

The easiest way to improve prd-to-issues results is to specify what “good breakdown” means for your team. Useful constraints include:

• maximum ticket size
• preference for AFK work
• release order
• risk tolerance
• systems that must not be changed

Without this, the skill may produce structurally correct but operationally unhelpful issues.

Improve the PRD before running the skill

This skill cannot rescue a weak PRD. Before using prd-to-issues, make sure the PRD clearly states:

• who the feature is for
• what job the user is trying to do
• what is in and out of scope
• success conditions
• known constraints or dependencies

Even a short PRD becomes much more decomposable when those basics are explicit.

Ask for thinner slices than you think you need

A common failure mode is accepting issues that are still too large. If the first pass looks heavy, ask:

“Make these slices thinner. Each issue should produce a verifiable user-visible or system-visible outcome with minimal parallel coordination.”

That usually improves pickup speed and reduces blocker chains.

Force end-to-end thinking

If the output starts drifting into component-based tickets, correct it directly:

“Rewrite these as vertical slices. No layer-only tickets unless a task is truly impossible to validate end-to-end.”

This is one of the highest-value edits you can make during prd-to-issues usage.

Separate uncertainty from implementation

When a slice contains hidden decision-making, ask the skill to split it into:

• a HITL decision or review issue
• one or more AFK implementation issues after the decision

This keeps autonomous work unblocked and makes human input visible instead of implicit.

Use a second-pass review on blockers

Blockers are often overdeclared. After the first draft, ask:

• which dependencies are real
• which slices can proceed in parallel
• which slices only need interface assumptions rather than completed upstream work

That makes the plan more executable, especially for small teams.

Compare the output against three quality checks

Before adopting the issue list, verify that each ticket:

1. is understandable without rereading the whole PRD
2. produces a demoable or testable outcome
3. does not hide major unanswered questions

If a slice fails any of these checks, revise it before creating issues.

Iterate with concrete feedback, not “make it better”

The best improvement prompt is specific. For example:

“Revise the prd-to-issues breakdown so the first two slices are mergeable within a day, maximize AFK, and isolate design-review dependencies into separate HITL issues.”

That kind of feedback materially changes the backlog. Generic feedback usually does not.