name	technical-planning
description	Use when creating implementation plans for features or tasks. Focuses on tactical execution planning with clear tasks, dependencies, and success criteria.
allowed-tools	Read, Grep, Glob, Bash

Technical Planning Skill

Create actionable implementation plans for features and tasks.

Core Principle

A good plan turns a vague goal into concrete, executable steps.

Planning vs Architecture

Technical Planning (this skill):

Tactical: "How do I build feature X?"
Specific implementation steps
Days to weeks of work
Breaks work into tasks
Focuses on execution

Architecture Design (architecture-design skill):

Strategic: "How should the system be structured?"
High-level design decisions
Weeks to months of impact
Defines components and patterns
Focuses on structure

Use planning for:

Implementing specific features
Breaking down work into tasks
Sequencing implementation steps
Estimating complexity

Use architecture for:

Designing new systems
Major refactors
Technology choices
Long-term strategy

The Planning Process

1. Understand Requirements

Clarify what success looks like:

What exactly needs to be built?
What problem does it solve?
What are the acceptance criteria?
What's in scope vs out of scope?

Ask questions:

Who will use this?
What's the expected behavior?
What edge cases should be handled?
Are there performance requirements?
Security concerns?

2. Analyze Current State

Understand what exists:

What code is already there?
What patterns are in use?
What can be reused?
What needs to change?

Research:

# Find similar implementations
grep -r "similar_pattern" .

# Find related files
find . -name "*related*"

# Check existing tests
grep -r "test.*similar" test/

3. Break Down Into Tasks

Good tasks are:

Specific: "Add user authentication" ❌ → "Create login API endpoint" ✅
Testable: Clear success criteria
Right-sized: Hours to days, not weeks
Independent (when possible): Can be done in any order
Ordered (when dependencies exist): Clear sequence

Task template:

### Task: [Specific deliverable]

**What:** [Concrete description]
**Why:** [Reasoning for this approach]
**Dependencies:** [None, or list of task numbers]
**Complexity:** S | M | L
**Success criteria:**
- [ ] Criterion 1
- [ ] Criterion 2

**Files affected:**
- `path/to/file1.ts`
- `path/to/file2.ts`

**Testing approach:**
[How to verify this works]

4. Identify Dependencies

Task dependencies:

Blocks: Task A must finish before Task B starts
Blocked by: Task B can't start until Task A finishes
Related: Tasks that should coordinate

Example:

Task 1: Create database schema (no dependencies)
Task 2: Create API endpoint (depends on Task 1)
Task 3: Create UI component (depends on Task 2)
Task 4: Add tests (depends on Tasks 1-3)

Parallel vs Sequential:

Can be parallel:
  Task A: Frontend component
  Task B: Backend API
  (If API contract is defined)

Must be sequential:
  Task 1: Database migration
  Task 2: Update queries to use new schema
  (Task 2 depends on Task 1)

5. Estimate Complexity

Use relative sizing, not time:

S (Small): 1-4 hours, straightforward
M (Medium): 4-8 hours, moderate complexity
L (Large): 1-2 days, complex or uncertain

If task is > L: Break it down further

Complexity factors:

How well-understood is the requirement?
How many unknowns?
How many files need changes?
Integration complexity?
Testing complexity?

Examples:

S: Add validation rule to existing form
M: Create new API endpoint with tests
L: Implement new payment provider integration

6. Define Testing Strategy

How will we verify it works?

Unit tests for business logic
Integration tests for API endpoints
E2E tests for user workflows
Manual testing steps

Example:

## Testing Strategy

**Unit tests:**
- Test validation logic
- Test calculation functions
- Test error handling

**Integration tests:**
- Test API endpoint with real database
- Test with various input scenarios
- Test error responses

**E2E tests:**
- User can complete full workflow
- Error messages display correctly
- Success case works end-to-end

**Manual testing:**
- [ ] Test in Chrome
- [ ] Test in Firefox
- [ ] Test on mobile

Plan Document Structure

# Implementation Plan: [Feature Name]

**Created:** YYYY-MM-DD
**Estimated complexity:** S | M | L | XL
**Status:** Draft | Approved | In Progress | Complete

## Goal

[One paragraph: What are we building and why?]

## Current State

