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.

Mode B: Local

Ask user:

Where should I save the Issue files? (default: .autoresearch/issues/[feature-slug])

Actions:

1. Create the feature folder with mkdir -p if it doesn't exist. One folder per feature keeps parallel agents from racing on a shared file.
2. For each Issue, in dependency order, save NN-[slug].md (zero-padded, NN is a real ticket ID so /goal 03 works):

   # [Title — a behaviour]
   
   ## 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 criterion 1]
   - [ ] [Falsifiable criterion 2]
   
   ## Blocked by
   [None / #NN, #NN]
   
   ## Priority
   [high / medium / low]
   
   ## SPEC Reference
   [Section X.Y — contracts only; omit if no SPEC]
   

3. Report created file paths in dependency order.

The wide-refactor exception

One shape breaks the tracer-bullet rule: a wide refactor — a single mechanical change (rename a column, retype a shared symbol) whose blast radius fans across the whole codebase, so one edit breaks thousands of call sites and no vertical slice can land green.

Sequence it as expand → migrate → contract instead:

• Expand — add the new form beside the old, so nothing breaks. One Issue.
• Migrate — move call sites over in batches sized by blast radius (per package, per directory), one Issue per batch, each blocked by the expand. CI stays green because the old form still exists.
• Contract — delete the old form once no caller remains, in an Issue blocked by every migrate batch.

Where even the batches can't stay green alone, have them share an integration branch and all block a final integrate-and-verify Issue; green is promised only there.

Step 7: Summary Report

✅ Issue creation complete!

Source: [PRD/SPEC path]
Mode: [GitHub / Local]
Issues created: N (in dependency order)

#  | Title (behaviour)                        | Blocked by | Identifier
---|------------------------------------------|------------|------------
1  | Extract task-mutation helper             | —          | #42 / 01-*.md
2  | Set & persist task priority              | #1         | #43 / 02-*.md
3  | Filter task list by priority             | #2         | #44 / 03-*.md
4  | Sort task list by priority               | #2         | #45 / 04-*.md

Frontier (no open blockers, start now): #1

💡 Dispatch is manual — one Issue per fresh session, cleared between them.
   Count the Issues with no open blockers, open that many sessions, implement with /goal:
   /goal 42                # GitHub mode
   /goal 01-*.md           # Local mode
   Note: /goal may not auto-close the ticket — update its state yourself when done.

It's working if

• Every Issue answers "what can I demo when this is done?" — and the answer is a behaviour, not a layer.
• The list came back numbered with a real "Blocked by" line on each, before anything was published.
• The Issue at the top has no blockers and can be started immediately.
• No Issue body carries a file path or line number (except a snippet a prototype produced).
• Each Issue reads like something a fresh session could finish without you in the room.
• Prefactoring, where any was found, sits at the front of the order — not mixed into feature Issues.
• Every acceptance criterion names an observation that fails at the base commit.

Edge Cases & Fallback

Relationship to Other Skills

/prd  →  /prd-to-spec (optional)  →  /to-issues  →  /goal  →  /review-it  →  /ship-it
 │              │                        │              │
 │  Requirements │  Technical design     │  Vertical    │  Implementation
 │  (what)       │  (how)                │  tickets     │  (code)

• /prd — produces the PRD (input to this skill)
• /prd-to-spec — produces the SPEC (optional; keep in the same context window as this skill)
• /to-issues — produces the vertically-sliced Issues (this skill)
• /goal — implements Issues one by one, one per fresh session