Frame: Problems, Requirements and Intent

Every piece of software starts as somebody's problem, and every defect that is not a coding slip starts as a gap between that problem and what was built. This chapter concerns D1 Frame, the first of the five developer functions defined in Chapter 4: understanding the problem, fixing intent as requirements and acceptance criteria, and keeping the specification that others can verify against. It treats framing without AI first, at some length, because the later question of what AI adds and what it distorts can only be answered against a clear picture of what a person does well when nobody helps. A reader who knows what a good specification looks like will see at once which part an assistant can draft, which part it must not own, and which part it quietly damages.

The argument has five steps. Understanding the problem comes before stating a requirement, and ambiguity is the cost that framing exists to remove. A requirement becomes useful when it can be checked, which is what an acceptance criterion is. The specification is the source of intent, and when code is generated cheaply it becomes the most valuable artefact in the repository. AI adds capacity to drafting, questioning and summarising, and the same properties produce failures that are specific to framing. A specification record, shown at the end with a worked example for Nordvik Region and a contrast from Hansa Mutual, makes the five steps reviewable.

From need to executable specification, with the human decision points

Figure 5.1: From need to executable specification: research, open questions, the product owner's decision on scope, the record, and tests written before generation.

The chapter builds on conclusions of the earlier volumes. Architecture as Code (Chapter 4) set the discipline of short, numbered, immutable decision records kept beside the code (161, Nordqvist, 2025), and the specification record of this chapter applies it to intent instead of design. AI Governance, Chapter 13, set the tiering of decisions: routine decisions at pipeline gates, exceptions at a design authority (162, Nordqvist, 2026); a specification that departs from policy is such an exception. AI Platform and Security, Chapter 5, set the rule that a record is validated against a schema and re-opened by evidence (163, Nordqvist, 2026). AI Red Team, Chapter 10, placed threat models in code beside the architecture (164, Nordqvist, 2026), which is where the security requirements of this chapter belong too. AI Leader, Chapter 6, showed that AI adds capacity to orientation and that the same properties produce homogenised advice, hallucinated evidence and sycophancy to the framing of the question, and that a briefing therefore carries provenance, a dissent field and independent sources (174, Nordqvist, 2026). Requirements work is orientation at the scale of one product, and this chapter reuses that conclusion. The stewardship principle of Chapter 4 reaches back to this chapter in one place: the test oracle must be independent of the generator, and the oracle starts life as the acceptance criteria written here.

Understanding the problem

A request arrives as a solution. A case handler asks for a new field in a form, a product owner asks for a button, a regulator's guidance becomes a ticket titled "add consent checkbox". Framing begins by asking what the person who asked is trying to achieve, for whom, and how anyone would know it had been achieved. The distinction between problem and solution is old, and the reason it keeps being restated is that the shortcut is always attractive: the solution is concrete and can be started on Monday.

Frederick Brooks put the difficulty in terms that have lasted. In "No Silver Bullet", reprinted in the anniversary edition of The Mythical Man-Month, he separated the essential difficulties of software, which come from the nature of the thing, from the accidental ones, which come from the tools, and argued that the hardest single part of building a software system is deciding precisely what to build (215, Brooks, 1995). The essay is an argument from experience and not a measured effect, and it was written long before generative AI. Its relevance here is structural. If tools reduce the accidental difficulty of turning a specification into code, then the essential difficulty, knowing what the specification should say, becomes a larger share of what remains. That is a conclusion of this book, labelled as such, and Chapter 2 gives the evidence on how developers spend their time.

Three practices make up understanding the problem.

Talk to the people who have the problem. User research is the means. For a citizen service it means case handlers who receive the applications, the citizens who fill them in, and the staff on the telephone who hear what went wrong. A single conversation with the person who wrote the ticket gives one account of the need, and an account is not evidence. Observed work, a sample of real submissions, call-centre reasons and complaint categories are evidence. The practical test is whether the framing contains at least one source that the person who raised the need did not choose.

