Problem
Three skills emit a ticket body with an "Acceptance criteria" section, and they have drifted apart:
create-ticket and align-ticket-with-implementation both define an identical Must/Should/Nice scaffold by hand — but their placeholder hints have already diverged, and align's "Should have" hint carries a spurious include single "Fix lint" item instruction. "Fix lint" is noise: CI enforces lint and formatting, so it goes without saying and conveys nothing as an acceptance criterion.
design-and-plan uses a different shape entirely (flat checkboxes, no tiers).
The "Fix lint" line is itself a symptom of maintaining parallel copies of the same block: one copy drifted and acquired cruft the other didn't. Fixing that line in isolation leaves the underlying duplication — and the next divergence — in place.
Context
Skill sources live under packages/agents/content/skills/ and are canonical; installed copies are regenerated from them. The repo already supports partials — reusable Markdown fragments inlined at install time by the directive expander (<!-- include: path / -->), documented in content/_partials/README.md. The project's stated doctrine: content appearing identically in 2+ files should be a partial whenever parallel copies would drift. These copies have drifted, so they clear that bar.
Design decisions settled during exploration:
- Canonical AC shape: Must/Should/Nice tiers (MoSCoW) with
- [ ] checkbox items. Tiers convey requirement priority; checkboxes make each criterion individually checkable.
- Empty tiers are omitted: a ticket renders only the tiers it populates — no empty "Should have"/"Nice to have" headers. This keeps small all-Must tickets clean and makes the change to
design-and-plan (which gains tiers) effectively shape-compatible with its current single-list output.
- No downstream risk: the only consumer of acceptance criteria,
review-branch (also used by review-pr), extracts criteria from whatever structure the source uses and maps them to a flat status table. Nothing parses the tier labels, so the shape can be chosen on its merits with no migration concern.
- Scope boundary: only the
## Acceptance criteria sub-block is unified. Each skill keeps its own surrounding sections (Description / Issues / Problem / Proposed solution / Context), which legitimately differ by workflow stage.
The "Fix lint" prescription appears in no other skill (audited). ex-post-facto, referenced in the original framing, is the former name of align-ticket-with-implementation (renamed in #628), not a separate skill.
Proposed solution
Introduce a single canonical acceptance-criteria partial and have all three ticket-producing skills include it in place of their hand-written scaffolds.
- Add
content/skills/_partials/acceptance-criteria-scaffold.md containing the ## Acceptance criteria heading, the three MoSCoW tiers with checkbox-style placeholders, and an explicit instruction to omit any tier with no criteria.
- Replace the hand-written AC block in
create-ticket, align-ticket-with-implementation, and design-and-plan with a self-closing include of the partial, positioned inside each skill's existing ticket-template fence.
- The "Fix lint" instruction is eliminated as a consequence — the drifted copy that hosted it is replaced by the shared source.
Acceptance criteria
Must have
Should have
Problem
Three skills emit a ticket body with an "Acceptance criteria" section, and they have drifted apart:
create-ticketandalign-ticket-with-implementationboth define an identical Must/Should/Nice scaffold by hand — but their placeholder hints have already diverged, andalign's "Should have" hint carries a spuriousinclude single "Fix lint" iteminstruction. "Fix lint" is noise: CI enforces lint and formatting, so it goes without saying and conveys nothing as an acceptance criterion.design-and-planuses a different shape entirely (flat checkboxes, no tiers).The "Fix lint" line is itself a symptom of maintaining parallel copies of the same block: one copy drifted and acquired cruft the other didn't. Fixing that line in isolation leaves the underlying duplication — and the next divergence — in place.
Context
Skill sources live under
packages/agents/content/skills/and are canonical; installed copies are regenerated from them. The repo already supports partials — reusable Markdown fragments inlined at install time by the directive expander (<!-- include: path / -->), documented incontent/_partials/README.md. The project's stated doctrine: content appearing identically in 2+ files should be a partial whenever parallel copies would drift. These copies have drifted, so they clear that bar.Design decisions settled during exploration:
- [ ]checkbox items. Tiers convey requirement priority; checkboxes make each criterion individually checkable.design-and-plan(which gains tiers) effectively shape-compatible with its current single-list output.review-branch(also used byreview-pr), extracts criteria from whatever structure the source uses and maps them to a flat status table. Nothing parses the tier labels, so the shape can be chosen on its merits with no migration concern.## Acceptance criteriasub-block is unified. Each skill keeps its own surrounding sections (Description/Issues/Problem/Proposed solution/Context), which legitimately differ by workflow stage.The "Fix lint" prescription appears in no other skill (audited).
ex-post-facto, referenced in the original framing, is the former name ofalign-ticket-with-implementation(renamed in #628), not a separate skill.Proposed solution
Introduce a single canonical acceptance-criteria partial and have all three ticket-producing skills include it in place of their hand-written scaffolds.
content/skills/_partials/acceptance-criteria-scaffold.mdcontaining the## Acceptance criteriaheading, the three MoSCoW tiers with checkbox-style placeholders, and an explicit instruction to omit any tier with no criteria.create-ticket,align-ticket-with-implementation, anddesign-and-planwith a self-closing include of the partial, positioned inside each skill's existing ticket-template fence.Acceptance criteria
Must have
content/skills/_partials/acceptance-criteria-scaffold.mdwith Must/Should/Nice tiers,- [ ]checkbox placeholders, and explicit guidance to omit empty tiers.create-ticket,align-ticket-with-implementation, anddesign-and-planall source their## Acceptance criteriablock from the partial via an include directive, retaining their own surrounding sections.include single "Fix lint" iteminstruction is removed and appears nowhere in the agents content tree.Should have
create-ticket,design-and-plan) and retroactive (align-ticket-with-implementation) authoring.