Interface spec: workspaces grouped by question, tabs and tool panels, plain-language task selection
This commit is contained in:
Sam
97
.pi/memory-vault/packs/paperclip-harness/20-context/home.md
Normal file
97
.pi/memory-vault/packs/paperclip-harness/20-context/home.md
Normal file
@@ -0,0 +1,97 @@
|
||||
---
|
||||
type: context
|
||||
id: context.paperclip-harness.home
|
||||
title: home
|
||||
status: active
|
||||
source_of_truth: false
|
||||
freshness: current
|
||||
last_reviewed: 2026-11-10
|
||||
tags:
|
||||
- pack/paperclip-harness
|
||||
- agent-memory/context
|
||||
- autolearn
|
||||
- rich-discovery
|
||||
- repo/home
|
||||
---
|
||||
|
||||
# home
|
||||
|
||||
## Rich discovery update (2026-11-10 02:04:26)
|
||||
|
||||
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
|
||||
|
||||
1. **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.
|
||||
2. **Six workspaces, or fewer?** Fewer means switching views inside panels, which hides state.
|
||||
3. **Which glyph set?** Must be checked against the font on the machine you actually sit at, not assumed.
|
||||
4. **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.
|
||||
|
||||
## Source paths observed
|
||||
|
||||
- `home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md`
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 84%
|
||||
- Reason: Update component/repository context with detailed discovered structure and configuration
|
||||
|
||||
## Related
|
||||
|
||||
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
type: context
|
||||
id: context.paperclip-harness.paperclip-harness-interface-spec-docs-ui-layout-md
|
||||
title: Paperclip Harness interface spec (docs/UI-LAYOUT.md)
|
||||
status: active
|
||||
source_of_truth: false
|
||||
freshness: current
|
||||
last_reviewed: 2026-11-10
|
||||
tags:
|
||||
- pack/paperclip-harness
|
||||
- agent-memory/context
|
||||
- paperclip-harness
|
||||
- ui-layout
|
||||
- bubbletea
|
||||
- lipgloss
|
||||
- spec
|
||||
---
|
||||
|
||||
# Paperclip Harness interface spec (docs/UI-LAYOUT.md)
|
||||
|
||||
`docs/UI-LAYOUT.md` (348 lines) is the single interface document for the Paperclip Harness Go TUI.
|
||||
|
||||
**Stack:** Go with Charmbracelet: Bubble Tea, Bubbles, Lipgloss. Available Bubbles components: list, table, viewport, textarea, textinput, help, key, spinner, progress, paginator, timer, stopwatch, filepicker, cursor. Note: there is NO tabs component in Bubbles; a view switcher inside a panel must be Lipgloss + help styling.
|
||||
|
||||
**Twenty-seven interface items**, each with purpose, Charmbracelet component, and empty/loading/failed behaviour. Key ones:
|
||||
- Panel frame: rounded border, bright edge when focused, plus the word `focus` in the title (focus never depends on colour alone).
|
||||
- Footer key hints: built from `help` and `key.Binding`; keys that would do nothing are not shown.
|
||||
- Stale marker: time of last successful read in the panel title, so a wrong panel is visibly stale.
|
||||
- Blocker badge: `waits on AUD-163`, read per task; when the blocker finishes but the task is still marked blocked the badge shows `ready`.
|
||||
- Needs-you card: one per decision (refused merge, task awaiting answer, ready-but-stuck task), says what happened and the one key that acts.
|
||||
- Composer: `textarea`, Enter sends, Shift-Enter new line, stated in footer.
|
||||
- Diff view: file headers, hunks, line numbers, additions/deletions marked by a leading character as well as colour; large diffs state how many lines were omitted and offer a key for all.
|
||||
- Result receipt: server's own words on failure, never paraphrased.
|
||||
- Health row: pass / fail / **not run** (three states; "not run" is not "pass").
|
||||
|
||||
**Styling:** one theme with semantic roles (text, muted, accent, success, warning, error, surface), light and dark variants from the start. One cell horizontal padding, one blank line between sections, none between rows. Columns computed from content, never hardcoded width. Truncation always visible with full text one key away. Only spinner and selection cursor animate. No colour without meaning a state.
|
||||
|
||||
**Sizes:** every panel declares a minimum useful size (task tree 30x10, diff 40x12, form 50x14); below it the panel draws its own short message naming what it has and what it needs, never a broken layout. Workspace minimum is 80x24.
|
||||
|
||||
**Responsive layout by width:** >=150 cols two/three panels side by side (tree beside summary with Needs you under tree; run log beside diff). 110-149: two panels per workspace, third becomes a tab inside the same-kind panel. 80-109: one panel per workspace full width in order Board, Work, Conversation, Author. Below 80x24: one message.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 90%
|
||||
- Reason: Rich discovery of the interface spec, component constraints, styling rules, and sizing/layout behaviour; anchors future implementation.
|
||||
|
||||
## Related
|
||||
|
||||
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
@@ -88,3 +88,30 @@ Say which layout you want, and I will build it — starting with the width-drive
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
|
||||
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Update (2026-11-10 02:04:26)
|
||||
|
||||
Rewrote `docs/UI-LAYOUT.md` (348 lines, commit b44bf73 "Interface specification: six workspaces, twenty-seven interface items, styling and keys") as the single interface document for the Paperclip Harness TUI, replacing the earlier layout note rather than adding a second one.
|
||||
|
||||
Deliverables: six workspaces, twenty-seven interface items each with purpose, Charmbracelet component, and empty/loading/failed behaviour, a semantic styling system, per-panel minimum sizes, and width-responsive layout rules.
|
||||
|
||||
Validation: discovered actual Bubbles/Lipgloss component availability by listing the vendored module sources (confirmed no tabs component) before writing the spec.
|
||||
|
||||
Follow-up: four open decisions (tree-driven navigation via `.harness/harness.toml` `watching` key, six vs fewer workspaces, glyph set verified against real font, diff panel placement) must be answered, then build Board first with the styling system established before the second panel.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 85%
|
||||
- Reason: Concrete completed deliverable with commit, path, and follow-ups.
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
type: decision
|
||||
id: decision.paperclip-harness.paperclip-harness-ui-six-workspaces-spec-first-four-panel-li
|
||||
title: Paperclip Harness UI: six workspaces, spec-first, four-panel limit
|
||||
status: active
|
||||
source_of_truth: false
|
||||
freshness: current
|
||||
last_reviewed: 2026-11-10
|
||||
tags:
|
||||
- pack/paperclip-harness
|
||||
- agent-memory/decision
|
||||
- paperclip-harness
|
||||
- tui
|
||||
- ui-design
|
||||
- workspaces
|
||||
- architecture
|
||||
---
|
||||
|
||||
# Paperclip Harness UI: six workspaces, spec-first, four-panel limit
|
||||
|
||||
The Paperclip Harness TUI is grouped by user activity, not data source, into six workspaces:
|
||||
|
||||
| Workspace | Question | Panels |
|
||||
|---|---|---|
|
||||
| Board | state of the work / what needs me | Task tree, Task summary, Needs you |
|
||||
| Work | what is happening / what changed | Run log, Diff, Worktree facts |
|
||||
| Conversation | what was said / reply | Thread, Composer, Task header |
|
||||
| Author | what am I asking / how judged | Task form, Guidance, Preview |
|
||||
| Project | folder, machine, limits, cost | Project facts, Costs, Settings |
|
||||
| Repair | layout sound / what broke | Layout map, Health, Log |
|
||||
|
||||
The shell workspace remains for moments needing a prompt.
|
||||
|
||||
Decision: maximum four panels per workspace (a fifth item becomes a view inside a panel or a new workspace). Spec-first workflow: every claim that "it works" is run once in TUIOS before relying on it, but no exploratory testing. The look/style system is established before the second panel exists so it does not drift per screen. Build order: Board first, in document order.
|
||||
|
||||
Rationale: more than four panels cannot be read at once; grouping by activity keeps related concerns together. Alternatives considered: fewer than six workspaces (rejected: switching views inside panels hides state).
|
||||
|
||||
Open questions before build: (1) does the tree drive other workspaces (proposal: Enter writes `watching = AUD-163` into the project's `.harness/harness.toml`, asks TUIOS to show Conversation, panels reload on file change); (2) six workspaces or fewer; (3) glyph set must be checked against the actual machine font, not assumed; (4) diff as its own panel in Work or a tab beside run log.
|
||||
|
||||
Review caveat: all of this is a specification, not yet implemented.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 90%
|
||||
- Reason: Explicit design decision with rationale, alternatives, and open questions; durable for future build work.
|
||||
|
||||
## Related
|
||||
|
||||
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
@@ -92,3 +92,84 @@ Say which layout you want, and I will build it — starting with the width-drive
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
|
||||
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Update (2026-11-10 02:04:26)
|
||||
|
||||
## Structural/configuration observations (2026-11-10 02:04:26)
|
||||
|
||||
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
|
||||
|
||||
1. **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.
|
||||
2. **Six workspaces, or fewer?** Fewer means switching views inside panels, which hides state.
|
||||
3. **Which glyph set?** Must be checked against the font on the machine you actually sit at, not assumed.
|
||||
4. **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.
|
||||
|
||||
## Source paths observed
|
||||
|
||||
- `home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md`
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 82%
|
||||
- Reason: Captured factual repo structure/configuration patterns from rich discovery
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
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
|
||||
|
||||
1. **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.
|
||||
2. **Six workspaces, or fewer?** Fewer means switching views inside panels, which hides state.
|
||||
3. **Which glyph set?** Must be checked against the font on the machine you actually sit at, not assumed.
|
||||
4. **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
|
||||
|
||||
## Related
|
||||
|
||||
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
Reference in New Issue
Block a user