To Issues

to-issues — PRD/SPEC to Issues

Decompose a PRD and/or technical SPEC into small, independently demoable Issues, each sized to fit a single fresh context window, then create them in your chosen platform. Works standalone — you don't need to have run /prd first.

Every Issue this skill produces is agent-ready by construction: a fresh session that has never seen your PRD/SPEC can pick it up and finish it.

Core principle: tracer bullets, not layers

This is the rule that matters most, and the one models break most often.

• A horizontal slice ships one layer of the change (all the schema in one ticket, all the API in another, all the UI in a third). Nothing works until every layer lands, and each ticket's acceptance criteria have to reach into work another ticket owns. This is the default the model falls into — avoid it.
• A vertical slice — the tracer bullet — ships one thin but complete path through every layer at once (schema + API + UI + tests for a single narrow behaviour). It is verifiable alone the moment it lands, and it owns everything it grades.

The test for every Issue: "What can I demo when this is done?" If the answer is a layer ("the database has a priority column") rather than a behaviour ("a user can set a task's priority and see it persist"), it is a horizontal slice — re-slice it.

Sizing floor: if the whole change fits in one context window, you don't need Issues at all. Say so and point the user straight at /goal.

Keep this skill in the same context window as /prd-to-spec. Don't clear or compact between them, or the SPEC has to be re-fetched and may truncate.

The Job

1. Locate input — find a PRD or SPEC file (auto-detect or user-specified)
2. Find prefactoring — surface "make the change easy, then make the easy change" work and order it first
3. Decompose into vertical Issues — break behaviour into tracer-bullet tickets with blocking edges
4. Quiz the user — present the numbered list and push on granularity, edges, and demo paths before publishing
5. Choose platform — GitHub / Local
6. Create Issues — blockers first, with native blocking links, then print summary

Step 1: Locate Input

Find the input document:

What should I base the Issues on?

A. Auto-detect: scan tasks/ for recent PRDs and SPECs
B. Specific PRD file (e.g., tasks/prd-priority-system.md)
C. Specific SPEC file (e.g., tasks/spec-priority-system.md)
D. Both PRD and SPEC (best: PRD for requirements, SPEC for technical contracts)
E. Paste requirements directly

If auto-detecting, list available files and let the user choose.

If both PRD and SPEC are available, use the SPEC's Section 10.2 (Issue Mapping) as the primary guide, supplemented by PRD's User Stories. If only PRD is available, generate Issues directly from User Stories.

Step 2: Find Prefactoring First

Before slicing features, look for prefactoring: mechanical groundwork that makes the feature Issues small and safe — extracting a shared helper, widening a type, adding a seam, moving a file. Order this work first, as its own Issue(s), so the feature tickets that depend on it stay thin.

If you find none, skip this step. Don't invent busywork.

Step 3: Decompose into Vertical Issues

Generate the Issue list. Rules:

• Each Issue is a tracer bullet — a narrow, complete, demoable path through every layer it touches. Not "the backend for X"; rather "X, end to end, for one case."
• Each Issue fits one fresh context window — a single agent session completes it without needing you in the room.
• Split by behaviour, not by layer — if a User Story is large, split it into 2-3 narrower behaviours, each still vertical, with explicit blocking edges. Never split it into a backend ticket and a frontend ticket.
• Merge tiny stories — 1-2 trivial criteria that don't stand alone as a demo should merge into a related Issue.
• Declare blocking edges explicitly — every Issue lists what must finish before it can start. These edges are the point of the artifact.
• Number Issues in dependency order — blockers first, so an implementer (or the tracker) always has a valid frontier to start from.
• If SPEC is available — enrich each Issue with SPEC references (API contracts, data model sections, error handling). But keep file paths and line numbers out of the body — they rot; describe behaviour and contracts instead.

Falsifiable acceptance criteria. For each criterion, name the observation that would show it false, and confirm it would fail at the commit the implementer starts from. Reject three shapes: a criterion already true at the base commit, one that can only be satisfied by work another Issue owns, and one that merely restates the request. A vertical slice delivers behaviour that didn't exist before, so it should be red at the base commit by construction.

Issue format:

Issue #N: [Title — a behaviour, not a layer]
---
Description: [What behaviour this delivers, end to end, and why]
Demo path: [The one thing you can show working when this lands]
Acceptance Criteria:
- [ ] [Falsifiable — names an observation that fails at the base commit]
- [ ] ...
Blocked by: [None / Issue #X, #Y]
Priority: [high / medium / low]
SPEC Reference: [Section X.Y — contracts only, no file paths; only if SPEC available]

Step 4: Quiz the User (do not skip)

Present the breakdown as a numbered list and quiz the user before publishing anything. Over-decomposition and accidental horizontal slicing are the two most common failures — this step catches both.

📋 Generated N Issues from [PRD/SPEC], in dependency order:

#1: Extract task-mutation helper (prefactoring) — Blocked by: none
#2: A user can set a task's priority and see it persist — Blocked by: #1
    demo: open a task, pick High, reload, still High
#3: A user can filter the task list to one priority — Blocked by: #2
    demo: select High, list shows only High tasks
#4: A user can sort the task list by priority — Blocked by: #2
    demo: click Sort, tasks reorder High→Low

Review before I create anything:
- Granularity: too fine? "merge #3 and #4". Too coarse? "split #2".
- Demo path: any Issue whose demo is a layer, not a behaviour, is mis-sliced — tell me.
- Edges: are the "Blocked by" links real? Any missing or spurious?
- Adjust: "change #2 priority to high", "add an issue for a priority badge"
- Confirm: reply OK to proceed

Wait for confirmation before creating any Issues.

Step 5: Choose Creation Mode

Choose where to create these Issues:

A. GitHub (via gh CLI, with native blocking links and optional sub-issues)
B. Local (one markdown file per Issue, dependency-ordered)

Your choice:

Step 6: Mode-Specific Creation

Mode A: GitHub

Prerequisites: gh CLI installed and authenticated, v2.94+ for --parent / --blocked-by.

Create blockers first so their Issue numbers exist before any Issue that depends on them. Capture each returned number.

Actions:

1. For each Issue, in dependency order:

   gh issue create \
     --title "[Title]" \
     --body "[Description + Demo path + Acceptance Criteria + SPEC Reference]" \
     --label "priority: [priority]" \
     --blocked-by [comma-separated blocker numbers, if any] \
     --parent [spec issue number, if creating as sub-issues]

   • Use native --blocked-by for edges. Only fall back to a "Blocked by #X" line in the body if the tracker rejects the flag.
   • If the SPEC lives in a GitHub issue, pass --parent <spec_issue> so these become sub-issues of it. To wire a parent after the fact: gh issue edit <parent> --add-sub-issue <n>.
2. If labels don't exist, create them first or skip the --label flag.
3. Report created Issue numbers and URLs.