# Atomic Task Decomposition Rules

CRITICAL: Agents must execute ONE small task per invocation. Never assign broad multi-step tasks.

## Problem

Agents frequently hang or produce incomplete results when given large, complex tasks. Token budgets are exhausted before completion.

## Solution: Atomic Task Principle

**1 agent invocation = 1 atomic task = 1 clear outcome = 1 verification**

## Atomic Task Definition

An atomic task meets ALL criteria:
- Completable in under 5 minutes
- Has a single clear deliverable
- Can be verified independently (test, lint, build)
- Produces at most 3-5 files
- No more than 100 lines changed per file

## Decomposition Rules

### Before Delegating

1. **Decompose first**: Break any task into 3-5 atomic subtasks
2. **Order by dependency**: Subtasks that depend on others come later
3. **Each subtask gets its own agent invocation**

### Task Sizing Guide

| Task Type | Max Scope | Max Files | Max Lines |
|-----------|-----------|-----------|-----------|
| Model/Entity creation | 1 model + 1 migration | 2 | 80 |
| API endpoint | 1 endpoint + 1 test | 2 | 100 |
| Service method | 1 method + 1 test | 2 | 60 |
| UI Component | 1 component + 1 test | 2 | 80 |
| Bug fix | 1 fix + 1 test | 2 | 50 |
| Config change | 1 config file | 1 | 30 |

### Violation Examples (DON'T)

```
❌ "Implement the entire e-commerce backend"
❌ "Create all models, controllers, and services for the product module"
❌ "Build the admin panel with all CRUD operations"
❌ "Fix all failing tests"
```

### Correct Examples (DO)

```
✅ "Create Product model with migration and factory"
✅ "Add POST /api/products endpoint with validation and test"
✅ "Build ProductCard.vue component with props and unit test"
✅ "Fix TypeError in OrderService::calculateTotal - add null check"
```

## Orchestrator Decomposition Protocol

When orchestrator receives a task:

1. **Count atomic subtasks**: How many minimal units?
2. **If > 5 subtasks**: Create sub-milestone issues in Gitea for tracking
3. **Delegate one subtask at a time** via Task tool
4. **Wait for completion** before delegating next
5. **Verify output** after each subtask
6. **Update Gitea issue** with progress after each subtask

## Agent Self-Regulation

Each agent must:

1. **Check task size**: If too broad, split it and report back
2. **Focus on one deliverable**: Don't expand scope
3. **Complete before extending**: Finish the assigned task, don't add extras
4. **Report precisely**: "Done: X" not "I also did Y and Z"

## Token Budget per Atomic Task

| Task Complexity | Token Budget | Time Budget |
|----------------|-------------|-------------|
| Simple (config, fix) | 5,000 | 2 min |
| Medium (endpoint, component) | 10,000 | 5 min |
| Complex (multi-service flow) | 20,000 | 10 min |

If approaching budget, STOP and report progress. Delegate continuation to next invocation.

## Pipeline Step Granularity

Pipeline steps must be fine-grained:

```
❌ Step 3: "Implement Backend" (too broad)
✅ Step 3a: "Create Product model + migration"
✅ Step 3b: "Add GET /api/products endpoint"
✅ Step 3c: "Add POST /api/products endpoint"
✅ Step 3d: "Create ProductService with list() and create()"
✅ Step 3e: "Add ProductRepository with filtering"
```

Each sub-step is its own agent invocation with its own Gitea comment.