Feature Planning Best Practices

This guide provides detailed best practices for creating effective implementation plans.

Task Granularity

Right-Sized Tasks

Too Large:

"Implement user authentication system"
"Build the entire dashboard"
"Add social media integration"

Too Small:

"Import the uuid library"
"Add a single line of code"
"Create an empty file"

Just Right:

"Create User model with email, password hash, and timestamps"
"Implement JWT token generation and validation utility"
"Add login endpoint with rate limiting"
"Create protected route middleware"

Task Independence

Each task should be implementable without needing to switch context frequently:

Good:

#### Task 1: Database Schema
Create the `users` table with proper indexes and constraints.
Dependencies: None

#### Task 2: User Model
Implement the User model class with validation methods.
Dependencies: Task 1

#### Task 3: Auth Service
Create authentication service for login/logout operations.
Dependencies: Task 2

Avoid:

#### Task 1: Part 1 of User Authentication
Add some user fields...

#### Task 2: Part 2 of User Authentication
Finish the user fields from Task 1...

Specificity in Task Descriptions

Include File Paths

Vague: "Add the authentication logic"

Specific: "Add authentication logic in src/services/auth.py:45 following the pattern from src/services/session.py:23-67"

Provide Context

Vague: "Update the user handler"

Specific: "Update the user handler in api/handlers/user.py:120 to validate email format using the existing validators.email() utility. Follow the validation pattern from api/handlers/auth.py:89"

Specify Expected Behavior

Vague: "Add error handling"

Specific: "Add try/except block to catch DatabaseError and return 500 status with error message. Log the full exception using the existing logger instance. See similar handling in api/handlers/base.py:34"

Architecture Decision Documentation

Always explain why, not just what:

Good:

### Architecture Decisions

**Choice: JWT tokens over sessions**
- Rationale: API needs to be stateless for horizontal scaling
- Trade-off: Tokens can't be revoked until expiry (mitigated with 15min expiry)
- Implementation: Use existing `pyjwt` library already in project

**Choice: Bcrypt for password hashing**
- Rationale: Industry standard, already used in related project
- Configuration: Cost factor of 12 (matches security team guidelines)

Avoid:

### Architecture Decisions
- Using JWT
- Using Bcrypt

Dependencies and Ordering

Explicit Dependencies

#### Task 1: Create User Model
Dependencies: None

#### Task 2: Create UserRepository
Dependencies: Task 1 (needs User model definition)

#### Task 3: Implement Registration Endpoint
Dependencies: Task 1, Task 2

#### Task 4: Add Registration Tests
Dependencies: Task 3

Natural Ordering

Follow the natural flow of development:

Foundation first: Models, schemas, database
Core logic: Services, utilities, business logic
API layer: Endpoints, handlers, middleware
Frontend: UI components, state management
Integration: Connecting pieces
Testing: Comprehensive tests
Documentation: User guides, API docs

Edge Cases and Error Handling

Identify Early

For each task, consider:

What could go wrong?
What are the edge cases?
How should errors be handled?
What validation is needed?

Example:

#### Task 3: User Registration Endpoint

**Core functionality:**
- Accept email and password
- Validate input
- Create user record
- Return success response

**Edge cases to handle:**
- Email already exists → Return 409 Conflict
- Invalid email format → Return 400 with validation error
- Password too weak → Return 400 with requirements
- Database connection failure → Return 500, log error
- Rate limiting → Return 429 if >5 attempts/minute

**Validation:**
- Email: Valid format, max 255 chars, lowercase
- Password: Min 8 chars, must include number and special char

Testing Strategy

Test Coverage Planning

For each feature, identify:

Unit tests: Individual functions and methods
Integration tests: API endpoints, database operations
Edge case tests: Error conditions, boundary values
Security tests: Authentication, authorization, input validation

Example:

### Testing Strategy

**Unit Tests:**
- `test_hash_password()` - Password hashing utility
- `test_validate_email()` - Email validation
- `test_generate_jwt_token()` - Token generation

**Integration Tests:**
- `test_register_user_success()` - Happy path registration
- `test_register_duplicate_email()` - Duplicate prevention
- `test_login_with_valid_credentials()` - Authentication flow
- `test_login_with_invalid_credentials()` - Auth failure

**Security Tests:**
- `test_sql_injection_prevention()` - Input sanitization
- `test_rate_limiting()` - Brute force protection
- `test_password_strength_requirements()` - Password policy

Example: Complete Feature Plan

## Feature: User Profile Management

### Overview
Allow users to view and edit their profile information including name, bio, and avatar. Profiles are public but only editable by the owner.

### Architecture Decisions

**Choice: Store avatars in S3**
- Rationale: Existing S3 bucket and upload utilities available
- Location: Follow pattern from `src/utils/s3_upload.py`
- Size limit: 5MB (enforced in backend)

**Choice: Optimistic UI updates**
- Rationale: Better UX, matches existing patterns
- Rollback on error via Redux state management

### Implementation Tasks