Learn the domain language and use it. Dan North's account of behaviour-driven development, which took from Eric Evans's domain-driven design the idea of a ubiquitous language based on the business domain and applied it to the analysis process itself: analysts, testers, developers and the business should use one vocabulary, so that a statement made in a meeting can be turned into a test without translation (123, North, 2006). In a regional administration that vocabulary includes words such as applicant, household, decision, reassessment and appeal, each with a legal meaning that the developer must not paraphrase. When the form says "income" and the legislation distinguishes four kinds of income, the specification must say which one.

Name the constraints that are not negotiable. Some requirements do not come from a user. Accessibility of a public-sector service is one: Directive (EU) 2016/2102 requires Member States to ensure that the websites and mobile applications of public sector bodies are perceivable, operable, understandable and robust (Article 4), allows an exception for a disproportionate burden (Article 5), which the body must then explain in its accessibility statement (Articles 5(4) and 7), and presumes conformity where content meets the harmonised standards or, in their absence, the European standard EN 301 549 (Article 6) (14, European Union, 2016). Data protection is another. The GDPR requires data protection by design and by default in Article 25, which for a form means that only the personal data necessary for each purpose is collected by default, and a data protection impact assessment under Article 35 where processing is likely to result in a high risk (4, European Union, 2016). These are implications for the requirement set, not legal advice, and they belong in the specification as requirements with a source, so that a later reader can see which are choices and which are duties.

The cost of ambiguity

Ambiguity is the cost that framing exists to remove, and its cost grows with the distance it travels. An unclear sentence in a ticket is cheap to clarify in the meeting where it is written. After a design has been drawn around it, the clarification costs a design change. After it has been coded, it costs a code change and a test change. After release, it costs a correction of data and, in a public authority, possibly a corrected decision to a citizen. This is an argument from the structure of the work, and the book's own conclusion. The widely repeated numeric curves that put a factor on each stage are not used here, because the sources for them are contested and none has been verified for this book.

Three kinds of ambiguity deserve names, because they need different remedies.

Kind Example Remedy
Vocabulary "Household" in the form means the applicant's family; in the case system it means everyone at the address A glossary entry in the specification, agreed with the case handlers
Scope "Make the application easier to complete" has no edge A list of what is out of scope, with the reason
Condition "Applicants who need help" does not say how need is established A scenario for the boundary cases, and a named person who owns the rule

The third kind is where framing meets the law. A condition that decides who receives a benefit or an obligation is a rule, and the person who may set it is named in legislation or in a delegation. The developer does not choose it, and neither does an assistant.

Requirements and acceptance criteria

A requirement is a statement of something the system must do or be, with a reason that can be traced to a need. The international standard for requirements engineering, ISO/IEC/IEEE 29148, gives guidance on applying the requirements processes of the system and software life-cycle standards and specifies the information items that those processes produce (24, ISO/IEC/IEEE, 2018). The book does not reproduce the standard, which is paid for and was read here only at the level of its catalogue entry, and takes from it one point: requirements work has processes and information items, and a team that has none is practising it anyway, only implicitly.

From need to testable statement

A need becomes a testable statement in three moves. The first is to separate kinds of requirement, because each kind is checked differently.

Kind What it states How it is usually checked
Functional What the system does for a user in a situation Scenario tests
Quality How well: response time, availability, readability, accessibility Measurement against a threshold, audit against a standard
Constraint What the solution must or must not use: a platform, a data location, a licence Review, automated policy check
Legal and policy What a duty requires: Directive 2016/2102, GDPR Article 25 Conformity evidence, review by the named function

The second move is to attach a reason and a source to each requirement. A requirement without a source cannot be challenged, and one that cannot be challenged cannot be removed when the need goes away.

