Planning and Specification Workflows

# Feature: User Password Reset

## Overview
Allow users to reset their password via email link.

## User Stories
- As a user, I want to reset my password if I forget it
- As a user, I want a secure process that expires old links

## Technical Requirements
- Password reset tokens expire in 1 hour
- One-time use tokens (invalidate after use)
- Rate limit: max 3 requests per hour per email
- Secure token generation (crypto.randomBytes)

## API Endpoints
POST /api/auth/forgot-password
- Input: { email: string }
- Output: { success: true } (always, to prevent email enumeration)

POST /api/auth/reset-password
- Input: { token: string, newPassword: string }
- Output: { success: boolean, error?: string }

## Database Changes
New table: password_reset_tokens
- id: uuid
- user_id: uuid (FK)
- token_hash: string
- expires_at: timestamp
- used_at: timestamp (nullable)

## Email Template
Subject: Reset your password
Body: Link expires in 1 hour, one-time use

## Security Considerations
- Hash tokens before storage
- Constant-time comparison for token validation
- Log all reset attempts for audit
- Don't reveal if email exists

## Edge Cases
- User requests multiple resets (invalidate old tokens)
- Token used twice (reject second use)
- Expired token (clear error message)
- Invalid token format (reject)

## Out of Scope
- Password strength requirements (handled by existing validation)
- Account lockout (separate feature)

I need to implement [feature description].

Help me create a detailed spec.md covering:
1. Overview and user stories
2. Technical requirements
3. API design (if applicable)
4. Database changes (if applicable)
5. Security considerations
6. Edge cases
7. What's out of scope

Context:
- Tech stack: [your stack]
- Existing patterns: [relevant patterns]
- Constraints: [any limitations]

Review this spec for completeness and potential issues:

[paste your spec]

Check for:
1. Missing requirements or edge cases
2. Security vulnerabilities
3. Scalability concerns
4. Unclear or ambiguous specifications
5. Potential implementation challenges

Suggest improvements for each issue found.

Play devil's advocate on this spec.

[paste spec]

Challenge:
1. Could this be simpler?
2. Are there requirements we don't actually need?
3. What could go wrong with this design?
4. What are we overcomplicating?
5. What's the MVP version?

I need to implement this feature:
[feature description]

Break this down into:
1. Discrete, atomic tasks (each completable in 1-2 hours)
2. Correct dependency order (what must come first)
3. Parallelizable tasks (what can be done simultaneously)
4. MVP tasks vs nice-to-haves

Format each task with:
- Clear deliverable
- Acceptance criteria
- Dependencies
- Estimated complexity (low/medium/high)

## Task Breakdown: User Dashboard

### Phase 1: Foundation (Sequential)
1. **Database schema for analytics**
   - Deliverable: Prisma migration with events table
   - Acceptance: Can store page views, actions
   - Dependencies: None
   - Complexity: Low

2. **Analytics tracking service**
   - Deliverable: Service that logs events
   - Acceptance: Events saved to database
   - Dependencies: Task 1
   - Complexity: Medium

### Phase 2: API Layer (Parallelizable after Phase 1)
3. **GET /api/dashboard/stats endpoint**
   - Deliverable: Returns aggregated stats
   - Acceptance: Returns counts, averages
   - Dependencies: Task 1, 2
   - Complexity: Medium

4. **GET /api/dashboard/activity endpoint**
   - Deliverable: Returns recent activity
   - Acceptance: Paginated activity list
   - Dependencies: Task 1, 2
   - Complexity: Low

### Phase 3: Frontend (Parallelizable)
5. **Dashboard layout component**
   - Deliverable: Grid layout with card slots
   - Acceptance: Responsive, matches design
   - Dependencies: None
   - Complexity: Low

6. **Stats cards components** (can parallel with 5)
   - Deliverable: Individual stat display cards
   - Acceptance: Shows loading, error, data states
   - Dependencies: Task 3
   - Complexity: Medium

### MVP (Tasks 1-3, 5-6)
### Nice-to-have: Task 4, additional chart types

I'm making an architecture decision and need to document it.

Decision: [what you're deciding]

Help me create an ADR (Architecture Decision Record) with:
1. Title
2. Status (proposed/accepted/deprecated)
3. Context (why we need to decide)
4. Decision (what we decided)
5. Consequences (pros, cons, trade-offs)
6. Alternatives considered

Context for my decision:
[provide your context]

# ADR-001: Use Redis for Session Storage

## Status
Proposed

## Context
Our application needs to store user sessions. Currently using
in-memory storage which doesn't work across multiple servers.

## Decision
Use Redis for session storage because:
- Supports our multi-server deployment
- Automatic expiration for session cleanup
- Familiar to the team
- Good ecosystem (connect-redis for Express)

## Consequences
### Positive
- Sessions persist across server restarts
- Works with load balancer
- Fast session lookup

### Negative
- Additional infrastructure to maintain
- Network latency for each request
- Need Redis monitoring

### Neutral
- Need to handle Redis connection failures gracefully

## Alternatives Considered
1. **Database sessions**: Rejected—too slow for every request
2. **JWT-only**: Rejected—can't invalidate sessions
3. **Memcached**: Rejected—Redis has better feature set

I need to build [component/feature].

Before coding, help me design it:

1. **Interface Design**
   - What props/inputs does it need?
   - What does it output/render?
   - What events does it emit?

2. **State Design**
   - What state does it manage?
   - What triggers state changes?
   - What are the possible states?

3. **Data Flow**
   - Where does data come from?
   - How does it transform?
   - Where does it go?

4. **Edge Cases**
   - What happens with no data?
   - What happens with lots of data?
   - What errors are possible?

Context: [your context]

Design an API for [feature].

Consider:
1. RESTful resource modeling
2. Endpoint naming and HTTP methods
3. Request/response schemas
4. Error handling approach
5. Authentication requirements
6. Pagination strategy
7. Rate limiting needs

Constraints:
- Must integrate with existing API at /api/v1/...
- Must support our standard error format
- Must be versioned