Quality gate: acceptance criteria required on every task

Vidar the Patient — Architecture

In one breath

Every task now requires a user-shaped ## Acceptance criteria section written before implementation begins — and reviewers are required to verify each item before approving a PR.

By the end of this chapter you’ll understand:

• What “user-shaped” acceptance criteria means and why “tests pass” or “PR merges” are invalid criteria
• Where the AC template appears in the task-worktree, review-protocol, and planning skills
• How phantom-complete issues — where code was correct but the user-visible outcome was never verified — drove this change

Quality gate: acceptance criteria required on every task

Status: Delivered
CAS: CAS-2732
Delivered: 2026-05-14
PRs: #725

What’s new

Every Casaconomy task now carries a mandatory ## Acceptance criteria section — a checklist of user-shaped outcomes written from outside the app before implementation begins. Reviewers are required to verify each item before approving a PR. Tasks without acceptance criteria, or with implementation-shaped criteria (“tests pass”, “PR merges”), are rejected at review time.

How to use it

When creating a task (for officers): The planning skill (Saga’s brief) now auto-inserts an ## Acceptance criteria template near the top of every generated CAS body, above ## Deliverables. Fill in 3–5 items that describe what a person using the app will be able to observe — name the screen, the action, and the outcome. Example format:

## Acceptance criteria
- [ ] User opens Settings → License on iPhone
- [ ] Enters a valid CASA-... code → status flips to ACTIVATED within 2 s
- [ ] Force-quits, reopens → status is still ACTIVATED

When reviewing a PR (for reviewers): The review-protocol skill now includes an explicit acceptance-criteria gate as the first check: did the engineer tick all AC items? Are the items user-shaped or implementation-shaped? A PR with missing or hollow AC fails this gate.

When writing the PR description (for engineers): The task-worktree skill’s CAS body scaffold leads with the AC template. Copy it into the PR description with ticked checkboxes to show the reviewer you ran the walk.

What changed under the hood

• .agents/skills/casaconomy-task-worktree/SKILL.md — CAS body scaffold now leads with ## Acceptance criteria template; HTML comment explains the required shape.
• .agents/skills/casaconomy-review-protocol/SKILL.md — “Prerequisite for every PR: acceptance-criteria validation” gate added as the first item in the reviewer checklist.
• .agents/skills/casaconomy-planning/SKILL.md — Sub-issue body template now auto-inserts the AC section before ## Deliverables; “Writing acceptance criteria” section rewritten with an explicit invalid-criteria list.

Why we built it

Phantom-complete issues — where an officer marks a task done because the code is correct but the user-visible outcome was never checked — were the root cause of several multi-day regressions in the iOS bug-report arc. No officer was explicitly responsible for verifying that the user could actually do the thing the task described. Mandatory, user-shaped acceptance criteria close that gap: they force the question “what will the user see?” at task-creation time, not after the regent finds a bug on a TestFlight device.

Known limitations / follow-on work

• Enforcement is skill/persona-level, not automated. A motivated officer can still merge a PR with hollow AC if the reviewer doesn’t catch it.
• No tooling yet to lint AC sections for implementation-shaped language. A future CAS could add a review-bot check.

See it as

A recipe that ends with “serve and enjoy” versus one that ends with “the sauce coats the back of a spoon, the pasta is al dente, and the plating is restaurant-standard.” The first tells you when to stop cooking; the second tells you when the dish is actually ready. Acceptance criteria are the second kind — written before you start cooking, so you know what you’re aiming for.

Recap

• The ## Acceptance criteria template is auto-inserted by the planning skill above ## Deliverables; the review-protocol skill requires it as the first gate before any other check.
• Valid criteria name a screen, an action, and an observable outcome from the user’s perspective; criteria shaped around implementation artifacts (“tests pass”) are explicitly rejected.
• The change targets phantom-complete issues — where code correctness was mistaken for user-visible correctness — which caused several multi-day regressions in the iOS bug-report arc.

What changed {#what-changed}

This feature shipped in CAS-2732. See: CHANGELOG → 2026-05-18