home / skills / yellinzero / aico / acceptance-criteria

acceptance-criteria skill

safe

/employees/pm/skills/acceptance-criteria

This skill defines clear, testable Given/When/Then acceptance criteria from user stories to ensure verifiable test cases.

npx playbooks add skill yellinzero/aico --skill acceptance-criteria

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.8 KB

---
name: aico-pm-acceptance-criteria
description: |
  Define clear, testable acceptance criteria using Given/When/Then (Gherkin) format that can be directly used for testing.

  Use this skill when:
  - User asks for "acceptance criteria", "AC", "test criteria", "done criteria"
  - User asks "how do we know it's done?", "what counts as complete?"
  - User story needs testable success conditions
  - QA needs test scenarios or test cases
  - Running /pm.plan and need to add AC to stories
  - Reviewing story and AC is missing or vague

  Format: Always use Given [context], When [action], Then [expected result] structure.
---

# Acceptance Criteria

## ⚠️ CRITICAL RULES - READ FIRST

1. **READ STORY FIRST**: Always read the story file from `docs/reference/pm/stories/` before writing criteria
2. **USE GIVEN/WHEN/THEN**: All criteria must follow this format
3. **UPDATE STORY FILE**: Add criteria to existing story file, don't create new files

## Language Configuration

Before generating any content, check `aico.json` in project root for `language` field to determine the output language. If not set, default to English.

## Process

1. **Review story/feature**: Understand what needs to be done
2. **Identify success scenarios**: Happy paths first
3. **Write Given/When/Then**: For each scenario
4. **Add edge cases**: Boundary conditions and errors
5. **Verify testability**: Each criterion must be independently verifiable

## Acceptance Criteria Template

```markdown
### Acceptance Criteria for [Story/Feature]

#### Scenario 1: [Scenario Name]

- **Given** [precondition/context]
- **When** [action/trigger]
- **Then** [expected outcome]

#### Scenario 2: [Scenario Name]

- **Given** [precondition/context]
- **When** [action/trigger]
- **Then** [expected outcome]

#### Edge Cases

- **Given** [edge case condition]
- **When** [action]
- **Then** [expected behavior]
```

## Criteria Categories

| Category       | Examples                    |
| -------------- | --------------------------- |
| Functional     | Feature works as specified  |
| Validation     | Input validation rules      |
| Error handling | Error messages and recovery |
| Performance    | Response time expectations  |
| Accessibility  | A11y requirements           |

## Quality Checklist

- [ ] Each criterion is independently testable
- [ ] No ambiguous language ("should", "might", "could")
- [ ] Edge cases are covered
- [ ] Error states are defined
- [ ] Performance expectations stated (if relevant)

## Key Rules

- ALWAYS use Given/When/Then structure
- MUST make each criterion independently testable
- ALWAYS include edge cases and error scenarios
- NEVER use vague language - be specific

## Common Mistakes

- ❌ Vague criteria ("works correctly") → ✅ Specific conditions
- ❌ Missing edge cases → ✅ Include boundary conditions
- ❌ Implementation details → ✅ Focus on observable behavior

Overview

This skill creates clear, testable acceptance criteria in Given/When/Then (Gherkin) format that can be used directly by QA and automation. It reads the existing story, follows the project's language setting, and appends criteria to the story file in docs/reference/pm/stories/. The output focuses on observable behavior, edge cases, and independent testability.

How this skill works

The skill inspects the user story in docs/reference/pm/stories/ and checks aico.json for the language setting. It generates multiple Gherkin scenarios: happy paths, edge cases, validation and error handling, and performance checks when relevant. All criteria strictly use Given/When/Then and are written to be independently verifiable and non-ambiguous.

When to use it

When someone asks for "acceptance criteria", "AC", "test criteria" or "done criteria"
When product asks "how do we know it's done?" or "what counts as complete?"
When a user story lacks clear or testable success conditions
When QA needs test scenarios or test cases derived from the story
When running /pm.plan and adding AC to stories
When reviewing stories and acceptance criteria are missing or vague

Best practices

Read the story file in docs/reference/pm/stories/ before writing criteria
Always use Given [context], When [action], Then [expected result] for every scenario
Write happy path scenarios first, then add validation, error, and edge-case scenarios
Make each criterion independently testable and avoid vague language (no "should", "might")
Include observable acceptance conditions and explicit success/failure messages or codes when applicable
Confirm language from aico.json and write criteria in that language

Example use cases

Add AC to a new feature story so QA can implement tests immediately
Convert vague story notes into specific Gherkin scenarios for automation
Provide edge-case and validation criteria for input fields and boundaries
Append performance and error-handling acceptance criteria to existing stories
Generate testable acceptance criteria when onboarding a new PM or QA to the codebase

FAQ

Do you create new story files?

No. The skill updates existing story files in docs/reference/pm/stories/ and does not create new files.

What format will the criteria use?

All criteria use Given/When/Then (Gherkin) and include happy paths, edge cases, and error handling.

How do you determine the output language?

The skill checks the language field in aico.json; if missing it defaults to English.