Planning System

This is a three-tier planning system for iterative project development. Each tier produces artifacts that inform the next.

The Three Tiers

Tier 1: Project Planning

High-level planning done once at project start. Defines goals, approach, architecture, and milestones.

• Output: docs/plan/project.md
• Produces: List of milestones with identifiers (e.g., m1-auth, m2-dashboard)

Tier 2: Milestone Planning

Done at the start of each milestone. Breaks the milestone into discrete tasks.

• Input: Project plan
• Output: docs/plan/milestones/{milestone}/milestone.md
• Produces: List of tasks with identifiers (e.g., m1.1-login-form, m1.2-signup-flow)

Tier 3: Task Planning

Done at the start of each task. Plans implementation, tracks execution, captures learnings.

• Input: Milestone plan + accumulated learnings
• Output: docs/plan/milestones/{milestone}/tasks/{task}/task.md
• Also appends to: docs/plan/learnings.md

Naming Convention

• Milestones: m{number}-{name} (e.g., m1-auth, m2-dashboard)
• Tasks: m{milestone}.{task}-{name} (e.g., m1.1-login-form, m1.2-signup-flow)

File Structure

docs/plan/
├── project.md              # Tier 1 output - goals, architecture, milestones
├── learnings.md            # Accumulated learnings from all tasks
├── decisions/
│   ├── 001-switch-to-graphql.md
│   └── 002-defer-analytics.md
└── milestones/
    ├── m1-auth/
    │   ├── milestone.md    # Tier 2 output - milestone plan and task list
    │   ├── {milestone-level artifacts}
    │   └── tasks/
    │       ├── m1.1-login-form/
    │       │   ├── task.md
    │       │   └── {task artifacts}
    │       └── m1.2-signup-flow/
    │           └── task.md
    └── m2-dashboard/
        ├── milestone.md
        └── tasks/
            └── m2.1-user-profile/
                └── task.md

Learnings and Decisions

Planning is imperfect. As work progresses, we discover things we didn't anticipate and make decisions that change the plan.

Learnings

Lessons learned during execution that inform future planning. Captured in docs/plan/learnings.md. These may be technical or process-related.

Technical examples:

• "API rate limits are lower than documented, need to batch requests"
• "Integration tests take 5 minutes, run selectively during development"
• "The auth library doesn't support refresh tokens out of the box"

Process examples:

• "Breaking tasks into half-day chunks improved estimation accuracy"
• "Spiking unfamiliar APIs before planning saved rework"
• "Pairing on complex integrations caught issues earlier"

Learnings are reviewed at the start of each planning session.

Decisions

Significant changes to the plan, recorded as individual documents in docs/plan/decisions/.

When a decision changes the plan:

1. Update the affected plan document (project.md, milestone.md) to reflect current state
2. Create a decision record documenting the change and rationale

Decision document format:

markdown
1# {Number}: {Title}
2
3## Status
4
5{Proposed | Accepted | Superseded by XXX}
6
7## Context
8
9{What situation prompted this decision?}
10
11## Decision
12
13{What are we changing?}
14
15## Rationale
16
17{Why this approach over alternatives?}
18
19## Consequences
20
21{What changes as a result? What are the tradeoffs?}

Decisions are numbered sequentially: 001-switch-to-graphql.md, 002-defer-analytics.md.

Workflow

This is a conversational process. Describe your intent and I will:

1. Identify which planning tier applies
2. Look up relevant identifiers from existing plans
3. Guide you through the appropriate planning process

Examples:

• "Let's plan a new project" → Tier 1 project planning
• "Let's start the auth milestone" → I look up the milestone in project.md, begin tier 2 planning
• "Ready to work on login" → I find the task in the milestone plan, begin tier 3 planning

Learnings from each completed task feed into future task planning. When discoveries require plan changes, we update the plan and record a decision.

Getting Started

Describe what you want to work on:

• Starting a new initiative? We'll do project planning.
• Ready to begin a milestone? Tell me which one.
• Ready to implement a task? Tell me what you're building.