Most bad specifications fail in one of two ways. Either they are a single sentence of hope (“improve account recovery”), or they are forty pages in which every template heading has been filled in and nobody can find the three decisions that matter. A coding agent handles both badly. With the first it invents the missing decisions. With the second it cannot tell which of the forty pages outrank the others.
A useful specification sits between the two. It is short enough to review properly and specific enough that two different people, or two different agents, would build recognisably the same thing from it.
This part takes one apart, section by section. We are still following Kestrel Mutual, a fictional South African insurer. Kestrel is fictional, and all figures are illustrative. Its feature, SPEC-017, is assisted account recovery: customers who can no longer receive a sign-in PIN on their registered mobile number recover access by passing approved identity checks, without opening a door for SIM-swap fraudsters.
Minimum metadata
Every spec starts with a small block that tells a reader, and an agent, what they are looking at before they read a word of it.
id: "SPEC-017"
title: "Assisted account recovery"
status: "draft"
owner: "Product owner, digital channels"
domain_expert: "Fraud and identity operations lead"
risk: "critical"
mode: "spec-anchored"
systems_affected:
- "Customer portal and app"
- "Identity service"
- "Risk engine"
- "Case management"
open_questions:
- "Q-03: retention period for selfie images (privacy office, due 30 September)"
Each line earns its place. Owner says who can approve a change to this behaviour. Risk decides how much review the change needs (Part 8 covers risk tiers). Mode records that this spec is kept current alongside the code, rather than archived after delivery. Systems affected tells the architect and every agent which boundaries are in play. And open questions being visible at the top means nobody can mistake a draft for a finished decision.
Problem and outcome
This is the section most often skipped, and the one that most shapes what gets built.
Weak:
Make account recovery easier.
Better:
Customers who cannot receive the one-time PIN on their registered mobile number currently phone the contact centre, about 4,000 calls a month. Add an assisted recovery route that verifies approved identity evidence and returns eligible customers to self-service, without weakening account-takeover controls.
The better version names who has the problem, what it costs, what success looks like, and the constraint that must not be traded away. That last clause is the one an agent would never guess. “Easier” on its own pushes a design towards fewer checks. Kestrel’s real outcome is fewer calls with no more takeovers, and those two pull in opposite directions. A spec that says so lets the team, and the agent, make the trade-off deliberately.
Scope and exclusions
In scope:
- start assisted recovery from the sign-in page;
- pass two of three approved evidence types: an identity check through an approved verification provider (ID number plus a selfie liveness check), a one-time code to the email address already on file, and confirmation of a recent policy detail;
- route high-risk attempts to the fraud operations team;
- record every decision and the evidence outcome;
- block banking-detail changes for 72 hours after a successful recovery.
Out of scope:
- replacing primary sign-in;
- replacing the identity provider;
- automatically overriding a fraud block.
Exclusions are not bureaucratic caution. They are instructions. An agent asked to “improve recovery” that notices the identity provider’s awkward session handling will cheerfully start rewriting it. Writing “replacing the identity provider is out of scope” stops that before it becomes a pull request touching the most sensitive code Kestrel has.
Actors and scenarios
Scenarios show the behaviour through concrete examples. The Given, When, Then shape, from behaviour-driven development, reads as plain language while being precise enough to become an automated test. Given sets up the situation, When is the action, and Then is what must be observable afterwards.
Scenario: High-risk recovery requires human review
Given a customer cannot use the registered mobile number
And the risk engine classifies the attempt as high risk
When the customer submits recovery evidence
Then the system must not reset the credential automatically
And an auditable case must be created for an authorised reviewer
Scenario: Banking details are protected after recovery
Given a customer recovered access less than 72 hours ago
When the customer tries to change the bank account for claim payouts
Then the change is refused with an explanation
And the customer is told when the change will be allowed
Choose examples that would catch a wrong implementation, not a long list that all pass trivially. The first scenario pins down the single most important rule in the whole feature. The second exists because a plausible-looking design, one that lets a recovered customer do anything a signed-in customer can, would fail it.
Rules and data
Business rules and data handling are where agents go wrong most quietly, because nothing looks broken. The spec should cover each of these, even briefly:
| Topic | What to state | Kestrel example |
|---|---|---|
| Rule precedence | Which rule wins when two conflict | A fraud block beats successful evidence |
| Authoritative sources | Which system owns each fact | The identity service owns assurance level; policy administration owns contact details |
| Schemas and validation | Shape and limits of the data | RecoveryDecision schema; ID number format checked before calling the provider |
| Error semantics | What each failure means | “Provider unavailable” is not a failed check and never counts towards lockout |
| Retention and classification | How long data lives and how sensitive it is | Selfie images deleted after the approved retention period |
| Idempotency | What a repeated request does | Resubmitting the same evidence never creates a second fraud case |
| Reconciliation | How records are compared | Daily check that every high-risk decision has a matching case |
| Language and accessibility | Who must be able to use it | Plain-language screens, screen-reader support, works on a low-data connection |
Two rows deserve a note. Idempotency means that doing the same thing twice has the same effect as doing it once, which matters whenever a customer taps a button twice on a slow network. And classification is where privacy enters the spec. If the verification check compares the selfie with an identity photo, it processes biometric information, which POPIA treats as special personal information. The spec does not decide the lawful basis for that; Kestrel’s privacy office does. What the spec must do is record that the question exists and who answers it.
Rule precedence is the row teams most often leave out. Without it, an agent that finds two rules in conflict picks one, and you discover which when the fraud team does.
Quality attributes
“Fast, secure and scalable” cannot be verified. Every quality the feature needs has to become a statement someone can test.
| Attribute | Testable example (illustrative) |
|---|---|
| Performance | 95% of recovery risk decisions complete within 800 ms at 100 requests per second |
| Availability | Monthly service level objective of 99.9%, excluding approved maintenance |
| Recovery | Recovery time objective four hours; recovery point objective fifteen minutes |
| Security | No reset completes below the required identity assurance |
| Privacy | Raw evidence is deleted after the approved retention period |
| Observability | Every attempt records a correlation ID, the outcome and the policy version |
Three terms in that table. A service level objective (SLO) is the reliability target the team commits to measure against. The recovery time objective (RTO) is how quickly the service must be restored after a serious failure, and the recovery point objective (RPO) is how much recent data the organisation could accept losing.
Numbers must be grounded in something: load tests, existing traffic, the contact centre’s real call volumes, a regulator’s expectation. Where nobody knows the number yet, the spec should say so and name who will find out. An agent given “fast” will make up a number. An agent given “to be confirmed by the architect by 30 September” will stop and ask.
Requirement language
Words like “must” and “should” mean different things to different readers. Many teams borrow the keywords from RFC 2119, which defines MUST, MUST NOT, SHALL, SHOULD, SHOULD NOT, MAY and a few others. RFC 8174 later clarified that they carry that special meaning only when written in capitals. So “the system MUST NOT reset the credential” is a hard requirement, while “the screen should feel reassuring” is ordinary English. If your team adopts the convention, say so at the top of the spec template. Part 2 showed EARS, another way of giving requirements a consistent shape.
Architecture and acceptance
The spec references principles and decisions rather than restating them. SPEC-017 points to ADR-024: identity decisions remain in the identity domain, and the portal never decides assurance itself. That one reference stops a whole family of plausible designs in which the portal checks evidence locally because it is quicker.
Create a new ADR when a decision will outlive the feature. “Recovery uses an external verification provider behind an adapter” will still matter when the provider changes, so it belongs in an ADR, not in a task list that will be closed next month.
Then define the evidence that will prove the feature works, before anyone builds it:
- unit, contract and integration tests, including TEST-REC-12 for the high-risk path;
- security and privacy tests, including an attempt to bypass the 72-hour banking-detail block;
- performance evidence against the 800 ms target;
- migration and rollback steps;
- business acceptance by the fraud and identity operations lead;
- operational readiness: alerts, a runbook, and a support view for the contact centre;
- the named human approval the risk tier requires.
What makes a requirement good
Test each requirement against seven qualities. It should be:
- necessary: removing it would lose something that matters;
- sufficiently unambiguous: two readers would build the same thing;
- feasible: it can be built with the systems and budget available;
- testable: someone can show it passes or fails;
- traceable: it links to an outcome above it and a test below it;
- owned: someone can approve a change to it;
- prioritised: the team knows what goes first if time runs short.
Unknowns are useful
Every real spec has open questions. They are not a sign of a weak spec. They become defects in only two situations: when someone silently guesses the answer, or when the question is left open forever.
Agents are particularly prone to the first. Ask an agent to implement SPEC-017 while Q-03 is open and it will pick a retention period, probably a sensible-sounding one, and write it into the code where the privacy office will never see it. So pair every unknown with an owner and a date, keep it visible at the top of the spec, and make it a rule of the workflow that an agent stops and asks when a task depends on an open question. Tools such as Spec Kit build a clarify step into their flow for exactly this reason.
What to take from this part
State the outcome and the constraint together. “Fewer calls, with no weaker takeover controls” shapes a design; “easier” does not.
Exclusions are instructions. They stop an agent improving things it was never asked to touch.
Choose examples that catch wrong implementations. Two sharp scenarios beat twenty that pass trivially.
Turn every quality into a testable number, or an owned question. Vague qualities invite invented numbers.
Keep unknowns visible, owned and dated. A silently guessed answer is a defect waiting for a customer to find it.
Next in the series: Intent architecture: from company purpose to one line of code.
How CloudNala can help
We review specifications the way an agent will read them: finding the missing outcome constraint, the rule precedence nobody wrote down, the quality attribute with no number, and the open question an implementation would silently answer. Then we help teams turn what they learn into a spec template short enough that people actually fill it in properly.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Plan an SDD Pilot or write to us at consult@cloudnala.co.za