| name | exec-plan-writing |
| description | Capture durable goal, intent, and decisions for a unit of work as an execution plan under docs/exec-plans/. Use when finishing a non-trivial change that needs a decision record, when a PR closes one or more issues and the rationale would otherwise live only in commit messages or PR descriptions, or when the user asks to write an exec-plan, decision doc, or to document the why behind a change. Distinct from PLAN.md (ephemeral, scrubbed by CI on merge) and design-docs (architectural). |
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:
- The work involves a non-obvious design choice (alternative approaches existed and were rejected for specific reasons)
- Closing multiple issues in one PR — record which decisions tie them together
- Bundling an opportunistic fix with the main change (future readers should know it was intentional)
- A reviewer would reasonably ask "why didn't you just do X instead?" — answer it here
- The change has explicit out-of-scope boundaries that affect how follow-up work is sequenced
Skip an exec-plan for purely mechanical changes (typo fixes, dependency bumps, link updates, formatting) where the what is the whole story.
Where it lives
docs/
└── exec-plans/
└── YYYY-MM-DD-kebab-case-slug.md
Filename: YYYY-MM-DD-kebab-case-slug.md. Use the date the PR was opened, not the merge date.
Slug: short, action-flavored. Match how a future reader would search. Good: robots-named-ai-bots, influxdb3-decision-pages-hub, api-tag-pages-rendering. Avoid: update-things, fix-bug.
Lifecycle: create the file when the PR opens or when PLAN.md grows durable
decision context. After merge, update the Status line from "In review" to
"Merged YYYY-MM-DD" when convenient. Do not move the file between lifecycle
directories.
Template
Copy this as the starting point. Trim sections that don't apply (don't pad them with "N/A"). Keep the doc focused — terse and load-bearing beats long and exhaustive.
# <Short title — matches PR title without the conventional-commit prefix>
**Status:** In review — PR [#NNNN](https://github.com/influxdata/docs-v2/pull/NNNN)
**Closes:** [#NNNN](https://github.com/influxdata/docs-v2/issues/NNNN), [#NNNN](https://github.com/influxdata/docs-v2/issues/NNNN)
**Parent:** [#NNNN](https://github.com/influxdata/docs-v2/issues/NNNN) (optional — link the epic if there is one)
## Goal
<One or two sentences. What does this change accomplish, and what observable behavior is different after it lands? Avoid restating the PR title.>
## Why now
<The concrete trigger. A user report, a security finding, a phase of an epic, a regression discovered in review. Distinguish "we did this now" from the broader "we want this eventually" — the trigger is what makes the difference.>
## Decisions
<Non-obvious choices, one bullet each. Lead with the choice, then the reason. A reviewer should be able to read this list and not need to ask "why didn't you just …". Capture both code-shape decisions (data structures, file locations) and process decisions (bundling vs splitting PRs, what stays out of scope).>
- **<Decision>.** <Rationale. If there's a discarded alternative, name it.>
- **<Decision>.** <Rationale.>
## Explicitly out of scope
<Adjacent work the reader might expect to see in this PR but won't. Link to issues if follow-ups already exist. This is where you protect future-you from being asked "why didn't you fix X while you were in there?" — answer it here.>
- <Item> ([#NNNN](https://github.com/influxdata/docs-v2/issues/NNNN))
- <Item>
## How to update
<Steady-state instructions: a future contributor wants to add to or change the thing this PR introduced — what file(s) do they touch, and what regenerates from there? One or two sentences max. Skip this section if the change is a one-shot fix with no extensibility surface.>
## Verification
<Reproducible commands or steps that confirm the change works. The PR description has a test plan; this section is for the *durable* repro that still makes sense six months from now.>
Worked example
The first exec-plan in this repo is the model:
docs/exec-plans/2026-05-21-robots-named-ai-bots.md
It covers two bundled issues (#7240 named AI-bot blocks, #7251 staging whitespace fix), records five concrete decisions (flat YAML, kept legacy IDs, mirrored staging guard, Allow not Disallow, bundled #7251), and explicitly defers four related issues (#7242, #7243, #7241, #7245). It's ~40 lines. That's the right length.
Writing checklist
Before opening (or updating) the PR:
After merge
When the PR lands:
- Update Status from "In review" to "Merged YYYY-MM-DD"
- Update the PR link if a follow-up PR delivered the final form
This housekeeping can ride along on the next docs-touching PR — it doesn't need its own.
Related skills and conventions
- The repo-root
PLAN.md convention (ephemeral working plan, tracked on
feature branches, blocked from the default branch) is documented in
CLAUDE.md.
- Future skills will cover
docs/design-docs/ (architectural beliefs), docs/product-specs/ (product specifications), and docs/references/ (LLM-ingestible reference corpora) — see the structure overview in the next gardening pass.
