Project Planning

Create consistent, scannable project plan documents that focus on outcomes, guardrails, and implementation steps rather than verbose explanations or code examples.

When to Use This Skill

Create a plan document when:

• Implementing new features or systems
• Refactoring existing code
• Planning technical migrations
• Documenting architectural decisions
• User explicitly requests a "plan" or "plan document"

Do NOT create plans for:

• Simple, single-step tasks
• Exploratory analysis or research questions
• Quick bug fixes without architectural impact
• General documentation (use appropriate doc type instead)
• Feature tracking documents (use separate tracking doc, link in References)

Plan Document Structure

ALL plan documents MUST follow this exact structure:

# [Project Name]

## Overview

**Status:** [Draft/In Progress/Complete]
**Created:** [YYYY-MM-DD]
**Last Updated:** [YYYY-MM-DD]

[2-3 sentence description of what this plan accomplishes and why it matters]

## Goals

- [Primary goal 1]
- [Primary goal 2]
- [Primary goal 3]

## Non-Goals

- [What this plan explicitly does NOT cover]
- [Scope limitations]

## Success Criteria

- [Measurable outcome 1]
- [Measurable outcome 2]

## Constraints & Guardrails

**Technical Constraints:**

- [Constraint 1]

**Business Constraints:**

- [Constraint 2]

**Documentation Principle:**

- ⚠️ **CRITICAL**: After ANY significant code change, implementation, or refactoring, the plan MUST include explicit steps to identify and update affected markdown files, README files, and documentation
- This includes: component READMEs, feature docs in `/docs/features/`, architecture docs in `/docs/architecture/`, and project guidance files (CLAUDE.md, AGENTS.md)
- Documentation updates are not optional follow-ups; they are required completion steps

**Key Risks:**

- [Risk 1]: [Mitigation approach]

## Implementation Steps

[See Implementation Steps section below for detailed format]

## Phase Completion Summaries

[Added after each phase completes - see Phase Completion section below]

## Open Questions

- [ ] [Question 1]
- [ ] [Question 2]

## References

- [Related docs, tickets, or resources]

Implementation Steps Format

Implementation steps MUST follow these rules:

Step Numbering Rules

Simple projects (< 10 steps):

## Implementation Steps

1. [Step name]
2. [Step name]
3. [Step name]

Complex projects (10+ steps or logical groupings):

## Implementation Steps

### Phase 1: [Phase Name]

1. [Step name]
2. [Step name]
3. [Step name]

### Phase 2: [Phase Name]

4. [Step name]
5. [Step name]

CRITICAL RULES:

