# Exec Plan Writing

> 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).

- Skill: `influxdata/exec-plan-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add influxdata/exec-plan-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/influxdata/exec-plan-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: influxdata (https://skillmd.com/u/influxdata)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/influxdata/exec-plan-writing

---


# 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.

```markdown
# <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:

- [ ] File is in `docs/exec-plans/` with `YYYY-MM-DD-slug.md` naming
- [ ] **Status** line links the PR; **Closes/Refs** line links every issue the doc covers
- [ ] Every bullet under **Decisions** is a choice + a reason — no restatement of what's in the diff
- [ ] **Out of scope** lists every adjacent issue the reader might expect, with links
- [ ] Sections that don't apply are removed, not left empty
- [ ] The doc is shorter than PLAN.md — if it's longer, content has leaked from "decisions" into "implementation steps"

## After merge

When the PR lands:

1. Update **Status** from "In review" to "Merged YYYY-MM-DD"
2. 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.