#### Task 1: Extend User Model
- **File**: `src/models/user.py:23`
- **Description**: Add profile fields to User model
- **Details**:
  - Add fields: `bio` (text, max 500 chars), `avatar_url` (string, nullable)
  - Create migration for new fields
  - Add validation methods
- **Dependencies**: None
- **Reference**: See model pattern in `src/models/post.py:15-45`

#### Task 2: Create Profile API Endpoints
- **File**: `src/api/routes/profile.py` (new file)
- **Description**: Add GET and PATCH endpoints for profile
- **Details**:
  - `GET /api/users/:id/profile` - Public, anyone can view
  - `PATCH /api/users/:id/profile` - Protected, owner only
  - Authorization: Use existing `@require_auth` decorator
  - Validation: Bio max 500 chars, avatar_url is valid URL
- **Dependencies**: Task 1
- **Reference**: Follow pattern from `src/api/routes/posts.py:67-89`

#### Task 3: Avatar Upload Utility
- **File**: `src/services/avatar_service.py` (new file)
- **Description**: Handle avatar upload to S3 with validation
- **Details**:
  - Accept image files (jpg, png, gif)
  - Validate size (max 5MB)
  - Resize to 400x400px
  - Upload to S3 using existing `S3Upload` class
  - Return public URL
- **Dependencies**: None (can work parallel to Task 1-2)
- **Reference**: Use `src/utils/s3_upload.py` and `src/services/image_processor.py`

#### Task 4: Frontend Profile Component
- **File**: `src/components/Profile/ProfileView.tsx` (new file)
- **Description**: Display user profile information
- **Details**:
  - Show avatar, name, bio
  - Conditional "Edit" button if viewing own profile
  - Responsive layout
  - Loading and error states
- **Dependencies**: Task 2 (needs API)
- **Reference**: Similar layout to `src/components/Post/PostView.tsx`

#### Task 5: Frontend Profile Edit Component
- **File**: `src/components/Profile/ProfileEdit.tsx` (new file)
- **Description**: Edit profile with avatar upload
- **Details**:
  - Form with bio textarea, avatar file upload
  - Character counter for bio (500 max)
  - Image preview before upload
  - Optimistic updates on save
  - Validation and error display
- **Dependencies**: Task 3, Task 4
- **Reference**: Form pattern from `src/components/Post/PostEditor.tsx`

#### Task 6: Integration Tests
- **File**: `tests/integration/test_profile_api.py` (new file)
- **Description**: Test profile endpoints
- **Tests**:
  - View any user's profile (public)
  - Edit own profile (success)
  - Edit other's profile (forbidden)
  - Bio validation (too long)
  - Avatar upload (success and size limit)
- **Dependencies**: Task 1, Task 2, Task 3

#### Task 7: Frontend Tests
- **File**: `tests/components/Profile.test.tsx` (new file)
- **Description**: Test profile components
- **Tests**:
  - ProfileView renders correctly
  - Edit button shown for own profile only
  - ProfileEdit form validation
  - Avatar upload preview
  - Optimistic update behavior
- **Dependencies**: Task 4, Task 5

### Testing Strategy

**Unit Tests:**
- User model validation methods
- Avatar resizing logic
- S3 upload utility

**Integration Tests:**
- API endpoints (all success and error cases)
- Authorization (owner vs non-owner)
- End-to-end profile update flow

**Security:**
- Authorization enforcement (can't edit others' profiles)
- File upload validation (type, size)
- XSS prevention in bio field

### Integration Points

**Existing systems affected:**
- User model (extends with new fields)
- S3 bucket (shares with post images)
- Auth middleware (reuses existing decorators)

**New routes:**
- `GET /api/users/:id/profile`
- `PATCH /api/users/:id/profile`
- `POST /api/users/:id/avatar` (upload)

Anti-Patterns to Avoid

1. Over-Planning

Bad: Planning every single line of code, including variable names and exact syntax.

Good: Plan structure, key decisions, and task boundaries. Let implementer handle details.

2. Under-Planning

Bad: "Add user profiles" with no further detail.

Good: Break down into tasks with context, files, and acceptance criteria.

3. Ignoring Existing Patterns

Bad: Designing from scratch without checking the codebase.

Good: Reference existing code patterns and maintain consistency.

4. Skipping Edge Cases

Bad: Only planning the happy path.

Good: Explicitly call out error handling and validation for each task.

5. Creating Dependent Chains

Bad: Every task depends on the previous one, forcing strict sequential execution.

Good: Identify tasks that can be parallelized (e.g., backend and frontend utilities).

Checklist for a Good Plan

Before handing off to plan-implementer, verify:

Requirements are clearly understood
Architecture decisions are documented with rationale
Tasks are right-sized (30min - 2hrs each)
Each task has clear acceptance criteria
Dependencies are explicitly stated
File paths and code references are included
Edge cases and error handling are addressed
Testing strategy is defined
Follows existing project patterns (checked CLAUDE.md)
User has reviewed and approved the plan

11 KiB Raw Permalink Blame History