For most of the history of software delivery, a weak requirement was quietly repaired by people. A developer who had worked on the claims system for six years read "the claim should be closed when complete" and knew what complete meant, including the exceptions nobody had written down. A tester who knew the business caught the case the developer forgot.
Agents do not carry that tacit knowledge. Give an agent a vague requirement and it will produce a confident, plausible implementation of whatever the words most likely mean. It will also generate tests that pass. The repair that people used to make silently now has to be made explicitly, in the specification, before the agent starts.
That makes specification literacy an organisational capability rather than an analyst's specialism.
Kalahari Assurance is fictional, and its systems and figures are illustrative. In Part 1 Kalahari's claims team discovered that an agent-generated suite had passed in full while missing the most important rule: a claim must not be closed while a fraud referral is open. The rule was well known. It was not in the specification, because everybody already knew it. The agent did not.
Specification-driven development is covered elsewhere
CloudNala has published a full series on spec-driven development, including the anatomy of a useful specification and how team structures change. This article does not repeat that material. Its question is narrower: in an organisation of several hundred people, what does each role need to know, and how do you teach it?
The four parts every reader should recognise
Kalahari's training uses a simplified view of a specification with four parts. Different methods use different templates, but these four appear in almost all of them:
- Intent and outcome. Why the change exists, who it serves and how success will be recognised.
- Acceptance criteria. Observable conditions that must be true for the change to be accepted, including the edge cases.
- Constraints and non-functional requirements. Performance, security, data handling, compatibility and regulatory limits.
- Agent boundaries. What the implementing agent may read, change and call, what it must not touch, and when it must stop and ask.
The fourth part is newer than the others, and it is the one most often missing. It is also the part that turns a specification from a description into a control surface.
Who does what
Every role touches every part, but differently. Kalahari agreed a simple working arrangement and made it part of the shared foundations:
A few points in that matrix are worth drawing out.
Analysts write, but do not own alone. Analysts write intent and acceptance criteria, with designers and testers co-writing. That is a change for organisations where the analyst produced a document and handed it on.
Architects own constraints and boundaries. Agent boundaries are an architectural decision. Which systems may an agent touch in this change? Which data classes may pass through the model? Those answers come from the same people who own the system's structure.
Testers co-write acceptance criteria. The most effective change Kalahari made was to bring testers into criterion writing before implementation. A tester asks "how would I prove this?" at the moment it is cheapest to fix the answer.
Leaders approve, and therefore must read. A leader who approves a specification's constraints and boundaries is accepting risk. Approving without reading is not delegation; it is absence. Leaders do not need to write criteria. They do need to recognise when a boundary is too wide.
Engineers mostly use, but must push back. The engineer running the agent is often the first person to notice that a criterion is ambiguous. Part of their training is to stop and send it back rather than let the agent choose.
Reading one criterion three ways
The shortest useful exercise in Kalahari's programme takes a single acceptance criterion and has three roles read it, each asking a different question.
The analyst asks whether this is the rule the business actually wants. Should a file over 10 MB be refused, or compressed, or accepted from brokers but not policyholders? The tester asks whether it can be proved, including the edges: what happens at exactly 10 MB, and with a file that claims to be small but is not? The agent, or the engineer acting for it, asks whether it can be implemented without guessing: what reason should the refusal give, and in which languages?
Run that exercise on twenty criteria from a team's own backlog and the gaps become obvious. It takes an hour and changes how people write.
What to teach, role by role
Kalahari's specification module is the same two hours for everyone, followed by one role-specific session:
| Role | Role-specific focus | Work product that completes the module |
|---|---|---|
| Analyst | Writing testable criteria and explicit exceptions | A specification reviewed by a tester and an engineer |
| Architect | Writing constraints and agent boundaries | Boundaries for one live change, approved by the risk owner |
| Engineer | Recognising ambiguity and stopping the agent | A rejected or clarified criterion from a real change |
| Tester | Deriving independent checks from intent | Intent-derived checks written before implementation |
| Designer | Specifying the human steps: correction, approval, error states | Criteria for one user-facing error path |
| Leader | Reading boundaries as risk acceptance | A recorded approval with one question asked |
The work products are the point. A module that ends with a reviewed artefact from real work produces evidence that the learning happened, which Part 7 returns to.
Plain wording is a capability too
Specification literacy is partly about structure and partly about language. In a South African organisation, a large share of the people writing and reading specifications work in English as a second or third language. That is normal and it is not a weakness, but it does change what good writing looks like.
Long sentences with several conditions, idioms, and words with more than one meaning are where ambiguity hides. "The claim should be finalised promptly once all documents are in" contains three words a reader might interpret differently: finalised, promptly and all. A model will pick one interpretation and implement it confidently. A colleague reading in their second language may pick another.
Kalahari added a short section on wording to the shared specification module. Its rules are simple: one condition per sentence where possible; the same word for the same thing every time; no idioms; numbers and units rather than "promptly" or "large"; active voice so it is clear who or what acts. Controlled-language approaches from technical writing, developed for exactly this problem in maintenance documentation, are a useful reference for teams that want to go further.
The effect was measurable in a small way: the number of criteria sent back by engineers as ambiguous fell, and the questions that remained were about the business rule rather than the wording.
Common failure modes
Three patterns show up repeatedly when organisations try this:
- The specification becomes a second backlog. Teams write long documents nobody reads. The fix is to keep specifications small and tied to one change, as the governance article in the SDD series describes.
- Agents write the specification and the code. If the same agent drafts the criteria and implements them, the criteria describe what the agent was going to do anyway. A human must own the intent and approve the criteria.
- Boundaries live in someone's head. If the architect knows the agent must never write to the policy ledger but that is not in the specification or the harness, it is not a boundary.
Next: Part 4, From personal tools to a governed team toolchain. All parts are on the series page.
How CloudNala can help
We help delivery teams build specification literacy across roles: a short shared module, role-specific sessions anchored to the team's own backlog, and a working agreement for who writes, reviews and approves each part of a specification. Where useful we also review a sample of live specifications and show where an agent would have had to guess.
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 AI Capability Programme or write to us at consult@cloudnala.co.za