decomposing-into-milestones

name	decomposing-into-milestones
description	Use when the architect (or Board Manager) brings a design doc, spec, or multi-point requirement that needs to be turned into GitHub Project cards. Triggers include "decompose this", "turn this into cards", "break this down into milestones", "what cards do we need for this feature". Produces cards sized so one Consumer session delivers one as one PR; enforces INVEST and vertical slicing.

decomposing-into-milestones

Turn a design doc into N GitHub Project cards, each sized so a single Consumer session can deliver it as one PR.

This is the plugin's single most load-bearing skill. Whether the board works lives or dies by how well decomposition obeys INVEST and vertical slicing — the downstream skills assume the cards they read were produced here.

Preflight

1. bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-deps.sh" — exit 2 → abort.
2. Invoke board-protocol to load the card schema into context. Every card you emit must pass that protocol.
3. Confirm .board-superpowers/config.yml exists. If not, redirect to using-board-superpowers for bootstrap — label creation must happen first or create-card.sh --label calls will silently fail.

Source material — what you can decompose

In order of preference:

1. Design doc from superpowers:brainstorming (docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md).
2. Design doc from gstack:/office-hours or gstack:/plan-eng-review.
3. Pasted design-doc content.
4. Multi-paragraph plain-text description.
5. Not acceptable: a one-liner like "add OAuth". Refuse and route back through intake — design pass first.

Read the source fully. Do not proceed until you can answer: what is the user-visible capability being delivered?

The INVEST gate

Every card you emit must pass every letter. If a candidate card fails one, split it further or fold it into a sibling.

Letter	Question	Fails if...
Independent	Doable in isolation, any order, relative to siblings (minus explicit deps)?	Requires a sibling merged first for reasons beyond a listed dependency
Negotiable	Describes outcomes, not a prescribed implementation?	Reads like a commit message or a checklist of files to edit
Valuable	Merging this card alone improves something user-visible or developer-visible?	Pure scaffolding — fold it into the first card that uses it
Estimable	An unfamiliar engineer can read it and know roughly the shape of the work?	Has "TBD" or "figure out" in the criteria
Small	One Consumer session can finish in one PR without heroics?	Expected diff > ~500 LOC or > ~10 files
Testable	Every acceptance criterion is an automatable check?	"Feels good", "is reasonable", "works well"

Vertical slicing — the non-negotiable heuristic

The most common decomposition mistake is splitting by layer (front, back, schema) instead of by capability (one user-visible thing, end-to-end, thin).

Correct:

Card 1: user can sign in with Google (happy path, minimal UI,
        skeleton DB schema just enough to store the session)
Card 2: user sees an avatar after sign-in (extends schema, adds UI)
Card 3: user can sign out (button, revocation, redirect)
Card 4: sign-in handles denied-consent error (error UI + backend)

Anti-pattern to reject:

Card A: add user table to DB
Card B: add OAuth backend routes
Card C: add sign-in UI
Card D: wire them together

The anti-pattern means A–C produce zero user value alone — they violate V. Until D merges, nothing works; the whole sprint is a big-bang merge in disguise. The architect cannot verify end-to-end after any of A–C.

When the design doc tempts you toward layer splits, re-slice vertically before writing any cards. The question to ask: "what is the thinnest thing a user could do after Card 1 alone merges?" That answers what Card 1 is.

Pattern library — common capability shapes and their canonical decompositions: references/decomposition-patterns.md. Skim first when the design matches a pattern (new user-facing feature, data model migration, new surface, refactor, bug fix, dep upgrade, feature flag, CRUD, async job).

Size calibration

Target distribution:

Label	Diff	Files	Intent
XS	< 50 LOC	1–2	Tiny wire-ups, single-function adds
S	50–200 LOC	2–5	Typical card — aim here
M	200–400 LOC	5–10	Acceptable; look once more for a split
L	400–500 LOC	up to 10	Ceiling. If you feel pressure to exceed, stop and split

Never emit XL. The ceiling is the commit the architect can still verify in one sitting; past 500 LOC that breaks down. If a capability genuinely needs more, it's more than one vertical slice — find the slices.

Procedure

1. Identify capabilities

Read the design doc. List every user-visible (or developer-visible, for internal tools) capability. Present to the architect:

"I see <N> capabilities in this design:

1. <one line>
2. ...

Any missing? Any that shouldn't be here? Any that should be merged?"

Do not proceed until the list is confirmed.

2. Order by dependency

For each capability, note hard deps on others. Hard = "cannot demonstrate B without A already working". Not = "would be nicer to build A first for cleanliness".

Present the dep graph as a simple list and confirm.

3. Slice each capability

For each confirmed capability, propose a thinnest-possible first slice, then successive slices. One capability at a time:

"Capability: <name>. Proposed slices:

Slice 1: <thinnest demonstrable version> Slice 2: <next increment> ...

OK to draft cards for this?"

Let the architect push back before anything lands on paper.

4. Draft each card

For each confirmed slice, fill in the five-section card body. See the full template, per-section rules, and a worked OAuth example in references/card-schema.md.

Key reminders while drafting:

• Context references the design doc by path, names 2–4 files the Consumer will touch, lists deps as Depends on #<N>.
• Acceptance Criteria are post-conditions ("X is true in the finished world"), not tasks. Every one is automatable.
• Out of Scope pre-empts gold-plating. List anything a Consumer might be tempted to fix "while in here".
• Size is a label: XS / S / M / L only.
• Execution Hints is optional — name a recommended execution skill and any known gotcha. Do not put acceptance criteria or scope here.

5. Review the set with the architect

Before pushing anything to the board:

"<N> cards, total estimated diff ~<X> LOC across ~<Y> files. Dependency chain: #A → #B → #C #D (independent) #E → #F

Thoughts before I push these?"

Common pushback and how to respond:

Architect says	Response
"Card C is too big"	Back to step 3 for that card, split further
"A and B should be one card"	Both probably too small alone (violates V); merge, revisit S
"What about capability X?"	Add to step 1 list, redo step 2
"Push them, looks good"	Proceed to step 6

6. Push to the board

For each card:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/create-card.sh" \
  --title "<title>" \
  --body-file /tmp/card-body.md \
  --project "$PROJECT" \
  --label "type:feature" \
  --label "size:S"

After creation, resolve cross-references: Depends on #<SLICE_2> placeholders → real issue numbers once both cards exist.

All cards land in Backlog, never Ready. The architect promotes to Ready in a separate move so that Ready always means "I looked at this again and decided it's actionable now".

7. Report

"<N> cards created in Backlog: #–#. Promote to Ready when you want, and I can generate kick-off prompts."

Do not promote to Ready automatically. Do not generate kick-off prompts here — hand back to managing-board and let the architect drive.

Anti-patterns

• ❌ Decomposing before the capability list is confirmed. You'll split along the design doc's structure instead of along user value.
• ❌ Splitting by layer (front/back/db). Always by capability.
• ❌ Cards bigger than L. Always split further.
• ❌ Acceptance criteria in "will do X" form. They must be "X is true", testable post-conditions.
• ❌ Skipping step 5. Creating 15 cards the architect didn't agree with is a loud, expensive mistake on GitHub.
• ❌ Adding cards for things the design doc didn't cover. Surface the gap in step 1, not as a silent new card later.