Issue Breakdown

The Breakdown agent converts your complete specification — PRD, design brief, technical spec — into implementation tasks structured as vertical slices. Each task is a self-contained piece of user-facing functionality ready to ship to an AI coding tool.

How breakdown works

The Breakdown agent acts as a senior Tech Lead. It reads all previous specification documents and produces issues that are:

• Vertical slices — Each issue spans all technical layers (UI, API, database) to deliver a complete user capability. See Vertical Slices.
• Sequenced by dependency — Issues are ordered so each one builds on what came before
• Self-contained — Each issue includes everything an AI coding tool needs: description, acceptance criteria, technical context, testing strategy

Breakdown detail levels

Before generating issues, you choose a detail level that controls how finely the work is broken down:

Complexity scoring

Each issue receives a complexity score from 1-10, mapped to estimated hours:

Issues scoring 7+ are automatically split into subtasks organized by technical layer within the vertical slice:

VERTICAL SLICE: "User can sign in with Google"
  ├─ Backend: OAuth provider integration
  ├─ Frontend: Sign-in button and flow
  ├─ Database: User profile storage
  └─ Testing: OAuth integration tests

Issue structure

Each issue in issues.json includes:

• Title and description — What the user can do after this issue is complete
• Estimated hours — Based on complexity scoring
• Dependencies — Other issue IDs that must be completed first
• Screens affected — IDs from screens.json that this issue touches
• Key decisions — Architecture and technology decisions relevant to this issue
• Acceptance criteria — Specific, testable criteria inherited from the PRD
• Technical details — Implementation guidance from the tech spec
• Testing strategy — Both automated tests and manual verification steps
• Human-in-the-loop verification — Specific steps for a person to verify the implementation

Testing philosophy

The Breakdown agent follows a critical-only testing approach:

Write automated tests for critical logic:

• Payment processing
• Authentication and authorization
• Security operations
• Critical user data operations
• Business-critical workflows

Skip automated tests for non-critical code:

• UI components and styling
• Simple CRUD on non-critical data
• Form validation (non-security)
• Display logic

Every issue includes manual verification steps — specific localhost testing instructions that a person follows to verify the implementation works correctly:

{
  "testing_strategy": {
    "automated_tests": "Integration test for OAuth callback flow",
    "manual_verification": "1. Visit localhost:3000/login\n2. Click 'Sign in with Google'\n3. Grant permissions\n4. Should redirect to dashboard"
  },
  "human_in_the_loop": [
    "Verify OAuth flow works with a real Google account",
    "Check error handling when user denies permissions",
    "Verify session persists across page refreshes"
  ]
}

Codebase awareness

If you've initialized SpecWright in an existing project, the Breakdown agent analyzes your codebase when creating issues. It accounts for:

• Existing components that can be reused (from screens.json component marking)
• Current file structure and naming patterns
• Installed dependencies and frameworks
• Existing API patterns and data models

Review and confirmation

After issues are generated, you see a preview with the issue count, titles, statuses, and estimated hours. Click "Confirm Issues" to finalize and open the issues board where you can:

• Review each issue's full details
• Change issue status via drag-and-drop
• Ship any issue to your AI coding tool

What's next?

• Ship to AI Tools — Send issues to Cursor, Claude Code, and more
• Vertical Slices — Why this task structure works
• Output Files — Full issues.json format reference