PRD — Session Detail v6: the Answer Card, finished

[silouone]

PRD — Session Detail v6: the Answer Card, finished

Synthesized from the 2026-07-02 prototype election (11 agents, 4 judge lenses, grounded
in the 332-session usage corpus), the 2026-06-27 widget election (docs/ELECTION_VERDICT.md,
6-juror unanimous-to-keep), and the elected synthesis prototype
specs/session-detail-mockups/v6-hybrid.html. Target branch: feat/session-detail-v6.

Problem Statement

When I open a session in the cLens dashboard I have two jobs: a 10-second triage
("did it work, what did it cost, anything weird?") and an occasional deep post-mortem
("where did it thrash, what did each agent do?"). Today the Overview greets me with a
12-widget bento grid that re-draws, at glance resolution, the same charts the four tabs
already own at full resolution — so triage is slower, not faster, and the signal I
actually need is diluted. Worse, my real sessions are multi-agent 74% of the time, yet
agents are dead-ends: I can see who ran but I can't follow one agent through the session.
At real data volumes (p90: 396 tool calls, 311 timeline events) the tab chrome scrolls
away, the timeline can't be narrowed to one agent, and a backtrack can't take me to the
exact moment it happened. Meanwhile 41% of my sessions modify no files and 49% have no
backtracks — half the page is empty shells on those runs.

Solution

Finish the elected Answer Card design: the Overview becomes one generous answer card
plus the four unanimous forensic tabs — nothing else. The card carries every
load-bearing number (verdict, request, narrative, health tiles with click-drills for
cost and context, git outcome, task completion); the tabs own all detail with the full
content width. Agents become destinations: any agent mention navigates to that
agent's own view. The tab bar stays pinned while scrolling, printed hotkey badges make
the existing keyboard layer discoverable, the Timeline gains a per-agent filter, and
backtracks jump to the exact anchored moment on the Timeline. Sections render only when
their data exists — quiet, honest instrument chrome at every session size.

User Stories

1. As a session owner, I want the Overview to be a single answer card, so that my 10-second triage never competes with duplicate glance widgets.
2. As a session owner, I want the verdict, cost, duration, tool calls, backtracks, and context peak visible without scrolling, so that triage costs one glance.
3. As a session owner, I want the git outcome (commits, +/− lines, files) on the answer card, so that I know what actually landed without opening a tab.
4. As a session owner, I want a task-completion gauge on the answer card when a task list exists, so that I can see plan progress at a glance.
5. As a session owner, I want to click the Cost tile and see the token mix (input/output/cache) with model and tier, so that I understand where an estimated cost comes from.
6. As a session owner, I want to click the Context Peak tile and see the full context curve with the breach line and compaction markers, so that I can spot context pressure and when compaction struck.
7. As a session owner running multi-agent workflows, I want every agent mention (sidebar tree, Communication tab graph/leaderboard/log) to navigate to that agent's view, so that I can follow one agent through the session.
8. As a session owner, I want an agent's view to show its ministats (type, tool calls, duration, messages sent/received) and its directional message log, so that a per-agent post-mortem needs no cross-referencing.
9. As a session owner scrolling a 300-event timeline, I want the tab bar to stay pinned, so that switching tabs never costs a scroll-back.
10. As a keyboard user, I want visible hotkey badges on the tabs and a back hint, so that the keyboard layer is discoverable instead of secret.
11. As a session owner, I want number keys to switch tabs without colliding with existing sidebar shortcuts, so that muscle memory stays safe.
12. As a session owner of an 8-agent run, I want to filter the Timeline to one agent, so that I can isolate a single agent's trail among hundreds of events.
13. As a session owner, I want the timeline's density ribbon to reflect the active agent filter, so that the picture and the list never disagree.
14. As a session owner investigating a backtrack, I want "jump to Timeline" to land on and flash exactly the anchored event, so that I see the moment in context instead of hunting for it.
15. As a session owner of a solo debugging run, I want team/harness sections absent (not empty), so that a solo session reads clean instead of embarrassing.
16. As a session owner of a read-only analysis run (41% of my corpus), I want zero-edit and zero-backtrack states to be small honest notes, so that empty panels never anchor the layout.
17. As a session owner, I want the archived widgets kept in code behind a single flag, so that any card can be restored by deleting one id.
18. As an OSS user on a light-themed OS, I want every new drill, badge, and filter to respect both themes and the design tokens, so that light mode stays first-class.
19. As an OSS user discovering cLens, I want the Overview to communicate the product's verdict-first philosophy at first open, so that the value proposition is legible in one screen.
20. As a maintainer, I want the grid dissolution to be reversible and covered by gate tests, so that the redesign carries zero data loss and no silent regressions.

