| name | deriving-acceptance-criteria-from-business-logic |
| description | Converts trusted business logic into product-owner-grade acceptance criteria and developer-ready tasks using Given/When/Then scenarios. Use when creating user stories, preparing for sprints, or turning BL into executable requirements. |
Deriving Acceptance Criteria from Business Logic
Project-agnostic. Use BDD/project_config.yaml → terminology for domain terms in scenarios when present (see tailor-bdd-skills-for-project).
Purpose
Transform trusted business logic into clear, testable acceptance criteria that can guide development and verify implementation. This is how BL starts leading software development.
Prerequisites
- Refined business logic document (use
refining-business-logic-for-implementation first)
- Understanding of the target audience (product owners, developers, QA)
- Access to project templates or standards for acceptance criteria
Instructions
Step 1: Parse the Business Logic Document
Read the refined BL and identify:
cat path/to/refined_bl_document.md
Extract:
- User-facing capabilities and features
- Business policies and constraints
- Workflows and user journeys
- Error conditions and edge cases
- Billing and financial rules
Step 2: Identify User Stories
For each capability, frame it as a user story:
Format:
As a <actor>,
I want to <capability>,
So that <business_value>.
Examples:
As a [user role],
I want to [perform core action],
So that [business value].
As an administrator,
I want to monitor [account/balance] state,
So that I can ensure service continuity.
Step 3: Generate Given/When/Then Scenarios
For each user story, create specific scenarios using the Gherkin format:
Scenario: <Descriptive title>
Given <initial context>
When <action occurs>
Then <expected outcome>
And <additional outcomes>
Scenario Categories:
- Happy path - Successful operation
- Sad path - Error conditions
- Edge cases - Boundary conditions
- Business rules - Specific policy enforcement
Step 4: Create Acceptance Criteria
For each user story, list concrete acceptance criteria:
Acceptance Criteria:
1. [Specific, testable requirement]
2. [Specific, testable requirement]
...
Good acceptance criteria are:
- Specific and unambiguous
- Testable (can be verified)
- Independent (not dependent on other stories)
- Negotiable (can be discussed and clarified)
Step 5: Add Implementation Checklist
Add technical checklist items for developers:
Implementation Checklist:
- [ ] Database migration if needed
- [ ] API endpoint changes
- [ ] Background task modifications
- [ ] Validation logic
- [ ] Error handling
- [ ] Logging requirements
- [ ] Test coverage
Step 6: Define Non-Functional Requirements
Add relevant non-functional requirements:
Non-Functional Requirements:
- Performance: <specific metrics>
- Security: <specific requirements>
- Reliability: <specific guarantees>
- Scalability: <specific constraints>
Step 7: Define "Done" Criteria
Specify what "done" means for this story:
Done Means:
- Code reviewed and approved
- Unit tests written and passing
- Integration tests passing
- API documentation updated
- Business logic document updated
- No critical bugs outstanding
Step 8: Output the Acceptance Criteria Document
Structure the document:
# Acceptance Criteria: [Feature Name]
## User Stories
[List of user stories]
## Scenarios
[Given/When/Then scenarios for each story]
## Acceptance Criteria
[Testable requirements for each story]
## Implementation Checklist
[Developer checklist]
## Non-Functional Requirements
[Performance, security, etc.]
## Done Criteria
[Definition of done]
Best Practices
Given/When/Then Guidelines:
- Given: Set up the initial state (avoid test setup details)
- When: Describe the action or event
- Then: Describe the observable outcome
- Use business language, not technical implementation
- Be specific with values (use actual numbers, not "valid value")
Acceptance Criteria Guidelines:
- Start each criterion with a verb
- Make it measurable (can be verified as pass/fail)
- Focus on what, not how
- Include business rules explicitly
- Cover error cases
Implementation Checklist Guidelines:
- Include all technical tasks
- Consider database changes, API changes, background tasks
- Don't forget tests and documentation
- Include monitoring and logging if relevant
Common Anti-Patterns to Avoid
❌ Vague scenarios:
Scenario: Query is processed
Given a valid request
When the request is processed
Then it should work
✅ Specific scenarios:
Scenario: Request submitted with sufficient balance
Given an account with 100 [balance units]
And the operation cost is 10 [units]
When the user submits the [operation]
Then the request is created with status "SUBMITTED"
And the account balance is 90 [units]
❌ Implementation details in scenarios:
Scenario: Database transaction works
Given the database is available
When the transaction starts
Then the lock is acquired
✅ Business-focused scenarios:
Scenario: Concurrent operations handled correctly
Given an account with exactly 10 [balance units]
When two users submit 10-unit operations simultaneously
Then only one operation succeeds
And the other is rejected with insufficient balance error
Examples
Example 1: Request/operation submission acceptance criteria
User request:
Create acceptance criteria for [request/operation] submission
You would:
User Story: As a [role], I want to [action], So that [value].
Scenarios: Write Given/When/Then for:
- Successful submission with sufficient balance (include balance deduction and ledger/audit if applicable)
- Rejection due to insufficient balance (correct status code, no deduction)
- Rejection due to invalid input (validation error, no charge)
- Concurrent submissions with exact balance (one succeeds, one rejected; balance never negative)
Acceptance Criteria: List testable conditions for: when the operation is accepted, when and how balance is deducted, when it is rejected and with which codes, and what the response includes.
Implementation Checklist: Validation, balance check, deduction (with concurrency safety if needed), ledger/audit, error codes, tests for concurrency. Use project terminology from config.
Example 2: Async job / status polling acceptance criteria
User request:
Create acceptance criteria for [async job] status polling
You would:
User Story: As a [role], I want to check [job/file] status so that I know when the result is ready.
Scenarios: Given/When/Then for: initial poll returns PROCESSING (with submission_time, estimated_completion); poll returns COMPLETED (with download/result URL and metadata); timeout leads to STALLED and user can request continue polling.
Acceptance Criteria: What the status API returns (status enum, timestamps, for COMPLETED: result URL/metadata, for STALLED: continue option); polling interval and max duration; STALLED and CONTINUE rules (reset counter, max CONTINUEs).
Non-Functional Requirements: Performance (e.g. API response time), reliability (retries), monitoring if applicable.
Acceptance Criteria Template
# Acceptance Criteria: [Feature Name]
## User Story
As a <actor>,
I want to <capability>,
So that <business_value>.
## Scenarios
### Happy Path
Scenario: [Descriptive title]
Given [context]
When [action]
Then [outcome]
### Sad Path
Scenario: [Descriptive title]
Given [context]
When [action]
Then [outcome]
### Edge Cases
Scenario: [Descriptive title]
Given [context]
When [action]
Then [outcome]
## Acceptance Criteria
1. [Requirement 1]
- [Sub-requirement or detail]
- [Sub-requirement or detail]
2. [Requirement 2]
- [Sub-requirement or detail]
## Implementation Checklist
- [ ] [Task 1]
- [ ] [Task 2]
- [ ] [Task 3]
## Non-Functional Requirements
- **Performance**: [Specific requirement]
- **Security**: [Specific requirement]
- **Reliability**: [Specific requirement]
## Done Means
- [ ] [Criteria 1]
- [ ] [Criteria 2]
- [ ] [Criteria 3]
Output Artifacts
The skill generates:
- User stories with clear value propositions
- Given/When/Then scenarios for BDD testing
- Acceptance criteria checklist for verification
- Implementation checklist for developers
- Non-functional requirements where applicable
- Done criteria for sprint completion
