Files
solution_architecture_agent/docs/adr/0008-scoping-starts-from-a-scope-spec.md
Jonathan Boniface c84dbdea20 feat: the solution architecture agent on the shared Execution engine
The reference agent's subject, cloud solution architecture, as an agent in
the operating model agent's pattern: the Execution engine (from
orchestration_engine) and one Workflow in app/solution_architecture,
built for the settings and provider bundle by assembly.workflow_for.

Copied from gcp_solution_architecture_agent at 8b397cd without its own
engine: its role files, Skills, provider bundle, ADRs, vocabulary, scripts
and evaluation datasets. The image takes the engine from a named build
context and installs Terraform. It is called through the Orchestration
engine, and its files are what the operating model agent digests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 19:49:28 +01:00

5.5 KiB

status
status
accepted

Scoping starts from a scope spec

An Execution began from the customer's request, a sentence or two saved word for word, and the requirements analyst filled everything else with assumptions. Most of what went wrong downstream traced to what nobody had stated, and nothing told the customer how much of their design rested on assumption. We decide that an engagement is scoped from a scope spec: a structured file that states what the customer wants and the facts a design depends on, which may arrive complete, partly filled or not at all, and which the customer approves before requirements begin.

The Intent stays the customer's own words. The scope spec sits beside it as the agreed, structured form.

What the spec is

  • A file of fields from a catalogue. A Skill holds the catalogue: each field's type, when it must be settled, the question to ask for it, and guidance for a default. The catalogue names no Cloud provider. A provider's bundle supplies the allowed values for the fields it leaves to a provider, in that provider's terms.
  • Every field says one of four things. A value is the customer's statement. ask, or the field left out, means not known. decide leaves the choice to the agent, recorded as an assumption. not_applicable asks and assumes nothing.
  • Whether a field is settled is read by code. No model decides what is missing.
  • Fields are essential, important or optional, and which is which depends on the kind of engagement: a workload, a platform foundation or a migration.
  • It carries the customer's own words and requirements: the statement verbatim, the requirements they stated with their own ids, and what they excluded.
  • It carries how to run the agent, so one file starts an Execution.

Decisions

Accepted by the owner on 2026-10-11, with each of these:

  1. The file supplied is never altered. The agent writes a completed copy beside it, with what it assumed, what is still unknown, where each value came from, and a status.
  2. A choice the customer states binds the design. A product, a topology or a setting written in the spec is a constraint every Specialist honours. The rule that requirements name no products is about what the agents introduce, not what the customer has already decided.
  3. A platform foundation is in scope, alongside the application workloads the agent was built on.
  4. An engagement and a Customer case are the same thing. A spec may name either; an engagement reference is turned into the case's id.
  5. The spec is provider-agnostic in shape. Provider vocabulary enters only as values a provider's bundle allows.
  6. An essential field that is not settled refuses a start that has nobody to ask. With someone present it is asked for.
  7. Scoping becomes a Phase the customer approves, before requirements discovery.
  8. Where the spec and a prose request disagree, the spec wins.

Considered Options

  • Judge the free-text request against a list of topics with a model or Jev: the first proposal. Rejected once a spec was on the table: a field that is filled or not is a fact, and a judgement about prose is not.
  • One file the agent completes in place: rejected. An author must be able to see that what they wrote is what was used.
  • Keep product names out of the spec, as out of requirements: rejected. A customer who has decided on an interconnect or a named appliance has stated a constraint; refusing to record it would lose it.
  • A separate spec for platform foundations: rejected. One catalogue with tiers by kind serves both, and a migration is usually some of each.

Consequences

  • The Requirements chain gains a start: a requirement traces to the customer's own requirement id or to a spec field.
  • The requirements analyst stops being where questions are asked and assumptions made. That moves to scoping.
  • A Change request may be an edited spec, compared field by field in code.
  • An evaluation case may be a spec, in place of answers matched by pattern.
  • The glossary gains Scope spec and Scoping, and Customer case says that an engagement is the same thing.
  • A platform foundation is new work for the agents. It needs its own evaluation case before it is relied on.
  • The spec holds client names and details. Like lesson candidates it is client data: kept with the Customer case, never in the repository, apart from the fictional benchmark specs.

This is built in stages; .agents/plans/iter-09-scoping/ says which are done.

As built (2026-10-12)

  • Built: the catalogue and reading a spec in code; scoping as the first Phase, completed in conversation or by assumption; a spec drafted from a sentence; a stated choice refused unless a requirement carries it; the status following the Execution; a Change request starting from the delivered scope.
  • Answers are given in conversation. Supplying an edited file part-way through is not handled.
  • A Change request is still stated in prose. Comparing an edited spec with the delivered one, field by field, is not built.
  • Exclusions are not checked in code. They are free text; the Specialists are told, and in the first landing-zone run they complied.
  • An organisation's standards are not part of the spec. They still arrive as overlay Skills (ADR-0004). Carrying them in the spec as stated requirements was discussed on 2026-10-12 and left undecided; it would amend that ADR.
  • A platform foundation has run twice with real models, as case-08-landing-zone.