issue-planning-patterns

name	issue-planning-patterns
description	Patterns for breaking specs into atomic issues with proper dependency graphs and execution ordering. Use when planning implementation of a spec or organizing complex work.

Issue Planning Patterns

Guidelines for breaking specs into implementable issues with proper dependencies.

When to Use

• Planning implementation of a spec
• Breaking down complex features
• Organizing multi-session work
• Establishing execution order
• Reviewing issue graph health

Atomic Issue Principles

1. Single Responsibility

Each issue should do one thing well.

❌ BAD: "Implement authentication and user profiles"

✅ GOOD:
- i-auth: "Implement authentication flow"
- i-profiles: "Implement user profiles"

2. Completable in One Session

An issue should be achievable in a focused work session.

❌ TOO BIG: "Build entire API layer"

✅ RIGHT SIZE: "Implement /api/markets endpoint"

3. Clear Acceptance Criteria

Define what "done" means.

❌ VAGUE: "Add search"

✅ CLEAR: "Add search
- Search input with debounce
- Results display in list
- Empty state when no results
- Loading state during search"

4. Proper Linking

Every issue should connect to the broader context.

Required links:
- implements → spec (what requirement this fulfills)
- OR parent → parent issue (if subtask)

Optional links:
- blocks → dependent issues
- discovered-from → source issue (if found during work)

---

Dependency Types

Type	Syntax	Purpose	Effect on ready
implements	link i-xxx s-xxx --type=implements	Connect issue to spec	None (documentation)
blocks	link i-xxx i-yyy --type=blocks	i-xxx must complete before i-yyy starts	i-yyy not ready until i-xxx closed
parent	upsert_issue parent=i-xxx	Hierarchical organization	None (hierarchy only)
discovered-from	link i-new i-source --type=discovered-from	Track provenance	None (documentation)
related	link i-xxx i-yyy --type=related	Soft connection	None (documentation)

When to Use Each

implements:

• Every implementation issue should link to a spec
• Creates traceability from requirements to work

blocks:

• Use for hard dependencies (A must finish before B starts)
• Database schema before API endpoints
• API endpoints before frontend integration
• Core utilities before features that use them

parent:

• Use for hierarchical organization
• Epic with subtasks
• Feature with sub-features
• Does NOT affect execution order

discovered-from:

• Bug found while implementing another issue
• New requirement discovered during work
• Tracks where work originated

---

Graph Patterns

Foundation Pattern

Build foundational pieces first, then parallel work, then integration.

┌─────────────┐
│   Setup     │  ← Foundation (blocks everything)
│  Database   │
└──────┬──────┘
       │ blocks
       ▼
┌──────┴──────┐
│             │
▼             ▼
┌─────┐   ┌─────┐
│ API │   │ API │  ← Parallel work (independent)
│  A  │   │  B  │
└──┬──┘   └──┬──┘
   │         │
   │ blocks  │ blocks
   ▼         ▼
┌─────────────┐
│  Frontend   │  ← Integration (blocked by both)
│ Integration │
└─────────────┘

Example:

upsert_issue title="Setup database schema"           → i-db
upsert_issue title="Implement /api/users"            → i-users
upsert_issue title="Implement /api/markets"          → i-markets
upsert_issue title="Build user dashboard"            → i-dashboard

link i-db i-users --type=blocks
link i-db i-markets --type=blocks
link i-users i-dashboard --type=blocks
link i-markets i-dashboard --type=blocks

---

Feature Breakdown Pattern

Parent issue with child issues for subtasks.

┌─────────────────────┐
│  Auth Feature       │  ← Parent (epic)
│  (i-auth)           │
└─────────┬───────────┘
          │ parent
    ┌─────┼─────┐
    │     │     │
    ▼     ▼     ▼
┌─────┐┌─────┐┌─────┐
│Login││Logout││Session│  ← Children (subtasks)
└─────┘└─────┘└─────┘

Example:

upsert_issue title="Implement authentication"        → i-auth
upsert_issue title="Login flow" parent=i-auth        → i-login
upsert_issue title="Logout flow" parent=i-auth       → i-logout
upsert_issue title="Session management" parent=i-auth → i-session

# Add execution order within children
link i-login i-session --type=blocks
link i-session i-logout --type=blocks

---

Pipeline Pattern

Sequential stages where each stage enables the next.

┌─────┐   ┌─────┐   ┌─────┐   ┌─────┐
│Stage│──▶│Stage│──▶│Stage│──▶│Stage│
│  1  │   │  2  │   │  3  │   │  4  │
└─────┘   └─────┘   └─────┘   └─────┘
  │         │         │         │
Research → Design → Implement → Test

Example:

upsert_issue title="Research caching options"        → i-research
upsert_issue title="Design caching architecture"     → i-design
upsert_issue title="Implement caching layer"         → i-impl
upsert_issue title="Test caching behavior"           → i-test

link i-research i-design --type=blocks
link i-design i-impl --type=blocks
link i-impl i-test --type=blocks

---

Diamond Pattern

Multiple paths converge to a single point.

        ┌─────┐
        │Start│
        └──┬──┘
     ┌─────┴─────┐
     ▼           ▼
  ┌─────┐     ┌─────┐
  │Path │     │Path │
  │  A  │     │  B  │
  └──┬──┘     └──┬──┘
     └─────┬─────┘
           ▼
       ┌─────┐
       │Merge│
       └─────┘

Example:

upsert_issue title="Setup project"                   → i-setup
upsert_issue title="Build backend API"               → i-backend
upsert_issue title="Build frontend UI"               → i-frontend
upsert_issue title="Integration testing"             → i-integration

