Plans Directory

This directory contains forward-looking implementation plans, roadmaps, and architectural decisions.

Purpose

Plans document what to do next, while worklogs document what was done:

• Plans → Future work, implementation strategy, roadmaps
• Worklogs → Historical record, outcomes, what was completed

Naming Convention

YYYY-MM-DD_{FEATURE}_plan.md

Examples:

• 2026-02-06_12-week-roadmap.md - Multi-week development roadmap
• 2026-02-10_mobile-app_plan.md - Implementation plan for mobile app
• 2026-03-01_api-refactor_plan.md - API refactoring strategy

When to Create a Plan

Create a plan document when:

• ✅ Starting major feature work (multiple PRs, weeks of effort)
• ✅ Making architectural decisions that affect multiple areas
• ✅ Planning multi-week or multi-month roadmaps
• ✅ Designing complex system interactions

Don't create a plan for:

• ❌ Simple bug fixes or single-file changes
• ❌ Routine maintenance tasks
• ❌ Work that's already documented in issues

Plan Structure

A good plan should include:

1. Context - Why this work is needed
2. Goals - What we're trying to achieve
3. Approach - How we'll implement it
4. Work Breakdown - Specific tasks and phases
5. Critical Files - Key files that will be modified
6. Verification - How to test the implementation
7. Dependencies - What needs to happen first
8. Timeline - Estimated duration

Keeping Plans Current

Plans are living documents:

• ✅ Update as priorities shift
• ✅ Mark sections complete as work progresses
• ✅ Add "Status" and "Last Updated" fields
• ✅ Archive or mark as "Superseded" when outdated

Related Documentation

• ../worklog/ - Historical record of completed work
• ../engineering/guides/DIRECTORY_DEFINITIONS.md - Codebase structure guide
• ../../CLAUDE.md - Project guidelines for Claude Code