# Write Plans

> Write and update durable project, implementation, migration, and architecture plans. Use when creating a new plan document, revising an existing plan, choosing where a plan belongs in a repository, or splitting a large plan into an indexed set of documents.

- Skill: `marcus/write-plans` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add marcus/write-plans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/marcus/write-plans/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: marcus (https://skillmd.com/u/marcus)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/marcus/write-plans

---


# Write Plans

Write plans as current instructions for future work, not as narratives of how the plan evolved.

## Preserve the Current State

- State the plan as it is now. When facts or decisions change, replace the outdated text instead of annotating the old text inline.
- Avoid historical comparisons such as “previously,” “now,” “changed from,” or “unlike the original plan” unless that history is necessary to execute or understand the work.
- Rely on version control for history. If essential context would otherwise be lost, add a very brief changelog at the bottom of the plan.
- Keep one clearly controlling plan. Remove or update stale guidance and references that could send an agent to an obsolete plan.

## Follow Repository Conventions

Inspect the repository before choosing a location or structure. Follow its existing plan directories, indexes, naming patterns, and status conventions.

If the repository has no convention, use:

```text
docs/plans/
├── planning/
├── active/
├── implemented/
└── deprecated/
```

Choose the directory that describes the plan's current state. Add another status directory when none of these categories fits. When moving a plan between states, update indexes and inbound references so its canonical location remains discoverable.

## Keep Plans Usable

- Make scope, intended outcome, important decisions, work sequence, dependencies, and acceptance evidence explicit when they matter.
- Distinguish settled decisions from unresolved questions. Do not present assumptions or proposals as established facts.
- Prefer a concise, navigable plan over an exhaustive narrative.
- If a plan would flood an agent's context, turn it into a directory with a concise index and focused supporting documents. Make the index identify the controlling document, recommended reading order, and purpose of each file.
- Do not include developer-time estimates unless the user explicitly requests them.
- Optionally include rough story or epic sizing when it helps communicate relative scope; sizing is not required.

## Update Existing Plans

Read the whole affected plan and its index before editing. Rewrite impacted sections into a coherent current-state document, then check for contradictions, stale links, duplicate authorities, and status mismatches across the plan set.