| name | gherkin-gate |
| description | Use before writing any test or implementation task, when observable behavior needs to be captured in business language scenarios and approved by the user before code begins |
Gherkin Gate
Overview
Capture observable behavior in business language before any test or code is written. User approval is the mandatory gate.
Hard rule: No test, no task, no implementation until scenarios are approved.
Writing Scenarios
Write 1-3 scenarios in Given/When/Then:
GIVEN [precondition in business language].
WHEN [action in business language].
THEN [observable outcome in business language].
Each scenario should be independent and verifiable in isolation. Cover the main success path and 1-2 key edge cases.
Spec-Leakage Rule (CRITICAL)
Scenarios must describe external observables only. Never reference implementation details:
| Forbidden | Allowed |
|---|
| Class names, method names | Business actions and actors |
| Repository, database, tables | Data in business terms |
| HTTP endpoints, status codes | Business outcomes |
| Internal state, variables | Observable system behavior |
❌ BAD: GIVEN the EligibilityPolicy has empty rules.
✅ GOOD: GIVEN no eligibility rules are configured.
❌ BAD: THEN the handler returns a 200 OK response.
✅ GOOD: THEN the request is accepted.
❌ BAD: WHEN I call POST /api/eligibility.
✅ GOOD: WHEN checking eligibility for the user.
Approval Gate
- Present scenarios clearly labeled: "Gherkin Scenarios — awaiting approval"
- WAIT for explicit user approval before proceeding
- If rejected: revise scenarios and repeat from step 1
- Only after approval: proceed to test writing or task planning
This gate is not skippable — even for "small" features.
Common Mistakes
| Mistake | Fix |
|---|
| Skipping scenarios for "trivial" features | Write 1 scenario minimum — even simple features benefit |
| Implementation details in scenarios | Business language only in Given/When/Then |
| Proceeding before explicit approval | "ok" or "proceed" counts, silence does not |
| More than 3 scenarios up front | Start with main success path, add edge cases after RED |