Implementation Decisions

• Widget grid dissolution (from the widget election, verbatim): a single
  ARCHIVED_WIDGETS set gates all 12 Overview widgets; nothing is deleted, imports and
  barrels stay; one-flag restore per widget; the grid container disappears while all ids
  are archived. Snippet from the election (encodes the decision precisely):

  const ARCHIVED_WIDGETS = new Set<string>([
    "w_activity", "w_agents", "w_context", "w_cost", "w_edits", "w_files",
    "w_outcome", "w_risk", "w_taskplan", "w_reasoning", "w_config", "w_harness",
  ]);
  const shown = (id: string) => !ARCHIVED_WIDGETS.has(id);

• HeroBand absorbs the four unique numbers with no tab home: git outcome line,
  task-completion mini-gauge (conditional on a task list), Cost tile click-drill
  (token-mix bar + model/tier + estimated flag), Context Peak tile click-drill (curve +
  80% breach line + compaction markers). Both drills follow the popover/inline patterns
  proven in the v6 prototype.

• Edits tab is the only tab gaining a permanent summary header (chains / edits /
  abandoned, churned-files bar, waste gauge, risk-ranked files) — it absorbs the Edits
  and Files widgets. The other three tabs already headline their content.

• Agents as destinations: the existing per-agent view (already routed via search
  params) becomes reachable from every agent mention — Communication tab graph nodes,
  leaderboard rows, swimlane/message-log names. No new agent page is built; this is
  wiring, not construction.

• Sticky tab bar: the tab bar pins within the detail scroll container (sticky, not
  fixed), with an opaque background and the established z-scale.

• Hotkey badges: printed kbd chips on tab buttons; keys must not fire when an input
  or contenteditable is focused. Number-key allocation must be reconciled with the
  existing sidebar shortcuts (sidebar owns agent selection keys today) — the builder
  resolves the collision and documents the final map in the keyboard help panel.

• Per-agent Timeline filter: chip row (ALL + one per agent, with event counts),
  rendered only for multi-agent sessions; filters both the event list and the density
  ribbon (ribbon re-derives from filtered events). Requires the timeline extractor to
  carry agent attribution on events where it is known; unknown stays unattributed and
  always visible.

• Anchored backtrack jump: a backtrack row jumps to the Timeline tab, clears the
  agent filter, scrolls to the event nearest its timestamp, and flashes only that row.

• Conditional rendering doctrine (from the usage corpus): harness/team/task sections
  render nothing when data is absent; zero-edit and zero-backtrack tabs show one-line
  honest empty states. No empty shells.

• Theme + identity: all new UI uses the locked design tokens (instrument identity,
  both themes); charts redraw on theme change.

Testing Decisions

• Test external behavior only: what renders for a given distilled-session fixture, and
  what navigation/filter state results from a user action — never internal component
  structure.
• Extend the existing gate tests (the design-token gate and the web-client state
  wiring gate are prior art) with: a grid-dissolution gate (archived widgets don't
  render; removing an id from the set restores the card) and a keyboard-collision gate
  (no key bound twice in the detail view).
• Unit-test the new pure logic at the lib level (timeline agent-filter derivation,
  ribbon re-derivation, anchor-nearest-event resolution) following the existing
  test/unit style.
• API/fixture tests reuse the existing distilled-session fixtures; add one solo and one
  zero-edit fixture to lock the conditional-rendering doctrine.
• Full suite (bun test), typecheck, and lint are merge gates for every slice; a final
  web-qa story pass drives the real dashboard through the seven headline interactions.

Out of Scope

• The session list, Usage, Insights, and Settings pages.
• The TUI and CLI renderings of the same data.
• Restyling the four tabs beyond the Edits header and the Timeline filter (their content
  won the election as-is).
• v3-style generated editorial headlines (post-launch experiment; needs a narrative
  generator over distill output).
• The v2 command palette (orthogonal to this page; revisit post-launch).
• Deleting archived widget code (explicitly kept behind the flag).
• Prototype-suite cleanup (tracked in the mockups NOTES.md, separate from this build).

Further Notes

• The v6 prototype (specs/session-detail-mockups/v6-hybrid.html, key 6 in the suite
  navigator) is the interaction reference; its 10-graft checklist doubles as the
  acceptance walk for the final web-qa pass. Prototype code itself is throwaway per the
  prototype doctrine — production implementations are written fresh against the real
  component library.
• Usage-corpus numbers cited throughout come from the 2026-07-02 profiling of 332
  distilled sessions (74% multi-agent, 41% zero-edit, 49% zero-backtrack, p90 396 tool
  calls / 311 timeline events).
• The web client is SolidJS — new work follows Solid idioms (Show guards, stores),
  matching the surrounding code.