BDD — Behaviour-Driven Development
npx machina-cli add skill bofrese/bob/bdd --openclawBDD — Behaviour-Driven Development
A thinking framework. Apply when defining tests, acceptance criteria, or evaluating whether something is "done".
The core discipline
Write acceptance criteria before you write code. If you can't state what success looks like in plain language, you don't understand the requirement yet. Go back.
The shape of a criterion
Every acceptance criterion follows this structure:
- Given — the precondition. The state the system is in before the behaviour is triggered.
- When — the action. What the user (or system) does.
- Then — the observable outcome. What changes — and how you'd know it changed.
If "Then" can't be observed — by a user, a log, an API response, a database state — it's not a real criterion. It's an implementation detail.
What we test: behaviour, not implementation
- Test what the system does, not how it does it.
- A good test survives a refactor of the internals. If your test breaks when you rename a private method, it's testing the wrong thing.
- Name tests after the behaviour.
user can reset passwordnotPasswordService.callResetEndpoint.
Acceptance criteria live in the plan
Before /bob:implement starts, the plan must contain testable acceptance criteria for every piece of new behaviour. Written in Given/When/Then. Reviewed by /bob:review-plan. This is the contract.
The golden check
Before shipping: does every acceptance criterion from the plan have a passing test or a verified manual check? If not, it's not done.
Overview
BDD is a thinking framework for defining tests, acceptance criteria, and evaluating when something is done. It emphasizes testing behaviour over implementation and uses Given/When/Then to describe criteria.
How This Skill Works
Before coding, write clear acceptance criteria in Given/When/Then. Tests should verify observable outcomes, not internal steps. Acceptance criteria live in the plan and guide implementation and shipping checks.
When to Use It
- Defining acceptance criteria for a new feature before any code is written
- Planning the testing strategy and success criteria for a release
- Evaluating whether a feature is complete by checking observable outcomes
- Reviewing the implementation plan with /bob:review-plan to ensure criteria are testable
- Renaming or refactoring code while ensuring tests still reflect behaviour, not internals
Quick Start
- Step 1: Write Given/When/Then acceptance criteria for the new behaviour
- Step 2: Add the criteria to the plan and review it with /bob:review-plan
- Step 3: Proceed with implementation only after criteria are testable and verifiable
Best Practices
- Write acceptance criteria before coding so success is well understood
- Use Given/When/Then for each criterion to specify preconditions, actions, and outcomes
- Test the behaviour, not the internal implementation
- Name tests after the behaviour (e.g., user can reset password)
- Ensure the plan contains testable acceptance criteria before starting /bob:implement
Example Use Cases
- user can reset password and receive a confirmation email
- adding an item to the cart persists across sessions and logs in
- search returns relevant results and highlights the query
- feature flag toggles behavior without changing code paths
- golden check: all acceptance criteria have a passing test before shipping
