write-plan

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

Create detailed, execution-ready implementation plans for complex or high-risk changes without coding. Use when scope is large, requirements are mostly known, and work should be broken into validated phases before execution.

3installs

Sourcebuiducnhat/agent-skills

Added on2026-03-01

NPX Install

npx skill4agent add buiducnhat/agent-skills write-plan

SKILL.md Content

View Translation Comparison →

Write Plan

Overview

Produce a complete, self-contained implementation plan that can be executed by

execute-plan

with minimal ambiguity.

This skill is for planning only:

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

Artifact Conventions

Use one consistent artifact structure for every plan:

Plan directory:
```
docs/plans/YYMMDD-HHmm-<plan-slug>/
```

Main summary:

docs/plans/YYMMDD-HHmm-<plan-slug>/SUMMARY.md

Phase files:

docs/plans/YYMMDD-HHmm-<plan-slug>/phase-01-<name>.md

,

phase-02-<name>.md

, etc.

Optional research notes:

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

Use

scripts/get-time.sh

for:

Folder timestamp:
```
YYMMDD-HHmm
```
Human-readable timestamp:
```
YYYY-MM-DD HH:mm:ss
```

Workflow

Step 1: Contextualize

Read project documentation first:

```
docs/project-pdr.md
```
```
docs/architecture.md
```
```
docs/codebase.md
```
```
docs/code-standard.md
```

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

Capture:

Existing patterns to follow
Constraints and dependencies
Risks, assumptions, and unknowns

Step 2: Initialize Plan Artifacts

Create:
```
docs/plans/YYMMDD-HHmm-<plan-slug>/
```
Create:
- ```
SUMMARY.md
```
- one phase file per implementation phase
Add
```
research/
```
only if needed.

Step 3: Define Strategy and Phases

Design a phased strategy that is safe and verifiable.

Each phase should have:

A clear objective
Ordered tasks
Verification commands
Exit criteria

Granularity rule:

Tasks should be small, concrete, and typically 2-10 minutes each.

Step 4: Research (Only if Needed)

Research is optional and should be proportional to uncertainty.

Preferred order:

Existing project docs and code
Existing skills and local references
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 5: Write Plan Content

SUMMARY.md

format

markdown

# Implementation Plan: <Title>

> Created: YYYY-MM-DD HH:mm:ss
> Status: Draft

## Objective

- What is being built/changed and why.

## Scope

- In scope
- Out of scope

## Architecture & Approach

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

## Phases

- [ ] **Phase 1: <name>** — Goal: <goal>
- [ ] **Phase 2: <name>** — Goal: <goal>

## Key Changes

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

## Verification Strategy

- Lint/typecheck/tests/build commands
- Manual checks if needed

## Dependencies

- New packages/tools (if any) with reason

## Risks & Mitigations

- Risk → mitigation

## Open Questions

- Items requiring user confirmation

phase-XX-<name>.md

format

markdown

# Phase XX: <Name>

## Objective

- Specific result for this phase.

## Preconditions

- What must already be true.

## Tasks

1. Context: files/components to inspect or modify
2. Implement: exact change steps
3. Verify: commands/checks to run
4. Confirm: expected outcome

## Verification

- Commands:
  - <command 1>
  - <command 2>
- Expected results:
  - <result>

## Exit Criteria

- Clear checklist that determines completion.

Step 6: 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
Risks/assumptions are explicit
Plan is executable without hidden context

Then present for user review.

If multiple viable approaches exist, present options and ask for one of:

Validate: refine via additional clarifying questions
Confirm: approve current plan for execution

Iterate until confirmed.

Step 7: Handoff

When approved, end with:

Plan

<relative_path_to_plan>/SUMMARY.md

is ready.
Use

/clear

and then

/execute-plan <relative_path_to_plan>/SUMMARY.md

to execute it.

Rules

Never automatically implement or execute the code change in the same session, or ask user for execution right now, always finished when completed planning and ready for user review.
Prefer explicit file paths and concrete commands
Align with project standards and existing architecture
Ask clarifying questions when uncertainty affects execution safety
Keep plans self-contained and deterministic