technical-planning

What this skill does

# Technical Planning

## Core Principles

**Focus on "What" Not "How"**: Define deliverable outcomes, not implementation details. Specify constraints and success criteria, but leave implementation choices flexible.

**Last Responsible Moment**: Defer decisions until you have enough information to make them well, but not so late that they block progress. Make reversible decisions quickly; delay irreversible ones until necessary.

**Risk-First Development**: Address highest-risk technical challenges first. Build proof-of-concepts before full implementation. Ship working but imperfect solutions to validate core assumptions early.

**Managed Deferral**: Explicitly document what's being deferred and when it will be addressed. Distinguish between core value delivery and polish/optimization.

### Progress Tracking with TodoWrite

Use TodoWrite to track planning progress through the four phases:

1. **At start**: Create todos for each phase:
   ```
   ☐ Phase 1: Requirements & Risk Analysis
   ☐ Phase 2: Milestone Planning
   ☐ Phase 3: Implementation Strategy
   ☐ Phase 4: Execution Framework
   ```

2. **During planning**: Mark phases in_progress → completed as you work through them. Add sub-todos for key deliverables:
   ```
   ☐ Extract core requirements (2-3 user journeys)
   ☐ Identify technical risks (high/integration/performance/architecture)
   ☐ Define milestones with success criteria
   ☐ Document deferred items with rationale
   ```

3. **For complex projects**: Track clarifying questions and their resolutions as todos - prevents proceeding with incomplete information

### Decision Timing Framework

**Decide Early (Requirements Phase)**:
- User problems being solved
- Success criteria and measurement
- Hard constraints (security, compliance, performance SLAs)
- Critical integrations and dependencies
- Technology choices that affect architecture

**Defer to Implementation (Execution Phase)**:
- Specific algorithms or data structures
- Internal API design details
- Code organization patterns
- Library choices (when multiple options work)
- Performance optimizations (until proven necessary)
- UI/UX details (until user testing)

**Why**: Early decisions should enable work without locking in details. Implementation decisions become clearer with hands-on experience and often reveal better alternatives than upfront planning suggests.

## Agent Guidelines

**Seek Clarity Before Proceeding**: Never assume unclear requirements, technical constraints, or business priorities. Only proceed when you have 80%+ confidence on critical aspects. Ask specific questions about:

- User problems being solved (not just features requested)
- Success criteria and measurement approaches
- Technical constraints and existing system dependencies
- Team capabilities and technology preferences
- Timeline constraints and priority trade-offs
- Performance and scalability requirements

## Phase 1: Requirements & Risk Analysis

### Prerequisites Check

Verify:

- What user problems are being solved?
- Who are the primary users and their workflows?
- How will success be measured?
- What are the technical and business constraints?

### Extract Core Requirements

1. Identify fundamental user problems being solved
2. Map primary user journeys (focus on 2-3 critical paths)
3. Define project success metrics

### Identify Technical Risks

1. **High-Impact Risks**: Technical unknowns that could invalidate the approach
2. **Integration Risks**: External system dependencies and compatibility concerns
3. **Performance Risks**: Scalability bottlenecks and algorithmic challenges
4. **Architecture Risks**: Fundamental design decisions with broad implications

### Risk Prioritization Matrix

- **Critical + Unknown**: Must be addressed in Milestone 1 with proof-of-concepts
- **Critical + Known**: Address in early milestones with established patterns
- **Non-Critical**: Defer to later milestones or eliminate

## Phase 2: Milestone Planning

### Prerequisites Check

Verify:

- Priority order of technical risks identified in Phase 1
- Team capacity and available timeline
- Dependencies between different components
- Definition of "working functionality" for this project

### Milestone Structure

- **Timeline**: 4-8 week cycles based on project complexity
- **Deliverable**: Each milestone must produce working, testable functionality
- **Risk Focus**: Sequence milestones to tackle highest-risk items first

### For Each Milestone, Define:

**Goal**: One-sentence description of milestone outcome

**Core Tasks**: 4-6 main implementation tasks following Last Responsible Moment principle:
- Define clear outcomes and constraints
- Identify dependencies and integration points
- Provide context and considerations (not step-by-step instructions)
- Leave implementation details flexible
- Flag questions to resolve during execution

**Success Criteria**:
- Minimum Viable Success (must achieve for milestone completion)
- Complete Success (ideal outcome including polish)

**Risk Mitigation**: Specific unknowns to be resolved in this milestone

**Deferred Items**: What's intentionally left out and target milestone for inclusion

### Task Breakdown Guidelines

When breaking down tasks, provide **guidance not prescription**:

**✓ Good Task Definition** (outcome-focused):
- Goal: "Enable users to authenticate securely"
- Constraints: "Must integrate with existing session middleware; <100ms response time"
- Guidance: "Consider session vs. token auth; review existing patterns in src/middleware/"
- Validation: "Users can log in, sessions persist, tests pass"

**✗ Poor Task Definition** (overly prescriptive):
- Step 1: "Create file auth.js with bcrypt import"
- Step 2: "Write hashPassword function using bcrypt.hash with 10 rounds"
- Step 3: "Create Express middleware checking req.session.userId"

**Why**: Good definitions let the implementer choose the best approach based on what they learn. Poor definitions lock in choices before understanding the context, often leading to rework.

### Example Milestone Definition

**Goal**: Validate user authentication and basic data retrieval from external API

**Core Tasks**:
1. Implement OAuth flow with provider
2. Create user session management
3. Build API client with error handling
4. Add basic user profile display

**Success Criteria**:
- Minimum: Users can log in and see their profile data
- Complete: Include profile editing and session persistence

**Risk Mitigation**: Confirm API rate limits and response time under load

**Deferred**: Advanced profile features, password reset flow (Milestone 3)

## Phase 3: Implementation Strategy

### Development Approach

- **Prototype First**: Build throwaway versions to test risky assumptions
- **Core Before Polish**: Implement functional features before UI refinements
- **Integration Early**: Test external system connections in first milestone
- **Measure Continuously**: Track performance and user metrics from day one

### Technology Selection Criteria

1. **Team Expertise**: Prefer technologies your team knows well
2. **Proven Reliability**: Choose mature, battle-tested options for core systems
3. **Integration Capability**: Ensure compatibility with existing tools/systems
4. **Scalability Path**: Technology should support anticipated growth

### Quality Gates

- All code must have basic test coverage
- Performance benchmarks must be met for core user journeys
- Security review required for authentication and data handling
- Accessibility standards met for user-facing features

## Phase 4: Execution Framework

### Sprint Planning

1. **Risk Assessment**: Identify unknowns in upcoming work
2. **Exploration Time**: Reserve 20-30% of sprint for prototyping/learning
3. **Definition of Done**: Must include working functionality, not just completed code
4. **Continuous Validation**: Regular stakeholder feedback on core user journeys

### Deferral Management

- **Regular Review**: Evaluate deferred items each milestone for continued relevance