Files
gcp_solution_architecture_a…/docs/adr/0008-scoping-starts-from-a-scope-spec.md
Jonathan Boniface afe78640f8
Some checks failed
validation / verify (push) Failing after 10s
feat: start an Execution from a scope spec (ADR-0008, iteration 9 step 1)
A scope spec is a YAML file of what the customer wants and the facts a design
depends on, complete or partly filled. It sits beside the Intent, which stays
in the customer's words.

- skills/scoping holds a provider-neutral catalogue of 63 fields; the Cloud
  provider's bundle supplies the values it allows for the fields left to it.
- app/scope.py reads a spec against the catalogue with no model: it refuses an
  unknown field or a value of the wrong type, and yields what is stated, what
  is left to the agent, what is unknown and how pressing each gap is. A field
  may say ask, decide or not_applicable.
- ExecutionEngine.start(scope=...), /generate, A2A metadata and evaluation
  cases accept one. Its statement is the request, its engagement reference
  names the Customer case, and its run options apply. A pre-approved start is
  refused when an essential field is not settled.
- The spec as supplied is kept unaltered beside a completed copy with
  assumptions, gaps, provenance, readiness and a status.
- Every Specialist is shown the spec and given the Skill: a stated choice
  binds, exclusions are out of scope.
- Covers workloads and platform foundations; case-08-landing-zone starts from
  a benchmark spec.

Plans for scoping (iteration 9) and the work breakdown structure (iteration
10, nothing built), and the design spec they come from. Not run with real
models.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 17:53:00 +01:00

51 lines
4.4 KiB
Markdown

---
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.