Atomic Task Design

You've learned that tasks should be "atomic" - small, focused units. But there's a tension:

Too Large:

• AI loses focus across many files
• Context overflow leads to errors
• Difficult to review massive changes
• Hard to isolate bugs when things break

Too Small:

• Excessive context switching overhead
• Each task requires re-reading specs and understanding codebase
• Integration overhead connecting tiny pieces
• Workflow becomes unwieldy with 50+ micro-tasks

The Question: Where's the sweet spot? How do you know if a task is "just right"?

An atomic task has these properties working together:

1. Clear, Testable Completion Criteria

✅ GOOD (Observable, Measurable):

• CommentRepository has create() method returning Comment
• Unit tests pass: pytest tests/unit/test_comment_repository.py
• Coverage ≥90%
• Type checking passes: mypy src/repositories/comment_repository.py

❌ BAD (Vague, Subjective):

• Repository works well
• Code is clean

2. Reasonable Implementation Scope (45-120 minutes)

✅ REASONABLE (60 min):

• Implement CommentRepository with 5 CRUD methods
• Write 8 unit tests with mocked DB

❌ TOO LARGE (>2 hours):

• Implement entire commenting system (8 files, 6 hours)

❌ TOO SMALL (<30 min):

• Add one method to existing repository (15 minutes)

Why 45-120 minutes?

• Below 45 min: Setup overhead exceeds implementation time
• Above 120 min: Fatigue sets in, AI context degrades, too much to review

3. Logical Cohesion (Complete Capability)

✅ COHESIVE: [T001] Implement Comment Creation

• Model + Repository + Service + API endpoint + Tests
• Result: Users CAN create comments (working feature)

❌ INCOHERENT: [T001] Create All Model Definitions

• Comment, Attachment, Notification, Tag models
• Result: 4 models exist but NO working features

4. Independent or Explicit Dependencies

✅ EXPLICIT DEPENDENCIES: [T005] Create Comment API Endpoints

• Depends on: T003 (CommentService), T004 (CommentSchema)
• Integration: Import from src/services/comment_service.py

❌ UNCLEAR: [T005] Create API Endpoints

• Depends on: "backend stuff"

1. Scope Management: Break 8-hour features into 2-hour chunks for fresh AI context and reviewable PRs

2. Parallel Work: Enable multiple developers to work simultaneously on independent tasks

3. Risk Isolation: Test complex areas (like external API integrations) separately before integration

4. Clear Milestones: Demonstrate incremental progress with working features

Example:

❌ ONE BIG TASK: [T001] Build Complete Commenting System (8 hours)

• No demo until day 8, entire feature blocked if issues occur

✅ PHASED TASKS: [T001] Comment Model + Repository (2 hours) [T002] Comment Service + Validation (2 hours)
[T003] Comment API + Integration Tests (2 hours) [T004] Authorization + E2E Tests (2 hours)

• 4 reviewable PRs, 4 milestones, can ship T001-T002 early