teamcraft:plan-iteration

What this skill does

## Goal

A backlog is a pile of work. An *iteration* is a decision: for the next fixed window, with the people and time you actually have, here is the one goal you're committing to and the specific, sequenced set of work items that serves it. This skill runs that decision with the developer — and writes the result onto the work items as a durable `iteration` label, so the rest of Teamcraft (the build loop, the work board, project status, retros) can see what's committed.

This is deliberately more than walking the feature list and calling `create-issue` N times. Planning is a conversation the feature list can't have on its own:

- **What's the goal of this iteration?** Not "do some items" — the outcome that makes the window a success.
- **How long is the window, and when?** One week, two weeks, a month.
- **How much capacity?** How many people, how much of their time, and what past throughput suggests is realistic.
- **Given all that, what actually fits — and in what order?** Honoring dependencies, and leaving out what won't fit, on purpose.

Read `references/example-iteration-plan.md` first — it shows the planning conversation, the proposed plan, and exactly what gets written to the work items.

## How an iteration is represented

Two parts, each with a single source of truth — nothing is stored twice:

- **Membership** lives on the work items. Every item in the iteration carries the same `iteration:` value in its frontmatter — a label the developer chooses (`2026-S24`, `onboarding-v2`, `cycle-3`; their scheme, not ours). An item with no `iteration:` field is simply unassigned.
- **The iteration itself** is a small file, `.teamcraft/iterations/<label>.md`, holding the iteration-level facts that don't belong on any one item: the goal, the window (start/end), capacity, and status (`active`/`closed`). Structured frontmatter, so status and retros can read it directly.

The iteration file does **not** list its members — membership is derived by scanning item frontmatter for the label, the same one-way principle Teamcraft uses for relationships (`blocked_by` is stored; `blocks` is computed on read). One source of truth each means the two can't drift. Create `.teamcraft/iterations/` on first use if it isn't there.

## Establish Intent

Iteration planning isn't one situation. Ask which this is, because the flow differs:

1. **First iteration on a new project** — backlog may be empty or sparse; the PRD (and roadmap, if there is one) is the primary input; some work items may need to be created as part of planning.
2. **Next iteration on an ongoing project** — plan from the existing backlog; carry over anything unfinished from the current iteration.
3. **Adjust the current iteration mid-flight** — scope changed; add, drop, or resequence items already committed without disturbing what's in progress.
4. **Review the current iteration** — just show what's committed, the goal, and how it's tracking (then hand off to `project-status` for the live read).

## Gather the Inputs

Works at any project state — a polished PRD with a roadmap, or nothing but a verbal goal in an empty repo. Assume nothing exists; offer to create what's missing.

- **Existing work.** Glob `.teamcraft/work/`, read `INDEX.md` and the items. Note each item's status, priority, effort, `blocked_by`, and any `iteration` label already set — so you carry over unfinished work and never double-assign an item that's mid-flight.
- **Existing iterations.** Glob `.teamcraft/iterations/`. An `active` one tells you what's currently committed, its goal, and what's still unfinished to carry forward. None is fine — this may be the first.
- **Requirements context (optional).** If a PRD exists, skim only the sections relevant to the stated goal — for acceptance context, not a full read. If there's no PRD, don't block; the developer's description of the goal is enough to plan against.
- **Past throughput (optional).** If completed items carry `started`/`completed` dates, they reveal the team's real pace. Use that to sanity-check capacity rather than guessing — but it's context, not a gate.

## Run the Planning Conversation

Gather the collective context the feature list can't supply. Keep it conversational, not an interrogation:

- the iteration **goal** — the outcome that defines success for this window;
- the **window** — duration, and start/end dates if they have them;
- the **capacity** — how many people and roughly how much of their time; if throughput history exists, offer what it suggests as a reality check ("last two windows you closed ~6 medium items each").

The developer owns all three. Your job is to make the trade-offs visible, not to decide for them.

## Assemble the Plan

From the candidate work items, propose a set that serves the goal and fits capacity:

- **Serves the goal first.** Pull items that move the stated outcome. A high-priority item unrelated to this iteration's goal can wait for the next window — say so explicitly rather than pulling it just because it's high priority.
- **Respect dependencies.** Don't schedule an item ahead of a `blocked_by` that is neither already done nor sequenced earlier in this same iteration. Order the set so blockers land before the work they gate.
- **Size honestly against capacity.** Use `effort` estimates as a guide and apply judgment — the goal is a set the team can actually finish with a little air, not a stuffed list that slips. Name what you're leaving out and why. Remember each item carries Definition-of-Done overhead (`../references/definition-of-done.md`) — tests and docs, not just feature code — so an estimate that counts only the feature work will overcommit.
- **Create the items the iteration needs, when they don't exist.** Greenfield, or a PRD with no issues yet: the items to plan may not exist. Draft each missing one as a **full work item per the work-item standard** (`../references/work-item-standard.md`) — title, why, acceptance criteria, priority, effort, `iteration` set from the start — sourced from the goal and the relevant PRD sections. Show them to the developer for review alongside the rest of the plan, then write and commit them. No stubs, no lighter version, and never hand item creation back to the developer to do separately — drafting these to standard *is* part of planning.

## Present for Approval

Show the full plan before writing anything: the goal, the window, the ordered item list with efforts, the total against capacity, and what you deliberately left out (and why). The developer adjusts — add, drop, reorder, resize — until they approve. Assign nothing until they say yes; planning proposes, the developer commits.

## Write the Iteration

On approval:

- **Label each member item.** Set `iteration: <label>` in the frontmatter of every item in the set. Edit existing items; on items you just created for this iteration, include it from the start. Don't touch items that aren't in the iteration.
- **Write the iteration file.** Create or update `.teamcraft/iterations/<label>.md` — frontmatter with the goal, `start`/`end`, capacity, and `status: active`; a short prose statement of the goal in the body. Don't list members here; they're derived from the item labels. Keep it light — no certification stamp (iteration files are operational planning artifacts, like work items, not captured knowledge).
- **Close out the iteration this replaces.** If you're planning the next iteration and an `active` one already exists, ask whether to mark it `status: closed`. Carry any unfinished items forward deliberately (see the constraint below) rather than stranding them under a closed label.
- **Commit** after approval, with the iteration label in the message (e.g., `chore(2026-S24): plan iteration`).

## Respect Domain Ownership

This skill plans an iteration. It does not author requirements (`capture-requirements`), capture architecture or tech decisions (`capture-technical-design`), implement work (`plan-and-implement-issue`), or pick the single nex