adzic-bdd

name	adzic-bdd
description	Guide on applying Gojko Adzic's Specification by Example (BDD) principles. Use this skill to write new feature files, refine acceptance criteria, or evaluate existing Gherkin scenarios using the Adzic Index. Triggers on 'adzic', 'bdd', 'specification by example', 'gherkin', 'feature file'.
metadata	{"version":"2.0.0"}

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

Trigger Scenario	Primary Dimension	Reason
Writing a new Feature Brief	Business-Readable	Verify non-technical stakeholders can read and confirm intent.
Planning an Epic	Living	Ensure all scenarios have executable step definitions.
Reviewing before a refactor	Intention-Revealing	Confirm scenarios won't break on internal implementation change.
Debugging brittle acceptance tests	Declarative	Expose UI-scripted steps that couple specs to the interface.
Pre-release quality audit	Living	No @pending scenarios at ship time.
Auditing inherited feature files	All six	Full health check of a legacy BDD suite.

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

Layer	Index	Question
BDD Specification	Adzic Index	Clear, executable, stakeholder-readable specification?
TDD Unit Test	Farley Index	Fast, honest, implementation-independent test?

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"