cad-atlas/docs/UX-REVIEW.md

CAD Atlas — Fresh-Eyes UX Review

Reviewer role: fresh-eyes UX (not implementer). This document critiques the copy and information architecture of the "From Signal to Pod" atlas and specifies the progressive-disclosure layer for the coming sprint. It does not change code.

Sources reviewed:

• internal/atlas/atlas.json (authored stages + nodes)
• internal/web/handler.go (which stages get live data overlaid)
• .context/PROJECT.md (ground-truth meaning of each stage/gate)

---

1. Diagnosis — why the current atlas is hard for a naive viewer

The atlas is written by the person who built the pipeline, for the person who built the pipeline. Almost every node names a mechanism (Ed25519 admission controller, var-go Oath, dma-cli, assessor-loop ledger, agentsquad, ISC, TELOS) rather than the thing that happens to a piece of work. A compliance officer or a new engineer cannot answer the two questions they actually have: "what is happening to the work at this step?" and "why does it move to the next step?"

The second question is completely unanswered. The atlas renders nine stages connected by arrows, but the arrows carry zero copy. There is no statement of what has to be true for work to advance — which is exactly where the interesting governance lives (a human sign-off at 04, a green CI gate at 06, an integrity check at 03). The pipeline's whole selling point is "auditable, gated flow," yet the gates between stages are invisible. A viewer sees a row of jargon boxes and an implied left-to-right drift, with no sense of what earns each hop.

Two smaller aggravators: (a) the reel is dense — 20+ nodes, colour-coded pills whose meaning is never keyed, and Swedish-homelab proper nouns (koala, iguana, flamingo) that a stakeholder can't decode; (b) Stage 06 is authored-empty (it's generated live from CI), so on a cold/offline load that column can read as "nothing happens here," which is the opposite of the truth — CI is a governance gate.

The fix is not to dumb it down. It is to make plain-language the default layer — a one-line "what happens + why" per stage, and a labelled "what must be true to advance" per arrow — and demote today's precise, correct technical copy to an on-demand layer.

---

2. Per-stage plain-language map (00–08)

