Skip to content

USER_JOURNEY.md

Latest commit

 

History

History
418 lines (334 loc) · 16.8 KB

USER_JOURNEY.md

File metadata and controls

418 lines (334 loc) · 16.8 KB
Raw

User Journey

Observogram has one product journey:

Discover -> Diagnose -> Remediate

The journey is not a marketing funnel and not a dashboard catalogue. It is a diagnostic workflow for one question:

Is this service's observability diagnostic-grade?

Design and implementation decisions must shorten the path from raw inputs to that answer.

The Three Questions

Step User question Product answer
Discover What do we have? Render the observogram from a repo, live scan, or pack.
Diagnose Can we trust it? Score coverage and trust; show declared-vs-live drift.
Remediate How do we fix it? Compile and deploy the source-backed delta.

The primary chrome uses these questions directly:

  1. Discover - What Do We Have?
  2. Diagnose - How reliable is this pack?
  3. Remediate - Resolve gaps

Advanced views exist, but they are not the core journey. They support expert analysis: References, Conformance, Schema, OTLP Coverage, Traceability, Atlas.

OLA And Observability Contract

The OLA is the service's observability intent. Observogram represents that intent as a canonical ObservabilityPack:

  • criticality and ownership
  • SLOs and SLIs
  • telemetry and backend bindings
  • recording rules and dashboards
  • alerts, routes, and remediations
  • validation evidence and freshness expectations

During the main dry-run flow, Pack A is the declared contract from the service repo and Pack B is the verified live state from MCP. Diagnose answers whether the live production posture satisfies the declared contract well enough to be diagnostic-grade.

North-Star Flow

Open app
  |
  v
Discover
  |
  |-- scan a service repo
  |-- generate from a live MCP endpoint
  |-- upload a YAML/JSON pack
  v
Pack A loaded: declared observability posture
  |
  v
Load Pack B: live production posture
  |
  v
Diagnose
  |
  |-- Assessment (diagnostic grade)
  |-- Coverage criteria
  |-- Trust criteria
  |-- Drift drill
  |-- Traceability chains
  v
Remediate
  |
  |-- A minus B delta
  |-- deployable source-backed artifacts
  |-- manual follow-up items
  |-- compile selected artifacts
  |-- deploy through MCP write tools
  v
Re-run live scan and compare again

Diagnostic Grade Contract

The Diagnostic Grade is the top-level answer. It is scored from seven criteria (grade schema 2), plus one informational operability check:

Coverage - Are We Observing The Right Things?

  1. Multi-modal - metrics, logs, traces, or profiles cover the service.
  2. Correlated - telemetry can be joined through trace context or log correlation.
  3. Calibrated - SLOs have numeric objectives and baselines exist.
  4. Comprehensive - coverage spans the major service layers.

Trust - Can We Trust What The Signals Show?

  1. Chaos-validated - recovery has fault-injection evidence.
  2. Drift-free - declared artifacts match live state.
  3. Fresh - the live signal was verified recently.

Operability - Can Oncall Act On What It Sees? (informational, not scored)

  • Actionable - alerts lead to a runbook or remediation path. This measures response readiness of the overall observability solution, not diagnostic capability, so it is observed and displayed but never moves the score (reclassified 2026-06-10; journey run records carry grade.schema so score history steps are explainable).

The audit verdict (the machine contract journeys gate on) is:

PASS when score > 85%
FAIL otherwise

The displayed verdict is the instrument grade the score lands on, rendered as a full ladder with the current rung highlighted:

Grade Class Score band
A++ Calibration / Reference Grade not score-reachable (external benchmarking)
A+ Laboratory / Research Grade ≥ 95%
A Diagnostic / Clinical Grade > 85% — anchored to the audit bar
B+ Inspection Grade ≥ 75%
B Industrial Grade ≥ 62.5%
C Field Grade ≥ 37.5%
D Consumer Grade < 37.5%

A or better and audit PASS are by construction the same statement. Journey run records carry grade.letter alongside grade.score.

Failed criteria still render as evidence. A score can pass while drift remains visible. That is intentional: the grade answers whether the posture is diagnostic-grade overall; the drill-down tells the team what to fix next.

Pack Roles

Role Meaning
Pack A The declared posture, usually generated from the service repo.
Pack B The verified/live posture, usually generated from MCP.
Reference pack A curated target posture used for benchmarking, not the default dry-run path.

The dry-run path is repo vs live, not repo vs aspirational reference.