The third move is to write the acceptance criterion in a form that a test can check. North's formulation is the most widely used: an acceptance criterion is a scenario with a context, an event and an outcome, "given some initial context, when an event occurs, then ensure some outcomes", and the description of a story's behaviour is simply its acceptance criteria (123, North, 2006). A criterion such as "the form is easy to use" fails the test of testability. A criterion such as "given an applicant who uses only a keyboard, when they complete and submit the form, then every field is reachable in a logical order and the confirmation is announced by a screen reader" can be run, and it can fail.

The discipline has one further rule that matters more with AI than before. The acceptance criteria are written, or at least adopted, by a named person before code is generated, and the person who owns them is not the generator. This is the first half of the corollary of the stewardship principle in Chapter 4, the independence of the test oracle. If an assistant writes the code and then writes the criteria that the code is tested against, the criteria will reflect what the code does, which is a different thing from what the user needs. Chapter 9 treats the oracle in full; here it is enough to note where the oracle comes from.

Specification as the source of intent

A specification is the place where intent is recorded in a form that people and tools can act on. For many years it was a document that drifted from the code. Two changes make the specification more important and make it harder to let it drift. Generative tools turn a precise description into working code in minutes, so the quality of the description becomes the quality of the first draft. And the code that comes out is often read less carefully than code a person typed, so the specification is the only place left where the intent is stated in words that someone chose.

Spec-driven development

Spec-driven development is the name now given to working from the specification first. In the description of the open-source toolkit that GitHub published in September 2025, the specification is "a contract for how your code should behave" and the source of truth that tools and agents use to generate, test and validate code. The toolkit's workflow has four phases: specify, in which the developer describes what is being built and why and the coding agent drafts a specification of user journeys and success criteria; plan, in which technical direction is added; tasks, in which the work is broken into small, reviewable pieces; and implement, in which the agent works through the tasks while the developer reviews focused changes and verifies the output at each phase (122, Delimarsky, 2025). The source is a vendor's description of its own toolkit. It describes a workflow and says nothing about outcomes, and this book claims no more for it than that: it is a published way of ordering the work so that the specification precedes the code and the human reviews at each step.

The workflow is compatible with the delegation ladder of Chapter 4 only if the phases are assigned to degrees of delegation and not to the tool. In the toolkit's own wording the agent drafts the specification. In the delegation profile of Nordvik Region (DLG-NR-DEV-01, adopted under AIDR-1101) the work class specify is Level 0 Advisory, so the same step is done by a person, with an assistant at most offering questions. In the profile of Hansa Mutual (DLG-HM-DEV-01, adopted under AIDR-1153) it is Level 1 Assisted, so an assistant may draft acceptance criteria for a product owner, who adopts or rejects each. Neither organisation lets any tool decide the scope.

The specification as code

A specification that lives in a wiki cannot be tested, versioned with the change or found by an agent. The same habits that Architecture as Code (Chapter 4) set for decisions apply to intent: a short record, numbered, kept in the repository beside the code it governs, changed by pull request, with a history. The record holds the need, the requirements with their sources, the acceptance criteria, what is out of scope, the open questions and the assumptions, and the links to the tests that check each criterion. Two properties make it more than documentation.

Traceability runs in both directions. From a need one can follow the requirement, the criterion and the test; from a test one can follow back to the need it protects. A test with no requirement is either a gap in the specification or a test that can be deleted; a requirement with no test is a promise nobody checks. Traceability is cheap to keep when the records are in version control and expensive to reconstruct afterwards, which is the same argument that AI Platform and Security, Chapter 5, made for decision records.

Change control treats the criteria as the oracle. A change to an acceptance criterion changes what counts as correct, so it is a change to the oracle in the sense of the Level 4 prohibitions of Chapter 4, and it is made by a named person in a reviewed change, never by an agent as part of the change it is meant to check. This does not forbid an agent from proposing the change; it forbids the agent from adopting it.

Where design decisions begin

The specification states what and why; the design chooses how. Chapter 6 takes the second. The boundary is not always clean, because a constraint such as "must run on the Region's own platform" is both. The working rule is that anything a stakeholder could reasonably want to change independently belongs in the specification, and anything chosen to satisfy the specification belongs in an Architecture Decision Record (ADR) (89, Nygard, 2011). Where the two conflict, as when a design choice makes a requirement impossible, the conflict is written into both records and taken to the design authority as an exception of the kind AI Governance, Chapter 13, described.

