Adzic Bdd

Adzic Specification by Example (BDD)

This skill provides comprehensive guidance on writing, refining, and evaluating Behavior-Driven Development (BDD) specifications based on Gojko Adzic's Specification by Example.

Writing BDD Scenarios

When authoring new .feature files or acceptance criteria, always adhere to these core principles:

• Business-Readable: Speak the domain language, not developer jargon.
• Intention-Revealing: Focus on what and why, not how.
• Declarative: Describe state and business rules, avoid imperative UI clicks (e.g., no "click button A").
• Focused: One scenario tests one specific business rule.
• Living Documentation: Ensure the scenario acts as the definitive source of truth.

Crucial Pitfall (via Kent Beck's Canon TDD): Do not mix implementation design decisions into your scenario list. The Test List is behavioral analysis. There will be plenty of time to decide how the internals look later.

Note: For tactical guidance on keeping test abstractions clean and avoiding brittle dependencies, use the test-design-review skill.

The Adzic Index Evaluator

A quantitative diagnostic tool that scores BDD .feature files against these principles. The companion to the Farley Index — together they cover the complete quality picture.

It shifts the question from "Do our scenarios pass?" to "Do our scenarios communicate the right thing to the right people?"

When to Use This Skill

Instructions

1. Read the full reference spec at docs/reference/adzic-index.md.
2. Collect inputs (feature file path; optionally step definition path and VCS flag).
3. Execute the evaluation protocol defined in the reference spec.
4. Output the adzic_index_score, per-dimension metrics, red_flags, and recommendations.
5. Tailor depth of analysis to the requesting agent's role:
   • Marge → focus on Business-Readable + Intention-Revealing (she writes the scenarios).
   • Lisa → focus on Living + Focused (Epic readiness gate).
   • Ralph → focus on Declarative + Living (step definition quality self-audit).
   • Bart → full audit; use as adversarial evidence base for merge decisions.
   • Lovejoy → focus on Living as a release go/no-go signal.

Relationship to the Farley Index

Target state: Both ≥ 7.0. This is "Clean Code that Works, clearly specified."

Triggers

• "adzic"
• "bdd"
• "specification by example"
• "write a feature file"
• "adzic index"
• "adzic-index"
• "BDD quality"
• "gherkin quality"
• "scenario quality"
• "feature file audit"
• "specification theatre"
• "living documentation"
• "acceptance criteria quality"
• "UI script theatre"
• "imperative gherkin"
• "are my scenarios any good"