designing-cldk-changes

name	designing-cldk-changes
description	Use when a CLDK change is structural — a new language, schema v2 evolution, a new analysis level, a new SDK facade surface, or any cross-repo feature — before touching an implementation rung.

Designing CLDK changes

The design mode of the CLDK ladder. Structural work — anything that moves the shared contract or spans repos — is designed here, as a spec plus a GitHub tracking record, before any implementation rung runs. You own contract evolution; the rungs (codeanalyzer-backend, cldk-sdk-frontend) consume what you decide.

Entry Preconditions

You are here because the work is structural: a new language, schema v2 evolution/migration, a new analysis level (L2/L3/L4), a new SDK facade surface, or any cross-repo feature. If it arrived as a "small fix" that turned out to move the schema v2 output or the public SDK API, maintaining-cldk's contract gate escalated it here — say so and continue; it is now a structural change, not a fix.

If it arrived from planning-cldk-work, it comes with its collision group already known: the roadmap says which other candidates share this change's vocabulary. Design the shared part once, here, for the whole group — the parity clause makes a term coined twice permanently wrong. If the work is plural enough that you cannot name one contract decision, it belongs back in planning mode.

Contract-Impact Triage

First move, always — before any design detail. Answer, out loud:

1. Does this change the schema v2 output? (a new node/edge kind, field, level, or id shape) — the keystone is references/canonical-schema.md.
2. Which repos are touched — analyzers, SDKs, docs?

Then state the change-type → repos-affected mapping:

Change type	Analyzers	SDKs	Docs
New language	new codeanalyzer-<lang>	python-sdk (+ TS SDK)	docs
Schema v2 evolution / migration	every affected codeanalyzer-*	every affected SDK	docs
New analysis level (L2/L3/L4)	that codeanalyzer-<lang>	SDK only if the surface changes	docs
New facade surface / SDK feature	—	python-sdk (+ TS SDK)	docs
Docs-only structural change	—	—	docs

Siblings share the schema — a "one analyzer" change is rarely one repo. Name every affected repo now. This list is the input to the decomposition decision below — it is not itself a list of issues to file.

Design Loops

Run the matching loop WITH the user, never solo — every divergence is the user's decision (AskUserQuestion), not a silent pick:

• Analyzer-side (schema shape: node/edge kinds, fields a language adds) → references/schema-design-loop.md, anchored on references/canonical-schema.md.
• SDK-side (facade query surface) → references/sdk-facade-design-loop.md, anchored on the Java + Python + C facades.
• Migrating an existing analyzer/SDK to a new schema major → references/schema-migration.md (compat shims, staging, version lockstep).

A new-language change usually runs both loops; a facade-only change runs just the SDK loop.

Decomposition and Release Plan

Decide this WITH the user — AskUserQuestion, never solo. The affected-repo list says what the change touches; it does not say how many issues to file. Filing one issue per repo per rung by reflex is how a backlog stops being readable, and an unreadable backlog buries the design record it was meant to preserve. Put both questions to the user once the triage and design loop are done:

The rule that replaces counting: tracking granularity follows PR granularity. Never step count, never repo count. Does a pull request close it? Then it is an issue. Is it a step inside a PR? Then it is a checkbox in that issue's GOALS.

1. Decomposition — what tracking shape? Offer the range, recommend one:
   • One work item, rungs as checklist items — the default when the change lands in one PR.
   • Epic + one sub-issue per PR — when the work spans repos that ship on their own clocks and need a coordination record.
   • Epic + a sub-issue stack — only when a rung is genuinely heavy (a full L3/L4 build, a multi-stage migration) and its units land as separate PRs.
2. Release plan — what ships when? Which release or train carries each piece, what gates what, and where two repos need version lockstep. A decomposition without a release plan is a pile of issues in no order.

Fewer, well-scoped issues beat more, thinner ones. When unsure, propose the smaller shape and let the user expand it.

File children just-in-time. An epic is filed at design time; its children are filed as each unit is picked up, not all at once up front. The committed spec already records the full plan — the backlog does not need to mirror it. Issues filed ahead of the work are inventory, and inventory rots.

No implementation rung may be entered for structural work until the spec exists and the work is tracked on GitHub. What "tracked" means is the decomposition decision above — for a single-repo change, one issue is a complete answer.

The gate binds to the design being written down and findable. It never binds to an issue count: do not skip the record, and do not inflate it either.

Spec → Tracking Record

1. Produce and COMMIT the spec — the triage table, the design-loop decisions, the affected-repo list, and the release plan. Specs are committed as provenance, so they are reviewable and diffable. A single-repo spec goes in that repo's docs/design/specs/; a cross-repo spec goes in the org .github repo, codellm-devkit/.github → docs/design/specs/, next to the epic that coordinates it.
2. File what the decomposition decision chose, using references/epic-and-issue-templates.md. Issue bodies come from the org-level forms in codellm-devkit/.github (.github/ISSUE_TEMPLATE/epic.yml, work_item.yml); the reference file covers which shape, when, and how to wire sub-issues.
3. Link the spec — do not paste it. The epic carries a path to the committed spec plus a short summary. Duplicating the design into the issue body is what made epic bodies unreadable.

Epics live in codellm-devkit/.github (the org config repo), never on the deliverable repo — that keeps working repos' trackers to work items only. Children are filed on the repo they change and attach as cross-repo sub-issues, never a hand-maintained CHILDREN checklist and never Part of #N trailers.

Only when the spec and its tracking record both exist is the gate satisfied.

Terminal State

The ONLY skill you invoke after designing-cldk-changes is the first affected rung: codeanalyzer-backend if any analyzer is touched, else cldk-sdk-frontend if only SDK surface is touched, else finishing-cldk-work (docs-only structural change).

Checkpoint first. Do not auto-invoke it. Summarize the locked decisions, the release plan, and where the tracking record lives, then AskUserQuestion — start the first rung now, start a different one, or stop here (see using-cldk-devtools → Transition Checkpoint). Parking after the spec and epic is a legitimate outcome: the gate is satisfied, and implementation can start in a later session without losing anything.

Red Flags

Rationalization	Reality
"We can write it up after it ships."	The gate exists precisely for this — the spec + epic are inputs to implementation, not paperwork produced afterward.
"It's a small additive change."	Additive schema changes still move the shared cross-language vocabulary; they enter design, under the gate.
"One issue can't be enough — this is structural."	Structural is about the contract moving, not about issue count. A single-repo change tracked in one well-scoped issue satisfies the gate.
"I'll file one per repo per rung, to be safe."	That reflex is what makes a backlog unreadable. Decomposition is a decision you put to the user, not a default you apply.
"The user is busy; I'll pick the decomposition and release plan myself."	Every divergence is the user's call — decomposition and release plan included. AskUserQuestion, never solo.
"A heads-up to the SDK is enough."	An affected repo is tracked — as its own child when the decomposition calls for one, otherwise as a named checklist item. Not a courtesy ping.
"I'll file every child now so nothing is forgotten."	The committed spec is what stops things being forgotten. Children are filed as they are picked up; filing ahead creates inventory that goes stale and buries the live issues.
"I'll paste the design summary into the epic so it's self-contained."	Link the committed spec. Pasting is what made epic bodies unreadable, and a doc is reviewable and diffable where an issue body is neither.
"I'll add a CHILDREN checklist so progress is visible."	Sub-issues roll up natively. A hand-maintained checklist drifts the moment anything moves, and so do Part of #N trailers.
"I'll just patch the parser / SDK model directly."	That is implementing before triage. Run Contract-Impact Triage first.