What AI adds

Four things are observable in practice, and none of them alters who owns the specification.

Drafting. An assistant produces a first version of a user story, a list of acceptance criteria or a glossary from a ticket, a meeting transcript or a regulation. The draft is fast and fluent. Its value is highest when the author already knows what the text should say and edits it, and lowest when the author uses it to discover what the need is. In the delegation profiles of both organisations drafting is the most that is delegated.

Clarifying questions. The more useful behaviour is the one in which the assistant does not answer at once but asks. There is research on this for code generation. ClarifyGPT, a preprint from 2023, has a model detect whether a requirement is ambiguous, generate clarifying questions, and regenerate code from the answers. On four benchmarks of function-level code generation, with simulated user answers, the average Pass@1 of GPT-4 rose from 68.02 to 75.75 per cent and that of ChatGPT from 58.55 to 67.22 per cent; in a human evaluation with ten participants on one benchmark (MBPP-sanitized), GPT-4 rose from 70.96 to 80.80 per cent (266, Mu et al., 2023). The finding is that asking before generating helped on small, well-defined programming tasks. It does not show that the same holds for the requirements of a case-management service, where the answers are not available in a benchmark and the person asked may not know. It is a preprint, and the ten-participant evaluation is small.

Summarising feedback. Assistants condense interviews, survey comments, support tickets and call notes into themes. No study of feedback synthesis for developers has been verified for this book, so the claim here is only that the use is observable and that its output is a pointer back to the source material, not a replacement for it. The rule from AI Leader, Chapter 6, applies: a summary carries provenance to the sources it condenses and a field for the view that did not survive the condensation (174, Nordqvist, 2026).

Surfacing what is missing. An assistant is good at checking a draft against a checklist: has the specification said what happens on timeout, on a second submission, on a withdrawn consent, on a screen reader. A list of questions the author had not asked is a cheap and real benefit, provided the author answers them from knowledge or research, and not by asking the assistant to answer its own questions.

The same ambiguity, moved

A distinct result concerns what a model does with what the specification leaves out. A 2025 preprint on underspecification in prompts reports that models infer unspecified requirements by default in 41.1 per cent of cases, that underspecified prompts are twice as likely to regress when the model or the prompt changes, and that specifying everything does not reliably help, because models follow instructions imperfectly and requirements can conflict (265, Yang et al., 2025). The study concerns requirements inside prompts to language models, not the requirements of a software product, and the page read did not name the models tested. Its relevance is the mechanism. A gap in a specification does not stop a generating tool; the tool fills it with the most plausible content, and the plausible fill is invisible in the output. The ambiguity has not been removed. It has moved from a question somebody would have asked to a decision nobody made. That is the reason this chapter keeps the unresolved questions in the record, and the reason the review in Chapter 9 asks which assumptions the generated code made.

Failure modes

The failures of AI in framing follow from the properties that make it useful. The list below is the book's own conclusion from the sources cited, and it is the checklist for reviewing an AI-assisted specification.

Plausible but wrong requirements. Weick's account of sensemaking observed that people act on an account that is plausible and coherent and do not wait for one that is accurate (85, Weick, 1995). A fluent draft is plausible by construction. A requirement such as "the system shall retain applications for 24 months" reads like a requirement; whether 24 months is right depends on an archives rule that the draft may have invented. The control is provenance: each requirement carries its source, and an unsourced requirement is marked as an assumption until a named person confirms it.

Sycophancy to the framing. In a 2023 study of five AI assistants fine-tuned with human feedback, all five showed sycophancy across four free-form text-generation tasks: they tended to match the user's stated beliefs, and responses that matched a user's views were more likely to be preferred in the preference data that the authors examined (86, Sharma et al., 2023). For framing the implication is direct. If a product owner asks an assistant to "write requirements for the solution we have chosen", the draft will support the solution; if the same owner asks for requirements for the problem, the draft differs. The control is to put the problem statement and the user evidence into the request and keep the chosen solution out of it, and to ask for the strongest objections separately.

