Task: Write the operations journeys
Table of Contents
This page documents a task in the Document the operations journeys story. It captures the goal, current status, acceptance, and any notes or results.
1. Goal
Five journeys document how a system administrator sees a running installation: See the running services, Watch the compute grid, Watch the message bus, Read the telemetry logs, and Check the versions and the database. Each follows the User Journey Extraction Standard, and a clickable prototype on a throwaway branch proves the screens.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Document the operations journeys |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-10-04 |
3. Acceptance
- The five journeys are
user_journeydocuments in the operations group, each following the User Journey Extraction Standard and passingcompass lint. - Every operation each journey names is checked against the generated protocol and marked exists, partial or missing; every gap is recorded.
- Every telemetry and super-admin screen of the legacy
ores.qtclient has a disposition: kept, changed or dropped. - A clickable prototype runs on a throwaway branch and is linked from each journey it proves.
4. Plan
- Agree the catalogue with the product owner before any document is written, as
the standard requires. Agreed before scaffolding: five journeys in a new
operationsgroup. - Read the generated protocol pages for
ores.telemetry,ores.computeandores.nats, the model pages behind them, and the repository code behind every handler, so each operation's status is checked, not assumed. - Write the five journey documents with
compass add user_journey, each following the document type's section contract. - Draw one PlantUML
saltwireframe per journey, render it beside the document, and embed it with a caption. - Write the group hub with the catalogue and the disposition of every legacy
ores.qttelemetry and super-admin screen, and add the group row to the journeys index. - Verify with
compass lintandcompass site page, review the diff, and land it.
5. Measurements
Every number this task claims about a tree, with the command that produced it
and the commit it was measured at. A number without both is not a measurement,
because a clean-up record describes a tree and trunk moves under a branch: a
consumer count, a gate's component count and a suite's size all change with no
code changing, and the reader of a bare number cannot tell which tree it came
from. Where the raw output matters, put it in an evidence/ file beside the
task and name that file in the Command column.
| What | Value | Command | Commit |
|---|---|---|---|
| Journey documents | 5 | ls doc/knowledge/journeys/operations/journey_*.org |
a1e507dc04 |
| Wireframe pairs (source and rendered) | 5 | ls doc/knowledge/journeys/operations/wireframe_*.png |
a1e507dc04 |
| Lint | passes: filetags and generator markers are valid | ./compass.sh lint |
a1e507dc04 |
| Site pages | 584 files, 0 failures | ./compass.sh site page |
a1e507dc04 |
6. Notes
The handler checks changed four claims. Reading the code behind the operations, not only the protocol pages, moved four statements: the heartbeat states a release and not a build, the services list keeps only the last five minutes, the grid read drops the failure counts the ingest stores, and the NATS counters are cumulative since the server started. Each became a gap the journey records.
The database fingerprint is the one genuinely missing read. The row exists, and exactly one reader touches it: each service at its own startup. No subject serves it to a person, so the versions journey states the panel as unknown until the read exists.
The legacy inventory lives on the hub. The standard asks for it, and the
story put it in the group hub's * Where the legacy screens went, next to the
journeys that carry the screens.
7. Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario)
that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
8. PRs
| PR | Title |
|---|---|
| #2614 | [docs] Write the operations journeys |
9. Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|
10. Result
Written 2026-10-04. The five journeys, their wireframes, the group hub and the
index row are on feature/implement-operations-journeys; compass lint passes
and every page publishes. The prototype acceptance is carried by
Prototype the operations journeys,
which draws these screens on a throwaway branch.