technical-planning skill

---
name: technical-planning
description: Plans technical projects with risk-first development, milestone structuring, and managed deferral. Use when planning software projects, defining milestones, structuring development phases, or breaking down complex tasks into manageable iterations.
---

# 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
- **Categories**: Technical debt, UX polish, edge cases, performance optimization, advanced features
- **Scheduling**: Plan deferred items into appropriate future milestones
- **Elimination**: Some deferred items may become unnecessary

### Documentation Requirements

- Technical specification focusing on deliverable outcomes
- Risk register with mitigation plans
- Deferred items registry with target scheduling
- Architecture decision records for major choices

## Decision Framework for Agents

**IF** project has unknown technical feasibility → Schedule proof-of-concept in Milestone 1
**IF** project requires external integrations → Test minimal integration in first milestone
**IF** project has performance requirements → Establish benchmarks and test core algorithms early
**IF** team lacks expertise in chosen technology → Include learning/exploration time in early milestones
**IF** project has tight deadlines → Focus on minimum viable success criteria and defer polish
**IF** project is greenfield → Spend extra time on architecture decisions and foundational setup
**IF** project is enhancement → Focus on integration points and backward compatibility

### When Unclear - Ask These Questions

**WHEN** requirements are vague → "What specific user problem does this solve? How will we measure success?"
**WHEN** technical scope is undefined → "What are the must-have vs. nice-to-have technical capabilities?"
**WHEN** timeline is unrealistic → "What are the non-negotiable deadlines and what flexibility exists?"
**WHEN** team capabilities are unknown → "What technologies does the team have experience with? What are the skill gaps?"
**WHEN** integration points are unclear → "What existing systems must this connect to? What are the data formats and API constraints?"
**WHEN** performance needs are unspecified → "What are the expected user loads and response time requirements?"
**WHEN** success criteria are missing → "How will we know this milestone is complete and successful?"

## Common Pitfalls to Avoid

- **Making assumptions instead of asking clarifying questions** when requirements are unclear
- **Proceeding with incomplete information** rather than requesting necessary details
- **Creating overly prescriptive task definitions** with step-by-step instructions instead of outcome-focused guidance
- **Making implementation decisions too early** when they could be deferred to execution
- Spending time on low-risk features while deferring critical unknowns
- Over-engineering solutions before validating core assumptions
- Planning implementation details instead of focusing on deliverable outcomes
- **Guessing at user needs** instead of understanding specific problems being solved
- Failing to document deferral decisions and rationale
- Optimizing prematurely instead of proving core functionality first
- **Locking in technology choices** before understanding the full context