Write Plan

Take a software task described in `$ARGUMENTS`, clarify every ambiguity with the user via CLAUDE.md §2-style Q1/Q2 multiple-choice questions, then write a detailed implementation plan to `docs/plans/<slug>-plan.md` and open a PR. `$ARGUMENTS` is **free-form prose** describing the task. It may contain optional references — issue / PR URLs, `#1234` refs, Actions run URLs, commit SHAs, file paths, related prior plans — but they are not required.

$ARGUMENTS

## Procedure

1. **Parse `$ARGUMENTS`.** Capture the free-form task description verbatim. Extract any references mentioned (URLs, file paths, issue numbers, SHAs) and note them for the clarification + research steps. If `$ARGUMENTS` is empty, contains no actionable description, or is so vague that no slug can be derived, **stop and ask the user to describe the task** before proceeding. Do not silently default to a guessed topic.

2. **Read project context.** Always read `README.md`, `agents.md`, and `CLAUDE.md` at the repo root before drafting. If the task plausibly touches a MongoDB collection, also read every relevant `/db/contracts/*.yml` (per CLAUDE.md §10). If references in `$ARGUMENTS` point at issues / PRs / files / prior plans, fetch and read them in full — use `mcp__github__*` tools or the `gh` CLI for GitHub reads (see [Tool Access](#tool-access)), the `Read` tool for local files, and `Grep` / `Glob` to locate related code. Do not guess at code, env vars, or workflow inputs — read the source.

3. **Clarify until zero items remain open.** Identify every ambiguity the task introduces — scope, behavior, edge cases, interfaces, data model, operational concerns, success criteria, propagation / consumer impact, rollout. Batch every blocking question in a single round using the [Clarification Format](#clarification-format) below. **Always include a question proposing the slug** (used for the filename and the branch name). Wait for the user's answers. **If any answer introduces new ambiguity, ask a follow-up batch — keep looping until every clarification item is resolved.** Do not proceed to step 4 while any question is still open: this command's contract is to ship a plan with zero open questions. Items that genuinely cannot be answered before drafting (e.g. an env value that only exists in prod, an integration result that depends on staging) are NOT recorded as open questions — surface them in the clarification round as proposed `## Risks & Mitigations` entries with `ACCEPTED — pending <discovery>` wording and have the user accept them explicitly before drafting.

4. **Draft the plan.** Write a markdown plan to `docs/plans/<slug>-plan.md` following the structure in [Plan Structure](#plan-structure) below. Cite project constraints by section number where relevant (e.g. "§6 — renames are breaking unless the old name is preserved as an alias"). Surface every assumption you made and every risk you spotted. By the time you reach this step, there are no open questions left — step 3's loop must have resolved every one. Create the `docs/plans/` directory if it does not yet exist.

5. **Sanity check.** Re-read the plan as if you were the reviewer. Does it answer: what is changing, why, how, what could break, what is verified, how is the work split into independently-mergeable phases (each production-safe and complete on its own per [Phases & Merge Strategy](#phases--merge-strategy)), what is rolled out? If any of those is hand-wavy, fix it before pushing. No commit-and-iterate cycle on the plan itself.

6. **Branch, commit, push, open PR.** Create a new branch `claude/write-plan-<slug>` (append `-2`, `-3`, … if a branch with that exact name already exists on the remote). Commit the new plan file with message `docs: plan for <topic>`. Push with `git push -u origin <branch>` (retry up to 4 times with exponential backoff on transient network errors per the project's git policy). Open a PR via `mcp__github__create_pull_request`:
   - **Base:** the repo's default branch, resolved with `gh repo view --json defaultBranchRef -q .defaultBranchRef.name -R <owner>/<repo>`. Do NOT hardcode `main`.
   - **Title:** `docs: plan for <topic>`
   - **Body:** the [PR Body Template](#pr-body-template) below.
   - **Draft:** `false` (ready for review).

7. **Report.** Emit the [Output Format](#output-format) in chat — short summary, file path, branch, PR URL.

## Clarification Format

Follow CLAUDE.md §2 exactly. Stable IDs `Q1`, `Q2`, …; letter-only answers (`A`, `B`, `C`, or `A+C`); mark at least one option `(RECOMMENDED)`; one decision per Q-ID; multi-select allowed only when stated explicitly. Never use numeric (1, 2, 3) prefixes — only Q-IDs.

Common questions to consider in the first batch (skip any already unambiguously answered in `$ARGUMENTS`):

- **Slug confirmation** — propose 2–3 slug candidates derived from the topic. Used for both `docs/plans/<slug>-plan.md` and the branch `claude/write-plan-<slug>`.
- **Scope** — which repo / module / service / runtime; prod vs staging vs dev.
- **Backward compatibility** — does any existing identifier get renamed or removed? Per §6, those are breaking unless aliased.
- **Data model** — collections touched, index changes, contract updates per §10.
- **Interfaces** — API / CLI / env vars / log keys affected; observability impact.
- **Success criteria** — what is the done condition; how is correctness verified.
- **Rollout** — feature flag, dark launch, gradual ramp, instant cutover, rollback path.
- **Out-of-scope explicitly** — what is NOT being planned here.
- **Propagation** — if the change must reach consumer repos per `.github/ai/consumer_repos.json` (CLAUDE.md §14), how.
- **GitHub API hygiene** — if the plan adds new `gh api` / MCP calls, how they batch / reuse existing calls per §15.
- **Phase breakdown** — propose how the work splits into independently-mergeable phases (count + one-line scope per phase). The plan is implemented by the AI orchestrator (unattended pipeline), and every merge lands in producti