Prd to gherkin

PRD to Gherkin Feature File Writer

Convert product requirements (PRDs, feature specs, user stories) into well-structured Gherkin .feature files grouped by business Rule, following BDD best practices.

Core Mental Model: PRD → Example Mapping → Feature File

This skill bridges two worlds: product thinking (PRD) and BDD thinking (Gherkin). The translation follows the Example Mapping structure:

PRD Section            →  Gherkin Construct
─────────────────────────────────────────────
Feature Name           →  Feature: <name>
Problem Statement      →  Feature description (narrative)
User Stories (As a...) →  Persona context in Background or step names
MoSCoW Requirement     →  Rule: <business rule>
  Must Have            →  Rule: (generate scenarios first)
  Should Have          →  Rule: (generate after Must Have)
  Could Have           →  Rule: (mark @future tag)
User Story Example     →  Scenario: <happy path>
Constraint / Edge Case →  Scenario: <alternative/error path>
Open Questions         →  # TODO: comment in feature file

The Rule: keyword is the key — it groups related scenarios under the business rule they validate, making the feature file self-documenting and traceable back to the PRD requirement.

---

Step 1 — Parse and Understand the PRD

When given a PRD or feature spec, extract:

1. Feature name — what is being built (1 Feature per PRD section / epic)
2. Primary persona(s) — who the user is (from User Stories or Problem Statement)
3. Business Rules — each Must Have / Should Have requirement maps to one Rule
4. Examples — specific behaviors or edge cases (from examples, constraints, or implicit logic)
5. Open questions — unresolved decisions → add as # TODO: comments

If the PRD is missing critical information to write complete scenarios, ask one targeted question before proceeding. Don't ask multiple questions at once.

---

Step 2 — Structure the Feature File

File naming

Use kebab-case matching the feature name:

payment-onboarding.feature
einvoice-submission.feature
kat-journal-entry.feature

Feature file structure (ALWAYS follow this order)

@[domain-tag]
Feature: [Feature Name from PRD]
  As a [primary persona]
  I want [goal from problem statement]
  So that [business value / outcome]

  Background: (optional — only if ALL scenarios share the same setup)
    Given [shared precondition]

  Rule: [Business Rule — extracted from MoSCoW requirement]

    Scenario: [Happy path — what success looks like]
      Given [initial state — who and what context]
      When [action the persona takes]
      Then [observable outcome]

    Scenario: [Alternative / Edge case]
      Given [different initial state]
      When [same or related action]
      Then [different observable outcome]

  Rule: [Next Business Rule]

    Scenario: [...]
      ...

---

Step 3 — Apply BDD Quality Rules

For every scenario generated, enforce these rules (from bdd-practices):

Cardinal Rules

• One scenario = one behavior. If you find yourself writing When... Then... When... Then... → split into two scenarios.
• Declarative over imperative. Never describe UI actions (click, enter, navigate). Describe business intent.
• Third person, present tense. the user logs in not I logged in or user will log in.
• 3–5 steps per scenario (max 9). If longer, abstract repeated setup to Background: or persona steps.

Rule quality check

Each Rule: should be:

• A business rule statement, not a technical statement
  • ✅ Rule: Only active merchants can submit invoices
  • ❌ Rule: Check merchant status in database before API call
• Traceable to a specific MoSCoW requirement in the PRD
• Testable — you can write at least 2 distinct scenarios for it (happy + edge)

Scenario quality check

Each Scenario: title should:

• Complete the sentence: "This system works correctly when..."
  • ✅ Scenario: Active merchant submits invoice with valid data
  • ❌ Scenario: Test submit button
• Not repeat the Rule name verbatim

---

Step 4 — Apply Tag Taxonomy

Tags serve three purposes: documentation, CI/CD pipeline slicing, and test layer routing (which runner executes this scenario).

Every scenario should have exactly one tag from each dimension:

Scenario = [test layer] + [execution scope] + [priority] + (optional domain)

Example: @api @smoke @regression
         @web @regression @p2
         @integration @smoke

---

Dimension 1 — Test Layer (REQUIRED on every Scenario)

This is the most important tag — it tells the CI runner which test harness to use.

Tag	Layer	When to use	Runner
@web	E2E / Browser	User-facing flows that require a browser — login screens, form submissions, UI state changes	Playwright + Cucumber
@api	API	Business logic verified via HTTP calls — no browser needed; the behavior is the API contract	REST client + Cucumber
@integration	Integration	Cross-service / cross-system flows — service A triggers something observable in service B	Multi-service test environment

Decision guide — which layer?

Ask: "Where does the core behavior live?"

Business rule is enforced in the backend (validation, calculation, state machine)
  AND the scenario doesn't require seeing a UI element
  → @api

The user must interact through a browser (UI state, navigation, form rendering)
  OR the acceptance criterion is about what the user SEES on screen
  → @web

The scenario spans two separate services / systems
  (e.g., POS emits an event → accounting system receives it)
  → @integration

Rule: never mix layers in one scenario. If a scenario needs both browser interaction AND a service call side-effect, split into:

• @web scenario: verifies UI behavior
• @integration scenario: verifies downstream effect

---

Dimension 2 — Execution Scope (REQUIRED on every Scenario)

Tag	When to use
@smoke	Happy path only — 1–2 per Rule max. Runs on every push.
@regression	All other scenarios. Runs on PR / nightly.
@wip	Under active development, expected to fail. Excluded from CI.
@future	Not yet automated (Could Have). Serves as living documentation.

