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:

Context - Why this work is needed
Goals - What we're trying to achieve
Approach - How we'll implement it
Work Breakdown - Specific tasks and phases
Critical Files - Key files that will be modified
Verification - How to test the implementation
Dependencies - What needs to happen first
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

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