[What exists today that's relevant to this plan?]
[What needs to change?]
[What can be reused?]

## Proposed Approach

[High-level strategy: How will we build this?]
[Key technical decisions made]
[Alternatives considered and why not chosen]

## Tasks

### Phase 1: Foundation

#### Task 1.1: [Specific deliverable] (Complexity: S)

**What:** [Concrete description of what needs to be built]

**Why:** [Reasoning for this approach]

**Dependencies:** None

**Success criteria:**
- [ ] Criterion 1 (testable)
- [ ] Criterion 2 (testable)
- [ ] All tests pass

**Files affected:**
- `src/components/Feature.tsx` (create)
- `src/types/feature.ts` (update)

**Testing approach:**
- Unit test for component logic
- Integration test for data flow

---

#### Task 1.2: [Next task] (Complexity: M)

**What:** [Description]

**Why:** [Reasoning]

**Dependencies:** Task 1.1

**Success criteria:**
- [ ] Criterion 1
- [ ] Criterion 2

**Files affected:**
- `api/routes/feature.ts` (create)

**Testing approach:**
- Integration test for API endpoint

---

### Phase 2: Integration

[Additional tasks organized by phase]

## Testing Strategy

**Overall approach:**
[How we'll verify the entire feature works]

**Test coverage goals:**
- Critical paths: 100%
- Happy paths: 100%
- Edge cases: 80%

## Risks & Considerations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Database migration fails | High | Test in staging first, have rollback plan |
| API performance slow | Medium | Add caching, monitor metrics |

## Out of Scope

**Explicitly NOT included in this plan:**
- [Feature A - deferred to v2]
- [Integration B - separate work]
- [Optimization C - premature]

## Open Questions

- [ ] Should we use library X or Y?
- [ ] What's the rate limit for the external API?
- [ ] Do we need to support IE11?

## Success Metrics

**How we'll know this is successful:**
- Feature ships to production
- All tests pass
- Performance meets requirements (< 200ms response)
- Zero critical bugs in first week

## References

- [Related documentation]
- [Design mockups]
- [API specifications]
- [Similar implementations]

Task Breakdown Strategies

By Layer

Frontend tasks:
- Task 1: Create UI component
- Task 2: Add form validation
- Task 3: Connect to API

Backend tasks:
- Task 4: Create API endpoint
- Task 5: Add business logic
- Task 6: Database queries

Infrastructure:
- Task 7: Update deployment config

By Feature Slice

User Authentication (vertical slice):
- Task 1: Login form (frontend)
- Task 2: Login API (backend)
- Task 3: Session management
- Task 4: E2E test for login flow

Password Reset (vertical slice):
- Task 5: Password reset form
- Task 6: Password reset API
- Task 7: Email notification
- Task 8: E2E test for reset flow

By Priority

Must Have (P0):
- Task 1: Core functionality
- Task 2: Critical path

Should Have (P1):
- Task 3: Nice to have feature
- Task 4: Enhancement

Could Have (P2):
- Task 5: Polish
- Task 6: Optimization

Planning Best Practices

Start Simple

Don't over-plan:

Start with high-level tasks
Add detail as you learn
Plans evolve during implementation

Good enough:

Plan should be clear enough to start
Not every detail needs to be known upfront
Iterate as you go

Make Tasks Actionable

Bad task:

- Improve performance

Good task:

### Task 3: Optimize database queries (Complexity: M)

**What:** Add indexes to users table for email and created_at columns

**Success criteria:**
- [ ] Query time reduced from 500ms to < 50ms
- [ ] Migration runs successfully
- [ ] No impact on existing queries

Document Decisions

Why matters:

## Why this approach?

We chose REST over GraphQL because:
1. Team is more familiar with REST
2. Simple CRUD operations don't need GraphQL flexibility
3. Can add GraphQL later if needed

**Trade-off:** Less flexible, but simpler to implement

Include Examples

Show, don't just tell:

## API Design

### Endpoint: POST /api/users

**Request:**
```json
{
  "email": "user@example.com",
  "name": "John Doe"
}

Response:

{
  "id": "123",
  "email": "user@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-01T00:00:00Z"
}


## Common Planning Mistakes

### ❌ Too Vague

BAD:

Implement user system
Add features
Make it work


### ❌ Too Detailed