bdd-specification

Files (3)

• SKILL.md
• refinement-chain.md
• scenario-craft.md

SKILL.md (first lines)

# BDD Specification

**BDD is a strategy, not a guardrail** - expressing acceptance criteria
as Given/When/Then scenarios. It is the default way to
satisfy the **acceptance-before-code guardrail**: *acceptance defined
before it is built - stated, and checkable*. Keep that relationship
straight.

- **Acceptance-before-code is the guardrail** - hard, checkable. No code is written that no stated,
  checkable acceptance criterion describes. The outcome - acceptance is stated
  and it is checkable - is non-negotiable on every delivery approach.
- **BDD is the strategy** - Given/When/Then is the *form*. It is the default,
  but it is a strategy: a context where the form genuinely does not
  fit is a recorded strategy deviation, not a framework violation. The hard
  line is that acceptance exists and is checkable; Given/When/Then is the
  default way to make it so.

In Compass the BDD spec is not documentation that precedes the tests - it *is*
the tests, read at a different time. `acceptance-criteria.md` is written once at
the define stage and run as the acceptance check at verify. It is also the one artifact
five roles read (see `skills/intent-interview/role-translation.md`). Write it knowing all of that.

## Example-first refinement chain

In `skills/bdd-specification/refinement-chain.md`.

## The Summary comes before the scenarios

A spec opens with a **Summary** in prose, above the role-guide block, before a
single Given/When/Then. Three fields:

- **Goal** - one sentence, what this change delivers in user terms.
- **Approach** - two to three sentences, the shape of the change at the level a
  perspective reviewer would want.
- **Why now / what changes** - one short paragraph, the visible outcome and what
  an adjacent role would notice afterwards.

This is the **cold-reader** strategy (write for a cold reader) applied to the spec itself. A
reviewer opening a spec they did not write should be able to say what is being
built and why before deciding whether to read the scenarios in detail. Without
it they have to synthesize that picture from the Gherkin - easy for the author,
progressively harder for everyone else, and the point at which review quietly
stops happening.

The Summary is **additive**. It does not replace scenarios, and it is not a
place to restate them. Length scales with the delivery approach the same way scenario depth
does: quick fix one to two sentences per field, the regular approach ordinary
paragraphs, the full approach up to 200 words per field where the work warrants it.

## Settle edge cases before scenarios

For an id or header field, agree the missing, empty and whitespace cases with
the person before you write a scenario. Do the same for any message the request
leaves out. Reproduce a reported bug on current code, not an old build.

## Failure modes the brief implies

After the happy path and the edges, ask which
input classes and failure modes the brief implies that no scenario yet covers. Each answer becomes a
scenario, a light one if need be, or is recorded with
`compass scenario descope "<mode>" --reason "<why>"`. The verifier lists every
recorded mode in the verification report, so nothing named is dropped
silently.

- **Worked example, a rate limit.** "Limit search to 100 requests a minute"
  implies a client exactly at 100, a client over it, two clients sharing an
  address, and the counter's reset at the minute boundary. The first three
  become scenarios; the reset is de-scoped because the limiter library's own
  tests cover the window.
- **Worked example, a CSV import.** "Import customers from a CSV file"
  implies an empty file, a header with no rows, a row missing a required
  column, a duplicate customer, and a file that is not UTF-8. The first four
  become scenarios; the encoding case is de-scoped as out of scope for this
  release, with a follow-up issue that adds encoding detection.

## Self-review before the requirements review

When `acceptance-criteria.md` is written, run these four scans over it yourself before
handing off. **Fix what you find inline** - edit the spec directly. Do not write
a review artifact, and do not invoke a reviewer agent or subagent for this.

1. **Placeholder scan** - any unfilled `{{...}}` left in the file, including the
   three Summary fields (Goal, Approach, Why now / what changes). An unfilled
   Summary is the most common one, because it is written first and easiest to
   defer.
2. **Orphan-intent scan** - every `INT-n` in the intent-links table has at least
   one scenario serving it. An intent with no scenario is a stated outcome
   nobody agreed to check.
3. **Untestable-Then scan** - any `Then` phrased as "it works", "is correct",
   "behaves properly", or "feels right". If it cannot fail, it cannot pass.
4. **Ambiguous-quantifier scan** - "quickly", "large", "most", "soon" with no
   number attached. Either attach the number or cut the word.

**This complements the requirements review; it does not replace it.**
The review still runs on the regular and heavier approaches, and it does
things this cannot: it QAs the spec against governance, resolves
contradictions, and records an ambiguity ledger with owners. The
self-check is simply what a spec-author owes the reviewer - the cheap
findings fixed by whoever made them, so the review's attention goes to
the questions that actually need a decision.

### The split, stated plainly

The two overlap enough that a reader meeting both wonders which is redundant.
Neither is. They differ in *who does them*, *what they cost*, and *what kind of
finding they can produce*.

| | Inline self-review (define stage) | Requirements review (its own stage) |
|---|---|---|
| **Who** | the spec-author, alone | spec-author plus reviewer; every role on the full approach |
| **Cost** | minutes - four mechanical scans over one file | a stage; needs reading, and often a human decision |
| **Finds** | placeholder, orphan-intent, untestable-`Then`, ambiguous-quantifier | contradictions between scenarios, gaps across the whole set, governance conflicts, ambiguities that need someone to *choose* |
| **Output** | edits to `acceptance-criteria.md`, in place | `requirements-review.md` - a ledger with a resolution and an owner per entry |
| **Delivery approaches** | every approach, including the quick fix | the regular approach and heavier; collapsed on quick fixes and hotfixes, skipped on spikes |

The dividing line: **the self-review fixes what one person can see and
settle alone; the requirements review resolves what needs a decision.** An unfilled placeholder has
one correct answer and the author already knows it. "Do these two scenarios
contradict each other, and which one is wrong?" does not - and pretending

From ayeo-io/compass, Apache-2.0.

More from ayeo-io/compass