The reference engagement · a fictional client
Halcyon Regional Water: the folder, week four.
A regional utility is replacing two thirds of its meters and wants to stop estimating bills. The record below is the whole engagement so far: what was asked, what was decided, what is still open. Everything on this page is generated from it.
What is in the folder
Plain files, beside the code.
- .yarramate/
- workspace.yaml the pointer your agent is given
- architecture/
- main.yaml (18 subjects, 14 relationships)
- projections/
- current-state.yaml
- landscape.yaml
- motivation.yaml
- profiles/water-utility.yaml the vocabulary
- patterns/metering-programme.yaml the building blocks
- questions/water-utility.yaml the questions
- integrations/likec4/ · likec4-project.yaml (for the diagrams)
- .yarramate-out/ (rewritten on every change)
- briefs/ · rtm/RTM.md · rtm/rtm.json · narrative.md · halcyon.xlsx · likec4/
Git holds the history. A pull request is how a decision is approved. Nothing here needs an account.
A record like this has already been handed from one agent to another on a public codebase. Read the case study
The brief, as the tool wrote it
briefs/meter-data-platform.md · yarramate export briefsMeter data platform
The neighbourhood of meter-data-platform as declared today.
The pieces
You are building "Cloud region, in-state", a node. The in-state cloud region proposed for the meter data platform. It realizes "Meter data platform". Constrained by "data-stays-in-region".
You are building "Meter data platform", a metering platform. Collects, validates and stores smart-meter reads. It accesses "Meter read". It comprises "Reads API". It realizes "Meter read ingestion". Constrained by "data-stays-in-region".
You are building "Meter fleet replacement programme", a metering programme. The programme of work that replaces the ageing meters and stands up the platform that reads them. It realizes "Meter data platform".
You are building "Meter read ingestion", an application service. Accepts reads from meters and field devices, validates them, and stores them.
You are building "Reads API", an application interface. How the billing system asks for validated reads.
"Field crew", a business actor, already exists. Reads and replaces meters on the ground. It flows to "Meter data platform".
"Meter read", a data object, already exists. One reading from one meter at one time, with its validation state.
An index and one brief per subject, in plain sentences.
Every requirement and goal, what meets it, and what is still missing.
The landscape view as one readable document.
The same record as a spreadsheet, for whoever asked for one.
The views written out for a diagramming tool to draw; the pictures are rendered from it, not stored.
The views
3 views, one record. Each is a question the engagement had to answer.
What runs today
The 2009 billing system in the regional data centre, the monthly billing run it serves, the customers and field crew around it. The planned subjects are hidden; this is the map the client's operations team recognises.
Where the engagement is going
Everything, current and planned, from the operations director's driver down to the two nodes. Served-by layout, top down. This is the view on the home page, live.
Why this engagement exists
The director, the ageing fleet, the goal, the requirement and the constraint, and nothing else. The one-slide answer to "why are we paying for this?"
What is still open
The next questions, and where each one starts.
The tool keeps the list, wave by wave. Each row names the subject it is open for and opens the editor there; every row can be handed to your agent instead.
The tool keeps the list, wave by wave. Each row names the subject it is open for and opens the editor there; every row can be handed to your agent instead.
The method kit that shipped with it
Copy three files and your next engagement starts here.
Halcyon was run with the water-utility kit: the vocabulary the sector uses, the building blocks a metering programme is expected to have, and the questions an architect asks a utility in week one. Swap them for your practice's own and the interview changes with them.
- id: accuracy-outcome-missing
wave: motivation
since: "1.0"
scope: workspace
trigger:
- condition: no-subject-of-kind
kinds:
- yarramate/core@0.1#outcome
question: >-
What number will show the board that billing accuracy improved?
askPlain: >-
When this is done, what figure do you want to put in front of the
board: fewer estimated bills, fewer disputed bills, something else?
materiality: >-
Without a measurable outcome the programme cannot be declared finished,
and the platform's read validation rules have no target to be tuned
against.
authority: human
resolution: >-
Add an outcome (for example an estimated-bill rate) and a realization
relationship from the outcome to the goal it makes measurable.