# [Feature Name] Implementation Plan

**Date**: YYYY-MM-DD

## Overview

[Brief description of what we're implementing]

## Related

- Spec: `specs/XX_feature.feature` (if applicable)
- Research: `research/YYYY-MM-DD-topic.md` (if applicable)
- Related issues/tickets: [references]

## Current State

[What exists now, what's missing, what needs to change]

## Desired End State

[What will exist after implementation]

**How to verify:**
- [Specific verification steps]
- [Expected behaviors]

## Out of Scope

[What we're explicitly NOT doing to prevent scope creep]

## Risks & Mitigations

[Identified risks and how we'll handle them]

## Phase 1: [Name]

### Changes Required

**File: `path/to/file.ext`**
- Changes: [Specific modifications needed]
- Tests: [What tests to write first (TDD)]

**File: `another/file.ext`**
- Changes: [Specific modifications needed]
- Tests: [What tests to write first (TDD)]

### Implementation Approach

[How we'll implement this phase - key decisions, patterns to use]

### Success Criteria

#### Automated:
- [ ] Tests pass: `npm test` (or relevant command)
- [ ] Type checking passes (if applicable)
- [ ] Linting passes (if applicable)
- [ ] Build succeeds (if applicable)

#### Manual:
- [ ] [Specific manual verification step 1]
- [ ] [Specific manual verification step 2]

### Dependencies

[Any dependencies on other work or external factors]

---

## Phase 2: [Name]

[Continue with same structure for each phase]

---

## Testing Strategy

**Following TDD:**
1. Write tests first for each behavior
2. Watch tests fail (Red)
3. Implement minimal code to pass (Green)
4. Refactor while keeping tests green

**Test types needed:**
- Unit tests: [What to unit test]
- Integration tests: [What integration scenarios]
- E2E tests: [If applicable]

## Rollback Strategy

[How to safely rollback if something goes wrong]

## Related Links

- [Related documentation]
- [Similar implementations in the codebase]
- [External resources]

User: Create a plan for implementing user authentication based on specs/auth.feature

Agent: I'll create an implementation plan for user authentication. Let me first read the spec and research the codebase.

[Reads spec file, searches for existing auth patterns, creates todo list]

Agent: Based on the spec and codebase research, I see we need JWT-based authentication. I found existing patterns in the API middleware that we should follow. I'll create a 3-phase plan:

Phase 1: JWT token validation
Phase 2: Authentication middleware
Phase 3: Protected route integration

[Creates plan file at plans/2026-01-12-user-authentication.md]

Here's the plan I've created: [summarizes key points]

The plan follows our existing API patterns and includes TDD approach. Any feedback before we proceed?

User: I need to add pagination to the user list endpoint

Agent: I'll create a plan for adding pagination. What would you like me to document?

Let me research the codebase first to understand:
1. How other endpoints handle pagination
2. Current user list implementation
3. Database query patterns

[Creates todo list, researches in parallel]

Agent: I found that other endpoints use cursor-based pagination with the pattern from utils/pagination.ts.

I have two design options:

**Option 1: Cursor-based (Recommended)**
- Pros: Consistent with existing endpoints, handles large datasets well
- Cons: Slightly more complex client implementation

**Option 2: Offset-based**
- Pros: Simpler client implementation
- Cons: Performance issues with large offsets, inconsistent with our patterns

I recommend Option 1 for consistency. Shall I proceed with that approach?

[After confirmation, creates detailed plan]

User: Create a plan for real-time notifications

Agent: Real-time notifications is a complex feature. Before I can create a detailed plan, I need to research several technical decisions:

1. Transport mechanism (WebSockets, SSE, polling?)
2. Current infrastructure capabilities
3. Scalability requirements
4. Client-side integration points

Let me research these first, then I'll present options and create the detailed plan. [Uses research command or explores]

[After research, presents 2-3 options with tradeoffs, gets alignment, then creates detailed plan]