To Issues

To Issues

To Issues turns a plan into independently executable backlog items. The goal is not to split work by layer, but to create thin vertical slices that are reviewable, testable, and dependency-aware.

When to Use

• A plan, spec, or PRD is approved and now needs implementation tickets
• A broad initiative must be broken into thin, demoable slices
• The current backlog is too coarse to delegate safely
• You need to separate work that can proceed independently from work that is blocked

When NOT to Use

Workflow

1. Start from an approved source

Use a real input artifact:

• plan
• PRD
• spec
• parent issue

Do not create issue slices from an unresolved conversation.

2. Extract vertical slices

Each issue should represent a thin end-to-end path, not a horizontal layer split.

Good slices usually:

• have one clear outcome
• can be tested or demonstrated on their own
• expose their dependency relationship to other slices

Bad slices are things like "database changes only" or "UI updates only" if they cannot be verified in isolation.

Exception — wide refactors: a single mechanical change (rename a column, retype a shared symbol) can have a blast radius that fans across the whole codebase, breaking thousands of call sites at once so no vertical slice can land green. Do not force this shape into a tracer bullet — see Wide Refactor Exception below.

3. Mark blockers explicitly

For each proposed issue, identify:

• what it delivers
• what blocks it
• whether it can start immediately

Publish blockers first so later issues can reference them cleanly.

4. Review the breakdown before publishing

Show the user the proposed issue set and ask whether:

• the slices are too coarse or too fine
• any issue should be merged or split
• the dependency order is correct

Only publish after the breakdown is approved.

4a. Draft locally before publishing

Before publishing, stage each proposed issue as its own local draft file rather than one combined scratch document:

.scratch/<feature-slug>/issues/<NN>-<slug>.md

• <feature-slug> groups all drafts for one plan/PRD pass
• <NN> is a zero-padded sequence number that reflects publish order
• <slug> is a short kebab-case title

One file per issue makes it possible to publish, edit, or drop a single slice without touching the others, and keeps the dependency-blocker references (Blocked by: #NN) resolvable against the local draft numbering before the tracker assigns real issue numbers.

5. Publish to the active issue tracker

Support the tracker the project already uses.

• GitHub: use gh issue create (or equivalent GitHub CLI workflow) when publishing approved issues
• GitLab: use the GitLab issue workflow or CLI available in the environment

Do not assume one provider if the project uses another.

Wide Refactor Exception

A wide refactor is one mechanical change whose blast radius fans across the whole codebase — a single edit breaks thousands of call sites at once, so no vertical slice can land green. Do not force it into a tracer bullet; sequence it as expand–contract instead:

1. Expand — add the new form beside the old so nothing breaks yet. One issue.
2. Migrate — move call sites over in batches sized by blast radius (per package, per directory). Each batch is its own issue, blocked by the expand issue. CI stays green batch to batch because the old form still exists alongside the new one.
3. Contract — delete the old form once no caller remains, in an issue blocked by every migration batch.

When even individual batches cannot stay green in isolation, keep the same three-phase sequence but let the batches share an integration branch that all block a final integrate-and-verify issue — green is promised only there, not batch by batch.

Use this exception only when the change is genuinely mechanical and blast-radius-driven (renames, retyped shared symbols, signature-wide API changes). A feature that merely touches many files because it has many concerns is not a wide refactor — slice it vertically instead.

Output Template

## Proposed Issue Breakdown

1. **Title:** ...
   **Blocked by:** None / #123
   **Delivers:** ...
   **Acceptance signal:** ...

2. ...

Issue Body Template

## Parent

[Reference to the source plan, PRD, or parent issue]

## What to build

[One thin vertical slice with end-to-end value]

## Acceptance criteria

- [ ] ...
- [ ] ...
- [ ] ...

## Blocked by

None - can start immediately

Common Rationalizations

Red Flags

• Several issues depend on work that has no explicit parent blocker
• A slice only changes one layer and cannot be verified on its own
• The user has not approved the breakdown before publication
• The issue titles use implementation jargon instead of domain language from the source artifact

Verification

• Every issue represents a thin vertical slice
• Dependencies are explicit
• The user approved the granularity before publishing
• The tracker-specific publish path matches the project actually in use

See Also

• create-prd — define the feature before turning it into backlog items
• wayfinder — build the destination-centric plan first for large, multi-session initiatives
• github-issue-triage — organize and review an existing GitHub issue backlog
• team-planner — assign the resulting slices across specialist agents