• ❌ NEVER use decimal numbering (1.1, 1.2, 2.1, etc.)
• ✅ Use sequential integers (1, 2, 3, 4...)
• ✅ Use phases ONLY to group related steps in large efforts
• ✅ Number sequentially across all phases (don't restart at 1)

Step Content Format

Each step should be concise and outcome-focused:

1. **[Action verb] [component/area]**
   - What: [One sentence describing what will be done]
   - Why: [Brief rationale if not obvious]
   - Considerations: [Guardrails, edge cases, or risks]
   - Dependencies: [What must be complete first, if any]

Example:

1. **Update authentication middleware**
   - What: Add JWT token validation to auth middleware
   - Why: Enable stateless authentication for API clients
   - Considerations: Maintain backward compatibility with session auth; validate token expiry
   - Dependencies: Step 3 (JWT utility functions must exist)

What to Include vs. Exclude

✅ DO Include:

• Desired outcomes - What the end state looks like
• Guardrails - Things that must NOT break or change
• Edge cases - Special conditions to handle
• Dependencies - Order of operations
• Risks - What could go wrong and how to mitigate
• Validation points - How to confirm success
• Brief rationale - Why this approach

❌ DO NOT Include:

• Code examples - Unless absolutely critical for understanding (rare)
• Verbose explanations - Keep descriptions to 1-2 sentences
• Implementation details - How to write specific functions
• Tutorial content - The plan is not a coding guide
• Multiple alternative plans - One clear plan per document
• Excessive detail - Focus on what and why, not how

Phase Completion Summaries

After completing each phase (or major milestone), add an executive summary:

## Phase Completion Summaries

### Phase 1 Complete (YYYY-MM-DD)

**Completed:**

- Added JWT authentication middleware
- Implemented token generation on login
- Updated user model with token fields

**Modified:**

- Changed login endpoint from session-based to hybrid (sessions + JWT)
- Reason: Maintain backward compatibility during migration

**Removed:**

- Deprecated old session validation helper functions
- Reason: Replaced by JWT validation

**Deviations from Plan:**

- Combined steps 2 and 3 as they shared implementation
- Added rate limiting to token endpoint (not originally planned but needed)

**Blockers/Issues:**

- None

Format rules:

• Keep each item to one line
• Include why for modifications/removals
• Note any deviations from original plan
• Document blockers even if resolved

File Location and Naming

ALL plan documents MUST:

• Be stored in /docs/ directory (create if it doesn't exist)
• Use lowercase kebab-case naming
• Have .md extension

Examples:

• ✅ /docs/authentication-refactor.md
• ✅ /docs/database-migration-plan.md
• ✅ /docs/api-v2-implementation.md
• ❌ /docs/Authentication_Refactor.md (wrong case)
• ❌ /docs/api_v2_plan.md (snake_case not kebab-case)
• ❌ /authentication-plan.md (not in /docs/)

Creating a Plan Document

Follow this workflow:

1. Confirm scope - Ensure the request warrants a plan document
2. Ask clarifying questions - Understand goals, constraints, context
3. Create document structure - Use the exact template above
4. Fill in sections - Focus on outcomes and guardrails
5. Review for violations - Check for code examples, decimal numbering, verbosity
6. Save to /docs/ with kebab-case name
7. Confirm with user - Show document location and ask if revisions needed

Updating Existing Plans

When asked to update a plan:

1. Read the existing plan from /docs/
2. Preserve structure - Keep the same format
3. Update relevant sections - Don't rewrite unnecessarily
4. Update "Last Updated" date
5. Save back to same location

Adding Phase Completion Summaries

When a phase is completed:

1. Read the plan from /docs/
2. Add new summary under "Phase Completion Summaries" section
3. Follow the exact format shown above
4. **Update "Last Updated" date
5. Save back to same location

Common Mistakes to Avoid

❌ Including multiple plan options

## Option 1: Microservices approach

## Option 2: Monolith approach

→ Present ONE recommended approach. Discuss alternatives with user first.

❌ Using decimal step numbering

1.1 Create database schema
1.2 Add migrations

→ Use sequential integers: 1, 2, 3

❌ Including code examples

3. Add validation function
   ```python
   def validate_user(user):
       if not user.email:
           raise ValueError()
   ```

→ Describe what the function should do, not how to write it

❌ **Overly verbose descriptions**
```markdown
1. Update the authentication middleware by first examining the current implementation, then identifying the areas that need modification, specifically focusing on...

→ Be concise: "Add JWT validation to authentication middleware"

❌ Phases without steps

### Phase 1: Setup

[No numbered steps]

→ Phases are only grouping mechanisms. Always include numbered steps.

Multi-Document Plans

If a project genuinely requires multiple documents:

• Create a main plan: /docs/project-name-overview.md
• Reference sub-plans: /docs/project-name-phase-1.md
• Keep each document focused on one aspect
• Link between documents in References section

Quality Checklist

Before finalizing any plan, verify:

• Document is in /docs/ directory
• Filename is lowercase kebab-case
• All required sections present
• Steps numbered sequentially (no decimals)
• No code examples (unless critically necessary)
• Descriptions are concise (1-2 sentences)
• Only ONE implementation approach
• Phases used only for large efforts
• Success criteria are measurable
• Constraints and guardrails identified

Example Plan

See below for a complete example following all guidelines:

# API Rate Limiting Implementation

## Overview

**Status:** Draft
**Created:** 2025-10-22
**Last Updated:** 2025-10-22

Implement rate limiting across all API endpoints to prevent abuse and ensure fair resource allocation. This will protect the system from excessive requests and improve reliability for all users.

## Goals

- Prevent API abuse through request rate limiting
- Protect backend resources from overload
- Maintain response times under load

## Non-Goals

- User quota management (separate billing concern)
- Rate limiting for internal services
- Geographic-based access restrictions

## Success Criteria

- 99.9% of legitimate requests complete successfully
- No successful DoS attacks in testing
- Response times remain under 200ms at 90th percentile

## Constraints & Guardrails

**Technical Constraints:**

- Must work with existing Redis infrastructure
- Cannot add more than 2ms latency to requests
- Must preserve existing API contracts

**Business Constraints:**

- Free tier: 100 requests/minute
- Paid tier: 1000 requests/minute

**Key Risks:**

- False positives blocking legitimate users: Mitigate with exponential backoff headers
- Redis failure causing cascading issues: Implement fallback to memory-based limiting

## Implementation Steps

### Phase 1: Core Infrastructure

1. **Add Redis rate limit counter**
   - What: Create Redis key structure for tracking request counts per user
   - Why: Centralized counting across all API servers
   - Considerations: Use sliding window algorithm to prevent boundary gaming
   - Dependencies: None

2. **Create rate limit middleware**
   - What: Add Express middleware to check and enforce limits
   - Why: Single enforcement point for all routes
   - Considerations: Must handle Redis failures gracefully; return 429 status with Retry-After header
   - Dependencies: Step 1

3. **Add rate limit headers**
   - What: Include X-RateLimit-\* headers in all API responses
   - Why: Help clients implement proper backoff strategies
   - Considerations: Include limit, remaining, and reset timestamp
   - Dependencies: Step 2

### Phase 2: Testing & Rollout

4. **Create rate limit test suite**
   - What: Add integration tests for various limit scenarios
   - Why: Ensure limits work correctly without blocking legitimate users
   - Considerations: Test boundary conditions, Redis failures, concurrent requests
   - Dependencies: Steps 1-3

5. **Enable shadow mode monitoring**
   - What: Log rate limit violations without enforcing
   - Why: Identify false positives before full enforcement
   - Considerations: Run for 1 week, analyze patterns
   - Dependencies: Steps 1-3

6. **Roll out to production**
   - What: Enable enforcement for all endpoints
   - Why: Protect production systems
   - Considerations: Start with paid tier (lower false positive risk), then free tier
   - Dependencies: Steps 4-5 complete with no major issues

## Phase Completion Summaries

[Will be added as phases complete]

## Open Questions

- [ ] Should websocket connections count against rate limits?
- [ ] How to handle rate limits for admin users?
- [ ] Should we implement per-endpoint limits or global only?

## References

- Existing Redis setup: `/docs/infrastructure/redis-architecture.md`
- API authentication docs: `/docs/api/authentication.md`