Skip to content
Skills Library
Programming · Planning

write-plan

/write-plan

Write an implementation plan. Use when the behavior is settled and how to build or fix it is open — a pinned cause, settled spec, hunt finding, or review comment. Not for deciding the behavior (write-specs) or multi-session work (frontier).

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Write an implementation plan. Use when the behavior is settled and how to build or fix it is open — a pinned cause, settled spec, hunt finding, or review comment. Not for deciding the behavior (write-specs) or multi-session work (frontier).

Original author description

Write an implementation plan. Use when the behavior is settled and how to build or fix it is open — a pinned cause, settled spec, hunt finding, or review comment. Not for deciding the behavior (write-specs) or multi-session work (frontier).

How it works

  1. Steps
  2. Referencing
  3. Template
  4. Sizing
  5. Secrets
  6. Handing off
Original SKILL.md headings · 151 lines, 1,142 words
SKILL.md preview
---
name: write-plan
description: Write an implementation plan. Use when the behavior is settled and how to build or fix it is open — a pinned cause, settled spec, hunt finding, or review comment. Not for deciding the behavior (write-specs) or multi-session work (frontier).
---

# Write Plan

It is read by a **cold executor**: a session with no memory of yours, possibly a cheaper model.

Three properties make a plan executable by that reader:

1. **Self-contained** — every path, excerpt, convention, and command is in the file. "As discussed above" is a broken plan.
2. **Gated** — each step ends in a command with an expected result, so the executor never has to _judge_ whether it worked.
3. **Bounded** — an explicit out-of-scope list, and STOP conditions that end the run.

## Steps

### 1. Recon

Open every file the plan will name. Fan out [research](../research/SKILL.md) when the change touches more files than you can open in one pass — it maps callers and conventions while you route, and you still open what the plan names. Run every command it will cite — guessed commands are the most common way a plan dies on contact. Record `git rev-parse --short HEAD`. Note the conventions the change must match, each with one exemplar file to imitate.

**Done when** every path, symbol, and command destined for the plan has been verified against the repo, every convention the change must match has a linked exemplar file to imitate, and the SHA is recorded.

### 2. Route

Order the steps so the build stays passing between them — e.g., add the new path, switch the callers, then delete the old one. Where the change spans layers, make the first step a thin **vertical slice** and widen from there. Tests are steps, not a wish at the end — a step that adds behavior is worked test-first by [tdd](../tdd/SKILL.md), so its Verify command is the suite.

**Done when** each step verifies on its own, and the step list reads in that order — every new path added before the caller switch, every caller switch before the deletion.

### 3. Write, then read it cold

Fill the template, then reread it as the executor. Wherever you filled a gap from memory, inline the missing fact.

**Done when** every **Current state** excerpt has been re-opened at its `file:line` and matched, every step is Gated, every file and symbol mention is a working relative link, every out-of-scope file is listed with a reason touching it is wrong, each STOP condition names a risk specific to this change, and every Verify and Done command has been run once and resolves (no command-not-found, unknown script, bad flag, or missing path), with its expected output naming the state after the step, not the state today.

## Referencing

