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_journey documents in the operations group, each following the User Journey Extraction Standard and passing compass 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.qt client 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

  1. Agree the catalogue with the product owner before any document is written, as the standard requires. Agreed before scaffolding: five journeys in a new operations group.
  2. Read the generated protocol pages for ores.telemetry, ores.compute and ores.nats, the model pages behind them, and the repository code behind every handler, so each operation's status is checked, not assumed.
  3. Write the five journey documents with compass add user_journey, each following the document type's section contract.
  4. Draw one PlantUML salt wireframe per journey, render it beside the document, and embed it with a caption.
  5. Write the group hub with the catalogue and the disposition of every legacy ores.qt telemetry and super-admin screen, and add the group row to the journeys index.
  6. Verify with compass lint and compass 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.

Emacs 29.3 (Org mode 9.6.15)