ometere123/the-skills-bible/acceptance-criteria-writer

Acceptance Criteria Writer

Purpose

Define observable conditions that prove whether a requirement has been satisfied without dictating unnecessary implementation details.

Use this skill when

• A user story or requirement lacks objective completion conditions.
• Different people interpret expected behaviour differently.
• A defect recurs because edge cases were not specified.
• A tester needs a reliable oracle for pass or fail.
• A change affects permissions, state, calculations, integrations, or failures.

Do not use this skill as the primary workflow when

• The underlying requirement has not been agreed.
• The request is to write low-level unit-test assertions only.
• A broad product vision is being explored and testable behaviour is intentionally deferred.

Required inputs

Collect only the inputs needed for the current risk and scope:

• Requirement, story, use case, or defect.
• Actors, permissions, and ownership rules.
• Business rules and examples.
• Current system behaviour.
• Design constraints and external contracts.
• Known edge cases and failure modes.

If an input is unavailable, identify whether it is:

• Blocking: work cannot continue safely or correctly.
• Important: progress can continue with a labelled assumption.
• Optional: useful for refinement but unnecessary for the current decision.

Do not interrogate the user with a long questionnaire when repository inspection, existing documents, or a safe reversible assumption can answer the question.

Core operating principles

• Treat the user's stated objective as the source of intent, but verify ambiguous or conflicting details before making consequential decisions.
• Distinguish facts, assumptions, constraints, preferences, risks, and unresolved questions.
• Prefer evidence from the actual repository, system, users, or supplied documents over generic best practice.
• Use the smallest process that produces sufficient confidence for the task's risk and complexity.
• Keep outputs traceable: every recommendation, requirement, task, or decision should connect to an observed need.
• Do not invent access, files, stakeholders, research findings, metrics, or approvals.
• Protect existing user work. Never overwrite unrelated changes or expand scope silently.
• Escalate before destructive, irreversible, production-facing, security-sensitive, financial, or legally consequential actions.
• State uncertainty plainly and identify the evidence needed to reduce it.
• Finish with an explicit completion check rather than relying on confidence or appearance.

Workflow

1. Identify the behaviour under test

• State the capability or rule in plain language.
• Identify actor, preconditions, trigger, expected result, and observable side effects.
• Separate one behaviour from adjacent concerns.
• Link the criterion to a requirement identifier.

2. Choose the right form

• Use Given/When/Then for scenarios with meaningful preconditions and events.
• Use rule-oriented bullet criteria for static constraints.
• Use examples or decision tables for combinatorial business rules.
• Use schema and response tables for APIs.

3. Define the happy path

• Specify valid input, authorised actor, expected response, persistent state, and user feedback.
• Include exact business outcomes where required.
• Avoid relying on subjective words.
• Do not specify visual details unless approved design requires them.

4. Add boundaries and validation

• Cover minimum, maximum, empty, missing, malformed, duplicate, unsupported, and expired values where relevant.
• Specify field-level and cross-field validation.
• State whether invalid input is rejected, corrected, ignored, or queued for review.
• Define error feedback without exposing sensitive internals.

5. Add permission and ownership cases

• Cover unauthenticated, unauthorised, wrong-tenant, suspended, and privileged actors as applicable.
• Specify both response and state preservation.
• Ensure forbidden actions do not leak resource existence or sensitive data.
• Include administrative override rules if approved.

6. Add state and lifecycle cases

• Define allowed and prohibited transitions.
• Cover repeated, concurrent, cancelled, expired, archived, and deleted states.
• Specify idempotency where duplicate requests can occur.
• Define audit or notification effects.

7. Add dependency and failure cases

• Cover timeout, unavailable dependency, partial completion, retry, compensation, and recovery.
• Specify what the user sees and what state remains.
• Avoid promising recovery guarantees the architecture cannot support.
• Define observability expectations for operational failures.

8. Check testability

• Ensure each criterion has a deterministic pass or fail result.
• Remove implementation details not required by the product.
• Resolve contradictory criteria.
• Use concrete examples for calculations, dates, currencies, and rounding.

