From rara-skills
Use when reviewing .feature files for quality before issue creation, validating Gherkin acceptance criteria against BDD best practices, or checking feature specs during the plan phase. Keywords: BDD review, Gherkin review, feature review, acceptance criteria review, quality gate, plan review.
How this skill is triggered — by the user, by Claude, or both
Slash command
/rara-skills:bdd-reviewThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**IRON LAW: Every review must be evidence-based.** Quote the exact line from the .feature file when citing an issue. Never give vague feedback like "could be better" — state what is wrong and how to fix it.
IRON LAW: Every review must be evidence-based. Quote the exact line from the .feature file when citing an issue. Never give vague feedback like "could be better" — state what is wrong and how to fix it.
You are the review agent. You receive .feature files from bdd-design during the plan phase (BEFORE issue creation) and validate them against BDD best practices. You run in a loop with bdd-design until quality is acceptable.
Copy and track progress:
- [ ] ⚠️ 1. Receive .feature content and plan spec from bdd-design
- [ ] ⚠️ 2. Review: Discovery completeness
- [ ] ⚠️ 3. Review: Formulation quality
- [ ] ⚠️ 4. Review: Step reuse
- [ ] ⚠️ 5. Review: Living documentation quality
- [ ] ⚠️ 6. Review: Anti-pattern detection
- [ ] ⚠️ 7. Produce structured verdict (GO / NO_GO)
- [ ] 8. If NO_GO, return feedback to bdd-design for fixes
Expect the following from bdd-design:
rara-bdd list (for step reuse check)Check whether business rules are adequately covered, not just code paths.
| Check | Criteria |
|---|---|
| Minimum scenarios | At least 3: happy path + error case + edge case |
| Business rule coverage | Are the plan spec's deliverables reflected in scenarios? |
| Boundary conditions | Are "what if...?" cases covered (empty input, max values, concurrent access, unauthorized user)? |
| Tester perspective | Would a QA engineer ask "but what about...?" for any uncovered case? |
Validate that scenarios follow Specification by Example principles.
| Check | Criteria |
|---|---|
| Business language | No SQL, HTTP methods, table names, or class names in steps |
| Single behavior | Each Scenario tests exactly one behavior (not multiple assertions on unrelated things) |
| Specific and verifiable | No "it works", "result is correct", "operation succeeds" — every Then step has concrete expected values |
| GWT responsibilities | Given = precondition setup, When = single action, Then = assertion on outcome |
| No compound When | Only one When per scenario (multiple When steps signal multiple behaviors) |
Check that the .feature maximizes reuse and avoids step definition explosion.
| Check | Criteria |
|---|---|
| Existing step reuse | Steps from rara-bdd list are reused where applicable (exact wording match) |
| Consistent parameterization | "quoted strings" for string params, bare integers for numbers |
| No synonymous steps | No two steps that mean the same thing but use different wording (e.g., "a user exists" vs "there is a user") |
| Parameterized over copy-pasted | Prefer Given a user with role "admin" over Given an admin user + Given a regular user |
Check that the .feature reads as useful documentation.
| Check | Criteria |
|---|---|
| Feature name | Clearly describes the business capability (not a technical component) |
| Scenario names | Describe the behavior being tested, not the test itself |
| Module tag | @module-name tag present on Feature |
| AC tags | Every Scenario has an @AC-XX tag |
| Logical organization | Scenarios ordered by business flow (happy path first, then errors, then edge cases) |
Flag common BDD anti-patterns.
| Anti-Pattern | What to look for |
|---|---|
| Scenario Outline overuse | More than 2 Scenario Outlines in a single Feature, or Outline used where distinct scenarios would be clearer |
| Fragile UI steps | Steps referencing CSS selectors, button labels, page layouts |
| Feature-coupled steps | Steps so specific they cannot be reused in any other feature |
| Incidental details | Steps containing irrelevant specifics (e.g., exact timestamps, UUIDs) that make scenarios brittle |
| Background overuse | Background with more than 3 steps (extract to a named Given step instead) |
Output the review in this exact format:
## BDD Review — Round <N>
### Dimension Results
| # | Dimension | Verdict | Notes |
|---|-----------|---------|-------|
| 1 | Discovery completeness | PASS / NEEDS_WORK / FAIL | <brief note> |
| 2 | Formulation quality | PASS / NEEDS_WORK / FAIL | <brief note> |
| 3 | Step reuse | PASS / NEEDS_WORK / FAIL | <brief note> |
| 4 | Living documentation | PASS / NEEDS_WORK / FAIL | <brief note> |
| 5 | Anti-pattern detection | PASS / NEEDS_WORK / FAIL | <brief note> |
### Fix List
(Only for NEEDS_WORK and FAIL dimensions. Omit this section if all PASS.)
**<Dimension name>**
- [ ] <Specific fix with quoted line from .feature> → <suggested replacement or action>
- [ ] ...
### Verdict: GO / NO_GO
<One sentence summary.>
Verdict rules:
If NO_GO, return the full review to bdd-design with the fix list. bdd-design will apply fixes and resubmit.
If GO, bdd-design proceeds to user confirmation and issue creation.
npx claudepluginhub rararulab/rara-skills --plugin raraGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.