planning: plan the typed-ticket-body lane

[kyle-sexton]

Parent

Refs #3799

What to build

Run /planning:plan for the typed-ticket-body lane, reading the container Brief on #3799 as the scope.

Plan output is a PLAN.md under docs/topics/<slug>/ on the working branch, plus a closing comment on this issue summarizing the plan and any deferred questions it surfaced.

The plan must name an approach for each implementation slice in the container: the convention registration, the interview and PRD acceptance-criteria change, the design typed-artifact targets, the decompose inline artifact, and the verification per-criterion verdict table.

Acceptance criteria

• PLAN.md exists under docs/topics/<slug>/ on the working branch and carries goal, approach, test strategy, and blast radius.
• Every implementation slice under container Epic: typed ticket body (EARS acceptance criteria + design artifacts) #3799 has its approach named in the plan.
• A closing comment on this issue summarizes the plan and lists any deferred questions.

Blocked by

None

[kyle-sexton]

[kyle-sexton]

Planning blocked: the container's model of the chain does not match the skills

A draft plan is on branch plan/3805-typed-ticket-body (commit 4a51f96b7). Two independent fresh-context reviews ran against it, one structural and one adversarial, with the author's reasoning withheld from both. They returned 22 findings between them, six critical, and the adversarial pass returned RETHINK.

They converge on the same structural problem, and it lives in #3799's Brief rather than in the plan. Both findings below were verified directly against the source before this comment was written.

The tag never reaches the reader

The container assumes a chain where an acceptance criterion is captured, carried into a ticket, and read back at verification. That chain does not exist as described.

plugins/work-items/skills/decompose/SKILL.md emits fresh placeholder criteria into each slice body: an ## Acceptance criteria section containing - [ ] Criterion 1, - [ ] Criterion 2, - [ ] Criterion 3. It authors new criteria for the slice; it does not carry the Brief's criteria through. Only the opt-in container carries the Brief verbatim.

Verification runs against a slice, not against the container. So a tag written at interview or PRD time lands in the Brief and stops there. #3824 would ship a detector for something the executed ticket never carries, and the verdict table would appear only in a single-session flow that skipped decomposition entirely.

A second, smaller mismatch sits underneath it: plugins/planning/skills/interview/context/loop.md emits Brief criteria as plain bullets (- <testable criterion>), not checkboxes. The checkbox shape belongs to decompose. So the tag grammar as specified does not fit the surface that would write it.

The scope label has no join key

#3823 matches a design artifact to a slice "by scope". plugins/planning/skills/design/SKILL.md scopes are library, module, data, integration, system, which is an architectural axis. A decomposed slice is a vertical tracer bullet that crosses layers by construction and carries no scope.

One design session picks one scope, so the artifact matches every slice or none. Matching two slices to one artifact is the normal case, not an edge case.

That skill also already ships a "Scope-specific artifacts" table mapping each scope to named artifacts. #3822 as written reads as though it introduces per-scope artifacts, so a worker would likely create a parallel second set beside the existing one.

Other blocking findings

• docs/conventions: register acceptance-criteria format and diagram-dialect conventions #3814's brief and its third acceptance criterion say the diagram-dialect default is mermaid for both artifact kinds, while Epic: typed ticket body (EARS acceptance criteria + design artifacts) #3799 says Mermaid C4 is not the system-scope default. A zero-config consumer running a system-scope design has no defined dialect.
• docs/conventions: register acceptance-criteria format and diagram-dialect conventions #3814's acceptance criteria require a version bump, README updates and a skill-quality pass for "every touched plugin", but the slice touches no plugin.
• A skill cannot defer to a convention document at runtime, because an installed plugin never sees this repository's docs/conventions/. Each consuming skill body must restate the resolution ladder. No slice currently requires that.
• The two keys need an Implementers row in the config-cascade table, which is the conformance record fleet audits read. No slice adds one.
• docs/conventions/rendered-views/ already owns a diagram-output consumer surface and its medium key. A diagram-dialect key needs a stated boundary against it or it becomes a second overlapping surface.

What is not affected

The always-on unwanted-behaviour coverage prompt in #3821 is independent of all of this. It needs no convention key, no tag, and no artifact. It is the one part of the lane with guaranteed reach, and it can ship on its own.

Recommendation

Re-slice rather than patch. The tag has to be emitted where slice criteria are actually authored, which is decompose, not interview and PRD. That moves work between #3821, #3823 and #3824. #3822 shrinks to selecting a dialect for artifacts the design skill already emits, plus the scope label. #3823's inline trigger needs a real join key or the inlining target moves to the container body, which does carry the Brief verbatim.

Planning is paused here rather than proceeding on a spec known to be wrong. No slice has been dispatched.

[kyle-sexton]

Upstream alignment checked: decompose should not change

The suspicion that our decompose diverged from the skill it was adapted from does not hold. Research against the upstream source, with a coverage ledger of 23 enumerated items all marked and both acceptance gates passing.

The upstream is to-tickets in mattpocock/skills, plugin v1.2.3, read at pinned commit 3cca18b3. It absorbed a deleted /to-issues. The wayfinder skill is a separate decision-map skill, not a rename of it.

It authors fresh per-ticket criteria and carries nothing through, and the reason it does not carry anything is that there was nothing to carry: the upstream to-spec artifact has no acceptance-criteria section at all, across all eight of its commits. Our slice template is a near-verbatim adaptation of that skill's issue template, so our fresh-criteria behaviour is inherited rather than invented.