Scope inflation. A drafted specification is easy to extend and costs nothing to read for the first few lines. No study of this has been verified for this book, so the statement is a hypothesis of the book and not a finding: when extending a draft costs nothing, each pass is likely to add a requirement for a case that somebody could imagine. The effect is a specification larger than the need, with more to build, more to test and more to maintain. The control is the out-of-scope list: every addition either links to a need or is moved there, and the product owner signs the scope.

Hidden assumptions. The mechanism in the preceding section: a model fills gaps silently. The control is the assumptions field and a review step that asks, for each generated artefact, which decisions it embodies that no record contains.

Lost dissent. A summary of interviews shows the majority view. The case handler who works the hardest cases and says the form misses them may be one of seven interviewees. AI Leader, Chapter 6, named this as the dissent that does not survive condensation (174, Nordqvist, 2026). The control is a dissent field filled by the person who ran the interviews, from their notes and not from the summary.

Circular verification. The most consequential failure for this book. If one assistant drafts the requirements and the criteria, a second or the same one generates the code, and a third writes the tests, the loop is closed by machines alone, and nothing in it has touched the user's need. It shows that the code matches the criteria, and the criteria may have been drawn from the code. The control is the independence of the oracle that Chapter 4 set and Chapter 9 develops: at least some criteria, and the scenarios that matter most, come from research and from people who own the need.

Practical guide: Turning a need into a specification record

Purpose. To produce a specification record with acceptance criteria that a test can check, in which every requirement has a source and every assumption is visible.

Roles. The product owner owns scope and the record. The developer or tech lead owns feasibility and the link to tests. The tester or quality engineer owns the criteria as oracle and writes the first tests from them. The architect or design authority is consulted for exceptions. The data protection officer and, where the service is public, the accessibility lead review the legal and policy requirements. The works council or union is informed where the change alters how staff work, in line with the agreement that applies.

Inputs. The original request, the evidence about the problem (observed work, a sample of real submissions, complaint or call categories), the applicable legal and policy sources, the domain glossary, and the delegation profile that states what an assistant may do in specify.

Steps.

  1. Restate the request as a problem for a named group of users, and record the evidence for it. Add at least one source that the requester did not choose.
  2. List the legal and policy requirements with their source, for example the accessibility and data-protection duties above.
  3. Draft the requirements. A person writes the first version, or an assistant drafts within the degree set by the profile and the author edits every line. Each requirement carries a source or is marked as an assumption.
  4. Ask the assistant, if the profile allows, for questions the draft does not answer and for objections to the proposed scope. Record the questions in the open-questions field. Answer them from research or from a named person, and never from the assistant.
  5. Write acceptance criteria as scenarios, one or more for each requirement, including at least one boundary case. The tester takes ownership of them.
  6. Write the out-of-scope list and the dissent field.
  7. Link each criterion to the test that will check it, even if the test does not exist yet; mark it as pending.
  8. Review the record with the product owner, the tester and the developer. The product owner signs the scope. Departures from policy go to the design authority.
  9. Commit the record to the repository. Generation of code begins only after the criteria are committed.
  10. At each review date, re-open the record against evidence: has the need changed, did the criteria fail anything.

Artefact. A specification record, SPC-*, in version control, linked to tests and to any ADR it triggers.

A specification record

The record below is an illustrative worked example for Nordvik Region. It is consistent with the development profile of the Region: the e-services team owns the citizen portal SVC-NR-002, Hanna Wikström is its product owner, Saga Edvardsson is the quality engineer who owns the portal's regression pack, and DLG-NR-DEV-01 sets specify at Level 0 Advisory. The assistant listed is the approved conversational assistant at Mode 1, which the profile allows for internal source code and not for special-category data; here it was used only to produce questions. The change itself is invented for the example.

