Plan

Technical Planning Skill

Create actionable implementation plans for features and tasks.

Name

han-core:plan - Create tactical implementation plan for a feature or task

Synopsis

/plan [arguments]

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