Write Plan

Write Plan

Overview

Produce a complete, self-contained implementation plan that can be executed by execute-plan with minimal ambiguity, even in a fresh context or by another agent.

This skill is for planning only:

• Do not implement code
• Do not modify production files (except plan artifacts)

Workflow

Step 1: Contextualize

Load only the project context relevant to the requested change:

• If docs/SUMMARY.md exists, read it first.
• Load only task-relevant detail docs.
• Prioritize Code Standard docs for implementation conventions.
• If docs conflict with code or user intent, use the available input/question tool before broad changes.

Then inspect only the code areas relevant to the requested change.

Capture:

• User-visible purpose and expected outcome
• Existing patterns to follow
• Constraints and dependencies
• Files, modules, commands, and docs that orient the executor
• Risks, assumptions, and unknowns

Step 2: Clarify Requirements

Ask clarifying questions to resolve any ambiguity in the request. Focus on:

• Scope and boundaries
• Success criteria
• Constraints and non-goals
• Priorities and trade-offs

Rules:

• If requirements are already clear or come from the brainstorm context, no need the confirmation step.
• Use input/question tool for gathering answers, context.
• If multiple interpretations of the request exist, list them and ask — never pick silently.
• Record assumptions later in SUMMARY.md once plan artifacts exist.

Step 3: Initialize Plan Artifacts

1. Create: docs/.plans/YYMMDD-HHmm-<plan-slug>/ 2. Create:

• SUMMARY.md
• one phase file per implementation phase with naming convention phase-XX-<name>.md

3. Add research/ only if needed.

Rules:

• Use timestamp commands from the shared General Principles for folder and document timestamps.

Step 4: Define Strategy and Phases

Design a phased strategy that is safe and verifiable.

Each phase should have:

• A clear objective
• The complexity and risk level appropriate to the phase with values: S, M, L, XL
• Ordered tasks
• Verification commands
• Observable acceptance criteria and exit criteria

Granularity rule:

• Tasks should be small, concrete, independently verifiable, and large enough to avoid noisy micro-steps.
• Prefer phases that can be resumed safely. Document idempotency, recovery notes, or rollback constraints for risky work.

Step 5: Research (Only if Needed)

Research is optional and should be proportional to uncertainty.

Preferred order:

1. Existing project docs and code 2. Existing skills and local references 3. External references (only if available in the current environment)

If external research capability is unavailable, proceed with local evidence and explicitly list assumptions and open questions.

Document findings in:

• docs/.plans/YYMMDD-HHmm-<plan-slug>/research/<topic>.md

Step 6: Write Plan Content

SUMMARY.md format

Follow the template inside references/summary-template.md

The summary must be a living plan, not a static proposal. Include empty sections for execution-time updates: progress, surprises/discoveries, decision log, and outcomes/retrospective. These sections give execute-plan a stable place to record what changed and why.

phase-XX-<name>.md format

Follow the template inside references/phase-template.md

Step 7: Review and Refine

Before presenting the plan, verify:

• Paths are exact and consistent
• Phase order is logical
• Tasks are actionable (no vague steps)
• Verification is defined for each phase
• Acceptance criteria are observable
• Risks/assumptions are explicit
• Plan is executable without hidden context from the current chat

Then present for user review.

If multiple viable approaches exist, present options and ask for one of: (use input/question tool for selection)

• Confirm: approve current plan for execution
• Confirm and Visualize: approve current plan and create a source-adjacent visualization in the same session
• Validate: refine via additional clarifying questions

If the user chooses Confirm and Visualize:

1. Use the current write-plan session context and the plan artifacts just created. 2. Do not restart project context loading or rediscover background that is already available in the session. 3. Follow the visualize skill output convention for plan folders:

• docs/.plans/YYMMDD-HHmm-<plan-slug>/visualize.html
• docs/.plans/YYMMDD-HHmm-<plan-slug>/visualize-assets/

