Skip to content

Consolidate the acceptance-criteria scaffold across ticket-producing skills #685

Description

@williamthorsen

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

  • A canonical acceptance-criteria partial exists at content/skills/_partials/acceptance-criteria-scaffold.md with Must/Should/Nice tiers, - [ ] checkbox placeholders, and explicit guidance to omit empty tiers.
  • create-ticket, align-ticket-with-implementation, and design-and-plan all source their ## Acceptance criteria block from the partial via an include directive, retaining their own surrounding sections.
  • The include single "Fix lint" item instruction is removed and appears nowhere in the agents content tree.
  • Install-time expansion succeeds for all three skills (no expansion error; the partial inlines cleanly within each template fence).

Should have

  • Placeholder wording in the partial reads correctly for both forward-looking (create-ticket, design-and-plan) and retroactive (align-ticket-with-implementation) authoring.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions