writing-acceptance-criteria

name	writing-acceptance-criteria
description	Use when a spec document has been approved during brainstorming and you need to produce testable acceptance criteria before writing the implementation plan - converts spec requirements into a structured acceptance criteria document

Writing Acceptance Criteria

Announce at start: "I'm using the writing-acceptance-criteria skill to convert the approved spec into a testable acceptance criteria document."

Core principle: Every requirement in the spec must become a criterion with a deterministic pass/fail check. If you cannot write such a check, the requirement is not yet specified well enough.

Save to: docs/superpowers/acceptance/YYYY-MM-DD-<feature>.md

---

The Hard Gate

DO NOT PROCEED TO writing-plans UNTIL THE USER HAS APPROVED THE ACCEPTANCE CRITERIA DOCUMENT.

Present the document, commit it, then wait for explicit user approval before invoking writing-plans. (Skip in autonomous mode — see below.)

---

Process

Step 1: Load the Spec

• Read the spec at docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
• Identify every distinct requirement, behavior, constraint, and success criterion stated in the spec
• Group them by feature area or user-facing capability

Step 2: Draft the Criteria

For each requirement, write one or more rows in the acceptance criteria table.

Every criterion must include:

Field	Meaning
ID	Sequential identifier: AC-001, AC-002, ...
Description	One sentence stating the observable behavior being verified
Test type	One of: UI interaction / API / Logic
Preconditions	System state, data, or setup required before the test runs
Expected result	The specific, measurable outcome that constitutes a pass

Test type definitions:

• UI interaction — requires a running browser; executed with superpowers:playwright-cli
• API — HTTP request/response or CLI invocation; executed with curl, httpie, or the project's test runner
• Logic — pure function, data transformation, or unit behavior; executed by running the project's test suite directly

Step 3: Coverage Check

• Every section of the spec has at least one criterion
• Error cases and edge cases from the spec are represented
• No criterion uses vague language ("works correctly", "behaves as expected") — expected results are specific and measurable
• No duplicate criteria

Step 4: Write the Document

Save to docs/superpowers/acceptance/YYYY-MM-DD-<feature>.md with this exact header:

# Acceptance Criteria: [Feature Name]

**Spec:** `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
**Date:** YYYY-MM-DD
**Status:** Draft

---

## Criteria

| ID | Description | Test Type | Preconditions | Expected Result |
|----|-------------|-----------|---------------|-----------------|
| AC-001 | ... | UI interaction | ... | ... |
| AC-002 | ... | API | ... | ... |
| AC-003 | ... | Logic | ... | ... |

Step 5: Self-Review

• Placeholder scan: any "TBD", vague phrases, or incomplete rows? Fix them.
• Every expected result is deterministic (unambiguous pass/fail)
• Test types are correct (a logic criterion should not require a browser)
• IDs are sequential with no gaps

Fix inline. No need to re-review after fixing.

Step 6: Commit and Await User Approval

git add docs/superpowers/acceptance/YYYY-MM-DD-<feature>.md
git commit -m "docs: add acceptance criteria for <feature>"

Announce:

"Acceptance criteria written and committed to docs/superpowers/acceptance/<filename>.md. Please review and let me know if any criteria need adjustment before we proceed to writing the implementation plan."

Wait for explicit user approval. If changes are requested, update the document, re-run self-review, and re-commit. Update Status: from Draft to Approved once the user approves.

---

Autonomous Mode

If the user previously granted autonomous mode:

• Skip the approval gate in Step 6
• Update Status: to Approved directly
• Announce: "Acceptance criteria complete. Autonomous mode active — proceeding directly to writing-plans."
• Invoke superpowers:writing-plans immediately

---

No Placeholders Rule

These are failures — never write them:

• "TBD", "TODO", "fill in later"
• "The feature should work as expected"
• "Verify the behavior is correct"
• Any expected result that cannot be checked with a deterministic command or observation

If a requirement cannot be made testable, stop. Return to the spec and clarify with the user before writing the criterion.

---

Red Flags

• Writing a criterion without a specific expected result
• Using test type UI interaction when the behavior is purely server-side
• Proceeding to writing-plans before user approval (outside autonomous mode)
• Criteria that cannot be mapped to a concrete test in acceptance-testing

---

Integration

Called after:

• superpowers:brainstorming — invoke this skill after the spec is approved and committed

Referenced by:

• superpowers:writing-plans — plan tasks should note which AC IDs they satisfy
• superpowers:executing-plans — subagents receive relevant AC IDs in their task-local context
• superpowers:acceptance-testing — reads this document to drive the final verification pass

Proceeds to:

• superpowers:writing-plans — invoke after user approval (or immediately in autonomous mode)