id: SPC-NR-2030-0001
title: Home-care application form, request for help completing the form
status: approved
date: 2030-10-14
service: SVC-NR-002
owner: Hanna Wikström            # product owner, e-services team
oracle_owner: Saga Edvardsson    # quality engineer; owns the criteria
delegation_profile: DLG-NR-DEV-01
specify_level: Level 0 Advisory
need:
  statement: >
    Case handlers return a share of home-care applications to the
    applicant because they are incomplete, and applicants who need
    help to complete the form have no way to say so.
  evidence:
    - source: sample of 60 returned applications, July to September 2030
      read_by: Hanna Wikström
    - source: reasons recorded by the telephone service, same period
      read_by: Gunilla Roos
  baseline: not measured   # take the return rate from the case system before build
requirements:
  - id: R1
    text: An applicant can state that they want help completing the form.
    source: need.evidence
  - id: R2
    text: The telephone number is optional and is collected only when help is requested.
    source: GDPR Article 25(2), data protection by default
  - id: R3
    text: The form meets EN 301 549 as used for Directive (EU) 2016/2102.
    source: Directive (EU) 2016/2102 Articles 4 and 6
  - id: R4
    text: A request for help reaches the case handler with the application.
    source: assumption   # confirm with the case-platform team
acceptance_criteria:
  - id: AC1
    covers: R1
    given: an applicant who opens the form
    when: they select the help option
    then: the application is marked as help requested and submitted
  - id: AC2
    covers: R2
    given: an applicant who has not selected the help option
    when: they submit the form
    then: no telephone number is stored
  - id: AC3
    covers: R3
    given: an applicant who uses only a keyboard and a screen reader
    when: they complete and submit the form
    then: all fields are reachable in order and the confirmation is announced
out_of_scope:
  - changes to the decision rules for home care
  - a call-back service
assumptions:
  - R4 depends on the case-platform interface accepting a new flag
open_questions:
  - question: Who may see the help flag in the case system?
    owner: Gunilla Roos
ai_involvement:
  - tool: approved conversational assistant (Mode 1)
    use: proposed 11 questions on the first draft; none answered by the tool
    reviewed_by: Hanna Wikström
dissent:
  - source: case handler interview
    note: The help flag may not reach the handler who works the case.
tests:
  AC1: pending
  AC2: pending
  AC3: pending
review_due: 2031-04-14

Three details are deliberate. The baseline is recorded as not measured rather than estimated, because the claim that the change reduces returned applications can only be tested against a baseline that exists; this is the discipline of claims with evidence that Chapter 20 develops for adoption. R4 is an assumption and appears as one, so that the dependency is visible to the case-platform team and not discovered in testing. The oracle owner is the quality engineer and not the developer who will build the change or the assistant that supplied questions, which is the corollary of the stewardship principle in its simplest form.

Across the degrees of delegation

The table sets out the highest degree of delegation of the work class specify that the two profiles allow for each usage mode, as of the start of the year in the development profiles. Document is treated in Chapter 12.

Usage mode Framing use Nordvik Region (DLG-NR-DEV-01) Hansa Mutual (DLG-HM-DEV-01)
Mode 0 Ambient AI Completion in the ticket tool or IDE; no framing task Level 0; no record of use Level 0; no record of use
Mode 1 Conversational assistants Questions, draft wording, glossary Level 0 Advisory Level 1 Assisted; criteria adopted line by line
Mode 2 Embedded workplace assistants Not a framing tool Not used for specify Not used for specify
Mode 3 Agentic work tools Draft a specification from a backlog item and a repository Platform team only; no specify delegation Level 1 Assisted for drafts; no agent changes criteria
Mode 4 Built AI applications A feedback-summarising service None built for this None built for this; HM-DEV-002 drafts tests, not criteria
Mode 5 Autonomous production agents None None; the Region has no such agent None; no coding agent merges or deploys alone

