Repository navigation
Description
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:decomposeauthors 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, andlibraryandmoduleemit 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
Activity
kyle-sexton commentedon Sep 6, 2026
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:decomposeauthors fresh criteria for each slice and never carries the Brief's through. That behavior is inherited near-verbatim fromto-ticketsinmattpocock/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,missingandunverifiableverdicts.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
libraryandmoduleemit 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
mermaidfor 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.docs(planning): shrink phase 4 to a pattern column and fix the plan's…
fix(work-items): scope GitHub sub-issues by url, not the absent repos…
feat(conventions): register the authoring-formats convention (#3874)
feat(planning): dialect-select and scope-label the design skill's per…
feat(work-items): inline the design artifact into the decompose spec …
feat(planning): always-on unwanted-behaviour coverage prompt, EARS ta…
feat(planning): always-on unwanted-behaviour coverage prompt, EARS ta…
feat(planning): always-on unwanted-behaviour coverage prompt, EARS ta…
fix(planning): name the bundled resolver in design so a configured di…
kyle-sexton commentedon Sep 7, 2026
Closing: the typed-ticket-body lane is delivered, and the close-out review verified every stated criterion against merged
main(a175a0362).This container set out to give the ticket body a declared, machine-recognizable shape in place of free-text prose reinterpreted at each hop, and it did. A consuming team may now declare two team-shared authoring formats in one convention doc and have the planning-to-verification chain honour them. Acceptance criteria gain an opt-in EARS format carrying all five requirement patterns, alongside an always-on unwanted-behaviour and state-driven coverage prompt that runs whatever the convention says and even with no convention surface present at all. The design skill types and dialect-selects the per-scope artifacts it already emitted, labelling each with the scope that produced it, and
/work-items:decomposeinlines those artifacts into the container body under a provenance note naming the scope and dialect. The close-out review's own acceptance-criteria rollup gains a pattern column whenever the criteria it retrieves carry EARS tags.Zero config is preserved in the sense the amendment scoped it to: emitted artifacts are unchanged for a consumer who declares nothing. The system-scope diagram key deliberately carries no default, so a consumer who never opted in emits no C4 container view, and mermaid's own C4 support is excluded on a recorded upstream fact rather than a preference.
Shipping pull requests. #3874 registered the convention, #3879 typed and dialect-selected the design artifacts, #3882 landed the coverage prompt and EARS tagging along with the planning plugin's copy of the shared convention-home resolver, #3890 inlined the design artifact into the container body, #3904 added the close-out pattern column, and #3926 corrected the design skill to name the resolver it had wrongly described as unbundled. Two sub-items closed without a pull request and both were the right outcome: #3805 produced an approved plan on its working branch, and #3881 was refuted by the worker sent to implement it, on the evidence that only the planning plugin reads an authoring-formats key at all.
What the close-out review verified, empirically rather than from descriptions. It executed the shared resolver's test suite (61 of 61 checks passing) and the cross-plugin sync check (clean, all copies byte-identical at sha256
77e9b778...). It built a convention fixture outside any checkout declaringdiagram_dialect.data: dbmlanddiagram_dialect.system: likec4, ran the design skill's resolution ladder against it, and confirmed the run reaches those declared values instead of falling through to the mermaid default, with a bare-root control confirming the documented soft degrade still fires when no pointer line is bound. It also grepped each key inside every skill named as a reader, requiring a hit for each one named and zero for each one removed.That last check is why #3924 exists. The first close-out pass graded acceptance criterion 4 as failed: the design skill was telling the running agent that the resolver it needed did not exist, which made the system-scope C4 view unreachable for every consumer and silently served mermaid to anyone who asked for DBML. The same pass found three documentation locations naming
/work-items:decomposeand/review:quality-gateas readers of keys neither skill reads. Both are now corrected, and the documentation names exactly the three real readers.One known gap is recorded rather than closed, as the amendment stated: a single-session flow that never decomposes reaches
verification:confirm, which reads an approved plan's criteria directly, so tagged criteria can arrive there with no pattern column. Three further findings against the shared resolver, a cwd-relative step-3 path as written, exit 3 also covering a missing target directory, and a UTF-8 BOM before the pointer marker yielding exit 1, are pre-existing and out of scope for this container. They are filed as #3929.