Implementation Plan Writer

---
name: implementation-plan-writer
description: Use when a feature, refactor, migration, or upgrade needs a written plan before anyone touches code. Triggers on "write an implementation plan", "plan this migration/refactor/feature", "break this into phases", or "I need a plan I can hand off". Produces a machine-readable planning document, not code.
---

# Implementation Plan Writer

A plan that only the person who wrote it can parse is not a plan, it is a note to self. This skill produces a document built around unique identifiers, so a task can cite the requirement it satisfies and a risk can cite its mitigation without either sentence re-explaining itself.

## Name the file first

`[purpose]-[component]-[version].md`, purpose from: `upgrade`, `refactor`, `feature`, `data`, `infrastructure`, `process`, `architecture`, `design`. Examples: `feature-sso-admin-1.md`, `migration-session-store-2.md`. The name alone tells a reader what kind of change this is before they open it.

## Frontmatter

```
goal: [concise title]
version: [1.0]
date_created: [YYYY-MM-DD]
last_updated: [YYYY-MM-DD]
owner: [team or person]
status: Completed | In progress | Planned | Deprecated | On Hold
tags: [relevant categories]
```

## The eight sections, in order

1. **Introduction** — one paragraph stating the goal, with the status badge from the frontmatter repeated inline.
2. **Requirements & Constraints** — every requirement (`REQ-001`), security requirement (`SEC-001`), constraint (`CON-001`), guideline (`GUD-001`), and pattern to follow (`PAT-001`), each declared once as a bullet or table row.
3. **Implementation Steps** — phases, each with a `GOAL-00N` and the `TASK-00N` items under it. A phase is independently processable: no task in phase 2 should silently depend on an undeclared output of phase 1. Every task needs a measurable completion criterion — "done when the migration script exits 0 against a staging snapshot and row counts match," not "done when it works."
4. **Alternatives** — approaches considered and rejected (`ALT-001`), with the one-sentence reason each lost. This is what stops the plan from being re-litigated mid-execution.
5. **Dependencies** — libraries, services, and other plans this one needs (`DEP-001`).
6. **Files** — every file the plan touches (`FILE-001`), with a phrase on what changes in it.
7. **Testing** — the verification for each phase (`TEST-001`), tied back to the task it verifies.
8. **Risks & Assumptions** — `RISK-00N` for what could go wrong, `ASSUMPTION-00N` for what the plan takes on faith. An assumption that turns out false should point straight at the tasks it invalidates.

## The one rule that makes this machine-readable

Every identifier is declared exactly once, at the point it is introduced. After that, later sections reference it by ID instead of re-describing it — `TASK-014` says "implements `REQ-003`," not a fresh paragraph repeating what `REQ-003` already said. This lets another agent, or a teammate weeks later, jump straight to the row that matters instead of reading the whole document to reconstruct context that was already written down once.

## Anti-patterns

- Prose paragraphs instead of identified, tabular requirements — reads fine to a human, unusable for anything that needs to cite a specific line
- A phase that quietly depends on an earlier phase's unstated side effect
- "Testing: manual QA" as a completion criterion — state what a reviewer actually checks
- Skipping Alternatives because the answer felt obvious at the time — obvious now is not obvious to whoever debugs this in six months

## Scope

This is the planning half. Turning the finished document into commits is implementation-plan-executor's job, task by task, with its own verification and checkpoints. Do not merge the two — a plan being edited while it is being executed stops being a reliable source of truth for either the executor or the next reader.