Required UI Invariants

  1. The first screen must be useful. Discover is the entry point and must let a user create or load a pack immediately.

  2. The three primary tabs are the workflow. Do not add another first-class navigation layer that competes with Discover, Diagnose, Remediate. The service page is the home's second level — a card opens it, its actions open the three tabs bound to the service — not a fourth tab.

  3. Pack identity must be explicit. Uploaded/crawled/drafted pack selectors must show enough source context to prevent stale or typo uploads from being mistaken for the dry-run input.

  4. Pack B means comparison. When a live pack is loaded as Pack B, Diagnose must be able to answer repo-vs-live drift without another conceptual mode.

  5. Diagnostic heading stays focused. The heading is DIAGNOSTIC GRADE plus PASS/FAIL. The live target belongs in the drift section, not in the grade title.

  6. Drift remains evidence, not decoration. Declared-not-live, drifted, and live-only signals must stay visible even when the overall grade passes.

  7. Remediate separates deployable from manual. Source-backed artifacts may be selected for deploy. Inferred guidance must be labelled and kept out of default deploy selections.

  8. State must not create false confidence. Persisted local state is useful, but reset and source labels must make stale comparisons easy to clear.

  9. Services are records. The home and the SERVICE selector read the services table (GET /api/services); a service page binds Discover · Diagnose · Remediate · Build to a service and an environment through one pack resolver (the newest primary); a pack-derived tile appears only where the table is unavailable (the static bundle) or for a registered pack whose service row was deleted, and behaves as before.

  10. Settings is entered from a menu, not a tab (Advanced → Settings; the account menu); it never competes with Discover · Diagnose · Remediate.

What Belongs In Each Step

Home and the service page

The home is the org's services table, one card per record, and a card opens the service page: the environments as tabs, each with the verdict the pack is graded to at the record's tier (a base grade is named as such when the pack declares no overlay for that environment; "no verdict yet" is said, never a zero), the MCP endpoint it is checked through, and the four actions — Discover · Diagnose · Remediate · Build — bound to the service and the environment through one pack resolver. Catalogue packs are listed apart; the affordances are drawn from the effective role the server reports for the active org (GET /api/orgs).

Belongs here:

  • the services table and the record's facts (tier, owners, the packs linked, the newest primary marked current);
  • the verdict per environment — the conformance report at the record's tier, the mismatch with the pack's own tier said;
  • the MCP endpoint as its name and origin only;
  • the four actions, worded for the rank that reads them (a control a role cannot use is drawn disabled with its reason, never as usable);
  • the record editor (name, owners, tier, description) for operators;
  • catalogue packs, apart from the records.