The rationale for per-slice ownership is stated upstream and is worth preserving. A vertical slice "is verifiable alone and owns everything it grades", as against horizontal slices whose "acceptance criteria have to reach into work that another ticket owns". Carrying a Brief's criteria down into slices would break exactly that property, so the earlier instinct to make decompose carry criteria through would have been a regression, not a fix.

Our real divergence is on the input side. Our Brief carries acceptance criteria and the upstream spec never did. We inherited a template built for a world with no upstream criteria, then built a Brief that has them. That is the actual mismatch, and it sits in the feature's assumptions rather than in decompose.

The chain that does exist

Decompose publishes the container body as the Brief verbatim, acceptance criteria included. Container close-out then invokes /review:quality-gate close-out --container <id>, which judges the container's acceptance criteria, and a missing or wrong finding against a stated criterion keeps the container open.

So a tagged criterion written at interview or PRD time does reach a reader. It reaches the container, and the close-out review reads it. The verdict table has a consumer; #3824 simply names the wrong one.

One genuine defect, separately filable

Two acceptance-criteria templates coexist in this repository: the generic slice template's bare - [ ] Criterion 1, and reference/agent-brief.md's - [ ] Specific, testable criterion 1, which decompose routes AFK slices to. Upstream issue #200 on that repository reports the concrete hazard of exactly this shape, two criteria lists in one ticket body drifting apart.

The upstream FAQ also names the bare placeholder as a defect source: "The template asks for criteria and says nothing about whether they can fail, so this happens." The prescribed bar is to name the observation that would show a criterion false and confirm it fails at the commit the implementer starts from.

Neither of these is part of this lane. Both are worth their own item.

Consequence for this lane

Decompose stays as it is. The lane re-slices narrowly rather than broadly: the capture slice is correct as written, the verification slice retargets to the close-out reviewer, the inline slice moves its target to the container body which actually carries the Brief, and the design slice shrinks to dialect selection over artifacts that already exist.

Full research artifact set is in the memory tier of the planning branch and is not committed.

[kyle-sexton]

Closing: plan approved

PLAN.md is on branch plan/3805-typed-ticket-body at commit 6f2008ff2, under docs/topics/typed-ticket-body/, alongside the design-gate early-exit artifact in design/design-resolution.md. The operator approved it on 2026-09-06.

Acceptance criteria

• PLAN.md exists on the working branch with goal, approach, test strategy and blast radius. Met. Six phases, each with a status tag and at least one mechanically verifiable sanity check, plus a consumer inventory, a test strategy, a files-affected table, alternatives with switch conditions, risks, an execution-shape analysis and a decisions table.
• Every implementation slice under Epic: typed ticket body (EARS acceptance criteria + design artifacts) #3799 has its approach named. Met. Phase 1 is docs/conventions: register acceptance-criteria format and diagram-dialect conventions #3814, Phase 2 is planning/interview+prd: unwanted-behaviour coverage prompt always on, EARS format opt-in via convention doc #3821, Phase 3 is planning/design: dialect-select and scope-label the existing per-scope artifacts #3822, Phase 4 is review/quality-gate close-out: pattern column on the acceptance-criteria rollup #3824, Phase 5 is work-items/decompose: inline the design artifact into the container body #3823. Phase 0 is a pre-flight consumer sweep that was completed in-session rather than deferred.
• A closing comment summarises the plan and lists deferred questions. This comment.

What the plan cost, and why that was the point

The first plan was rejected by two independent fresh-context reviews. The second was rejected by a third. Both rejections were the same mistake in different places: assuming a chain existed without checking where each hop actually reads from.

Revision 1 assumed criteria flow from capture through decompose into a slice and are read back by slice-level verification. Decompose authors fresh criteria per slice and never carries the Brief's through. Upstream research established that behaviour is inherited from to-tickets in mattpocock/skills with a stated rationale, that a vertical slice "owns everything it grades", so decompose is deliberately not changing.

Revision 2 retargeted to the close-out review, which was the right surface, but assumed the verdict machinery there needed building. It already exists: the close-out already anchors on the container's criteria, already gives each one a delivered / partial / missing / unverifiable verdict, and already renders the rollup unconditionally. So the slice shrank to a single pattern column.

The net effect is that two slices got substantially smaller and one convention got sharper, before any code was written.

Amendments this slice produced

The container Brief on #3799 was amended in its body, since close-out grades a container against its body rather than its comments. Three of its acceptance criteria were superseded and two constraints corrected. All five implementation slices were amended: #3814 collapsed to one registry row and dropped criteria it could not satisfy, #3821 gained the literal tag grammar and non-interactive behaviour, #3822 shrank to typing artifacts that already exist, #3823 moved its target to the container body and named the file it edits, and #3824 shrank twice.

Deferred questions

• The single-session flow is uncovered. verification:confirm reads an approved plan's acceptance criteria directly, so a flow that never decomposes can carry tagged criteria to it with no pattern column. Out of scope for this container, recorded as a known gap.
• Two acceptance-criteria templates coexist in this repository. The generic slice template's bare Criterion 1 and reference/agent-brief.md's Specific, testable criterion 1. Upstream issue feat: absorb owner-approved mechanisms from the external-skills census #200 on mattpocock/skills reports exactly this drift hazard. Not part of this lane; worth its own item.
• The bare placeholder has no falsifiability bar. The upstream FAQ names it as a recurring defect source and prescribes naming the observation that would show a criterion false. Also worth its own item.
• Data-model drift remains deferred on the container, unchanged.

Known execution risk

Phases 2 and 3 both bump the planning plugin's changelog, manifest and README. scripts/check-stale-base-overlap.sh is a hard failure on overlap rather than a warning, so they are authored in parallel and merged serially, with the second rebased before it can go green.