Writing Execution Plans

Purpose

Execution plans are durable, checked-in records of why a unit of work was done a particular way. They survive past merge, so future agents and humans can reconstruct intent without spelunking through commit history or closed PR descriptions.

They are not:

• PLAN.md at the repo root — that file is the in-flight working plan. It is tracked on feature branches and blocked from the default branch by a PR check. PLAN.md captures step-by-step how; the exec-plan captures durable why.
• Design docs under docs/design-docs/ (coming) — those capture architectural beliefs and cross-cutting decisions. Exec-plans are scoped to one change/PR.
• Commit messages or PR descriptions — both are useful but tied to a specific moment; PR descriptions get buried, and squash-merge commit messages frequently lose detail.

When to write one

Write an exec-plan when any of these apply: