Files

Sam 5b829000ae Interface spec: workspaces grouped by question, tabs and tool panels, plain-language task selection

2026-11-10 13:25:55 +11:00

6.8 KiB

Raw Blame History

type: session id: session.paperclip-harness.rich-discovery-home-2026-11-10-02-04-26 title: Rich discovery: home 2026-11-10 02:04:26 status: active source_of_truth: false freshness: current last_reviewed: 2026-11-10 tags: - pack/paperclip-harness - agent-memory/session - autolearn - rich-discovery - repo/home

Rich discovery: home 2026-11-10 02:04:26

Sanitized rich discovery snapshot captured automatically from the completed turn.

Source paths observed

home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md

Final answer snapshot

You are right to call it, and I will not push back on the substance: the last few turns drifted into proving commands rather than designing the thing. Here is the line I would hold, briefly — when a claim reaches you as "it works", it gets run once in TUIOS, because a spec built on an unproven assumption is the failure that cost you three restarts. One check per claim. Not exploratory testing. Everything else, spec first.

I have rewritten docs/UI-LAYOUT.md as the single interface document (348 lines, replacing the earlier layout note rather than adding a second one).

How it is grouped

By what you are doing, not by which system the data came from:

Workspace	Question it answers	Panels
Board	what is the state of the work, what needs me	Task tree · Task summary · Needs you
Work	what is happening now, what changed	Run log · Diff · Worktree facts
Conversation	what was said, what do I say back	Thread · Composer · Task header
Author	what am I asking for, how will it be judged	Task form · Guidance · Preview
Project	which folder, machine, limits, cost	Project facts · Costs · Settings
Repair	is the layout sound, what broke	Layout map · Health · Log

Six, not sixteen. Four panels maximum per workspace, and the shell workspace stays for the moments you need a prompt. More than four panels cannot be read at once, so a fifth thing becomes a view inside a panel or a new workspace.

The interface items

Twenty-seven, each with a purpose, its Charmbracelet component, and its empty, loading and failed behaviour. The ones that matter most:

Panel frame — rounded border and bright edge when focused, plus the word focus in the title, so focus never depends on colour alone.
Footer key hints — built from help and key.Binding, so a key that would do nothing is not shown.
Stale marker — the time of the last successful read, in the panel title. A wrong panel is visibly stale instead of quietly wrong.
Blocker badge — waits on AUD-163, read per task; when the blocker finishes but the task is still marked blocked the badge changes to ready, because that is our most confusing state.
Needs-you card — one per decision: a refused merge, a task waiting on an answer, a task ready but stuck. Each says what happened and the one key that acts.
Composer — textarea, Enter sends, Shift-Enter new line, stated in the footer because a text area normally does the opposite.
Diff view — file headers, hunks, line numbers, additions and deletions marked by a leading character as well as colour; a large diff says how many lines it left out and offers a key for all of it.
Result receipt — the server's own words on failure, never a paraphrase.
Health row — pass, fail, or not run, three states, because "not run" is not "pass".

Components: list for rows and decisions, table for figures, viewport for anything scrollable, textarea for the composer, textinput for single-line fields, help and key for the footer, spinner and progress for feedback. One honest note: there is no tabs component in this collection, so a view switcher inside a panel is Lipgloss and help styling, not a Bubbles widget.

Styling

One theme with semantic roles (text, muted, accent, success, warning, error, surface) and a light and dark variant from the start. One cell of horizontal padding, one blank line between sections, no blank line between rows. Columns computed from the content in view, never a hardcoded width. Truncation always ends visibly and the full text is one key away. Only two things animate: the spinner and the selection cursor. No colour that does not mean a state.

Sizes

Every panel declares a smallest useful size (the task tree needs 30 by 10, the diff 40 by 12, the form 50 by 14). Below it, the panel draws its own short message naming what it has and what it needs — never a broken layout, never a scrollbar to hide the problem. The workspace needs 80 by 24.

Layout follows the width

150 columns and wider: tree beside summary with Needs you under the tree; run log beside diff. 110 to 149: two panels per workspace, the third becomes a tab inside the panel of the same kind. 80 to 109: one panel per workspace, full width, in the order Board, Work, Conversation, Author. Below 80 by 24: one message.

Four decisions before I build

Does the tree drive the other workspaces? Proposal: Enter writes watching = AUD-163 into the project's .harness/harness.toml and asks TUIOS to show Conversation; the other panels reload when that file changes. One fact, one owner, survives a restart.
Six workspaces, or fewer? Fewer means switching views inside panels, which hides state.
Which glyph set? Must be checked against the font on the machine you actually sit at, not assumed.
Diff: its own panel in Work, or a tab beside the run log?

Answer those four and I will build Board first, in the order the document lists, with the styling system established before the second panel exists — so the look is settled once instead of drifting per screen.

Evidence

Confidence: 86%
Reason: Preserve full sanitized discovery detail from a rich investigation turn

packs/paperclip-harness/00-system/pi-agent/memory-manifest

6.8 KiB Raw Blame History