/plan-backlog

name: plan-backlog
description: Turn an idea or description (in any format) into a well-formed backlog — epics, user stories with acceptance criteria, sub-tasks — and create it in the team's tracker after approval. Elaborates progressively (guided, the default) or in one shot (`--quick`). Supports Jira, Linear, GitHub Issues, and Azure DevOps via adapters. Use when a product owner wants to draft or create tickets from an idea, brief, or document.

Plan Backlog

Turn a product idea into a structured, well-formed backlog in the team's tracker — the **upstream** half of the issue-to-PR workflow, for the product-owner persona. It closes the loop **idea → backlog → ticket → PR** (created stories feed straight into `work-story`).

This is the *write* counterpart to `issue-fetch` (which reads). **Nothing is created until you approve the draft.** You **facilitate** the PO's thinking — offer options and ask for decisions; never decide the product for them.

Trigger

A request to turn an idea / brief / description / document into tickets, epics, or a backlog — e.g. *"draft stories for this feature"*, *"create Jira tickets from this doc"*, *"break this initiative into a backlog"*.

Project configuration

Read `.claude/dev-kit.json` at the consuming repo root. The `tracker` block names the active adapter and its settings:

{ "tracker": { "type": "jira" | "linear" | "github" | "azure", ... } }

**If the file does not exist (or has no `tracker` block), run `dev-kit-setup` first** — it detects the tracker and persists the config, then returns here. Don't ask for values setup can discover.

1. Intake — read the idea in whatever form it arrives

• **Pasted text / chat description** → use directly.
• **PDF** → read it (page range as needed).
• **Word (`.docx`)** → not natively readable; convert first (`textutil -convert txt file.docx -output -` on macOS, or `pandoc file.docx -t markdown`), then read. If neither tool is available, ask the user to paste the text or export a PDF.
• **Artifact / Confluence page / URL** → fetch it.
• **Figma link** (`figma.com/(design|file)/…`) → run `figma-fetch` for design context.
• **A `plan-definition` product definition** — passed in chat, or a `docs/definitions/<slug>.md` file → read it as the source. It carries the framing already (problem, users, goals/non-goals, metrics, chosen direction), which is what triggers the **lighter framing** in §4a. Check its provenance markers / "not established" / `[unverified]` notes: a definition that flags core gaps is **not** ready for the light path (see §4a).

Work only from what the source says plus what the user confirms — **never invent scope or acceptance criteria.**

2. Discovery-first — learn the team's hierarchy and conventions

Don't impose a structure; **mirror the team's.** Using the adapter for `tracker.type`, discover:

• the **issue types available and their hierarchy** (Epic / Story / Task / Feature / Sub-task, …),
• the **fields that matter** (acceptance criteria, story points/estimate, epic/parent link, labels, components),
• a **sample of recent issues** to calibrate granularity and writing style.

Ask only what can't be discovered.

3. Choose the mode — guided by default

Two modes; **decide per invocation, never persist a mode** — a mature project can still hold a brand-new feature, so there are **two maturities: the project's and the feature's**. Judge each run.

• **Guided (default):** elaborate progressively, zoom-out → zoom-in, offering alternatives and asking for a decision at each level (§4). This is the right default; it keeps the PO doing the *definition* work instead of handing every decision to the agent.
• **Quick (`--quick`):** produce the whole backlog in one draft (§4, Quick). An explicit opt-in for when the PO just wants a fast draft.

**Signals for how much guidance a run needs** (discovery-first, never assumed):

• **Repo docs:** an empty/greenfield repo vs. one with a defined stack, conventions, and `CLAUDE.md` — the emptier it is, the more definition help the framing step should give.
• **Brief context:** how much useful context the idea/brief already carries.

Even on a mature project, still do a **light framing check** (§4a) — don't skip framing on the assumption it isn't needed. If the mode is genuinely ambiguous, **ask once**.

4. Draft the backlog

Guided mode (default) — zoom-out → zoom-in

Move through **three levels**; at each, present **2–4 alternatives** (as many as the situation needs, no padding), recommend one with a reason, and **wait for the PO's decision** before going deeper. Ground every option in the intake + discovery — never fabricate.

**4a. Framing (zoom-out) — help *define*, not just structure.** Restate the goal and map the problem space (users, outcomes, constraints, unknowns). Offer 2–4 **framing alternatives** — e.g. MVP vs. full, different ways to slice the initiative, different sequencing — with the trade-offs of each. → PO chooses the framing.

> **If a `plan-definition` product definition was handed in** (problem statement, users, goals/non-goals, metrics, chosen direction), the problem is already framed — *if it's grounded.* Before taking the light path, **check the definition, not just its headings**: a doc whose core must-haves are "not established", or whose thesis rests on `[unverified]` claims, is a spark with a template around it — treat it as an ordinary idea and frame from scratch (§4a). Only when the definition is genuinely grounded, run a **lighter framing**: *confirm* its direction and slice from it rather than re-deriving. Also re-open framing if the definition leaves the backlog-relevant slicing undecided. The presence of the five sections is not the signal; their groundedness is.

**4b. Epics / themes.** For the chosen framing, propose the epics/themes with **alternatives** where the breakdown could reasonably differ. → PO adjusts.

**4c. Stories.** Within each chosen epic, propose user stories (*"As a `<r