Technical Planning

Core Principles

Focus on "What" Not "How": Define deliverable outcomes, not implementation details.

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.

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 (avoid sub-task details)

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

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
• 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