Files

145 lines
9.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# The target operating model agent
Status: needs-triage
The design for the first slice. Vocabulary is in `CONTEXT.md`. The decisions the owner has taken, the Phases and the order of work are in `IMPLEMENTATION_PLAN.md`; this spec says what the plan leaves loose: the formats, the rules and the arithmetic. The engine it runs on is specified in `../orchestration_engine/.scratch/engine/spec.md`.
## The first slice
Six Deliverables, enough to go from Sources to a priced, validated operating model.
| Phase | Deliverable | Specialist | Data file |
| --- | --- | --- | --- |
| scoping | `operating_scope` | `scope-analyst` | `operating-spec.yaml`, `scope.json`, `solution.json` |
| operational_requirements | `operational_requirements` | `operations-analyst` | `operational-requirements.json` |
| operating_model_design | `capability_model` | `capability-modeller` | `capabilities.json` |
| operating_model_design | `target_operating_model` | `operating-model-architect` | `target-operating-model.json`, `findings.json` |
| validation | `validation_results` | `validator` | `verdicts.json`, `scenarios.json` |
| packaging | `operating_model_guide` | `packager` | |
Each depends on the one above it. `capability_model` and `target_operating_model` share a Phase, so the customer approves the design once, from the graph.
## The Operating spec
Read against `skills/operating-scoping/assets/catalogue.yaml` by the engine's spec reader. Every field holds a value, `ask`, `decide` or `not_applicable`.
| Field | Type | Tier | Notes |
| --- | --- | --- | --- |
| `metadata.customer_case` | string | essential | |
| `engagement.kind` | enum | essential | `workload`, `platform_foundation`, `migration` |
| `intent.statement` | text | essential | The customer's words |
| `intent.requirements` | records `id`, `statement` | optional | Binds: each must reach an Operational requirement |
| `intent.exclusions` | list | optional | |
| `solution.items` | records `id`, `name`, `kind`, `product`, `environments`, `source_ref` | essential | At least one |
| `solution.conditions` | records `id`, `on`, `condition`, `source_ref` | important | `on` names an Item |
| `solution.build.duration_days` | integer | important | The transition plan is checked against it |
| `solution.build.customer_owned` | list | optional | |
| `solution.inherited_risks` | records `on`, `risk`, `source_ref` | optional | |
| `solution.cloud_provider` | enum | essential | Values from the provider bundle |
| `operations.support_hours` | enum | essential | `business`, `extended`, `24x7`. Binds |
| `operations.availability_hours` | enum | important | The hours the solution must be available |
| `operations.change_process` | text | important | |
| `operations.monitoring` | text | optional | |
| `sourcing.model` | enum | essential | `customer_operated`, `provider_operated`, `shared` |
| `sourcing.delivery_countries` | list | important | ISO country codes. Binds where Roles may sit |
| `organisation.existing_teams` | records `name`, `party`, `skills`, `hours` | important for `migration`, else optional | |
| `organisation.headcount_limit` | integer | optional | |
| `service_management.tooling` | text | important | |
| `service_levels.priority_1_response_minutes` | integer | important | |
| `service_levels.recovery_time_hours` | number | important | |
| `compliance.frameworks` | list | important | Selects Capabilities from the catalogue |
| `commercial.currency` | enum | essential | Values are the currencies the rate card can convert to |
| `commercial.monthly_run_budget` | number | optional | In `commercial.currency` |
| `transition.go_live_date` | date | optional | |
| `run.pre_approved` | boolean | optional | |
`solution.items` and `solution.conditions` are written to `solution.json` and reach only the Specialists that list it. Everything else is in `scope.json`, which every Specialist is given.
### Digesting an architecture Execution
A code adapter, `app/operating_model/digest/architecture.py`. No model.
| From | To |
| --- | --- |
| `target-architecture.json` Elements | `solution.items`: `id` is `S-n` in order, `source_ref` the Element's id, `name`, `product` and the component as `kind` |
| `target-architecture.json` Checks | `solution.conditions`: `id` is `K-n`, `on` the Item of the Check's Element, `source_ref` the Check's id |
| A Check on a Relationship | A condition `on` the Item of the Relationship's source |
| `scope.json` | Every field both catalogues share, as stated; `solution.cloud_provider` from `estate.cloud_provider` |
| `requirements.json` | Nothing directly. Kept as a Source so a Specialist can read what a condition's requirement said |
| `verdicts.json`, verdict `fail` or `not_verifiable` | `solution.inherited_risks` |
| `work-breakdown.json` | `solution.build.duration_days` from its computed schedule; activities owned by the customer to `customer_owned` |
Rules: every Element yields exactly one Item and every Check exactly one Condition, or the digest fails and names what it could not place. `target-architecture.json` is required; each other file that is absent leaves its fields as `ask`. A value digested has provenance `digested`, with the file and its hash.
## Data files
`operational-requirements.json`: a list.
```json
{"id": "OR-1", "statement": "A fault on the hub network is responded to at any hour.",
"kind": "service_level", "source": ["K-4", "operations.support_hours"]}
```
`source` names a stated requirement's id, a Condition's id or a spec field. Refused: an entry with no source; a source that does not exist; a stated requirement, or a spec field marked as binding with a stated value, that no entry names.
`capabilities.json`: a list.
```json
{"id": "C-1", "catalogue": "incident-management", "serves": ["OR-1"], "items": ["S-1", "S-4"],
"hours": "24x7", "effort_hours_per_month": 30, "basis": "Two priority 1 incidents a month at eight hours, plus triage."}
```
Refused: a `catalogue` id that is not in the catalogue, unless `catalogue` is `custom` with a `reason`; a Capability that serves nothing; an Item no Capability covers; an Operational requirement no Capability serves; `effort_hours_per_month` missing or not positive.
`target-operating-model.json`: Parties, Roles, Capabilities as above by reference, Responsibilities and Checks, as in the plan's section 7. A Role carries `country` and `level`.
`findings.json`: a list, as in the plan's section 7. May be empty.
`verdicts.json`: one entry per Check, `pass`, `fail` or `not_verifiable`, with evidence. `scenarios.json`: each Scenario and the path code traced for it.
## Staffing and cost
Computed when the Target operating model is submitted, from the graph and `skills/rate-card/assets/rates.yaml`.
For a Role *r* in country *c* at level *l*, covering hours *h*:
- **effort** = the sum of `effort_hours_per_month` of every Capability *r* is responsible for. Where several Roles are responsible for one Capability, its effort is divided equally among them unless the Responsibility states a `share`.
- **productive hours a month** = `productive_days[c]` × `hours_per_day[c]` ÷ 12.
- **people** = effort ÷ productive hours a month; and, where *h* is wider than business hours, never fewer than `cover[h].minimum_roster`. Shown to one decimal place.
- **cost a month**, only where the Role's Party is of a kind the card prices and is not the customer = people × `day_rate[c][l]` × `productive_days[c]` ÷ 12 × `cover[h].uplift` × `conversion.rates[commercial.currency]`.
A Role's hours *h* are the widest hours of any Capability it is responsible for.
Refused at submission: a Role with a country or level the card lacks. Refused at the start: a `commercial.currency` the card has no conversion rate for.
Written into the Deliverable by code: people and cost per Role; totals by Party, by country and by Capability; the total against `commercial.monthly_run_budget`; the card's version, and the conversion rate and its date.
### Digesting anything else
A model drafts `solution.items` and `solution.conditions` from a document. Each record carries `evidence`: the file and the passage it was read from, quoted. A record without evidence is dropped by code and reported. Its provenance is `drafted`, and the scoping Approval lists drafted records apart from digested ones.
## Validation
Structural verdicts, by code: one per refusal rule of the graph, restated as a Check that passes, so the guide shows what was verified and not only what was refused.
Scenarios, generated by code and traced by code:
| Scenario | Generated for | Passes when |
| --- | --- | --- |
| A fault out of hours | Each Item whose Capabilities must cover hours wider than `business` | A Capability covers the Item, a Role responsible for it works those hours, and the Capability has an accountable Role |
| A change | Each Item | A Capability from the catalogue's change domain covers it, with a responsible Role |
| A Condition falls due | Each Condition | A Check carries it, on a Capability with a responsible Role |
| Loss of a Party | Each Party that is not the customer | Every Capability it is accountable for names a Role in another Party as consulted or responsible |
| Over budget | When a budget is stated | The total is within it, or the Deliverable names the overrun |
The validator, a model, judges only what code cannot: whether each Check's condition is verifiable as written, and whether a Capability's stated effort is plausible for the Items it covers. A Check that depends on a Finding is `not_verifiable`.
## Not in the first slice
The current operating model, the service model, dimension advisors, process definitions, organisation design, tooling, the transition plan, Change requests, and the lessons loop.
## Open
- The first entries of the capability catalogue, and which frameworks are in the register.
- Whether effort shared between Roles defaults to an equal division, as written above, or must always be stated.