The Level 4 prohibitions of Chapter 4 bite on framing in one place. An agent may not change the acceptance criteria that its own output is tested against, since criteria are the test oracle for that change, and may not change the mandate under which it drafts specifications. The people prohibition also applies: a specification that encodes a rule deciding about a named person's employment, pay or access to work is not drafted at a degree above Level 0 Advisory, and the rule is owned by the person the law or delegation names.

The stewardship tests apply to the record itself. Name: the owner and the oracle owner appear in the record. Understand: the owner can state the need, the scope and the reason for each requirement without the assistant. Revert: a specification can be withdrawn or amended by pull request, and a change built from it can be reverted by the owner of the code under Chapter 11.

Nordvik Region and Hansa Mutual

Nordvik Region frames work from case-handler needs and legal requirements. The e-services team's product owner, Hanna Wikström, builds prototypes herself with the Mode 1 assistant, which is why the delegation profile sets specify at Level 0 Advisory and the record above states what the assistant was used for. The Region's public-access and archives rules mean that source code and design documents can be requested and must be kept as records. A specification record in the repository is therefore a public record in waiting, and it is written for that reader: the evidence is described, no applicant is named, and the dissent field records views, not individuals. Whether prompts to coding and framing tools are also records is an open question for the archivist and legal counsel that this chapter does not settle. The Region's accessibility duty follows from Directive 2016/2102 as transposed, and it appears in the record as a requirement with a source. Saga Edvardsson's question, who writes the oracle, has its answer in the record's first lines.

Hansa Mutual frames work from product hypotheses and regulatory change. The profile DLG-HM-DEV-01 allows specify at Level 1 Assisted, so an assistant may draft acceptance criteria for a product owner. A hypothesis-driven change in the claims portal of the group, for instance a shorter claims notification form in the customer portal SVC-HM-005, is recorded as SPC-HM-2030-0001 (illustrative) with a hypothesis, a measure and a review date, for example that fewer fields increase the share of notifications completed in one session, with the baseline taken from the portal's own telemetry before the build. A change prompted by regulation carries the instrument and article as the source of each requirement, and the product owner records which parts are duties and which are choices. The records live in the Hansa Forge catalogue beside the owner of the service. The group's change policy for the critical or important functions requires two human approvals for production changes; the specification record is the document that those approvers read to know what the change was meant to do. Aylin Demir, the junior developer in the claims portal team, reads the record for her first change and writes the first tests from the criteria; Chapter 13 returns to what that teaches her.

The two organisations differ in what they must prove. The Region answers to a public that can request its records and to the duty to give reasons for case decisions that its software supports; Hansa answers to supervisors under DORA and to customers whose claims it pays. The record serves both, as evidence of intent.

Observable, expected, speculation

Observable. Drafting of requirements, stories and acceptance criteria with AI assistants is in use; clarifying questions and checklist-style review of drafts are in use; sycophancy to the user's framing and the silent filling of unspecified requirements are measured behaviours of current models in the studies cited above. Toolkits that order work as specify, plan, tasks and implement have been published (122, Delimarsky, 2025).

Expected. Specification-first workflows in which an agent works from a committed specification and the developer reviews at each phase are expected to become a normal way of using agentic tools, because the tools are being published and the pressure to review smaller pieces is already present; the evidence on whether they improve outcomes has not been established, and this book does not claim it. Expected also: demand from auditors and supervisors for traceability from need to test where AI took part in the change.

Speculation. Products framed entirely by AI, from market signals to specification to code to release, with no person owning the need, are plausible and unevidenced. This book does not rely on them, and the stewardship principle of Chapter 4 says why an organisation should not either: a need has an owner, and the owner is a person.

Summary

