Gurki

A tiny flavour of Gherkin for describing systems — what exists, what happens, what is produced, what changes, and what becomes possible next.

You can learn it in five minutes. That is the point.

Gurki is not a Cucumber dialect. Cucumber lets you translate Given / When / Then; it cannot add Output, Outcome, or Activates as first-class step kinds. The body stays line-oriented like Gherkin so the parser is a small extension, not a new grammar.

A sports-day first-aid tent

A cost line is easy. Gurki is for the products a spreadsheet drops: hours, treated injuries, a career pathway — and the outcome that the volunteer is now financially stressed. That is why the sports day can run, and what it costs the person who made it run.

System: Sports-day first aid

Scenario: A student volunteer covers the school sports day
Given a secondary school sports day with no paid medic
And a Year 13 student who has paid for a first-aid certificate
When the sports day runs
Then injuries are treated on the field
Output 6 treated injuries
And 8 volunteer hours
And $175 certificate fee paid by the student
Outcome the student holds event-first-aid experience toward a health career
And the school can run the day without hiring a medic
But the student is financially stressed by the unpaid day and the fee
Activates A teenager sits a first-aid certificate

System Outputs
6 treated injuries
And 8 volunteer hours
And $175 certificate fee paid by the student

System Outcomes
the student holds event-first-aid experience toward a health career
And the school can run the day without hiring a medic
But the student is financially stressed by the unpaid day and the fee

The same shape shows up in Wellington Free Ambulance event medics and Red Cross volunteer medical certificates. See examples.

Keywords

Each keyword answers one systems question. The closed set is keywords.json.

Keyword	Question
System	What system are we modelling?
Scenario	What event-path are we examining?
Given	What already exists?
When	What event occurs?
Then	What immediately happens?
Output	What was produced or transferred?
Outcome	What is now different?
Activates	What could happen next?

System: holds a set of scenarios — Gherkin's Feature, named for systems. After the scenarios, a value report lists every Output and every Outcome in appearance order:

Keyword	Question
System Outputs	What did the whole system produce?
System Outcomes	What is now different for the whole system?

Those two lines are derived from the scenarios. They read as one Gherkin chain: the primary positive as a statement, then And, then one But, then more And. Heterogeneous texts ($276 levy, 8,400 dwellings) stay as separate lines. gurki decode regenerates them.

And is a further positive; But is the strain or the loss. Without that split, the student is financially stressed sits in the list looking like a benefit.

Inherited from Gherkin (not Gurki inventions): And / But continue the previous step kind; # starts a comment.

Step kinds are first-class. Output is not an alias of Then.

Any subset of step kinds is valid. The intended shape is the full lifecycle in that order.

Explicitly not keywords

Write these as facts in sentences, or classify them later in software:

Actor, Input, Capability, Asset, Risk, Opportunity, Constraint, Cost, Benefit, Impact, Measure.

Also out of v0.1: Background, Rule, Scenario Outline. Gherkin Feature is System: here. Frontmatter remains file metadata.

One language, two envelopes

Same Gurki body everywhere. Only the envelope differs.

Book / prose — ordinary markdown. Embed scenarios as fenced gherkin blocks. No *.spec.md required. Gurki is a representational language, like a diagram.

There is no Gurki highlighter. Book fences use gherkin so the editor's Gherkin grammar can run. It colours a closed keyword list at the start of the line (Scenario:, Given, When, Then, And, But, # comments). System:, Output, Outcome, Activates, and the value-report headings usually stay uncoloured.

Modelling / simulation — *.spec.md files. YAML frontmatter first (qmd-ready), then the same Gurki body. This is what the linter and encoder consume.

Do not invent Cucumber Markdown-with-Gherkin (# Scenario, * Given). That is extra syntax. One body syntax everywhere.

The specification is the machine-oriented contract.

Conventions

These are writing style, not syntax:

• Prefer observable facts over opinions.
• Put quantities and money in Output. Hours, certificates, and treated injuries belong there too — Output is not only a dollar line.
• Put capabilities, pathways, and other stock changes in Outcome, including strain on the people the system relies on.
• Loss of life: Output the death without a name (1 dead pilot); Outcome is a grieving family and community.
• Then describes immediate consequences only.
• Activates should name another Scenario where possible.
• Actors live in the sentences, not as keywords.
• Put a System: above the scenarios it groups. The value report is derived; do not hand-edit System Outputs / System Outcomes as a second source of truth.
• Prefer named, real operations people can look up. Say which figures are sourced and which are sketches.
• Time in steps is elapsed duration (after 22 days), not a calendar date. Absolute dates belong in the note, and only when the spec is a named historical incident.

Net outputs and outcomes

A listing double-counts a system that builds a thing and then dismantles it. System Net Outputs and System Net Outcomes roll the listing up by account:

System Net Outputs
units in private accounts: net -29,015,800 NZU, churn 38,993,770 NZU

System Net Outcomes
units in private accounts: net increase
outstanding compliance obligation: net decrease

Churn is the sum of absolute movements, and it only prints when movements offset each other. That is the point: nearly 39 million units moved to produce a net fall of 29 million, and an account that cancels out exactly still reads as jobs: net 0, churn 24 rather than as nothing having happened.

Netting needs judgement the parser does not have — nothing in the text says 12 jobs created and 12 jobs cut are one account. So it comes from an analysis sidecar, where each step carries a ledger entry naming the account, a direction, and an optional quantity. Outcomes carry no quantity and net by direction alone.

The net sections are derived like the listing, so decoding without --analysis drops them. Worked example: NZ ETS. How to run the toolchain is on the workbench.

Status

v0.1 is the language plus a deterministic workbench (parse / lint / encode / decode / compare / analysis check) and a mixin skill. There is no Gurki highlighter; book fences use gherkin. Simulation is out of scope. Resist new keywords until the examples hurt.