Does not belong here:

  • a URL or a token (the endpoint's safe form is all the page shows);
  • environment CRUD, members, MCP endpoint records (Settings);
  • journeys (Neuron) and the deploy history.

Settings

The org's administration, as a mode of its own: Advanced → Settings or the account menu opens it, its Back returns to where it was opened from, and a journey tab leaves it. The sections and every control in them are drawn from the rank the server reports for the active org; a section or a write that rank cannot use is listed aria-disabled with its reason, never hidden as if it did not exist and never drawn as usable.

Belongs here:

  • environments — every service's, each with its tier, bindings, links and MCP endpoint — read by every member, added, edited and deleted by operators (the same editor opens from the service page);
  • the org's MCP endpoint records for admins — the URL and the token as the NAME of a server variable under the org's prefix, never its value; a viewer reads the name and the origin only;
  • members and the org's name for admins — add by login or verified email, change a role, remove; the last-admin rule drawn before the server says it;
  • the audit for admins: the org's rows, filtered by whole UTC days, paged back; for owners, the deployment's;
  • for owners, the deployment: users (a new local user's temporary password shown once, changed at first sign-in; the last-owner rule drawn first), organisations (create and switch to it, act in one they are not a member of, remove with the id typed) and the join role beside the sign-in mode it applies to;
  • one banner naming the way in where the server names one — a token-only server, a server without sign-in, the static bundle — in the server's words;
  • every editor a pop-up over one record, its status line naming what the server changed, or its refusal as served.

Does not belong here:

  • services themselves (Build and the service page write them);
  • a secret's value — a token anywhere on the page, a password outside the one dialog that shows a new temporary password once;
  • an email in a member row;
  • a journey tab.

Build (no pack yet)

A parallel journey for a service that has no pack, in the same visual language as the three steps below and ending in Discover (BUILD_JOURNEY.md). It is reached from the home hero, the service gate and the upload popover, never from the three primary tabs, and it does not change what Discover, Diagnose or Remediate show. Both landings open with the first decision — check an existing service or pack, or build a new one — and both paths join at Discover.

Belongs here:

  • the pack as the axis of the screen on every step: a sticky definition column on the left — on Define the live form (the service; the tier as a segmented control with its MUST · SHOULD counts; the library entries as chips with their evidence dot), on Compile and Verify the read-only seed card it becomes once the pack is seeded (Seed the pack →; Change seed → returns), and under both the conformance summary — pass · on a placeholder · fail, the failing clauses, todos and placeholders left — and the layer stack of the pack being compiled as the main surface — L1 SLI/SLO · L2 Metrics/Logs/Traces · (L2X) · L3 Dashboards/Recording Rules · L4 Alerts/Policy/Self-healing · L5 Self-check · GOV — drawn through the same adapter and the same artefact cards Discover uses, each slab's edge carrying the rubric's verdict for that layer (pass · pass on a placeholder · fail · neutral when no clause applies), a placeholder artefact as Scaffold, a clause the tier still needs as a ghost card on its slab
  • a sheet per layer, opened from the slab head: the layer's question (L1 What should we measure? … GOV Who owns it?), its clauses at the tier with their state, and what the pack can carry on that layer — always read from the instantiated pack, never a made-up menu; one sheet at a time, Esc closes, focus returns to the slab; a preview on Define (Compose in Compile →), editable on Compile, read-only with the layer's todos on Verify
  • Define: the service name, owners, environment, the criticality tier and the library entries in the definition column; the tier as the silhouette of the pack it demands (one ghost per clause per slab, reshaping with the tier), the entries' SLIs and their SLOs as candidates on L1
  • Compile: composition on the sheets — the SLI rolodex on L1 (the selected entries' SLIs, every product's behind a filter, any SLI addable — one above the tier says which profile it starts from; the tier is a seed, not a gate — the objective and window it starts with, add / remove as a switch; adding from a product not yet selected selects it too; Customise edits a card's copy of the library's values in place — objective, window, bound, PromQL, description, each back to the library default in one click, an edited expression dropping the library's evidence to custom — and + Custom SLI writes one from scratch) and the SLOs switch; the Dashboards, Policy, Routes and Validation switches on their layers, each saying which clauses it drops; the scrape targets, endpoints, channels and probe targets as params on the layer they shape — over the live stack of the instantiated pack (a section off dims its slab, marks its head off and its clauses go red on the edge), the pack YAML as a collapsible below
  • Verify: the conformance verdict at the tier with three clause states (pass · pass on a placeholder · fail) and a maturity bar per layer, the schema verdict, the warnings, the stack with the todos pinned to the slab of the artefact each names (and on that layer's sheet) and the parameter that fills each one, the compiled artefacts, the hand-off ("Ready to continue?": resolve or adjust at Define, or continue with visible gaps, which registers the pack as an upload)

Does not belong here:

  • a fourth primary tab (the header shows the build cards only while building)
  • a pack that pages nobody presented as done: a placeholder-laden pack is conformant on paper, so the third clause state, the amber slab edges and the todo count travel with it into Discover
  • a library value that cannot be changed, or a tier that forbids an SLI: the library seeds and the rubric grades; what the team measures is the team's (an edited expression carries no library evidence, and says so)
  • a second rendering of the pack: the stack is the adapter's projection — the artefacts Discover will show, id for id — never a Build-only drawing of the canonical
  • deploy actions (Remediate's, on the registered pack)

Discover

Belongs here:

  • repo scan
  • live MCP generation
  • YAML/JSON upload
  • pack catalog selection
  • layered artifact inventory
  • source metadata and crawler summary

Does not belong here:

  • final diagnostic verdict
  • deploy actions
  • benchmark marketing copy

Diagnose

Belongs here:

  • Diagnostic Grade
  • score, coverage, trust, verified status
  • evidence table
  • drift drill
  • traceability to explain why an artifact matters
  • the response path: which alert each declared remediation answers to, and whether that alert is live (read-only here; the fixes are on Remediate)
  • comparison and atlas analysis as advanced diagnostics

Does not belong here:

  • deploy submission
  • compile output as the main surface
  • unrelated reference browsing

Remediate

Belongs here:

  • A minus B delta
  • deployable rows
  • manual follow-up rows
  • compile preview
  • deploy modal
  • validation status
  • rollback/dry-run affordances
  • the response path's next steps: deploy a missing burn alert, reconcile a drifted one, name the alert an unresolved trigger means

Does not belong here:

  • hiding drift because the grade passed
  • deploying artifacts without provenance
  • forcing all artifacts through the same deploy path

Dry-Run Golden Path

For the Krystaline dry run:

  1. Clear stale uploads if needed.
  2. Load the supplied krystaline.service.repo.yaml repo pack as Pack A.
  3. Load the generated or supplied production-live.pack.yaml as Pack B.
  4. Open Diagnose.
  5. Confirm Diagnostic Grade renders PASS when score is greater than 85%.
  6. Explain remaining drift from the drill-down.
  7. Open Traceability for SLO-to-artifact evidence.
  8. Open Remediate.
  9. Compile the settlement latency remediation artifacts.
  10. Deploy only when the MCP write target and token are ready.
  11. Re-run live generation and compare again.

See DRY_RUN.md for the executable checklist.

See Also