---
title: "Notation"
description: "One standard notation at every step — EARS requirements, Given/When/Then scenarios, ZOMBIES tags, scenario ids in test names."
canonical_url: "https://razcue-agent-kit.vercel.app/en/concepts/notation"
---
# Notation

> One standard notation at every step — EARS requirements, Given/When/Then scenarios, ZOMBIES tags, scenario ids in test names.

<table>
<thead>
  <tr>
    <th>
      Step
    </th>
    
    <th>
      Standard
    </th>
    
    <th>
      Looks like
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Why and scope
    </td>
    
    <td>
      Proposal
    </td>
    
    <td>
      <code>
        work/changes/004-invoices/proposal.md
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Requirement
    </td>
    
    <td>
      <strong>
        EARS
      </strong>
    </td>
    
    <td>
      <code>
        ### invoices.R2 — Totals
      </code>
      
       + <code>
        When an invoice is saved, the BFF shall round its total to 3 decimals.
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Acceptance
    </td>
    
    <td>
      <strong>
        BDD / ATDD
      </strong>
    </td>
    
    <td>
      <code>
        #### invoices.R2.S3 — Rounding edge @boundary
      </code>
      
       + Given / When / Then
    </td>
  </tr>
  
  <tr>
    <td>
      Choosing cases
    </td>
    
    <td>
      <strong>
        ZOMBIES
      </strong>
    </td>
    
    <td>
      one tag per scenario
    </td>
  </tr>
  
  <tr>
    <td>
      Tests
    </td>
    
    <td>
      Traceability
    </td>
    
    <td>
      <code>
        it("invoices.R2.S3 rounds 0.0005 up")
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Test data
    </td>
    
    <td>
      ZOMBIES on data
    </td>
    
    <td>
      <code>
        -- @fixture invoices.R2.S3 @boundary
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      QA
    </td>
    
    <td>
      Checklist
    </td>
    
    <td>
      one item per scenario
    </td>
  </tr>
</tbody>
</table>

## EARS requirements

EARS (Easy Approach to Requirements Syntax) limits each requirement to one sentence in one of these shapes:

<table>
<thead>
  <tr>
    <th>
      Pattern
    </th>
    
    <th>
      Template
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Ubiquitous
    </td>
    
    <td>
      The <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Event
    </td>
    
    <td>
      When <code>
        <trigger>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      State
    </td>
    
    <td>
      While <code>
        <state>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Unwanted
    </td>
    
    <td>
      If <code>
        <condition>
      </code>
      
      , then the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Optional
    </td>
    
    <td>
      Where <code>
        <feature>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Complex
    </td>
    
    <td>
      While <code>
        <state>
      </code>
      
      , when <code>
        <trigger>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

Name a concrete system ("the BFF", "the invoices page"), one behaviour per requirement, and measurable outcomes (`within 15 minutes`, `answers 409`). `agent-kit specs lint` rejects any other shape.

## Scenarios (BDD / ATDD)

Each requirement has scenarios written as examples — `Given` a context, `When` an action, `Then` an observable outcome (`And` / `But` extend a step). They are agreed before code and are the **acceptance tests**.

## ZOMBIES

Pick the scenarios (and the test cases) with ZOMBIES and tag each scenario with the one category it covers:

<table>
<thead>
  <tr>
    <th>
      Tag
    </th>
    
    <th>
      Ask
    </th>
    
    <th>
      Example
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @zero
      </code>
    </td>
    
    <td>
      nothing / empty
    </td>
    
    <td>
      no invoices → empty state
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @one
      </code>
    </td>
    
    <td>
      the single basic case
    </td>
    
    <td>
      one line totals correctly
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @many
      </code>
    </td>
    
    <td>
      several, order, duplicates
    </td>
    
    <td>
      three lines in two currencies
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @boundary
      </code>
    </td>
    
    <td>
      limits and edges
    </td>
    
    <td>
      the 5th failed login blocks; last day of a period
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @interface
      </code>
    </td>
    
    <td>
      the contract
    </td>
    
    <td>
      403 for another provincia; API shape
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @exception
      </code>
    </td>
    
    <td>
      bad input, failure
    </td>
    
    <td>
      invalid code → clear error, nothing saved
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @simple
      </code>
    </td>
    
    <td>
      the happy path
    </td>
    
    <td>
      create and see it in the list
    </td>
  </tr>
</tbody>
</table>

Lint warns when a requirement has no `@exception` or `@boundary` scenario. Money, permissions and data rules always get them.

## Traceability

A test that proves a scenario **starts its name with the scenario id**:

```ts
it("auth.R2.S2 shows the login page for an expired session", () => { /* … */ })
```

A scenario proven without a test (a visual check, a manual flow, an SQL check) gets a ✅ row in the change's `tasks.md`:

```markdown
| auth.R2.S2 | manual: reloaded with an expired token, login shown | ✅ |
```

`agent-kit specs trace` and `agent-kit work trace NNN` list `✗ not covered` scenarios; preflight blocks a done change with any.


## Sitemap

See the full [sitemap](https://razcue-agent-kit.vercel.app/sitemap.md) for all pages.