prd-to-issues

name	prd-to-issues
description	Break a PRD or plan into independently-grabbable, vertically-sliced Markdown issues that an agent can work one-by-one in a ralph loop. Use when the user wants to turn a PRD or plan into issues, tickets, tasks, or work items, or asks to "slice this into issues" or "prep this for a loop".
license	MIT
effort	high
allowed-tools	Read Write Edit Bash Glob Grep Skill

/prd-to-issues

Break a PRD or plan into independently-grabbable issues using vertical slices (tracer bullets), then file each as a local Markdown work order in issues/. The output is designed to be consumed by a ralph loop — an agent that picks the next eligible issue, implements it, and moves it to issues/done/, one iteration at a time.

Issues are work orders, not archival docs

A PRD is durable and abstract on purpose. Issues are the opposite: ephemeral, concrete work orders consumed once by the loop and then retired. A fresh-context agent picking up an issue has no memory of this conversation — so be concrete:

• Name the modules, files, and existing patterns the agent should touch or copy. Stale pointers are fine; the issue is discarded the moment it's done.
• Reference the PRD for why and for the broader context; tell the issue where and what.
• Over-abstracting an issue "for durability" is the main way it becomes unexecutable. Don't.

Workflow

You may skip steps the conversation already covered — capture, don't re-interview.

1. Locate the PRD or plan

The source is a local Markdown file (or content already in your context).

• If a PRD/plan is already in context, use it.
• Otherwise look in prds/ (the create-a-prd default) with Glob, or ask the user for the path.
• Read it in full before slicing. If it's a raw plan rather than a PRD, it may have no numbered user stories — that's fine, degrade gracefully (see user_stories below).

2. Explore the codebase (optional)

If you haven't already, explore the repo to understand the current state and — critically — to identify every integration layer a slice must cut through (e.g. migration → model → service → route → UI → test). You can't draw a vertical slice without knowing the layers it crosses. Note concrete module names and existing patterns to cite in the issues.

3. Draft vertical slices

Break the PRD into tracer-bullet issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end — NOT a horizontal slice of one layer ("add the model", "add the route" are horizontal; avoid them).

Slicing criteria — every slice must be:

• End-to-end — observable behavior, from entry point to persistence and back.
• One iteration — completable by a single agent run / one focused PR. If it's too big to finish in one sitting, split it. This is what makes the loop work.
• Independently grabbable — implementable on its own once its blockers are done.
• Typed afk or human. human slices need a human in the loop (an architectural decision, a design review, a credential). afk slices can be implemented and merged without human interaction. Prefer afk — push human work earlier so it unblocks the afk run.

Numbering is topological. Order the slices so dependencies always point backward: issue NNN may only be blocked_by issues numbered lower than NNN. This makes "lowest-numbered eligible issue" trivially correct for the loop.

4. Quiz the user

Present the proposed breakdown as a numbered list. For each slice show: Title, Type (afk/human), Blocked by, User stories covered.

Ask:

• Does the granularity feel right? Is each slice one iteration's worth of work — too coarse, too fine?
• Are the dependency relationships correct?
• Should any slices be merged or split?
• Are the right slices marked human vs afk?

Iterate until the user approves. If the quiz drags, hand off to /grill-me for a tighter loop.

5. Create the issue files

Once approved, create one file per slice in dependency order in issues/, named NNN-slug.md (zero-padded number = topological order; slug from the title). Derive acceptance criteria from the PRD's user stories — map the criteria already written under each story; don't invent new ones.

Then write issues/README.md as an index (a derived view — the issue files are the source of truth).

Do NOT modify the parent PRD.

---
slice: NNN
title: <short descriptive name>
type: afk            # afk | human
blocked_by: []       # list of slice numbers, e.g. [1, 3]; [] if none
user_stories: []     # PRD story numbers, e.g. [3, 7]; [] for a plan with no stories
prd: prds/prd-<feature-name>.md
---

# <Title>

## What to build

A concise description of this vertical slice — the end-to-end behavior, not a
layer-by-layer plan. Be concrete: name the modules, files, and existing patterns
to touch or copy. Reference the parent PRD for the broader why.

## Acceptance criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Tests cover the new behavior through its public interface

## Blocked by

- #NNN <title>   (or "None — can start immediately")

## User stories addressed

- Story 3, Story 7   (from the parent PRD; omit if the source was a plan)

The ralph-loop contract

Write this contract into issues/README.md so the loop and the human both know the rules. Completion is tracked by file location, not a status field — zero parsing, atomic with the commit:

• Todo = a file in issues/*.md. Done = a file moved to issues/done/.
• Each iteration, the agent takes the lowest-numbered afk issue in issues/*.md whose blocked_by are all already in issues/done/.
• It implements the issue, then git mvs the file into issues/done/ in the same commit as the work. If an iteration dies mid-work, nothing moved — the next iteration simply retries it.
• The loop skips human issues and any issue with unmet blockers, and stops when no eligible afk issue remains — surfacing the leftover human/blocked issues for the user.
• "What's left" is just ls issues/*.md. No status to parse, no state to desync.

# Issues — <feature name>

Derived from `prds/prd-<feature-name>.md`. **The issue files are the source of
truth; this index is a snapshot.**

## How the loop consumes these

1. Pick the lowest-numbered `afk` issue in `issues/*.md` whose `blocked_by` are all in `issues/done/`.
2. Implement it; `git mv` the file to `issues/done/` in the same commit.
3. Repeat until no eligible `afk` issue remains. `human` and blocked issues are left for review.

## Slices

| # | Title | Type | Blocked by | Stories |
|---|---|---|---|---|
| 001 | <title> | afk | — | 1, 2 |
| 002 | <title> | human | 001 | 3 |
| 003 | <title> | afk | 001 | 4, 5 |

After filing, tell the user how many issues were created, which are human, and where they live. Suggest pointing the ralph loop at issues/.