plan

name	plan
description	Explore a codebase and produce a detailed implementation plan before writing any code. Use when asked to plan a feature, think through an approach, or figure out how to implement something.

Planning

Do not write code. Do not modify files. Explore and think.

Step 1: Clarify the goal

Before exploring, make sure you understand what done looks like.

• What is the user trying to achieve?
• Are there constraints (must not break X, must stay compatible with Y)?
• Is there an existing pattern in the codebase to follow?

If the goal is ambiguous, use the questionnaire tool to ask.

Step 2: Explore the codebase

Use grep, find, read, and ls to understand the relevant code.

Find:

• The entry point or feature area affected
• Types and interfaces that the feature will touch
• Existing similar features to use as a model
• Tests that cover adjacent behavior

Take notes as you go. You will use these in the plan.

Step 3: Identify the approach

Before writing steps, decide on the approach:

• What is the minimal change that delivers the goal?
• Is there a simpler alternative worth mentioning?
• What are the main risks or unknowns?

Step 4: Write the plan

Goal

One sentence. What will be true when this is complete.

Approach

2-3 sentences explaining the strategy and why.

Steps

Numbered, ordered, atomic. Each step names the exact file and function to touch.

1. `src/types.ts` — Add `theme: 'light' | 'dark'` to the `UserPreferences` interface
2. `src/store/preferences.ts` — Update `savePreferences()` to persist the new field
3. `src/components/Settings.tsx` — Add a theme toggle that calls `savePreferences`
4. `src/components/App.tsx` — Read `preferences.theme` and apply a CSS class to the root element

Files to touch

• path/to/file.ts — what changes

New files needed

• path/to/new.ts — purpose (omit if none)

Risks

Specific things to be careful about. Name callers that could break, shared types that must stay compatible, performance implications.

Open questions

Anything that needs a decision before implementation can proceed.