Files
gcp_solution_architecture_a…/.scratch/scoping-and-work-breakdown/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

365 lines
21 KiB
Markdown

# Spec: Scoping from a scope spec, and a work breakdown structure
Status: ready-for-agent
Accepted by the owner on 2026-10-11. Stage 1 is built; `.agents/plans/iter-09-scoping/` says what is done.
- Glossary: [`CONTEXT.md`](../../CONTEXT.md). New terms this would add are in **Language** below.
- Builds on: [ADR-0005](../../docs/adr/0005-the-target-architecture-is-an-explicit-graph.md) (ids along the Requirements chain), [ADR-0006](../../docs/adr/0006-a-change-request-starts-from-a-baseline-execution.md) (Change requests), [ADR-0002](../../docs/adr/0002-skills-are-the-portable-unit-of-behaviour.md) (behaviour in Skills).
- Would need: one new ADR, for a new first Phase and a new start to the Requirements chain.
## Problem
The Intent is the customer's request, saved word for word. For case 06 it is one sentence. Everything else a design needs (how many users, what availability, which region, what budget, which compliance regime, what exists today) is assumed by the requirements analyst or, in the evaluation, supplied by pattern-matched answers.
Three days of runs trace most downstream trouble to what nobody stated: Checks the validator asks for on topics the customer never raised, checklist items the request cannot settle, a "low-carbon region" no code can show. Nothing tells the customer at the start how much of their design rests on assumption, and a requirement does not record whether the customer stated it or the agent assumed it.
Separately, the agent delivers a design and its code but no plan for building it.
## Decisions taken
The owner accepted these defaults on 2026-10-11.
1. **Scoping is a Phase the customer approves,** before requirements discovery.
2. **Its centre is a scope spec:** a YAML file that may arrive complete, partly filled or not at all.
3. **Architects write the spec,** the owner and colleagues, not end customers. Field names may be technical.
4. **A small set of fields is essential** and always settled before work starts. Which they are depends on the kind of engagement.
5. **Two files.** The file supplied is never altered. A completed copy is written beside it.
6. **The run options live in the spec,** so one file starts an Execution.
7. **Where the spec and the prose request disagree, the spec wins** and the customer is shown the conflict.
8. **The work breakdown structure is a new Deliverable,** after validation, in the packaging Phase, grouped by component as the technical decomposition is, covering the technical build.
9. **Scoping is built before the work breakdown structure.**
## Language
Terms to add to `CONTEXT.md` when built:
- **Scope spec:** the structured statement of what the customer wants and the facts a design depends on, as a file. It sits beside the Intent, which stays in the customer's words.
- **Scoping:** the Phase that completes the scope spec and has the customer approve it.
- **Work breakdown structure:** the Deliverable that divides building the Target architecture into work packages and activities, with a timeline.
- **Work package:** a unit of work that delivers named Elements and is done when their Checks pass.
Already in the glossary and used here: Intent, Customer question, Change request, Baseline, Requirements chain.
## The scope spec
### What a field can say
Every field holds a value or one of three words:
| Written | Meaning | What the agent does |
|---|---|---|
| a value | The customer states this | Uses it. Recorded as `supplied`. |
| `ask`, or the field left out | Not known yet | Asks, when someone is present. Otherwise treats it as `decide` and lists it under `discovery_gaps`. |
| `decide` | You choose | Picks a default, recorded as `assumed` with the default and what it affects. |
| `not_applicable` | Does not apply | Asks nothing and assumes nothing. |
A field name the catalogue does not have is an error that names the field. Nothing is silently ignored.
### Tiers
| Tier | When it is settled |
|---|---|
| essential | Always, before any work: asked when someone is present, and refused with a list when nobody is and it is neither supplied nor `decide`. |
| important | Asked when someone is present; defaulted otherwise. |
| optional | Defaulted unless supplied. |
### The draft
Revised on 2026-10-11 to combine the first draft with the owner's own example, an engagement spec for a regulated landing zone. What each brought is listed under **How the two were combined**. Essential fields are marked; which are essential depends on `engagement.kind`. Values shown are from the owner's example.
```yaml
schema_version: 1 # the catalogue this file is written against
metadata:
customer_case: fintech-global-landing-zone # essential: groups this work's Executions
engagement_reference: ENG-2026-UK-084 # yours; carried through, never interpreted
client_name: FinTech Global UK
author: Pre-Sales Engineering
revision: "1.1.0" # yours: the version of this document
status: DRAFT # written by the agent; see Status below
engagement:
kind: platform_foundation # essential: workload | platform_foundation | migration
# 1. What the customer said. The source of truth; nothing here is rewritten.
intent:
statement: | # essential: verbatim, or consolidated from calls and documents
We are a UK-regulated payment platform expanding into Google Cloud. We need an
enterprise-grade landing zone ready in under 10 weeks ...
requirements: # what the customer stated outright, with their ids
- id: REQ-01
category: Timeline
statement: Platform foundation must be ready for workload ingestion within 10 weeks.
- id: REQ-03
category: Networking
statement: 10Gbps on-premises hybrid connectivity; centralized Palo Alto inspection for egress.
exclusions:
- Application container deployment (managed by app squads).
- Active-active secondary region in phase 1 (warm standby acceptable).
success_criteria: decide
# 2. Where it runs.
estate:
cloud_provider: gcp # essential; must be a provider this deployment has
mode: greenfield # essential: greenfield | brownfield_expansion | migration
regions:
primary: europe-west2 # essential
secondary: europe-west1
resiliency_tier: warm_standby
data_residency: United Kingdom # essential
existing_systems: ask
# 3. Who uses it and how hard. Essential for kind workload; not_applicable for a foundation.
workload:
users: {who: not_applicable, count: not_applicable, peak_concurrent: not_applicable}
availability: {target: ask, hours: always, recovery_time: ask, recovery_point: ask}
# 4. Regulation and governance.
compliance:
industry: financial_services
frameworks: [DORA, ISO27001, PCI_DSS_v4] # essential; an empty list means none apply
data_classification: confidential # essential
encryption: {type: cmek, key_rotation_days: 90}
audit_logging: {retention_days: 365, immutable_retention_policy: true}
# 5. Network.
networking:
exposure: internal_only # internal_only | internet_facing
topology: shared_vpc_hub_and_spoke # allowed values come from the Cloud provider's catalogue
hybrid_connectivity: {enabled: true, type: cloud_interconnect, bandwidth_gbps: 10}
egress_control: {model: centralized_appliance, appliance_vendor: palo_alto}
cidr_allocations: ask
# 6. Identity, environments and operations.
governance:
identity_source_of_truth: entra_id
pipeline_authentication: workload_identity_federation
environment_tiers:
- {name: development, archetype: corp_workload}
- {name: staging, archetype: corp_workload}
- {name: production, archetype: pci_regulated_workload}
operations:
operating_model: central_platform_broker
support_hours: decide
monitoring: decide
integrations: []
# 7. How it will be delivered. The work breakdown structure is built from this.
delivery:
target_start_date: 2026-11-01
window_weeks: 10 # essential when the customer has a deadline
commercial_model: fixed_price_milestone
iac_tooling: terraform
ci_cd: github_actions
team_size: ask
working_days_per_week: 5
cost:
monthly_budget: ask # essential for kind workload
currency: GBP
# 8. How to run the agent.
run:
pre_approved: false
allow_cloud_read: false
overlay_skills: []
terraform_modules: false
```
### Sections the agent writes
Only in the completed copy. The supplied file never has to carry them, and if it does they are read as the last run's and replaced.
```yaml
inferred_assumptions:
- id: ASSUMP-01
field: networking.hybrid_connectivity
category: Network Telecom
statement: Assumes the client manages the carrier circuit lead time for the 10Gbps interconnect.
impact_if_invalid: Blocks the hybrid routing test; delays every activity after it.
discovery_gaps:
- field: networking.cidr_allocations
prompt: Specify IP subnet sizes for spoke workloads, for example /22 per environment.
severity: HIGH # HIGH is an essential field; MEDIUM important; LOW optional
provenance: # where every settled value came from
estate.regions.primary: supplied
cost.monthly_budget: answered
operations.monitoring: assumed
readiness: {supplied: 34, answered: 3, assumed: 6, unknown: 2}
```
`provenance` is one of `supplied`, `answered`, `discovered` (read from the customer's cloud environment), `assumed`, `unknown`. Every `assumed` field has an entry in `inferred_assumptions`, and every `unknown` one in `discovery_gaps`.
### Status
The owner's example carries a status. The agent sets it in the completed copy from what has happened; a status written by the author is not trusted.
| Status | Means |
|---|---|
| `DRAFT` | Gaps remain, or the conversation is still filling them. |
| `UNDER_REVIEW` | Complete, and waiting for the scoping Approval. |
| `APPROVED` | The customer approved it; requirements and the later Phases run from it. |
| `BASELINE_LOCKED` | Its Execution completed. This copy is the record a Change request starts from, and is never altered. |
### How the two were combined
| From the owner's example | How it is kept |
|---|---|
| The request, verbatim, inside the spec | `intent.statement`. It is also still saved as the Intent, as today. |
| The customer's stated requirements, with ids | `intent.requirements`. The agent's requirements trace to these ids, so the Requirements chain starts at what the customer wrote. |
| Stated exclusions | `intent.exclusions`. The design is checked for nothing built that is excluded. |
| Engagement metadata and status | `metadata`, with the status set by the agent. |
| Estate, compliance, networking and governance sections | Kept as written. |
| Start date, delivery window, commercial model, tooling | `delivery`. The window becomes a limit the plan is checked against. |
| Assumptions with their impact, and gaps with a prompt and a severity | The two agent-written sections, in place of the first draft's flat provenance table. Severity is the tier. |
| From the first draft | How it is kept |
|---|---|
| `ask`, `decide` and `not_applicable` | Unchanged. The example had no way to say "not known" other than omission. |
| Tiers | Kept, as the severity of a gap. |
| Two files | Kept. The author's file is untouched; the agent's sections go in the completed copy. |
| Where each value came from | Kept, as `provenance`. |
| Users, scale, availability target, budget | Kept under `workload` and `cost`, and essential only for a workload. |
| Run options | Kept under `run`. |
### Where the two pull apart
Four tensions, each with the resolution proposed. They are the owner's to confirm.
1. **The example states solution choices; the agent keeps requirements free of them.** A hub-and-spoke topology, an interconnect, customer-managed keys and a named inspection appliance are design decisions. The rule that requirements name no products exists so the agents do not pick a design before the design Phase. It should not stop a customer who has already decided. Proposed: a choice the spec states is a constraint the design must honour and may not change, recorded as supplied. The agents still add none of their own.
2. **The example is a landing zone; the agent has only designed workloads.** Every benchmark case is an application. A platform foundation has no users or response times, and has an organisation hierarchy, shared networking and environment archetypes the cases have never exercised. `engagement.kind` lets one spec serve both, but a platform foundation is a new kind of work for the agent and needs its own evaluation case before it is relied on.
3. **The example uses one Cloud provider's vocabulary in general fields.** `shared_vpc_hub_and_spoke`, `cloud_interconnect` and `cmek` are Google Cloud's terms. Proposed: the general catalogue says a field such as `networking.topology` exists; the Cloud provider's bundle supplies its allowed values. A second provider then brings its own list and the spec's shape does not change.
4. **"Engagement" is a word the glossary avoids.** The agent's term is Customer case. Proposed: `customer_case` stays the key the agent groups by, and `engagement_reference` carries the owner's own number untouched. If the owner would rather the agent's term became Engagement, that is a glossary change to make before this is built.
### Where the catalogue lives
A provider-neutral Skill holds the catalogue: each field's type, tier by engagement kind, the question to ask, and guidance for the default. A Cloud provider's bundle adds its allowed values and any fields of its own. An overlay Skill may raise a field's tier, so an organisation can make `compliance.encryption` essential. Code validates a spec against the catalogue; no model decides what is missing.
## How scoping runs
| What arrives | What happens |
|---|---|
| A complete spec | Validated. No gaps, no questions. With `pre_approved` the Phase passes without stopping. |
| A partly filled spec, someone present | Gaps are asked for, essential first, a few related fields at a time, with a count of how many are settled. |
| A partly filled spec, nobody present | Essential gaps refuse the start, with the list. Others are defaulted and recorded. |
| Only a sentence | A model drafts a spec from it, marking everything it did not find as `ask`. It is then a partly filled spec. |
In conversation an answer is a value, "you decide", or "skip". A skipped field becomes `unknown` and a Customer question in the output. A free-text answer is turned into the field's value and read back before it is written. The customer may supply an edited file at any point in place of answering.
The Phase ends when the customer approves the completed spec.
### What it writes
Under the Customer case, beside the Intent:
```
intent/
001.md # the request, in the customer's words (as today)
001.scope.yaml # the spec as supplied, unaltered; absent when none was
001.scope.completed.yaml # the completed copy: status, assumptions, gaps, provenance, readiness
```
The scoping Deliverable is a short document written from the completed copy: the scope statement, the information register as a table, and the readiness summary. The solution guide opens with that summary.
### What it changes downstream
- **The requirements analyst derives; it no longer asks or assumes.** Each requirement names the stated requirement (`REQ-03`) or the spec field it comes from, so the Requirements chain starts at what the customer wrote. A requirement from an `assumed` field says so.
- **A stated choice binds the design.** A product, topology or setting the spec states is carried to the design as a constraint, and a design that departs from it is refused.
- **Exclusions are checked.** Nothing in `intent.exclusions` may appear in the Target architecture.
- **Customer questions** from the pillar checklists (built 2026-10-10) are joined by the `unknown` fields.
- **A Change request may be an edited spec.** Code compares the two specs field by field, and that list is what changed. A sentence still works, as now.
- **An evaluation case becomes a spec,** replacing the pattern-matched answers.
## The work breakdown structure
A new Deliverable in the packaging Phase, produced by a new Specialist after validation, summarised in the solution guide.
### Its data file
```json
{
"work_packages": [
{"id": "WP-1", "name": "Network foundation", "parent": null,
"components": ["C-2"], "elements": ["E-1", "E-2"],
"scope": "The VPC, its subnet and outbound access.",
"produces": ["a private network the services attach to"],
"skills": ["network engineering"]}
],
"activities": [
{"id": "A-1", "work_package": "WP-1", "name": "Create the VPC and subnet",
"days": 1, "after": []},
{"id": "A-2", "work_package": "WP-1", "name": "Configure outbound access",
"days": 1, "after": ["A-1"]}
]
}
```
### What code checks and computes
- Every Element belongs to a work package, and every work package to a component or a parent. A design cannot be left out of the plan.
- A work package's acceptance criteria are the Checks on its Elements. They are read from the Target architecture, not written again.
- Activities form no cycle, and every `after` names an activity that exists.
- **The plan is checked against the delivery window.** When `delivery.window_weeks` is set and the computed total exceeds it, the Deliverable says so and names the critical path; it does not shorten estimates to fit.
- **An assumption can hold up the plan.** An entry in `inferred_assumptions` that an activity depends on, such as a carrier's lead time, appears as a dependency the customer owns, so its `impact_if_invalid` is visible on the timeline.
- **Milestones.** With a `commercial_model` of fixed price by milestone, each top-level work package ends in a milestone.
- **The schedule is computed, not written.** From each activity's days and what it comes after, code works out its earliest start and finish, the critical path and the total. With `delivery.team_size` it limits how many activities run at once.
### What it renders
Three views, all written by code from the data file, as the architecture diagram is:
- **WBS dictionary:** the hierarchy, each work package with its scope, what it produces, its Elements, its acceptance Checks and the skills it needs.
- **Activity sequence list:** each activity with its days, what it follows, its start and finish day, and whether it is on the critical path.
- **Timeline** on a relative axis, Day 0 to Day N:
```
Activity Day 0 5 10 15 18
A-1 Create the VPC and subnet ██
A-2 Configure outbound access ██
A-3 Provision the database █████
A-4 Deploy the application ████
A-5 Load balancer and access ███
A-6 Monitoring and alerts ██
A-7 Validation in test ████
```
The chart format is to be settled when built: a Mermaid Gantt chart if it can show a relative day axis, and otherwise a drawn table like the one above.
### What it says about itself
Durations are a model's estimates. The Deliverable states their basis (working days, the team size from the spec) and that they are indicative. The timeline stays on a relative day axis; when `delivery.target_start_date` is set, the activity list also gives calendar dates.
## Order of work
| Stage | What | Usable on its own |
|---|---|---|
| 1 | The catalogue, validation, the gap list, the two files saved beside the Intent, the run options read from the spec | Yes: a complete spec starts a pre-approved Execution |
| 2 | The conversation that fills gaps; scoping as a Phase with its Deliverable and Approval; a spec drafted from a sentence | Yes |
| 3 | Requirements traced to spec fields; readiness in the guide | Yes |
| 4 | An edited spec as a Change request | Yes |
| 5 | The work breakdown structure | Yes, with stage 1 for `delivery` |
| 6 | Evaluation cases as specs | Yes |
## Not in this spec
- Attaching documents (a statement of work, a diagram) as a source for the spec.
- Reading the customer's cloud environment to fill `current_estate`. The `discovered` source is reserved for it.
- Delivery activities beyond the technical build, such as security review, user acceptance and cutover.
- Cost of the work, or named people.
## Open questions
1. The four tensions under **Where the two pull apart**: are the proposed resolutions right?
2. Which fields are essential for each engagement kind? The draft marks them; the owner's example suggests the delivery window and compliance frameworks matter more than budget for a foundation.
3. In `pre_approved` runs an essential gap refuses the start. Is that right, or should it default and warn?
4. Should the scoping Approval be skippable when the spec arrived complete and someone is present?
5. Is a platform foundation in scope now, with its own evaluation case, or should scoping be built against workloads first?
## Comments
- 2026-10-11, the owner: a platform foundation is in scope now; an engagement name and a Customer case are equivalent references; the implementation will eventually be provider-agnostic. The other tensions and open questions were taken as proposed: a stated choice binds the design; an essential gap refuses a pre-approved start; the scoping Approval is not skipped. Recorded in ADR-0008.