4. Copy the fixed visualization theme into the adjacent assets folder. 5. Verify the visualization enough to confirm the HTML, local CSS link, Mermaid import, source metadata, and primary content blocks are present. 6. Then continue to the normal handoff.

Step 8: Handoff

End with:

Plan <relative_path_to_plan>/SUMMARY.md is ready. Make new session and use execute-plan <relative_path_to_plan>/SUMMARY.md to execute it.

If visualization was created, also include:

Visualization <relative_path_to_plan>/visualize.html is ready.

Rules

• Never automatically implement or execute the code change in the same session. Optional plan visualization is allowed only after user selection and only for the plan artifacts.
• Prefer explicit file paths and concrete commands
• Align with project standards and existing architecture
• Keep plans self-contained, deterministic, and resumable. A fresh agent should be able to continue from the plan folder alone.
• Plan the minimum viable change: No speculative phases, no "just in case" abstractions, no flexibility that wasn't requested. If a plan can be 3 phases instead of 6, make it 3. Every task should trace directly to a stated requirement.
• If the write-plan request comes from a brainstorm session, we can skip many steps like gathering documents, clarifying requirements, and researching, because those should have been covered in the brainstorm session. In that case, confirm the brainstorm context is sufficient, initialize plan artifacts, then continue from Step 4: Define Strategy and Phases.

Phase XX: <Name>

Objective

• Specific result for this phase.

Scope

• Files/modules this phase may touch:
• Files/modules this phase must not touch:

Preconditions

• What must already be true.

Tasks

1. Context: files/components to inspect or modify 2. Implement: concrete change steps, grouped into meaningful units 3. Verify: commands/checks to run 4. Confirm: expected observable outcome

Acceptance Criteria

• User-visible or system-observable result:
• Required changed files:
• Required unchanged behavior:

Verification

• Commands:
• <command 1>
• <command 2>
• Expected results:
• <result>
• Evidence to record in SUMMARY.md:
• <short command result, manual observation, or artifact path>

Idempotence and Recovery

• Safe to re-run:
• Recovery if interrupted:
• Rollback notes:

Exit Criteria

• Clear checklist that determines completion.

Implementation Plan: <Title>

Created: YYYY-MM-DD HH:mm:ss

Purpose / Big Picture

• User-visible outcome in 1-3 sentences.
• Why this change matters now.
• Link to brainstorm artifact if applicable. Eg: Brainstorm artifacts

Objective

• What is being built/changed and why.

Context and Orientation

• Relevant docs loaded:
• Relevant files/modules:
• Existing patterns to follow:
• Constraints, dependencies, and compatibility notes:

Scope

In scope

Out of scope

Architecture & Approach

• Design decisions and rationale.
• Constraints and compatibility notes.

Progress

• [ ] Plan approved for execution.
• [ ] Phase 1 pending.
• [ ] Final verification pending.

Phases

• [ ] Phase 1 [<complexity rate>]: <name> — <goal>
• [ ] Phase 2 [<complexity rate>]: <name> — <goal>

Key Changes

• Files/modules likely to change
• Data/API/schema impacts

Validation and Acceptance

• Lint/typecheck/tests/build commands
• Manual checks if needed
• Observable acceptance criteria:

Idempotence and Recovery

• Safe re-run notes:
• Rollback/recovery notes:
• Irreversible operations or destructive steps:

Dependencies

• New packages/tools (if any) with reason

Risks & Mitigations

• Risk → mitigation

Surprises & Discoveries

• Record execution-time findings that affect the plan.
• If none yet: None yet.

Decision Log

• YYYY-MM-DD HH:mm:ss — Decision: <decision>. Rationale: <why>.
• If none yet: None yet.

Outcomes & Retrospective

• To be completed by execute-plan after final verification.
• Include final result, verification summary, deviations, and follow-ups.

Open Questions

• Items requiring user confirmation