9. Prioritise criteria

• Distinguish release-blocking behaviour from future enhancement.
• Mark security, legal, data-integrity, and financial criteria as mandatory.
• Keep the set proportional to risk.
• Move broad quality requirements to non-functional requirements when appropriate.

Decision rules

Required outputs

Produce only the artefacts needed for the task, but keep the following structure available:

• Acceptance-criteria set linked to its requirement.
• Happy-path scenarios.
• Validation and boundary scenarios.
• Permission and ownership scenarios.
• State-transition scenarios.
• Dependency failure and recovery scenarios.
• Examples or decision tables where needed.
• Open questions and untestable assumptions.

Output quality standard

Every output must:

• Use stable identifiers where traceability matters.
• Separate confirmed information from assumptions and proposals.
• Link recommendations to evidence, goals, requirements, risks, or constraints.
• Use specific language and avoid decorative jargon.
• Make ownership, approval, status, and unresolved decisions visible.
• Be concise enough to use operationally, not merely impressive to read.
• Preserve the user's terminology unless a glossary clarifies a necessary distinction.
• Avoid claims of stakeholder agreement, research, testing, or validation that did not occur.

Failure handling and escalation

Pause, narrow the task, or escalate when:

• Two authoritative inputs contradict each other.
• A missing decision changes security, privacy, money, legal obligations, data integrity, architecture, or user-visible behaviour.
• The next step requires authority, credentials, access, or evidence that is unavailable.
• The proposed approach is destructive, irreversible, production-facing, or outside the approved scope.
• A stakeholder conflict cannot be resolved through evidence or existing governance.
• The requested result would misrepresent certainty, approval, compliance, testing, or completion.

When blocked, report:

1. The exact blocking condition.
2. Why it matters.
3. What has already been verified.
4. The smallest decision or evidence needed.
5. A safe alternative path, when one exists.

Common anti-patterns

• Writing criteria that restate the story without adding precision.
• Using subjective terms such as user-friendly or fast.
• Specifying code structure or framework choices.
• Covering only the happy path.
• Combining many behaviours into one scenario.
• Making criteria impossible to satisfy together.
• Writing tests as acceptance criteria rather than product outcomes.

Completion checklist

Do not declare the skill's work complete until the applicable items are true:

• [ ] Every criterion is observable and has a clear pass or fail result.
• [ ] Happy path, validation, permission, state, and failure behaviour are proportionate to risk.
• [ ] Criteria do not silently add new scope.
• [ ] Examples clarify complex rules.
• [ ] Sensitive error handling is safe.
• [ ] The criteria are consistent with the requirement and approved design.
• [ ] A tester can derive tests without guessing expected behaviour.

Handoff format

Use this concise structure when handing work to another skill, agent, or person:

# Handoff
 
## Objective
[Approved outcome]
 
## Current state
[What is known or completed]
 
## Key artefacts
[Identifiers, documents, files, diagrams, or links]
 
## Decisions
[Approved decisions and rationale]
 
## Assumptions
[Labelled assumptions and reversal cost]
 
## Open questions
[Only unresolved items that matter]
 
## Risks and dependencies
[Owners, triggers, and mitigations]
 
## Required next action
[One clear continuation]
 
## Completion evidence
[How the next owner will prove success]

Related skills

• requirements-analyst
• user-story-writer
• scope-definition-specialist
• feature-decomposer
• project-planner

Use related skills only when their capability is actually required. Do not invoke a chain of skills merely because they are listed.

Maintenance rules

Review and update this skill when:

• Repeated use reveals the same missing decision rule or failure mode.
• The workflow becomes tied to one framework, vendor, industry, or project.
• The SKILL.md file approaches 500 lines or contains reference material not needed on every activation.
• A supporting template, checklist, example, or deterministic script would reduce repeated work.

Move heavy reference material to references/, reusable output scaffolds to assets/, and deterministic utilities to scripts/. Link each supporting file from this document and state exactly when it should be loaded.