Technical Planning (this skill):

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

Architecture Design (architecture-design skill):

Strategic: "How should the system be structured?"
High-level design decisions
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): Straightforward, minimal unknowns
M (Medium): Moderate complexity, some unknowns
L (Large): Complex or uncertain, multiple files

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?

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]

**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?

## 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 Principles

Good plans are:

Specific: Concrete steps, not vague ideas
Actionable: Each task can be started immediately
Ordered: Dependencies clear, sequence logical
Right-sized: Tasks are not too large
Testable: Success criteria for each task

Bad plans are:

Vague ("Make it better")
Missing dependencies ("Do A and B" when B depends on A)
Too large (one task = weeks of work)
Missing context (no reasoning for decisions)

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

BAD:

Add import statement on line 5
Declare variable on line 6
Call function on line 7


### Missing Dependencies

BAD: Task 1: Create UI Task 2: Create API (But UI depends on API contract)


### No Success Criteria

BAD: Task: Add validation (How do we know when it's done?)

GOOD: Task: Add validation

Email format validated
Required fields checked
Error messages displayed
Tests pass


## Adaptive Planning

**Plans are living documents:**
- Update as you learn
- Add newly discovered tasks
- Remove tasks that aren't needed
- Adjust estimates based on reality

**When to update plan:**
- Discovered new requirement
- Found existing code to reuse
- Identified additional complexity
- Changed approach

## Planning Checklist

Before finishing plan, verify:

- [ ] Goal is clear and specific
- [ ] Current state analyzed
- [ ] Approach is feasible
- [ ] Tasks are specific and actionable
- [ ] Dependencies are identified
- [ ] Success criteria defined for each task
- [ ] Testing strategy included
- [ ] Risks documented
- [ ] Out of scope explicitly stated

## Examples

When the user says:

- "How should I implement user authentication?"
- "Plan out the shopping cart feature"
- "What's the approach for migrating to the new API?"
- "Break down this Jira ticket into tasks"
- "Create a plan for adding dark mode"

## Integration with Other Skills

- Use **simplicity-principles** - Keep plan simple (KISS, YAGNI)
- Use **architecture-design** - For high-level structure decisions
- Use **test-driven-development** - Include testing in tasks
- Reference **solid-principles**, **structural-design-principles** for implementation guidance

## Remember

1. **Plans are guides, not contracts** - Adapt as you learn
2. **Start simple, add detail** - Don't over-plan
3. **Make tasks actionable** - Specific and testable
4. **Document decisions** - Explain the "why"
5. **Include testing** - How will we verify it works?

**A good plan makes it easy to start coding.**

plan

Technical Planning Skill

Name

Synopsis

Core Principle

Planning vs Architecture