link i-setup i-backend --type=blocks
link i-setup i-frontend --type=blocks
link i-backend i-integration --type=blocks
link i-frontend i-integration --type=blocks

---

Planning Workflow

Step-by-Step Process

1. UNDERSTAND THE SPEC
   show_spec <id>
   - Read requirements thoroughly
   - Identify success criteria
   - Note technical considerations

2. IDENTIFY WORK UNITS
   - What are the distinct pieces of work?
   - Can each be completed in one session?
   - Are acceptance criteria clear?

3. IDENTIFY DEPENDENCIES
   - What must happen first? (foundation)
   - What can happen in parallel?
   - What must happen last? (integration)

4. CREATE ISSUES
   - Create all issues first (don't worry about order yet)
   - Use clear, actionable titles
   - Include acceptance criteria in descriptions

5. LINK TO SPEC
   - Every issue gets: link <issue> <spec> --type=implements

6. ADD DEPENDENCIES
   - Add blocks relationships for execution order
   - Add parent relationships for hierarchy

7. VERIFY WITH READY
   - Run: ready
   - Should show foundation issues first
   - Check: circular dependencies? Missing links?

Planning Checklist

□ All work units identified
□ Each issue is atomic (single responsibility)
□ Each issue is achievable in one session
□ Acceptance criteria defined for each
□ All issues link to spec (implements)
□ Dependencies captured (blocks)
□ Hierarchy captured (parent) if applicable
□ No circular dependencies
□ ready shows correct starting issues

---

Handling Changes

Adding Work Mid-Implementation

1. Create new issue
2. Link: discovered-from original issue
3. Decide: Does this block current work?
   YES → link new-issue blocks current-issue
         upsert_issue <current> status=blocked
   NO  → Continue current work, new issue in backlog

Replanning When Scope Changes

1. Review current issue graph: list_issues
2. Identify affected issues
3. Update or close obsolete issues
4. Create new issues for new scope
5. Update dependencies
6. Verify: ready

Splitting a Too-Large Issue

1. Create child issues with specific scope
2. Link: parent=original-issue
3. Add blocks relationships between children
4. Original issue becomes parent/epic
5. Close parent when all children closed

---

Anti-Patterns

Circular Dependencies

❌ BAD:
i-a blocks i-b
i-b blocks i-c
i-c blocks i-a  ← Circular! Nothing can start

✅ GOOD:
i-a blocks i-b
i-b blocks i-c
(i-a has no blockers, can start)

Missing Foundation

❌ BAD:
Create API endpoints and frontend in parallel
Both need database schema that doesn't exist

✅ GOOD:
i-schema blocks i-api-a
i-schema blocks i-api-b
i-api-a, i-api-b block i-frontend

Over-Granular Issues

❌ BAD:
- "Add import statement"
- "Define function signature"
- "Implement function body"
- "Add return statement"

✅ GOOD:
- "Implement calculateTotal function with tests"

Under-Specified Issues

❌ BAD:
Title: "Do the thing"
Description: (empty)

✅ GOOD:
Title: "Implement user search endpoint"
Description:
- GET /api/users/search?q=query
- Return matching users (name, email)
- Pagination with limit/offset
- Empty array if no matches

Orphan Issues

❌ BAD:
Issue exists with no links to specs or parent issues
(Why does this work exist?)

✅ GOOD:
Every issue either:
- implements a spec, OR
- has a parent issue, OR
- has discovered-from link (and eventually links to spec)

---

Quick Reference

Creating Issues

upsert_issue title="..." description="..."     # Create
upsert_issue <id> status=in_progress           # Claim
upsert_issue <id> status=closed                # Complete

Linking

link <from> <to> --type=implements             # Issue → Spec
link <blocker> <blocked> --type=blocks         # Execution order
link <child> <parent> --type=parent            # Hierarchy (use parent= in upsert)
link <new> <source> --type=discovered-from     # Provenance

Checking Graph

ready                                          # Unblocked issues
list_issues status=blocked                     # What's waiting
show_issue <id>                                # See relationships

---

Example: Planning Authentication Feature

# Given Spec: s-auth (Authentication System)

## Step 1: Identify Work Units
- Database: user table, session table
- API: register, login, logout, session refresh
- Frontend: login form, register form, auth state
- Testing: unit tests, integration tests

## Step 2: Create Issues

upsert_issue title="Create user and session tables"     → i-db
upsert_issue title="Implement register endpoint"        → i-register
upsert_issue title="Implement login endpoint"           → i-login
upsert_issue title="Implement logout endpoint"          → i-logout
upsert_issue title="Implement session refresh"          → i-refresh
upsert_issue title="Build login/register forms"         → i-forms
upsert_issue title="Implement auth state management"    → i-auth-state
upsert_issue title="Write auth integration tests"       → i-tests

## Step 3: Link to Spec

link i-db s-auth --type=implements
link i-register s-auth --type=implements
... (all issues implement s-auth)

## Step 4: Add Dependencies

# Foundation
link i-db i-register --type=blocks
link i-db i-login --type=blocks
link i-db i-logout --type=blocks
link i-db i-refresh --type=blocks

# API before frontend
link i-login i-forms --type=blocks
link i-register i-forms --type=blocks
link i-forms i-auth-state --type=blocks

# Everything before integration tests
link i-auth-state i-tests --type=blocks

## Step 5: Verify

ready
# Should show: i-db (only unblocked issue)

# After i-db closes:
ready
# Should show: i-register, i-login, i-logout, i-refresh (parallel)

---

Remember: A good issue graph makes execution obvious. When you run ready, the next step should be clear. If you're confused about what to work on, the graph needs improvement.