Files
gcp_solution_architecture_a…/.agents/plans/iter-09-scoping/steps/step-2.md
Jonathan Boniface 545097530b
Some checks failed
validation / verify (push) Failing after 10s
feat: scoping is the first Phase, completed in conversation (iteration 9 step 2)
Every Execution now begins by agreeing the scope, before requirements.

- A new Phase and Deliverable, produced by a scope analyst with two tools:
  scope_read shows what is settled and what is not; scope_set records fields
  with where each value came from (the request, the customer's answer, or an
  assumption with its reason). Code checks each value against the catalogue.
- With someone present the analyst asks for what is missing; with nobody
  present it assumes it, visibly. With no spec it drafts one from the request.
  A value the customer stated in the file is changed only by their own answer.
- A submission cannot leave an essential field unknown. Code writes the
  completed spec, the data every later Specialist reads, and the information
  register, from what was recorded.
- The spec's status follows the Execution: under review, approved, then
  locked as a Baseline. A Change request starts from the delivered scope.
- The requirements analyst derives from the agreed scope and no longer asks
  for what it settles.

About 80 tests assumed requirements came first; tests/scoped.py runs scoping
ahead of a test's own script, and tests about order and counts are updated.
Not run with real models.

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

3.8 KiB

Step 2 — Implementation Detail

Built on 2026-10-11. Not run with real models.

  1. Scoping is the first Phase. PhaseId.SCOPING comes before requirements discovery, with one Deliverable, scope, produced by a new Specialist, the scope analyst (agents/scope-analyst.md). Requirements depend on it. Every Execution now begins with it, whether or not a spec was supplied, and the customer approves it before requirements begin.
  2. The scope analyst completes the spec with two tools (app/tools/scoping.py). scope_read shows what is settled and what is not, with the question to ask for each. scope_set records fields, each with where its value came from: request (the customer's request says it), answered (they said so in conversation) or assumed (the analyst chose, and must say why). Code checks every value against the catalogue as it is recorded.
  3. What the customer stated in the file stays. The analyst cannot overwrite a supplied value by assumption; only the customer's own answer changes it.
  4. The conversation. With someone present the analyst asks, through needs_input, for the essential fields and the important ones that most change a design, up to eight at a time. An answer is recorded as answered; "you decide" becomes an assumption; a skipped field stays unknown. With nobody present it assumes the essential and important fields from the catalogue's guidance and what the request implies.
  5. A spec drafted from a sentence. With no spec supplied the analyst starts from an empty one, records what the request states and settles the rest the same way.
  6. A submission cannot leave an essential field unknown. It is refused, naming the fields.
  7. The Deliverable is written by code from what was recorded. The analyst writes the scope statement. Code writes the two files (scope.yaml, the completed spec; scope.json, what every later Specialist reads) and appends the information register, the assumptions with what each would change, and what is still to confirm.
  8. Every later Specialist reads the agreed scope, as scope in its context: what the customer stated, what was assumed for them (shown apart), and what is unknown. The requirements analyst derives from it and no longer asks for what it settles.
  9. Status is kept current in the Execution's scope.yaml and in the copy beside the Intent: UNDER_REVIEW once submitted, APPROVED when the Phase is approved, BASELINE_LOCKED when the Execution completes (which closes step 6). execution.json carries the status and the readiness count.
  10. A Change request starts from the scope that was delivered, with where each value came from, and the analyst records only what the change reaches. A Baseline delivered before scoping existed has no scope; the analyst then completes one from the change and the delivered requirements.
  11. The Approval summary for scoping says how much was assumed and what is unknown.

What it changed elsewhere:

  • About 80 existing tests assumed requirements came first. tests/scoped.py holds helpers that run scoping ahead of a test's own script, so tests about later Phases start where they always did. Tests about order, counts and first prompts were updated to the new truth.
  • workflow.yaml gains the Phase.

Not done here:

  • No real model has run the scope analyst. How well it drafts from a sentence, how many questions it asks, and what it costs are unknown. Every evaluation case now begins with it.
  • Answers are parsed by the model, not by code, before scope_set checks their type. Nothing reads a value back to the customer other than the draft they approve.
  • A re-supplied file part-way through a conversation is not handled; the customer answers in chat.

Tests: tests/execution/test_scope_spec.py (12), and the existing suites as updated.