plan

Implementation Planning Skill

Use this skill to transform an explicitly approved feature specification into a concrete plan.md containing ordered, traceable, implementation-ready tasks.

The outcome is a plan, not code. Optimize for clarity, traceability, completeness, and verifiability over speed or convenience.

Non-Negotiable Rules

• Follow the stages exactly in order.
• Do not skip, merge, or reorder stages.
• Do not proceed without an approved feature specification.
• Do not write implementation code.
• Do not include architecture designs, function signatures, schemas, new library choices, or tooling choices not already present in the repository.
• Do not invent file paths or system structure.
• Validate every file path against the repository, or explicitly mark it as a file creation task.
• Every task must trace back to the specification.
• Every task must include executable or directly observable verification.
• Do not automatically proceed to implementation after writing the plan.

Stage Checklist

Track progress internally and make the current stage clear in responses.

• Stage 1: Resolve context
• Stage 2: Read and anchor to spec
• Stage 3: Map the codebase
• Stage 4: Define tasks
• Stage 5: Write the plan
• Stage 6: Self-review
• Stage 7: Handoff

Stage 1: Resolve Context

Goal: Confirm the feature identity, approved spec, and target plan location.

Do:

• Identify the feature by slug, identifier, title, or user-provided path.
• Locate the corresponding feature specification using available repository tools.
• Verify the specification is approved. Look for explicit approval language, an approval status, or a clear user instruction identifying it as approved.
• Determine where plan.md should be written. Prefer the same directory as the approved specification unless the user explicitly provides another location.
• Check whether plan.md already exists at the target location.

If no approved specification exists:

• Refuse to proceed.
• Explain that planning requires an approved spec as the single source of truth.
• Ask the user to provide or approve a specification first.

If plan.md already exists:

• Ask the user whether to continue from it, overwrite it, or cancel.
• Do not proceed until the user gives explicit direction.

Do not:

• Infer approval from a draft-like document.
• Create a plan from a vague feature idea.
• Read unrelated project areas before the approved spec is identified.

Proceed to Stage 2 only after the approved spec and plan target are clear.

Stage 2: Read and Anchor to Spec

Goal: Treat the approved specification as the source of truth.

Analyze the specification in full and extract:

• Goals.
• Non-goals.
• Success criteria.
• Chosen approach.
• User experience or behavior requirements.
• Scope boundaries.
• Open questions.

Create an internal trace map from spec items to planning obligations. Every planning decision must map to one of these categories.

Rules:

• Do not introduce scope not present in the spec unless clearly labeled "Inferred" and necessary for planning.
• If an inferred item materially affects scope, ask the user before proceeding.
• Preserve non-goals as exclusion constraints.
• Carry unresolved open questions forward unless they block planning.

Proceed to Stage 3 only once the spec anchors are understood.

Stage 3: Map the Codebase

Goal: Identify real repository files and integration surfaces relevant to the approved spec.

Use available tools to inspect the repository. Prefer fast, targeted searches:

• Use file listing tools to identify candidate areas.
• Use text search to find related existing behavior, entry points, tests, and documentation.
• Read only files needed to understand relevant modules and integration surfaces.

Build a mental model of:

• Relevant modules.
• Entry points.
• Existing user-facing surfaces.
• Existing tests or verification patterns.
• Files that should be changed.
• Files that should be created.

Rules:

• Validate all existing file paths.
• Do not invent or assume file locations.
• If a needed file does not exist, identify the correct creation location based on observed repository structure.
• Do not use Git history as a source of truth unless the user explicitly asks.
• Do not plan against files that were not verified.

Proceed to Stage 4 only after file targets and creation targets are grounded in the repository.

Stage 4: Define Tasks

Goal: Break the work into discrete, atomic, commit-sized tasks.

Each task must include:

