plan

name	plan
version	1.0.0
description	This skill should be used when the user asks to explore a codebase and design implementation plans without making any changes. Trigger when users say 'plan how to implement X', 'design an approach for Y', 'explore the codebase before changing Z', 'create an implementation strategy', 'analyze how to refactor X', 'map out dependencies for Y', 'I want a plan before we start coding', 'plan to fix issue
metadata	{"mode":"read-only"}

Plan Mode: Read-Only Codebase Exploration and Implementation Design

CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS

This is a read-only planning task. Make no file modifications of any kind — no creating, editing, deleting, moving, or copying files. No package installs. No git state changes. No redirect operators or heredocs that write to disk. Explore using only: grep, ls, read_file, glob, task or bash (for read-only operations only eg. git status, git log, git diff, etc.).

Focus EXCLUSIVELY on exploring the codebase and designing implementation plans. The deliverable is a plan document, not code changes.

NEVER invoke other skills (via the skill tool) during this planning session. If the task or issue references a skill (e.g., "use /init", "run /security-audit"), include it as a step in the plan rather than executing it.

---

Step 1: Assess Complexity

Before exploring, determine which tier the task falls into. This drives how much effort to invest.

Tier	Scope	Plan Length
Simple	< 1 hour — bug fix, CSS tweak, copy change, single validation	A few paragraphs
Medium	1 hour–1 day — new form field, search filter, component refactor	1–3 pages
Complex	Multi-day — auth system, major refactor, migration, new service	Multiple pages

Guiding principle: Provide enough detail for confident implementation, but no more. Reserve comprehensive documentation for genuinely complex changes.

---

Step 2: Explore the Codebase

Scale exploration effort to complexity.

If the request references a platform issue or merge request (for example #123, !456, or an issue/PR URL), fetch the full issue or merge request details from the Git platform tools before drafting the plan.

Simple tasks: Read the specific files that need to change. Run a few targeted greps to verify the change fits existing patterns.

Medium tasks: Trace through relevant code paths. Identify integration points and component dependencies.

Complex tasks: Conduct thorough reconnaissance before designing anything.

• Review all files mentioned in the prompt first
• Map project structure: modules, config files, build system, key dependencies
• Trace data flow end-to-end (entry → transformation → persistence)
• Use parallel tool calls to explore independent areas simultaneously (e.g., frontend and backend at the same time)
• Identify existing patterns — naming conventions, architectural style, error handling, testing approach
• Look for similar features already implemented that can serve as templates

Exploration techniques (all tiers):

• Use the task tool with subagent_type=explore to investigate the codebase efficiently
• git log --follow <file> surfaces intent behind existing decisions
• Stay focused — use grep and glob deliberately, don't explore unrelated code

---

Step 3: Design the Solution

For All Tasks:

• Consider how the change fits existing patterns
• Think through edge cases
• Plan for appropriate testing

For Medium/Complex Tasks:

Architectural Analysis:

• Evaluate multiple implementation approaches
• Consider trade-offs between different designs
• Assess impact on existing components
• Identify integration points with current codebase
• Plan for backwards compatibility where needed

Pattern Alignment:

• Follow established patterns in the codebase
• Justify deviations from existing patterns when necessary
• Ensure consistency with project conventions
• Respect architectural boundaries and separation of concerns

Risk Assessment (Complex Tasks Only):

• Identify potential challenges and blockers
• Note areas requiring special attention
• Flag dependencies on external systems or teams
• Consider edge cases and error scenarios
• Anticipate testing challenges

---

Step 4: Write the Plan

Use the format that matches complexity. See examples/ for worked samples.

HARD CONSTRAINT: Output the plan directly — no preamble, no transition sentences. Start immediately with the plan heading.

HARD CONSTRAINT: Keep code minimal. Plans should describe what to change and where, not provide ready-to-paste implementations. Use short pseudo-code or 2–3 line snippets only when the approach would be ambiguous without them. Save full code for the implementation phase.

Simple Format

# [Brief Title]

## What's Changing
[1–2 sentence description]

## Changes
- `path/to/file.js` (line ~45) — [what changes]
- `path/to/test.js` — [add test for...]

## Notes
- [Key consideration or edge case]

Medium Format

# [Title]

## Overview
[Problem and solution summary]

## Changes
1. **[Step description]** — [purpose]
   - `file1.js` (line ~N) — [what changes]
   - `file2.js` — Create — [what to add]

2. **[Step description]** — [purpose]
   - `file3.js` — [what changes]

## Testing
[What to test and how]

## Edge Cases
[Scenarios to handle]

Complex Format

Use the template in references/complex-plan-template.md.

---

Plan Quality Checklist

Simple: Change is clearly located. Key considerations noted. Concise — don't over-explain obvious steps.

Medium: Logical change sequence. Each step lists the files it touches. Testing approach defined. Edge cases and dependencies noted.

Complex: Problem statement and objectives clear. Architectural overview provided. Each phase lists steps with their files inline. Implementation sequence is logical. Dependencies, config, and environment changes identified. Testing strategy defined. Edge cases and error handling addressed. Trade-offs and risks discussed.