Skip to content
Back to skills

Prd To Issues

ASecurity

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".

  • 5 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 18, 2026
documentationbashgit

Security analysis

A100/100

Pro scans all 2 files and shows the line behind each finding

Scanned November 18, 2026

npx -y skills add ghalex/skills --skill prd-to-issues --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Prd To Issues?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Prd To Issues
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/ghalex-prd-to-issues/badge)](https://www.skillsdirectory.com/skills/ghalex-prd-to-issues)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
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.**

<issue-template>

```markdown
---
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)
```

</issue-template>

## 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 mv`s 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.

<index-template>

```markdown
# 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 |
```

</index-template>

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

Files in this skill

  • README.md2.5 KB
  • SKILL.md7 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in documentation →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.