implementation-planner

Overview

This skill provides structured approaches for creating comprehensive implementation plans, technical specifications, and architecture documentation. Used by architects to plan complex features, coordinate multi-domain work, and provide clear roadmaps for development teams.

When to Use This Skill

• Planning multi-phase features or projects
• Creating technical specifications for complex work
• Breaking down large initiatives into manageable tasks
• Coordinating work across multiple domains (frontend + backend + CMS)
• Documenting architecture decisions and technical approaches
• Providing implementation roadmaps for development teams

Implementation Plan Structure

Adapt sections based on project complexity - smaller projects need less formality, larger projects benefit from more thorough planning.

Basic Structure

# [Feature/Project Name] Implementation Plan

## Overview
- **Problem**: What problem are we solving and why?
- **Success Criteria**: What does "done" look like?
- **Users**: Who will use this and how?
- **Impact**: What's the expected benefit or outcome?

## Technical Approach
- **Architecture**: High-level design and key components
- **Technology Choices**: Key decisions and rationale
- **Data Models**: Important data structures or schema changes
- **Integrations**: External services, APIs, or dependencies
- **Trade-offs**: Technical decisions and their implications

## Implementation Plan

Break work into logical phases. Phase duration depends on project size:
- Small projects: Days
- Medium projects: Weeks
- Large projects: Sprints or months

### Phase 1: Foundation
**Goal**: Establish core structure and dependencies

**Tasks**:
- [ ] Task 1 (Complexity: Small, Assigned: Backend Developer)
- [ ] Task 2 (Complexity: Medium, Dependencies: Task 1)
- [ ] Task 3 (Complexity: Large, Assigned: Frontend Architect)

**Deliverables**: What's ready at end of this phase?

### Phase 2: Core Functionality
**Goal**: Implement primary features and workflows

**Tasks**:
- [ ] Feature implementation (Complexity: Large)
- [ ] Business logic (Complexity: Medium)
- [ ] Integration work (Complexity: Medium, Dependencies: Phase 1 complete)

**Deliverables**: What's working end-to-end?

### Phase 3: Polish & Deploy
**Goal**: Finalize, test, and prepare for production

**Tasks**:
- [ ] Error handling and edge cases (Complexity: Medium)
- [ ] Testing (E2E, integration, unit) (Complexity: Large)
- [ ] Documentation and deployment (Complexity: Small)

**Deliverables**: Production-ready feature

## Considerations

### Assumptions
- What are we taking for granted?
- What needs to be validated before starting?

### Constraints
- **Time**: Deadlines or timeline requirements
- **Budget**: Resource limitations
- **Technical**: Platform or technology limitations
- **Team**: Available developers and expertise

### Risks & Mitigations
- **Risk 1**: [What could go wrong] → **Mitigation**: [How to prevent or handle it]
- **Risk 2**: [Potential issue] → **Mitigation**: [Backup plan]

## Out of Scope

Features or improvements intentionally excluded:
- Future enhancements saved for v2
- Nice-to-have items not essential for MVP
- Related features that would expand scope

## Success Metrics

How will we measure success after implementation?
- Performance targets (response time, throughput)
- User metrics (adoption, satisfaction)
- Business metrics (conversion, efficiency)

Complexity Estimates

Use consistent complexity estimates across plans:

• Small (S): 1-2 hours, straightforward work, no unknowns
• Medium (M): 3-8 hours, some complexity or research needed
• Large (L): 1-3 days, significant complexity or multiple components
• Extra Large (XL): 4+ days, major feature or architectural change

Task Assignment Guidelines

When assigning tasks to agents:

Backend Work → @Backend API Developer

• API endpoints, business logic, database migrations

Frontend Architecture → @Frontend Architect

• Library design, major refactoring, architectural decisions

Frontend Implementation → @Frontend Developer

• UI components, features, E2E tests

CMS Planning → @Content Architect

• Payload CMS patterns, content architecture

Cross-Domain → @Project Architect

• Multi-domain coordination, architecture oversight

Examples for Different Project Sizes

Small Project (1-3 days)

# Add Export to CSV Feature

## Overview
- **Problem**: Users need to export event registrations as CSV
- **Success**: Download CSV with all registration data
- **Users**: Event administrators

## Approach
Add export endpoint and download button

