Plan Feature

• Break down into atomic, testable tasks
• Order tasks by dependencies
• Write the plan to the todo list using TodoWrite

Task Breakdown Structure

Backend Tasks (if applicable)

[ ] Define API contract (Commands/Events/Queries in api module)
[ ] Implement domain logic (aggregates, entities, value objects)
[ ] Create command/query handlers
[ ] Update read model projections
[ ] Add usecase tests for handlers
[ ] Add integration tests

Frontend Tasks (if applicable)

[ ] Design component structure
[ ] Implement state management (stores/hooks)
[ ] Create UI components
[ ] Wire up API integration
[ ] Add component tests

Cross-Cutting Tasks

[ ] Update shared types/contracts
[ ] Add documentation if needed
[ ] Verify build passes
[ ] Run full test suite

Analysis Guidelines

Questions to Answer

1. What problem does this solve? - Clear user value
2. Who is affected? - Which users/roles
3. What are the boundaries? - What's in/out of scope
4. What could go wrong? - Failure modes and mitigations
5. How will we know it works? - Testability criteria

Architecture Considerations

Domain Layer:

• New aggregates or entities needed?
• Changes to existing aggregate behavior?
• New domain events?

Application Layer:

• New commands or queries?
• Handler orchestration complexity?
• Transaction boundaries?

Adapter Layer:

• API endpoint changes?
• Persistence schema updates?
• External service integrations?

UI Layer:

• New pages or components?
• State management approach?
• User interaction flows?

File Naming Convention

Plans are saved to .claude/plans/<feature-slug>.md where:

• Feature slug is derived from the feature name
• Convert to lowercase
• Replace spaces and special characters with hyphens
• Remove consecutive hyphens

Examples:

• "Custom Voting Decks" → custom-voting-decks.md
• "Add User Authentication" → add-user-authentication.md
• "Fix Timer Bug" → fix-timer-bug.md

Output Format

Write the plan to the file using this structure:

# Feature: [Name]

> **Created**: [YYYY-MM-DD]
> **Status**: Draft | Approved | In Progress | Completed

## Summary
[1-2 sentence description of what this feature does]

## Affected Modules
- [ ] api (contracts)
- [ ] guessimate-lobby
- [ ] guessimate-session
- [ ] guessimate-ui

## Key Design Decisions
1. [Decision 1 with rationale]
2. [Decision 2 with rationale]

## Implementation Tasks
[Numbered list of specific, actionable tasks]

## Risks & Considerations
- [Risk 1]
- [Risk 2]

## Open Questions
- [Question needing user input]

Example

For a feature request like "Add ability to customize voting deck", the plan would be saved to .claude/plans/custom-voting-decks.md:

# Feature: Custom Voting Decks

> **Created**: 2026-01-02
> **Status**: Draft

## Summary
Allow lobby owners to create and select custom card decks for estimation sessions instead of using only the default Fibonacci sequence.

## Affected Modules
- [x] api (new commands/events for deck management)
- [x] guessimate-lobby (deck storage in lobby aggregate)
- [ ] guessimate-session (use selected deck)
- [x] guessimate-ui (deck configuration UI)

## Key Design Decisions
1. Store custom decks at lobby level (not user level) - simpler model, decks tied to where they're used
2. Provide preset templates (Fibonacci, T-shirt, Powers of 2) - quick setup for common cases
3. Validate deck has 2-15 cards - reasonable constraints

## Implementation Tasks
1. Add Deck value object with validation to api module
2. Add CreateCustomDeckCommand and DeckCreatedEvent to api
3. Implement deck storage in LobbyAggregate
4. Create DeckSelectionComponent in UI
5. Add deck preview functionality
6. Update session creation to use selected deck
7. Add usecase tests for deck commands
8. Add integration test for full flow

## Risks & Considerations
- Migration: existing lobbies need default deck assigned
- UI complexity: deck editor could become complex

## Open Questions
- Should decks be shareable between lobbies?