DevLoop Runner

Introduction

When running a Dev Run with DevLoop Runner, one of the biggest factors determining output quality is Issue granularity (size).

The Issue writing guide introduced basic sizing principles, but this article goes much deeper. We will explore what task size allows AI to perform at its best, how to measure it, and how to split tasks systematically.

Optimizing Issue granularity does more than improve Dev Run success rates. It also reduces review workload and increases overall development throughput.

Why Issue Size Matters for AI

Context Window Constraints

AI models have a limit on how much information they can process at once (the context window). When an Issue is too large, several problems emerge.

Loading diagram...

In DevLoop Runner's 10-phase workflow, each phase receives output from the previous phase. When an Issue is large, the plan created in the Planning phase becomes harder to maintain consistently through the Implementation phase.

Coherence Degradation

AI delivers very high coherence on small tasks, but that coherence tends to degrade as the scope of changes grows.

Change Size	File Count	Coherence	Approximate Success Rate
Small	1-3 files	Very high	85-95%
Medium	4-7 files	High	70-85%
Large	8-15 files	Moderate	50-70%
Very large	16+ files	Low	Below 30%

These numbers are guidelines, but the correlation between change size and success rate is clear.

The Sweet Spot Where AI Performs Best

Target: 50-200 Lines of Changes

Based on practical experience, the change size where AI most reliably produces high-quality code is 50-200 lines of changes.

Under 50 lines:

The benefit of using AI may be marginal
The overhead of running all 10 Dev Run phases may not be justified
However, test addition and documentation tasks can still be effective at this size

50-200 lines:

AI can maintain full context awareness while generating consistent implementation
Reviews can typically be completed in a single pass
Tests are generated at an appropriate granularity

Over 200 lines:

A signal that splitting should be considered
If proceeding without splitting, the Issue needs detailed technical constraints

Over 500 lines:

Splitting is almost certainly necessary
Handling this in a single Issue carries a high risk of significant quality degradation

How to Estimate Size Before Running

Estimating the change size before executing a Dev Run is important for making the right call.

Method 1: Estimate with Plan Only mode

Running a Dev Run in Plan Only mode produces output for the Planning, Requirements, and Design phases. The Design phase output reveals the number of target files and the scope of changes.

Judging from Plan Only design output:
- Target files: 3 files → Appropriate size
- Target files: 12 files → Consider splitting

Method 2: Estimate from similar tasks

If you have previously run Dev Runs on similar tasks, use those results to estimate the scope.

Method 3: Manual estimation

Read the requirements and mentally list the changes needed.

How many new files will be created?
How many existing files will be modified?
How many test files will be needed?

If the total exceeds 7 files, consider splitting.

Splitting Strategies by Task Type

Splitting Feature Additions

Feature additions are the task type most likely to need splitting.

Before splitting (oversized Issue):

Title: Implement user profile feature

Requirements:
- Create profile page UI
- Implement profile edit form
- Avatar image upload functionality
- Profile information API endpoints
- Profile validation
- Public/private profile settings

After splitting (right-sized Issues):

Issue 1: Implement profile information API endpoints
  → Backend data layer and API (~100 lines)

Issue 2: Create profile page display UI
  → Read-only profile view (~80 lines)

Issue 3: Implement profile edit form
  → Edit UI and validation (~120 lines)

Issue 4: Add avatar image upload functionality
  → File upload and storage integration (~150 lines)

Issue 5: Add public/private profile settings
  → Settings UI and access control (~80 lines)

Splitting principles:

Create a dependency chain: data layer → display → editing → additional features
Each Issue should be independently testable
Make the order explicit when dependencies exist

Splitting Refactoring Tasks

Refactoring tasks are generally easier to split because of the constraint that behavior must not change.

Splitting approaches:

Split By	Example	Best For
File	Refactor file A, refactor file B	Changes are independent
Layer	Refactor data layer, refactor UI layer	Architecture layers are separable
Pattern	Convert callbacks to async/await, clean up type definitions	Same type of improvement applied across the codebase

See the AI refactoring guide for more details.

Splitting Bug Fixes