Every file, line, and symbol the plan names is a link, so the executor opens it instead of searching for it. A plan lives beside its spec as `<name>.plan.md`, under the [referencing convention](../write-specs/SKILL.md#referencing) — paths relative to the plan file.

```markdown
file [`src/lib/db.ts`](../../../src/lib/db.ts)
line [`db.ts:42`](../../../src/lib/db.ts#L42)
range [`db.ts:40-60`](../../../src/lib/db.ts#L40-L60)
symbol [`Pool.acquire()`](../../../src/lib/db.ts#L40)
requirement [`R2`](<name>.spec.md#requirements)
sibling spec [`<name>.spec.md`](<name>.spec.md)
```

Commands, flags, patterns, and expected output stay in plain backticks — nothing to open.

## Template

```markdown
# Plan: <imperative title — what is true once this lands>

> **Executor rules**: work the steps in order. Run every Verify command and
> confirm its expected result before moving on. On any STOP condition, stop and
> report the condition, the step, and the evidence.
>
> **Written against** commit `<short SHA>`, <YYYY-MM-DD>.
> **Drift check (run first)**: `git diff --stat <SHA>..HEAD -- <in-scope paths>`
> Its file list is what narrows the excerpt match: compare
> [Current state](#current-state) against the live code for every file it flags.
> A mismatch is a [STOP](#stop) condition.

## Goal

2–5 sentences: the problem, its concrete cost, what improves when this lands.
Requirements covered: [`R2`](<name>.spec.md#requirements), [`R5`](<name>.spec.md#requirements)
— or "none, this is a fix".

## Current state

The facts, inlined — every excerpt readable without opening another document:

- [`<path>`](<rel-path>#L10-L40) — its role here, and the lines that matter
- Short excerpts as the code exists today, each headed by its linked
  `file:line`, enough that the executor can confirm it is looking at the right
  thing
- Each convention to match, with its linked exemplar: "errors follow the
  pattern in [`result.ts:12-30`](<rel-path>#L12-L30)"
- Any decided constraint from a spec or ADR, quoted, with the source linked —
  the executor has not read those documents

## Commands

| Purpose   | Command | Expected on success |
| --------- | ------- | ------------------- |
| Typecheck | `<cmd>` | exit 0, no errors   |
| Tests     | `<cmd>` | all pass            |

## Scope

**In scope** — the only files to modify:

- [`<path>`](rel-path)

**Files out of scope** — leave alone even though they look related:

- [`<path>`](rel-path) — <why touching it is wrong>

## Steps

### 1. <imperative title>

Exactly what to do, with every file and symbol linked. Include the target shape
where it is load-bearing — the pattern to produce, not every line.

**Verify**: `<command>` → `<expected output>`

### 2. …

## Done

Machine-checkable. All must hold:

- [ ] `<typecheck cmd>` exits 0
- [ ] `<test cmd>` exits 0, including the new tests for <case>
- [ ] `git status` shows no files outside the in-scope list

## STOP

Stop and report if:

- The code at a [Current state](#current-state) location does not match its
  excerpt.
- A step's verification fails twice after one fix attempt — a second failure
  means the step's assumption is wrong, not its implementation.
- The fix appears to require an out-of-scope file.
- <the key assumption this plan rests on> turns out to be false.

## Notes

- What a reviewer should scrutinize, and anything deliberately deferred.
- Rollback, as commands — for migrations, deletions, and production data only.
```

## Sizing

The full template is the default. For a change touching at most two files with no ordering constraint, drop Commands and Notes and keep every other section: run-plan's Orient runs the header's Drift check, its Stopping reads STOP, and Done's last box checks Scope. With no Commands table to fall back on, every step carries its own Verify line.

## Secrets

Secrets never appear in a plan: reference `file:line` and the credential type, and recommend rotation.

## Handing off

The plan is written, not trusted. Hand it to
[plan-hunt](../plan-hunt/SKILL.md) — a blind refuter kills dead steps cheaper
than run-plan discovers them. A plan of at most two steps against files this
session already read may go straight to [run-plan](../run-plan/SKILL.md); say
which route you took and why.

A plan comes back from plan-hunt with a `<name>.plan-hunt.md` report when the hunt confirmed a finding. Revise it rather than rewriting it: fix each step or section a Confirmed finding names, re-run [Recon](#1-recon) for the files those fixes touch, update **Written against** if HEAD moved, and hand the plan to plan-hunt again. A Suspected finding is a check, not a fix: run its **Settles it** check, and change the step only if the check fails.

Versions

RepositoryScoreLicence
This page · j0hanz/j0hanz-marketplace100MIT
jelvodev/yaap100MIT
trihuynh-agilityio/workez100MIT
Marcdaou/claude-plugins100MIT
existential-birds/beagle100Apache-2.0
Ovich/charrette90MIT

Database snapshot: 13.11.2026 · package version c675be1c5ee2 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 85design-and-plan
    Use to specify non-trivial behavior or interfaces, resolve requirements or tradeoffs, or produce a multi-step implementation plan. Do not use for a mechanical edit, routine status update, or execution of a settled plan.
  • 92implement
    Implement a settled plan test-first, one small slice at a time. Read this skill before you write code for a spec or a settled plan. Read it also when the plan is small. Use it when the user says \"implement this\" or \"build it\", or names a spec to implement.
  • 100write-adr
    Record a settled decision as an ADR. Use when the decision will outlive the effort that made it. Not for behavior a change must deliver (write-specs), or decisions not yet settled (grilling).
  • 100write-specs
    Spec a feature's observable behavior. Use when asked for requirements, when a request says what the system should do but not how, or to capture what a built system already guarantees. Not for how to build it (write-plan).
  • 100shape
    Use when a feature has settled intent and codebase facts but multiple viable implementation approaches remain.
  • 90close-spec
    When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned task that produced a spec), archive it to specs/done/ and rewrite it from a build-plan into a durable rationale — the why, the principles, the invariants — pointing back to the real code for…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.