---

Dimension 3 — Priority (maps to PRD MoSCoW)

PRD Priority	Tag	CI behavior
Must Have	(no tag — default)	Always runs
Should Have	@p2	Runs in full suite
Could Have	@p3 @future	Excluded from automation

---

Dimension 4 — Domain (on Feature block, optional per team)

Customize these to your product areas. Examples:

Tag	Domain / Area
@[domain1]	e.g., @billing
@[domain2]	e.g., @auth
@[domain3]	e.g., @reporting

---

Full example with layer tags

@billing @einvoice
Feature: Invoice Submission

  Rule: Only active subscribers can issue invoices

    # Business rule lives in API — no browser needed
    @api @smoke
    Scenario: Active subscriber issues an invoice successfully
      Given Minh has an active paid subscription
      And Minh has a completed order
      When Minh calls the invoice submission API
      Then the API returns 201 Created
      And the invoice status is "Submitted"

    @api @regression
    Scenario: Free-tier user is rejected by the API
      Given Lan has a free subscription
      When Lan calls the invoice submission API
      Then the API returns 403 Forbidden
      And the error message is "Subscription upgrade required"

  Rule: Invoice form pre-fills with order data

    # Requires seeing the rendered form — browser needed
    @web @smoke
    Scenario: Invoice form opens pre-filled with order data
      Given Minh has completed order #ORD-001
      When Minh opens the invoice form for the order
      Then the invoice form displays the order's products and amounts
      And the buyer information is pre-filled from the order

  Rule: Issued invoices sync to the accounting system

    # Cross-service: POS issues invoice → accounting receives journal entry
    @integration @smoke
    Scenario: Issued invoice creates a journal entry in accounting
      Given Minh has issued invoice #INV-001
      When the sync process runs
      Then a journal entry appears in the accounting system for #INV-001

    @integration @regression
    Scenario: Failed sync triggers an alert after 3 retries
      Given invoice #INV-001 has been issued
      When the accounting sync fails 3 consecutive times
      Then the system sends an alert to the accountant
      And the invoice is marked "Sync pending"

  Rule: Merchants can preview invoice before issuing

    @web @regression @p2
    Scenario: Merchant edits buyer info in the preview
      Given Minh is viewing the invoice preview for order #ORD-001
      When Minh updates the buyer's tax code in the preview
      Then the updated tax code appears in the preview form

  Rule: Merchant receives SMS on invoice approval

    @api @future @p3
    Scenario: Merchant receives SMS when invoice is approved
      Given Minh has a mobile number registered
      When the tax authority approves invoice #INV-001
      Then Minh receives an SMS notification with the approval reference

---

Tag combinations cheat sheet

Scenario type	Tags to use
Core business logic, backend only	@api @smoke or @api @regression
UI flow, user-visible behavior	@web @smoke or @web @regression
Service A → Service B side effect	@integration @smoke or @integration @regression
Should Have API scenario	@api @regression @p2
Could Have, not yet automated	@web @future @p3 (or @api @future @p3)
Active development, may fail	@web @wip

---

Step 5 — Handle Scenario Outline (Parametrization)

Use Scenario Outline ONLY when:

• Multiple equivalence classes exist (not just different data values)
• The behavior changes meaningfully per row
• The table has ≤ 5 rows (more → extract to step definitions or test data files)

# ✅ Good use — different subscription tiers = different behavior
Rule: Access level matches subscription tier

  Scenario Outline: Member accesses content matching their subscription
    Given <user> has a <tier> subscription
    When <user> requests <content_type>
    Then the system <grants_or_denies> access

    Examples:
      | user  | tier    | content_type    | grants_or_denies |
      | Minh  | free    | premium article | denies           |
      | Lan   | basic   | premium article | grants           |
      | Hung  | premium | premium article | grants           |

# ❌ Bad use — same equivalence class, different strings
Scenario Outline: Search returns results
  When the user searches for "<term>"
  Then results related to "<term>" are displayed

  Examples:
    | term     |
    | invoice  |
    | receipt  |   # Same behavior, wastes CI time
    | payment  |   # Same behavior, wastes CI time

---

Output Format

Always output:

1. One .feature file per PRD epic/feature (not one file per requirement)
2. Summary table after the file showing traceability:
3. Vietnamese language for all steps, unless the PRD is in English and explicitly states to keep it in English and keep Gherkin syntax in English.

## Traceability Matrix

| Rule | PRD Requirement | Scenarios | Tags |
|------|----------------|-----------|------|
| Only active merchants can submit | Must Have #1 | 2 | @smoke @regression |
| Invoice total must match line items | Must Have #2 | 2 | @regression |
| Draft invoices can be edited | Should Have #1 | 3 | @regression @p2 |

3. Open questions block if PRD has unresolved items:

## ⚠️ Open Questions (from PRD)

These items need clarification before scenarios can be written:

- [ ] What happens when merchant submits duplicate invoice number?
      → Needed for: Rule "Invoice number must be unique"
- [ ] Is there a timeout for draft invoice expiry?
      → Needed for: Rule "Draft invoices can be saved"

---

Reference Files

• references/mapping-guide.md — Detailed PRD section → Gherkin construct mapping with examples
• references/domain-glossary.md — Domain terms for consistent step language across feature files

Read mapping-guide.md when the PRD format is unusual or when you're unsure how to extract Rules from the requirements structure.