## Tasks
1. Backend: CSV generation endpoint (M)
2. Frontend: Download button (S)
3. Testing: E2E test for export flow (S)

## Risks
- Large exports may timeout → Use streaming for 1000+ records

Medium Project (1-2 weeks)

# Implement Payment Integration

## Overview
[Full overview section]

## Technical Approach
- Vipps payment API integration
- Payment state management
- Webhook handling for async updates

## Implementation Plan

### Phase 1: Backend (3 days)
- [ ] Payment models and migrations (M)
- [ ] Vipps API client (L, @Backend Developer)
- [ ] Webhook endpoint (M)

### Phase 2: Frontend (2 days)
- [ ] Payment UI components (M, @Frontend Developer)
- [ ] Checkout flow (L, @Frontend Developer)
- [ ] Payment status display (S)

### Phase 3: Testing (2 days)
- [ ] E2E payment flow tests (L, @Frontend Developer)
- [ ] Integration tests (M, @Backend Developer)

## Considerations
[Full considerations section]

Large Project (4+ weeks)

# Multi-Tenant CMS Implementation

## Overview
[Comprehensive overview with business context]

## Technical Approach
- Payload CMS multi-tenant plugin
- Organization isolation at database level
- Shared and tenant-specific collections
- Access control per organization

## Implementation Plan

### Phase 1: Foundation (Week 1)
**Assigned**: @Project Architect, @Content Architect, @Backend Developer

[Detailed task breakdown]

### Phase 2: Core Collections (Week 2-3)
**Assigned**: @Content Architect, @Frontend Developer

[Detailed task breakdown]

### Phase 3: Access Control (Week 3-4)
**Assigned**: @Backend Developer, @Frontend Developer

[Detailed task breakdown]

### Phase 4: Testing & Migration (Week 4)
**Assigned**: All agents

[Detailed task breakdown]

## Considerations
[Comprehensive risk analysis, assumptions, constraints]

## Success Metrics
- Organizations can only access their own content
- Performance: <200ms for filtered queries
- Migration: Zero data loss from existing system

Best Practices

Planning Guidelines

1. Start with "why" - Clearly articulate the problem and expected outcome
2. Break down complexity - Divide large tasks into smaller, trackable units
3. Identify dependencies - Note what must happen before other work can start
4. Assign ownership - Clear accountability for each task or phase
5. Document decisions - Capture technical choices and reasoning
6. Plan for risks - Anticipate problems and define mitigations
7. Define "done" - Clear success criteria and deliverables

Common Pitfalls to Avoid

• ❌ Vague tasks without clear scope ("Improve performance")
• ❌ Missing dependencies causing blockers
• ❌ Unrealistic timelines without buffer for unknowns
• ❌ No assignment leading to confusion about ownership
• ❌ Skipping risk analysis and getting surprised later
• ❌ Planning in too much detail too far ahead (vs. adaptive planning)

Adaptive Planning

For longer projects:

• Plan Phase 1 in detail
• Plan Phases 2-3 at high level
• Refine later phases as you learn from earlier work
• Adjust based on actual complexity and findings

Integration with Eventuras Monorepo

Monorepo Considerations

When planning features in the Eventuras monorepo:

Cross-App Features:

• Identify which apps are affected (web, historia, api)
• Plan shared library extraction early if code will be reused
• Coordinate API contracts between frontend and backend

Library Design:

• Plan library APIs before implementation
• Consider future consumers beyond immediate need
• Document library usage patterns

Testing Strategy:

• E2E tests in apps/web-e2e for user flows
• Integration tests in apps/api/tests for backend
• Component tests for shared libraries

File Organization

Implementation plans should be stored:

• Multi-domain features: /docs/implementation-plans/[feature-name].md
• App-specific features: apps/[app]/docs/plans/[feature-name].md
• Library design: libs/[lib]/docs/design/[feature-name].md

Template Files

You can create reusable templates for common scenarios:

• small-feature-template.md - Simple feature additions
• api-integration-template.md - External service integrations
• library-design-template.md - New shared library planning
• migration-template.md - Data or system migrations

Collaboration

Implementation plans facilitate:

• Async communication - Team members can review and comment
• Progress tracking - Check off completed tasks
• Knowledge transfer - New team members understand decisions
• Retrospectives - Compare actual vs. planned complexity

---

This skill helps architects create clear, actionable plans that guide development teams from concept to completion.