Bug fixes are usually best handled as a single Issue. However, consider splitting in these cases:

Multiple root causes: Create separate Issues for each cause
Large refactoring needed alongside the fix: Separate the bug fix from the refactoring
Multiple components affected: Split by component

Splitting example:
Issue 1: Fix query escaping bug in search API (core fix)
Issue 2: Extract shared validation function for search API (refactoring)
Issue 3: Add edge case tests for search API (test hardening)

Decision Criteria for Splitting

When you are unsure whether to split an Issue, use the following decision matrix.

Decision Matrix

Condition	Split	Keep as One
8+ files likely to change	Recommended	--
200+ lines of changes likely	Recommended	--
Contains multiple independent features	Recommended	--
5+ requirements	Consider	Keep if requirements are tightly coupled
Changes are confined to one layer	--	Proceed as is
5 or fewer files to change	--	Proceed as is
Focused on a single purpose	--	Proceed as is

Flowchart for Decision Making

Loading diagram...

Chaining Dependent Issues

After splitting an Issue, you need to manage the execution order when dependencies exist.

Making Execution Order Explicit

Include dependency information in the Issue title or body.

Title: [2/4] Create profile page display UI

## Prerequisites
- Issue #123 (Profile API) must be completed

## Requirements
- Use the API endpoints created in Issue #123 to...

Using Batch Processing

Independent Issues can be run simultaneously using batch processing, significantly improving development speed.

Dependency map:
  Issue 1: Profile API → Run first
  Issue 2: Profile display UI → Run after Issue 1
  Issue 3: Avatar upload → Run after Issue 1 (parallel with Issue 2)
  Issue 4: Public/private settings → Run after Issue 2

Issues 2 and 3 are independent of each other and can be batch-processed simultaneously.

Worked Example: Splitting an Oversized Issue

Let us walk through a concrete splitting process.

Original Issue

Title: Implement notification feature

Requirements:
- Design and implement notification data model
- Notification CRUD API endpoints
- Real-time notifications (WebSocket)
- Notification list page UI
- Read/unread management
- Notification settings (per-type on/off)
- Email notification sending
- Batch notification deletion

Analyze with Plan Only Mode

First, run Plan Only mode and review the AI's design output.

Design output summary:
- Files to change: 18 files
- New files to create: 12 files
- Estimated lines of change: 800-1200
→ Clearly too large

Splitting Result

Issue 1: Implement notification data model and CRUD API (~150 lines)
  - Data model definitions
  - Basic CRUD endpoints
  - Unit tests

Issue 2: Create notification list page UI (~120 lines)
  - Notification list component
  - Pagination
  - Uses Issue 1's API

Issue 3: Add read/unread management (~80 lines)
  - Unread count display
  - Mark-as-read functionality
  - Extends Issue 1's API

Issue 4: Implement real-time notifications via WebSocket (~180 lines)
  - WebSocket connection management
  - Real-time UI updates
  - Extends Issue 2's UI

Issue 5: Add notification settings (~100 lines)
  - Settings UI
  - Per-type on/off API

Issue 6: Add email notification sending (~120 lines)
  - Email sending logic
  - Filtering based on Issue 5's settings

Issue 7: Add batch notification deletion (~60 lines)
  - Multi-select UI
  - Batch delete API

One Issue with 8 requirements became 7 right-sized Issues. Each Issue falls within 60-180 lines of changes, right in the AI's sweet spot.

Summary

AI performs best with 50-200 lines of changes and 7 or fewer files modified
Oversized Issues cause coherence and quality degradation due to context constraints
Plan Only mode helps estimate change size before committing to a full run
Optimal splitting strategies differ by task type (feature, refactoring, bug fix)
Use the decision matrix and when in doubt, lean toward splitting
Chain split Issues with explicit dependencies and use batch processing for parallel execution
Issue granularity optimization, alongside Issue writing quality, is the most critical factor for Dev Run success

Simply being mindful of Issue size can dramatically improve your Dev Run success rate. Before your next Dev Run, check your Issue against the decision criteria in this article.

Optimizing Issue Granularity: The Task Size Where AI Performs Best