stage	plain_title	plain_what (one jargon-free sentence)	keep_technical (on-demand)
00 Signals	Notice what's happening	New ideas and developments worth reacting to are collected — mostly an automated daily/weekly scan of AI news, plus things saved by hand.	"Signals → mathias/signals"; Applied AI Radar (Tier-1 daily / Tier-2 weekly), verified-primary bar; brain capture; aspirational inbox surfaces (not built).
01 TELOS	Why we're here	The mission, goals, and problems we're actually trying to solve live here — every piece of work downstream has to trace back to one of these goals.	"TELOS — intention substrate", wiki/telos/, brain_query wing=telos.
02 Strategic session	Think it through	A human and AI models work out what to do and why, debating hard calls and writing down the decision and what "done" will mean.	"Strategic session" — claude.ai frontier + brain MCP; ADRs/specs; ISC acceptance criteria; LLM Council (fan-out → anonymous cross-review → chairman synth); Autoresearch Council.
03 Spec → Gitea issue	Write the work order	The decision is turned into a precise, self-contained work order that an AI agent can execute unsupervised — with a pass/fail definition of done, a risk rating, and a tamper-proof seal.	"Spec → Gitea issue" — binary ISC, risk tier LOW/MED/HIGH, reg-risk assessment, no open human deps; Ed25519 admission controller (#36); var-go Oath (single fenced block, fail-closed).
04 Human dispatch gate	Human says go	A person reviews the work order and its risk and decides whether to release it — this is the one and only checkpoint where work does not move on its own.	"Human dispatch gate — the only checkpoint"; ratify plan + risk tier; Session-Dispatch bridge (claude.ai MCP → workflow_run_trigger → cad-dispatch.yml → agentsquad); dispatch-allow eligibility.
05 Execute · agentsquad	Agents do the work	AI agents actually build the thing — one writes, a second independent one reviews it to avoid marking its own homework — and every step is logged for the audit trail.	"Execute · agentsquad" on koala; Task API (POST /tasks); executor+reviewer loop (ADK Go + LiteLLM, reviewer on distinct tier); dma-cli routing + 3-layer scope guardrail; assessor-loop attestation ledger + brain session_log.
06 PR → CI	Automatic quality checks	The proposed change is run through automated tests and safety checks — including a check that it actually satisfies the work order's definition of done — and only a clean pass lets it continue.	"PR → CI" — Gitea Actions cd.yml; go test/vet/lint/govulncheck; var-go/oath gate (correctness floor over the reviewer, anti-rubber-stamp #55). Nodes generated live from the latest CI run.
07 CD → pod	Ship it	Once everything is green, the change is deployed automatically to the live server — with the rule that merging code alone doesn't ship it; the release has to be pointed at the new version.	"CD → pod" — Flux GitOps → k3s on koala; "push ≠ deploy: bump tag in mathias/infra"; ntfy on deploy. Deploy + Flux state overlaid live.
08 Loop back	Did it work?	The result is scored against the goal that started it and fed back into the mission board, so the next round of planning learns from what shipped.	"Loop back → TELOS (feedback bus)"; session_log + attestation → brain; outcome scored vs originating goal; arc partly manual (improvement target).

---

3. Per-node plain restatements

The existing d text stays as the technical detail layer. Each plain line below is the jargon-free default. Kept accurate to PROJECT.md.

Stage 00 — Signals

• Applied AI Radar → "An automated scan reads AI news every day (and deeper every week) and keeps only claims backed by a real paper, benchmark, code, or named lab."
• Manual capture → "Anything interesting spotted by hand gets saved into the same inbox."
• Aspirational surfaces → "Planned-but-not-built: sending ideas in by Telegram, voice, or a URL." (mark clearly as a gap / not yet real.)

Stage 01 — TELOS

• Intention substrate → "The master list of mission, goals, problems, and current status — the yardstick everything downstream is measured against."

Stage 02 — Strategic session

• Design · ADRs · specs → "A human and a top-tier AI model figure out the approach and write down the decision plus what a finished result must prove."
• LLM Council → "For hard calls, several AI models answer independently, anonymously critique each other, and a 'chair' model synthesises one verdict — reduces any single model's bias."
• Autoresearch Council → "A parallel version of the same review that vets research findings before they're allowed through."

Stage 03 — Spec → Gitea issue

• Contract enforced → "The work order must have a clear pass/fail test, a risk rating, a regulatory-risk note, and no unfinished human dependencies before it counts as agent-ready."
• Admission controller → "The work order is cryptographically signed when created, so any later tampering is detectable and the eventual change can be checked against it."
• var-go Oath → "A machine-checkable 'definition of done' is embedded in the work order — exactly one, or the order is rejected — later used to prove the result actually meets the spec."

Stage 04 — Human dispatch gate

• Human triggers execution → "A person confirms the plan and its risk level, then releases the work — nothing runs until they do."
• Session-Dispatch bridge → "The approval flips a switch that hands the signed work order over to the agents to start execution."

Stage 05 — Execute · agentsquad

• Task API → "A request kicks off a job and hands back an id you can poll for progress."
• Executor + reviewer loop → "One agent does the work; a second, independent agent on a different model reviews it — so nothing marks its own homework."
• dma-cli · routing + scope → "A router sends each agent to the right AI backend and enforces what it is and isn't allowed to touch, with a confirmation gate as a guardrail."
• assessor-loop ledger → "Every step is recorded in a tamper-evident log so the whole run can be audited afterwards."

Stage 06 — PR → CI (nodes generated live from the latest CI run — no authored nodes)

• Live jobs render here; the plain framing for the column is: "Automated tests and safety checks run on the proposed change, including a check that it truly satisfies the work order — only a clean pass moves on."

Stage 07 — CD → pod

• Deploy on green → "When all checks pass, the release system rolls the new version onto the live server automatically — but only once the release is pointed at that version (merging code alone doesn't ship it)." (live deploy + Flux status also shown.)

Stage 08 — Loop back

• Close the loop → "The outcome is scored against the goal that started it and written back to the mission board, so future planning learns from what actually shipped."

---

4. Transitions — the key deliverable

For each arrow: what moves the work forward, and what must be true for it to advance. These should be rendered on the arrows themselves (see §5). Today they are blank.

• 00 → 01 — "Does it matter to us?" A raw signal only advances if it connects to something we actually care about. Most captured signals stop here; the few that touch the mission get pulled up against a goal.

• 01 → 02 — "Worth a session?" A goal or problem on the board becomes the seed for a design session when it's decided it's worth working on now. The goal is the input the session must trace back to.

• 02 → 03 — "Decision reached." Once the debate converges on a decision (and what "done" will mean), it advances only when that thinking is written down as a concrete, testable specification — not while the answer is still open.

• 03 → 04 — "Order written, sealed, agent-ready." Work advances to the gate only when the spec is a complete contract: a pass/fail test, a risk tier, a regulatory note, no open human dependencies, one embedded Oath, and a valid cryptographic signature. A malformed or unsigned order fails closed and does not reach the gate.

• 04 → 05 — "A human said go." This is the hard stop. Nothing crosses automatically. A person must review the plan and risk and explicitly release it, and the repo must be on the allow-list, before any agent starts. This is the single human checkpoint in the whole pipeline.

• 05 → 06 — "Agents produced a change." Work advances when the agents finish and open a proposed change (a PR) with its audit log attached. Until there's a concrete change to test, nothing moves.

• 06 → 07 — "All checks green." The change advances only if every automated check passes — tests, linters, security scan, and the Oath check proving it meets the original work order. Any red gate stops it here; a passing reviewer is not enough to override a failed Oath.

• 07 → 08 — "It's live." Once the new version is actually running on the server, the deployed outcome becomes the input to scoring. Advancing means "shipped and observable," not just "merged."

• 08 → TELOS (feedback bus, dashed) — "What did we learn?" The scored outcome flows back into the mission board so goals, problems, and priorities update. This is the loop that makes the pipeline a cycle rather than a line. Note per PROJECT.md this arc is partly manual today and is an explicit improvement target — the dashed styling should read as "aspirational / not fully automated," not just decorative.

---

5. Progressive-disclosure recommendations

Default (Plain) layer — what everyone sees on load:

• Each stage column shows: the plain_title as the headline, the technical title as a smaller subtitle, and the one-line plain_what directly under it.
• Each node shows its plain one-liner as the primary text. The current d string is hidden by default.
• Each arrow shows a short transition label (the bolded phrase from §4, e.g. "A human said go", "All checks green") — this is the single biggest comprehension win and must ship in the default layer, not behind a toggle.

On hover / expand (per node):

• Reveal the technical d text, the tags, and the pill's meaning.
• On the arrow, hovering expands the short label into the full "what must be true to advance" sentence from §4.

Plain ⇄ Technical toggle (global):

• A single top-level switch, defaulting to Plain. Persist the choice (localStorage).
• Plain: plain_title headline, plain_what, plain node lines, short arrow labels. Proper nouns (koala/iguana/agentsquad/TELOS) suppressed or shown only as a footnote.
• Technical: today's exact copy — titles, d strings, tags, substrate host specs — i.e. the atlas as it exists now. Nothing is lost; the current view becomes "Technical."
• The toggle should crossfade in place, not reflow the whole layout, so a viewer can flip back and forth and map plain↔technical on the same node.

Visual cues for the currently-bare transitions:

• Give every arrow a label chip sitting on the spine. Gate arrows (04→05 human, 06→07 CI) get a distinct treatment — a lock/shield glyph and a stronger colour — because those are the governance moments the whole atlas exists to show.
• Make the 08 → TELOS feedback bus visibly different (dashed + "partly manual" tag) so its aspirational status is honest, matching PROJECT.md's dogfooding-honesty discipline.
• Add a small, always-visible legend keying the pill colours and the three gate types (integrity / eligibility / correctness), since colour is currently unexplained.
• For Stage 06 (authored-empty, generated live): when no live CI data is present, show the plain_what placeholder ("Automated tests and safety checks run…") rather than an empty column, so it never reads as "nothing happens here."

Three-gate overlay (stretch, high value for the compliance audience):

• A "show governance gates" toggle that highlights the three orthogonal gates on top of the pipeline: integrity (03, Ed25519), eligibility (04/05, dispatch-allow), correctness (06, Oath). This directly serves the "audit chain is the viz data" thesis for a compliance/exec viewer.

---

6. Prioritized punch list (top 8 by comprehension impact)

1. Label every arrow with a plain "what must be true to advance" phrase (§4). Biggest miss, biggest win — turns a row of boxes into a story of gated flow. Default layer.
2. Add a plain_what one-liner per stage as the default column copy (§2), with the technical title demoted to subtitle.
3. Ship the Plain ⇄ Technical global toggle, defaulting to Plain, persisting choice; current copy becomes the Technical view (nothing thrown away).
4. Rewrite node primary text to the plain lines (§3); move existing d to hover/expand.
5. Visually distinguish the two real gates (04 human, 06 CI) with lock/shield glyphs and stronger colour so the checkpoints read as checkpoints.
6. Add a legend keying pill colours and the three gate types — colour currently carries meaning nobody can decode.
7. Fix the Stage-06 empty-column problem: show a plain placeholder when live CI data is absent, so the CI gate never looks like a no-op.
8. Make the 08→TELOS feedback bus honestly aspirational (dashed + "partly manual" tag), and suppress homelab proper nouns (koala/iguana/flamingo/agentsquad/TELOS) in Plain mode, surfacing them only in Technical or a footnote.