plan-work-items

## Project Context

- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
- feature-implementation-plan.md: !`find . -maxdepth 5 -name "feature-implementation-plan.md" -type f`

# Plan Work Items

Break an implementation plan into vertical slices (tracer bullets) and write them as work items to a single `work-items.md` file.

This skill mostly coordinates: locating the plan or context, resolving where the file goes, printing the breakdown, writing the work-items file. It runs autonomously end to end. Step 5 is where the judgement comes into play, in dividing up the plan.

## Operating Principles

- **Run autonomously.** After the initial request, run end to end without pausing for human confirmation. When a decision has a reasonable default (where the file goes, how the plan divides), make it, state it, and proceed. Print the work item breakdown for visibility, but never gate on approval to continue. Stop for the user only when the skill genuinely cannot continue without input — there is no plan or context to work from at all.
- **One file, no repository awareness.** This skill produces exactly one `work-items.md`. It does not split work by repository, count repositories, or reason about cross-repository integration. The breakdown is driven only by the plan or context it is given.
- **Save incrementally — never lose work.** Write the work-items file as soon as the title and intro are drafted, then append each work item as it is finalized. Do not buffer the whole document in conversation memory and write it at the end.
- **All sub-agents in this skill run on sonnet.** When launching any Agent tool call in this skill, pass `model: "sonnet"`.

## Rules

- Do NOT modify, annotate, or comment on the source implementation plan or context. It is read-only input.
- Each work item is a **vertical slice**: a narrow but complete path through the relevant layers (schema, API, UI, tests) that is demoable or verifiable on its own. Not a layer, not a stub.
- Every work item body MUST link the reference artifacts an implementer needs: API/event contracts, design frames, schema docs, runbooks, ADRs, coding standards. A work item that consumes an HTTP endpoint or event payload MUST link the contract section that defines it.
- UI work items, when the plan folder has a `ui-designs/` subfolder, MUST reference the relevant design screenshots by a relative path from the work-items file to the screenshot. See [references/work-item-template.md](./references/work-item-template.md).
- `Depends on` lists other work items **in this same file** that must complete first, or `None`.
- NEVER include process artifacts in work item bodies or the preamble. Excluded categories: iteration histories, decision logs, review findings, team findings, facilitation summaries, gap analyses, and anything under an `artifacts/` subfolder of the plan that is not a contract or design reference. Restate plan-level decisions inline in the work item with `See plan: D-N` as the breadcrumb. Full include/exclude list in [references/reference-artifact-inventory.md](./references/reference-artifact-inventory.md).

## Process

### 1. Locate the implementation plan or context

The breakdown is built from an implementation plan when one exists, or from whatever context the user provided when one does not.

- If the user provided a file path, read it. If a feature name was given, look for `docs/features/<feature-name>/feature-implementation-plan.md` (or the equivalent under the project's documentation root).
- If nothing was provided, check for existing plans (the injected `feature-implementation-plan.md` results above help here). If there is exactly one, use it. If there are multiple, use the most recently updated one. If there are none, use whatever plan-like context the user supplied inline in the conversation.
- If the plan references other files (a feature specification, a contract file, an ADR), read those too. The plan content is the union of all these sources.
- If there is still no usable plan or context, ask the user — in one short message — for the implementation plan file path or the context to break down. Do not proceed without it.

### 2. Resolve the output location

The skill writes exactly one file: `{folder}/work-items.md`.

Resolve `{folder}` in this order:

1. If the user specified an output folder, use it.
2. If the plan is a file, default to the same folder as the plan file.
3. If there is no plan file but the provided context points at a folder or document location, write next to that.
4. Otherwise, make a best educated guess based on the provided context: choose a folder of **2 to 4 words** in kebab-case, placed under an existing documentation root surfaced via CLAUDE.md, `project-discovery.md`, or a Glob fallback (`docs/features/<feature>/`, `docs/plans/`, `docs/`). State the chosen folder in one short line and proceed; do not wait for confirmation.

If `work-items.md` already exists in the chosen folder, do not silently overwrite it and do not stop to ask: write to a timestamp-suffixed name (e.g., `work-items-2026-05-18.md`) and state which file was written. The existing file is preserved.

### 3. Explore the codebase when needed

If the plan references existing code or boundaries that aren't in your context, explore the affected code. Skip exploration if the plan is self-contained and the boundaries are already clear.

### 4. Inventory reference artifacts

Before drafting work items, list every artifact an implementer of those work items will need. See [references/reference-artifact-inventory.md](./references/reference-artifact-inventory.md) for the include list, exclude list, and screenshot-to-work-item mapping rules.

If an expected artifact is missing (for example, the plan touches an HTTP boundary but no contract file exists), note it in the breakdown report rather than stopping: draft the work items that do not depend on it, and f