• Title: concise and intent-based.
• Spec Trace: the exact spec goal, success criterion, scope boundary, or open question the task supports.
• Scope: the bounded change area for this task.
• Files: validated existing paths and intentional new paths.
• Intent: what product-visible or repository-visible change should happen, not how to implement it.
• Dependencies: explicit references to earlier task numbers, or "None".
• Verification: a runnable command or directly observable check.
• Notes: optional, only for constraints or deferred questions.

Task quality rules:

• One task equals one logical change.
• Tasks must be independently verifiable when their dependencies are complete.
• Do not mix unrelated concerns.
• Do not create vague tasks or placeholders.
• Order tasks strictly by dependency.
• Maintain stable numbering for traceability.
• Keep verification realistic based on existing repository commands or observable checks.

Avoid vague language:

• Replace "handle logic" with the specific behavior the task must enable.
• Replace "update things" with named surfaces or files.
• Replace "make changes" with the intended outcome.

Proceed to Stage 5 only once all tasks are traceable, ordered, and verifiable.

Stage 5: Write the Plan

Goal: Produce the plan.md document.

Write plan.md at the target location identified in Stage 1. Use this exact structure, adapting only the bracketed content:

# Plan: [Feature Name]

## Overview

[Brief summary of the feature and planning approach.]

## Spec Anchors

- Goal: [spec goal]
- Non-goals: [spec non-goals]
- Success criteria: [spec success criteria]
- Chosen approach: [spec approach]
- Scope boundaries: [spec scope boundaries]

## Tasks

### Task 1: [title]

- Spec Trace: [spec anchor]
- Scope: [bounded task scope]
- Files:
  - [validated existing path]
  - [new path, marked "create"]
- Intent: [what changes, not how]
- Dependencies: None
- Verification: [runnable command or observable check]
- Notes: [optional]

### Task 2: [title]

- Spec Trace: [spec anchor]
- Scope: [bounded task scope]
- Files:
  - [validated existing path]
- Intent: [what changes, not how]
- Dependencies: Task 1
- Verification: [runnable command or observable check]

## Dependency Graph

[Optional. Include only if it clarifies ordering.]

## Open Questions

- [Only unresolved items that could not be clarified earlier.]

Plan writing rules:

• Keep the plan concrete and terse.
• Include enough context for another agent or engineer to execute the tasks without re-deciding scope.
• Do not include implementation code.
• Do not include hidden assumptions.
• Do not list files that were not validated or explicitly marked for creation.

Proceed to Stage 6 after writing the plan.

Stage 6: Self-Review

Goal: Validate the plan before handoff.

Review against the specification:

• Every goal is represented.
• Every success criterion is covered.
• Non-goals are respected.
• Scope boundaries are reflected.
• Open questions are preserved or resolved explicitly.

Review task quality:

• No vague language.
• No placeholders.
• Clear intent for every task.
• Each task is atomic and commit-sized.
• Dependencies reference valid task numbers.
• Verification is runnable or directly observable.

Review repository alignment:

• All existing file paths were verified.
• All new files are intentionally marked for creation.
• Planned work fits the observed repository structure.

If issues are found:

• Refine plan.md.
• Repeat the self-review.
• Continue only when the plan is internally consistent and grounded in the spec.

Stage 7: Handoff

Goal: Deliver the finalized plan and stop before implementation.

State that plan.md is ready for execution.

Summarize:

• Task count.
• Key dependencies.
• Any deferred questions.

Do not:

• Start implementing.
• Offer code.
• Expand into technical design beyond what the plan already contains.

Refusal and Clarification Rules

Refuse to plan when:

• No spec exists.
• The spec is not approved.
• The user asks to plan from a vague idea instead of an approved spec.

Ask for clarification when:

• Multiple approved specs match the identifier.
• The target plan.md already exists and overwrite behavior is unclear.
• An open question blocks task boundaries.
• A necessary planning assumption would materially change scope.

When clarification is required, ask the smallest useful question and recommend a default direction with reasoning.

Final Standard

The finished plan.md must be execution-ready: every task is grounded in the approved specification, mapped to verified files or intentional new files, ordered by dependency, scoped to one logical change, and paired with a clear verification step.