This chapter treated D1 Frame: understanding the problem, fixing intent in requirements and acceptance criteria, and keeping the specification as the source of intent. Without AI, framing is the discipline of finding the problem behind the request, using the language of the domain, naming the duties that are not negotiable, such as accessibility under Directive (EU) 2016/2102 and data protection by design under the GDPR, and writing criteria that a test can fail. Ambiguity is the cost: it travels downstream and becomes more expensive with every stage, and a generating tool does not stop at a gap but fills it with something plausible.

AI adds capacity to drafting, to clarifying questions and to checking a draft against a checklist. The evidence is early. A preprint reports that asking clarifying questions raised Pass@1 on function-level code benchmarks, a second reports how often models infer what a prompt leaves unspecified, and a third line of work shows that assistants tend to agree with the framing they are given. The failure modes follow: plausible but wrong requirements, sycophancy, scope inflation, hidden assumptions, lost dissent and circular verification. The controls are provenance on every requirement, an assumptions and open-questions field, an out-of-scope list signed by the product owner, a dissent field filled from the researcher's notes, and acceptance criteria owned by a person who is not the generator, written before code is generated.

The specification record SPC-* makes this reviewable. It sits in version control beside the code, links need to requirement, criterion and test, names the owner and the oracle owner, and records what the assistant did. At Nordvik Region specify is Level 0 Advisory and at Hansa Mutual Level 1 Assisted, and at neither does a tool own the scope or change the criteria that its own output is tested against. These are the book's conclusions from the sources cited, not measured effects of a particular tool.

Chapter 6 turns to D2 Design, where the specification meets constraints and the choice of how is recorded as an ADR. Chapter 7 and Chapter 8 take up D3 Build, and Chapter 9 returns to D4 Prove and the independent oracle that begins with the criteria written here.

Sources

  1. European Parliament and Council of the European Union. Regulation (EU) 2016/679 (General Data Protection Regulation). Official Journal of the European Union. (4, European Union, 2016)
  2. Weick, K. E. Sensemaking in Organizations. Sage Publications, 1995. (85, Weick, 1995)
  3. Sharma, M. et al. Towards Understanding Sycophancy in Language Models. arXiv:2310.13548, 2023. (86, Sharma et al., 2023)
  4. Nygard, M. Documenting Architecture Decisions. Cognitect blog, 2011. (89, Nygard, 2011)
  5. Nordqvist, G. Architecture as Code. The Architecture as Code Series, Book 1. (161, Nordqvist, 2025)
  6. Nordqvist, G. AI Governance. The Architecture as Code Series, Book 2. (162, Nordqvist, 2026)
  7. Nordqvist, G. AI Platform and Security. The Architecture as Code Series, Book 3. (163, Nordqvist, 2026)
  8. Nordqvist, G. AI Red Team. The Architecture as Code Series, Book 4. (164, Nordqvist, 2026)
  9. Nordqvist, G. AI Leader. The Architecture as Code Series, Book 11. (174, Nordqvist, 2026)
  10. Brooks, F. P. The Mythical Man-Month: Essays on Software Engineering, Anniversary Edition. Addison-Wesley, 1995. (215, Brooks, 1995)
  11. ISO/IEC/IEEE. ISO/IEC/IEEE 29148:2018 Systems and software engineering: Life cycle processes: Requirements engineering. (24, ISO/IEC/IEEE, 2018)
  12. Yang, C. et al. What Prompts Don't Say: Understanding and Managing Underspecification in LLM Prompts. arXiv:2505.13360, 2025. (265, Yang et al., 2025)
  13. Mu, F. et al. ClarifyGPT: Empowering LLM-based Code Generation with Intention Clarification. arXiv:2310.10996, 2023. (266, Mu et al., 2023)
  14. Delimarsky, D. Spec-driven development with AI: Get started with a new open source toolkit. GitHub Blog, 2025. (122, Delimarsky, 2025)
  15. North, D. Introducing BDD. Dan North & Associates, 2006. (123, North, 2006)
  16. European Parliament and Council of the European Union. Directive (EU) 2016/2102 on the accessibility of the websites and mobile applications of public sector bodies. Official Journal of the European Union, 2016. (14, European Union, 2016)