planning-cldk-work

name	planning-cldk-work
description	Use when CLDK work is too plural for one design session — a theme that decomposes into several contract decisions, or several initiatives competing for a quarter — before any one of them enters design mode.

Planning CLDK work

The planning mode of the CLDK ladder, and the only mode that reasons across more than one contract decision at a time. Every other mode is single-change scoped: they take "we have decided to do X" and carry X to release. This one comes before that — it decides which decisions, in what order, and which of them are secretly the same decision.

Planning is shallow across many; design mode is deep on one. Resist designing here.

Entry Preconditions

The test: can this be stated as a single contract decision? If yes, it is design mode. If no, it is planning. Two shapes fail that test, and both belong here:

• A theme that decomposes into several contract decisions — "microservice static analysis" is one initiative, still plural. Step 1 of the loop breaks it down.
• Several initiatives competing for the same quarter. The portfolio case.

Either way there is something to order, group, and exclude.

Counter-test, so the mode does not fire on ordinary work: if you can name the one contract decision and the only open question is how its PRs sequence, that is designing-cldk-changes's decomposition step, not a roadmap. Go L3/L4 on one analyzer is one decision; do not manufacture a roadmap for it.

Vague wording is fine and expected — the sweep works on rough shapes. Vague altitude is not: a theme left whole has to be broken into the decisions it contains before the sweep can compare anything (step 1).

The Loop

Run it WITH the user — every ordering and grouping call is theirs (AskUserQuestion), not a silent pick.

1. Inventory — at the altitude of contract decisions

One line per candidate. No design detail.

A theme is not a candidate — decompose it first. "Microservice static analysis" is not one row; it is boundary-edge vocabulary, service topology, per-framework entrypoints, cross-service reachability — each a contract decision that can be ordered, deferred, or found to collide with something else. Break themes down to that altitude before going further, or the collision sweep has nothing to compare.

The test for a row: could it be one design session? If it is clearly several, split it. If two rows would obviously be decided together, merge them.

2. Contract-collision sweep — the reason this mode exists

For each candidate, ask the Contract-Impact Triage question shallowly: does it move schema v2 output (a node/edge kind, field, level, or id shape)? Then cross-reference the answers:

Which candidates touch the same vocabulary?

Any overlap is one decision, not two — it must be settled in a single design session even if the features ship months apart. The parity clause forbids renaming or repurposing shared vocabulary once it exists, so a term coined twice is coined wrong permanently.

Output: collision groups. A group is a set of candidates plus the vocabulary they share.

3. Dependency order

A DAG, not a list. For each candidate: what must exist first? Blocked-by relationships are the plan — a roadmap that does not say what unblocks what is an unordered wishlist.

4. Release trains

Which train carries which candidate, and where a schema major forces lockstep between repos. Candidates sharing a schema major should ride one migration, not one migration each — that is usually the largest saving planning finds.

5. Explicit not-now

What is deliberately excluded from this pass, and why. A roadmap without a not-now list is a wishlist; the exclusions are what make the inclusions mean something.

6. Commit the roadmap, then start at most one thing

Write the roadmap to codellm-devkit/.github → docs/design/roadmap.md, per references/roadmap-template.md. It is committed and reviewable, alongside the epics and cross-repo specs it coordinates.

Then file an epic for the single feature actually starting now — and nothing else. The roadmap records the rest; the tracker does not need to mirror it.

No candidate may enter designing-cldk-changes until every theme has been decomposed to contract-decision altitude AND the collision sweep has run over the result. Both halves, or neither counts: a sweep across undecomposed themes runs clean, reports no groups, and satisfies nothing — the collision is still there, just invisible.

Designing a feature in isolation that shares vocabulary with another candidate is the one planning mistake the parity clause makes permanent. Every other planning error is recoverable by re-planning.

The gate is on decomposition and the sweep, never on the roadmap's length or polish.

Terminal State

The ONLY skill you invoke after planning-cldk-work is designing-cldk-changes, for the one feature being started.

Checkpoint first. Do not auto-invoke it. Summarize the collision groups, the dependency order, and what was excluded, then AskUserQuestion — start the first feature's design now, start a different one, or stop here (see using-cldk-devtools → Transition Checkpoint).

Parking after the roadmap is a legitimate outcome, and often the right one. The roadmap is the deliverable of this mode; starting a feature is optional and can happen in a later session without losing anything.

Red Flags

Rationalization	Reality
"File all six epics so the board shows the quarter."	Six idle epics is inventory, and inventory rots. File the one you are starting; the roadmap records the rest.
"These are separate features, design them separately."	Run the collision sweep first. Shared vocabulary decided twice is decided wrong, permanently.
"Put the roadmap in a tracking issue so it's visible."	Docs carry content, trackers carry state. The roadmap is a committed doc; the Project board is the live view.
"'Microservice analysis' is one row on the roadmap."	It is a theme, not a decision. Undecomposed, the sweep runs clean and finds nothing — the gate passes and the collision ships anyway.
"The user is busy; I'll group and order these myself."	Grouping and ordering are the user's calls. AskUserQuestion, never solo.

Scope Guard

This mode plans CLDK feature work. It is not a general project-management tool: no estimation, no capacity modelling, no velocity. It reasons about contracts, dependencies, and release trains — the things specific to a multi-repo analyzer ecosystem governed by a shared schema.

If a planning session is really a meeting between people, this mode records and challenges; it does not facilitate. Capture what they decide, surface the collisions they missed, and say plainly when a call is theirs to make.