Agile Workflow: Research → Plan → Implement

A structured approach for working effectively on large, complex codebases with AI assistance.

The Problem

AI coding tools excel at greenfield but struggle with brownfield (100k+ LOC production codebases).

Root cause: Context degradation. As conversations grow, AI loses coherence and makes poor decisions.

Core Insight

"The contents of your context window are the ONLY lever you have to affect the quality of your output."

Context quality optimizes for:

1. Correctness - Most critical
2. Completeness - All relevant information
3. Size minimization - Less noise
4. Trajectory clarity - Clear direction

The Three-Phase Framework

RESEARCH ──────▶ PLANNING ──────▶ IMPLEMENT
Understand        Milestones       Execute tasks
Map files         Task list        Verify & commit
Patterns          Test plan        Fresh context

Human review points between each phase.

Phase 1: Research

Purpose: Understand the codebase as it exists today.

Principles:

• Document, don't critique
• Find WHERE files live, HOW code works
• Use subagents for exploration (preserves context)

Outputs:

• Files involved with brief purposes
• Architecture overview
• Key patterns and conventions
• Potential approaches with tradeoffs

Phase 2: Planning

Purpose: Create detailed, verifiable implementation plan.

Principles:

• Break large work into milestones (see /milestone-planning)
• Milestones break into tasks (see /task-sizing)
• Each milestone fits in context, has verifiable end state
• Get human buy-in at each milestone

Outputs:

• Vision statement (overall goal)
• Roadmap (milestone breakdown)
• Current milestone: task list with exit criteria
• Explicit scope boundaries (what we're NOT doing)

Phase 3: Implementation

Purpose: Execute the approved plan with verification.

Principles:

• ONE task at a time using fresh-context subagents
• Run automated verification after each task
• Git commits mark progress
• Pause for review between milestones

Human Leverage Hierarchy

Where human attention multiplies impact:

Phase	Error Multiplier	Review Priority
Research	1 mistake → 1000s bad lines	HIGH
Planning	1 mistake → 100s bad lines	HIGH
Implementation	1 mistake → isolated issue	Lower

Insight: Review research and plans, not code details.

When to Use This Workflow

Full workflow:

• 5+ files
• Unfamiliar codebase
• Complex refactoring
• Unclear approach

Skip to planning:

• Well-understood changes
• Familiar code
• Clear bug with known fix

Skip to implementation:

• Single-file changes
• Trivial fixes
• Previously planned work

Context Management

Maintain 40-60% context utilization (see /context-health):

• Research: Subagents preserve context
• Planning: Document to external files
• Implementation: Fresh context per task
• Between milestones: Start fresh, state persists

Related Skills

• /milestone-planning - Break work into milestones
• /task-sizing - Size tasks for implementers
• /context-health - Context management strategies