Epic: typed ticket body (EARS acceptance criteria + design artifacts)

[kyle-sexton]

AMENDED 2026-09-06. Close-out grades this container against the amended set below, not the original.

Planning slice #3805 found this Brief mismodelled the chain. work-items:decompose authors fresh criteria for each slice and never carries the Brief's through, which is inherited behaviour with a stated rationale, so it is not changing. And a design scope is architectural while a decomposed slice is vertical, so neither an EARS tag nor a design artifact ever reaches a slice.

Superseded acceptance criteria. The one on the decompose slice body inlining an artifact: the target is this container body instead, since it stands one-to-one with the design session (#3823). The one on the fresh-context verifier returning a row per criterion: the reader is the close-out review, whose per-criterion rollup already exists and already carries delivered / partial / missing / unverifiable, so the slice is now one pattern column (#3824). The one on the design skill emitting an artifact per scope: it already ships a per-scope artifact table, so the slice types and dialect-selects what exists, and library and module emit nothing (#3822).

Corrected constraints. Zero-config is scoped to emitted output; the always-on coverage prompt is deliberately outside that guarantee. The system-scope diagram key has no default, so a zero-config consumer emits no C4 view.

The first three acceptance criteria, the out-of-scope list, and the per-item-PR execution shape all stand. Full rationale is in the 2026-09-06 amendment comment on this issue.

Brief

TLDR

Give the ticket body a type. Acceptance criteria gain an opt-in EARS format and an always-on unwanted-behaviour coverage prompt; design gains typed artifact targets per scope (data-model, contracts, C4 container); decompose inlines those artifacts into slice bodies; verification returns a per-criterion verdict table when criteria carry EARS tags. Four extends plus one convention registration. No new plugin, no new skill.

Goal

A planning-to-verification chain where the shape of an acceptance criterion and the shape of a design artifact are both declared, machine-recognizable, and carried forward into the ticket and the verification verdict — instead of free-text prose re-interpreted at each hop.

Constraints

• Team-shared format choices (EARS on/off, diagram dialect) live in the consumer's convention doc per the configuration-ownership doctrine in PLUGIN-PHILOSOPHY. No userConfig for team conventions.
• Zero-config behavior is preserved: a consumer with no convention doc sees today's behavior unchanged (free-text acceptance criteria, mermaid diagrams).
• Diagram craft is cited from an installed community diagram skill, presence-gated, never authored here.
• Mermaid C4 is experimental and is not the system-scope default.

Acceptance criteria

• The convention registry carries a row for the consumer convention doc's two new keys (acceptance-criteria format, diagram dialect), and the consumer-facing convention doc shape documents both with their defaults.
• Acceptance-criteria capture in the interview and PRD skills always asks once whether an unwanted-behaviour (IF-THEN) and a state-driven (WHILE) case is missing, regardless of convention.
• When the consumer convention selects EARS, emitted acceptance criteria are tagged with the five EARS patterns; without it, criteria are emitted free-text as today.
• The design skill emits a data-model artifact for data scope, a contracts artifact for integration scope, and a C4 container view for system scope, each in the dialect the convention names.
• The decompose slice body inlines a design artifact produced for that slice's scope as a fenced diagram block with a provenance note, and emits nothing when no artifact exists.
• The fresh-context verifier returns one row per criterion (criterion, pattern, evidence, verdict) when the retrieved criteria carry EARS tags, and its existing narrative form otherwise.

Captured assumptions

• GitHub renders mermaid natively in issue bodies, so an inlined mermaid artifact is readable without tooling.
• A consumer adopting EARS wants tags on the criteria themselves, not a separate requirements document.
• OpenAPI 3.1 is the sketch dialect for integration contracts; no other API description language is offered in this increment.

Out-of-scope

• Reqnroll scaffolding, a standalone Gherkin-authoring skill, and a full EARS-to-Gherkin-to-living-documentation pipeline. No second stakeholder reads living docs, and Gherkin overlaps the test-authoring skill. Gherkin export is named as a deferred extension point only.
• A standalone design-document skill.
• Authoring mermaid craft guidance in-house.

Deferred questions

• C1: data-model drift — reconciling a design ERD against the runtime data model (for example an EF Core DbContext). The only novel capability found in this lane; depends on typed design artifacts landing first.

Execution shape: per-item PRs

[kyle-sexton]

Amendment, 2026-09-06: three acceptance criteria corrected

Planning slice #3805 ran against this Brief and produced a plan that two independent reviews and one upstream-research pass rejected. The defects were in this Brief's model of the chain, not only in the plan, so three of the six acceptance criteria above are superseded. This container's own close-out review grades the shipped work against its stated criteria, so leaving them uncorrected would grade the lane against work it deliberately abandoned.

What the Brief got wrong

It assumed an acceptance criterion is captured, carried into a ticket by decompose, and read back by the fresh-context verifier. That chain does not exist. work-items:decompose authors fresh criteria for each slice and never carries the Brief's through. That behavior is inherited near-verbatim from to-tickets in mattpocock/skills, whose stated rationale is that a vertical slice "is verifiable alone and owns everything it grades", against horizontal slices whose "acceptance criteria have to reach into work that another ticket owns". Carrying Brief criteria into slices would break that property, so decompose is not being changed.

What decompose does carry is this container: its body is the Brief verbatim, acceptance criteria included. The reader of those criteria is the close-out review, which already anchors on them and already renders a per-criterion rollup with delivered, partial, missing and unverifiable verdicts.

It also assumed a design artifact could be matched to a slice by scope. Design scopes are architectural; a decomposed slice is vertical by construction and carries no scope. One design session picks one scope, so an artifact matched every slice or none.

Superseded acceptance criteria

The fifth criterion, on the decompose slice body inlining a design artifact, is superseded. The inline target is the container body, which stands one-to-one with the design session that produced the artifact. Slice bodies are unchanged. Tracked in #3823.

The sixth criterion, on the fresh-context verifier returning one row per criterion, is superseded. The verifier reads slice criteria, which are freshly authored and never tagged. The reader of tagged criteria is the close-out review, whose rollup already exists and already carries a verdict per criterion; what it lacks is the EARS pattern. The slice is now that one column. Tracked in #3824.

The fourth criterion, on the design skill emitting an artifact per scope, is narrowed. The design skill already ships a Scope-specific artifacts table covering all five scopes. That slice now types and dialect-selects the artifacts that exist rather than introducing a family beside them, and library and module emit no typed artifact. Tracked in #3822.

Corrected constraint

The zero-config constraint above promises a consumer with no convention doc sees today's behavior "with no change and no prompt". That is now scoped to emitted output: emitted criteria and artifacts are unchanged. The always-on unwanted-behaviour coverage prompt is deliberately outside the guarantee, because it is the one part of this lane whose reach does not depend on anyone opting in.

The diagram-dialect constraint is sharpened: the system-scope key has no default. Giving it one would make a consumer who never opted in start emitting a C4 container view they did not ask for. With the key unset, no C4 view is emitted. This supersedes #3814's original statement that resolution returns mermaid for both artifact kinds.

Unchanged

The first three acceptance criteria stand: the convention registration, the always-on coverage prompt, and EARS-tagged emission under the convention. The out-of-scope list stands in full. The execution shape stays per-item PRs.

Known gap, stated rather than closed

A single-session flow that never decomposes reaches verification:confirm, which reads an approved plan's acceptance criteria directly. Tagged criteria can arrive there with no pattern column. That path is not covered by this container and is recorded here so it is a known gap rather than a silent one.