Risk rules are the best specification target in regulated software, and the worst-written. They are numeric, they are stateful over a window, and the failures are expensive and quiet.
This guide covers the four things a risk specification must get right. All four are cases where a reasonable implementer reading an ambiguous requirement produces a different system than the one that was intended — and neither is obviously wrong.
Thresholds are not self-describing
"A position above 500,000 triggers a margin call" does not say what "above" means, what the 500,000 is measured in, or what happens at exactly 500,000.
Feature: Net position limit
Background:
Given account "ACC-9" has a base currency of EUR
Scenario: A position within the limit is accepted
Given account "ACC-9" has an open net position of 499,999.99 EUR
When account "ACC-9" requests a new position of 0.01 EUR
Then the request is accepted
And account "ACC-9" has an open net position of 500,000.00 EUR
And no margin call is issued
Scenario: A position beyond the limit is rejected
Given account "ACC-9" has an open net position of 500,000.00 EUR
When account "ACC-9" requests a new position of 0.01 EUR
Then the request is rejected with code "NET_POSITION_LIMIT_EXCEEDED"
And account "ACC-9" has an open net position of 500,000.00 EUR
Three details make this work, and each of them is a decision that would otherwise be made by accident:
The boundary is included in the limit. 500,000.00 is permitted; 500,000.01 is not. The first scenario asserts exactly that — it puts the position exactly at the limit and asserts acceptance. That single clause is often the entire difference between the specified system and the built one.
The unit is stated. EUR, not "the base currency", and not a bare number. In a system with multiple accounts and currency conversion, a bare number is not a specification.
The state after rejection is asserted. "The request is rejected" and "the position is unchanged" are different facts, and only the second one tells you whether the order was aborted before or after the position was updated.
Aggregation windows are part of the rule
Turnover limits, daily loss limits, and rate limits are all measured over a window, and the window’s definition is where implementations diverge.
Scenario: The daily loss limit is measured over the trading day
Given the trading day started at 00:00 UTC
And account "ACC-9" has realised losses of 25,000 EUR today
When account "ACC-9" realises a further loss of 5,001 EUR
Then the order is rejected with code "DAILY_LOSS_LIMIT_EXCEEDED"
Scenario: The trading day resets at 00:00 UTC regardless of local time
Given the current time is 23:59:59 UTC
And account "ACC-9" has realised losses of 25,000 EUR today
When the current time is 00:00:01 UTC
Then account "ACC-9" has realised losses of 0 EUR today
The second scenario is worth its weight in gold. "The trading day" is ambiguous between UTC, the exchange’s local time, and the account’s local time. All three are defensible. Without an explicit scenario, the choice is made by whoever wrote the code, and it is invisible until a loss limit fires at the wrong moment for one account and not another.
Every window needs three clauses: when it opens, when it closes, and what happens exactly at the boundary.
Currency conversion is a rule with a timestamp
Any limit expressed in the account’s base currency implies a conversion, and the conversion has a timestamp.
Scenario: A position is converted at the reference rate at order time
Given account "ACC-9" has a base currency of EUR
And account "ACC-9" has an open net position of 100,000 USD
And the reference rate at order time is 0.92 EUR per USD
When account "ACC-9" requests a new position of 50,000 USD
Then the new position is valued at 46,000 EUR
And the total net position is 138,000 EUR
"at order time" is doing real work. The alternatives — the valuation time, the previous close, the mid-market at the moment of evaluation — are all reasonable, all different, and all produce different results near a limit.
And the case where the rate is unavailable is the one that matters most, because it happens:
Scenario: A valuation is refused when no reference rate is available
Given account "ACC-9" has a base currency of EUR
And no reference rate is available for USD at order time
When account "ACC-9" requests a new position of 50,000 USD
Then the request is rejected with code "REFERENCE_RATE_UNAVAILABLE"
Failing closed versus failing open is a risk decision with a large price tag. It has to be written down, and it has to be the same decision for every limit that depends on it.
Stale data is a state, and it needs a rule
Risk systems read market data. Market data is late, stale, or missing. What the system does then is a rule, and it is a rule with real money attached.
Scenario: A limit is not evaluated against stale price data
Given the market price for "ACME" is 3 minutes old
And account "ACC-9" holds 200,000 ACME
When account "ACC-9" requests a new position in ACME
Then the request is rejected with code "PRICE_DATA_STALE"
Staleness thresholds are usually defined in configuration rather than in code, and that is fine — but the behaviour at the threshold still belongs in the specification. A limit evaluated against stale data is not a conservative approximation; it can produce a false accept, which is the failure mode that actually loses money.
What to leave implicit
- Matching and fill algorithms. Price-time priority versus pro-rata is a venue decision, not a risk rule, and it does not belong in a risk specification.
- Order types and execution semantics. Stop, limit, market — these belong to the execution specification, not the risk one.
- Performance targets. Latency budgets are SLOs, not clauses.
The review question for this domain
For each clause, ask:
Would a risk manager recognise this as their rule?
Not "would a developer understand it" — a developer will understand almost anything. A risk manager recognising their own rule in the specification is the signal that it has been stated correctly, in the right units, at the right boundary, and that it does not depend on a paragraph of prose nobody will read in six months.
If the answer is no, the clause is not ready. Rewrite it in the risk manager’s terms, with their numbers, and their boundaries.
Related
- Gherkin feature files — format and conventions
- Gherkin for payment and refund workflows — the same shape of problem, smaller stakes
- Assertion strength — why "the limit is enforced" is not an assertion