pantheon-org/acceptance-criteria

Acceptance Criteria

Navigation hub for writing measurable, test-ready acceptance criteria.

Use When

• "Write acceptance criteria for this feature."
• "Define done conditions for this story."
• "Create testable requirements before implementation."
• "Apply INVEST quality checks to this story."

When Not to Use

• Architecture decisions and system design tradeoffs.
• Deep technical specifications about implementation internals.

Workflow

1. Capture user outcome and business intent.
2. Select criteria format (Given/When/Then or rule-oriented).
3. Draft must-pass criteria with measurable outcomes.
4. Add negative and boundary scenarios.
5. Validate with checklist before sign-off.

Worked Example

Starting Point (Vague Requirement):

"Users should be able to reset their password easily."

Step 1: Capture Intent

• User outcome: User regains account access after forgetting password.
• Business intent: Reduce support tickets; maintain security.

Step 2: Select Format Choose Given/When/Then (Gherkin) for clarity.

Step 3: Draft Must-Pass Criteria

Given a user is on the login page
When they click "Forgot Password"
Then a password reset form appears within 1 second

Given a user enters a valid email in the reset form
When they click "Send Reset Link"
Then an email is sent within 30 seconds
And the email contains a clickable reset link valid for 24 hours

Given a user clicks the reset link from the email
When they enter a new password (min 8 chars, 1 uppercase, 1 number)
And click "Update Password"
Then the password is updated
And they are redirected to login within 2 seconds

Step 4: Add Negative & Boundary Scenarios

Given a user enters an unregistered email
When they click "Send Reset Link"
Then they see "Email not found" message (no account enumeration)

Given a user's reset link has expired (>24 hours old)
When they click the link
Then they see "Link expired, request a new one"

Given a user enters a weak password (e.g., "pass")
When they click "Update Password"
Then validation error appears: "Password must be 8+ chars with uppercase and number"

Step 5: Validation Checklist

• ✓ All criteria are measurable (pass/fail).
• ✓ Happy path (valid email → reset → new password) covered.
• ✓ Failure paths (invalid email, expired link, weak password) covered.
• ✓ Wording describes outcomes, not implementation ("email is sent within 30s" not "use SendGrid API").
• ✓ Scope clear: password reset flow only, not account recovery via SMS.
• ✓ Product, engineering, and QA can all understand and test.

Quick Commands

# Find vague language
grep -nE "\b(should be|user-friendly|fast|easy|good)\b" <file>.md

# Count checklist criteria lines
grep -nE "^- \[ \]" <file>.md | wc -l

# Detect missing negative/error words
grep -niE "invalid|error|timeout|denied|failed" <file>.md

Expected Output

User Story:
As a [role], I want [action], so that [benefit].

Acceptance Criteria (Must Have):
- [ ] ...
- [ ] ...

Negative/Edge Scenarios:
- [ ] ...

Out of Scope:
- ...

Anti-Patterns

NEVER use vague, non-measurable criteria

WHY: vague language cannot be tested objectively. BAD: "The system should be fast." GOOD: "Search returns in <= 2s for 95% of requests."

NEVER write implementation instructions as acceptance criteria

WHY: criteria define outcomes, not implementation details. BAD: "Use JavaScript validation on submit button click." GOOD: "Invalid form input shows error message within 1 second."

NEVER skip negative and boundary scenarios

WHY: real users hit error and edge conditions. BAD: only valid-login scenario listed. GOOD: include invalid credentials, timeout, and expired session behavior.

NEVER couple multiple behaviors into one ambiguous criterion

WHY: broad criteria hide failure source and reduce test clarity. BAD: "Checkout and email and invoice should work." GOOD: split into separate measurable criteria.

NEVER bypass audience alignment on definition of done

WHY: misalignment causes rework at QA/review time. BAD: criteria written without stakeholder validation. GOOD: confirm criteria with product and QA before implementation.

Verification Checklist

• [ ] Every criterion is measurable (pass/fail).
• [ ] Happy path and failure paths are both covered.
• [ ] Wording describes outcomes, not implementation.
• [ ] Scope boundaries are explicit.
• [ ] Criteria are understandable by product + QA.

References

| Topic | Reference | | --- | --- | | INVEST criteria | references/invest-criteria.md | | Gherkin examples | references/gherkin-examples.md | | Pattern selection | references/patterns-by-type.md | | Scenario examples | references/examples.md | | Reusable templates | references/templates.md |

• Gherkin Reference