submarine/notes/usability-plan.md

Usability plan (draft)

Status: items 1–8 and 11 are done (D31, D32); the rest is a proposal. Items that change behavior need a decision in decisions.md and updates to ux-guide.md / actions.md when they are taken up.

Done differently than proposed below: the labels are x restore to pin and X restore committed pins; the tools read ! problems only • / filter • f fetch (most useful first, dropped from the end); space toggle stays, as it now follows ←→/hl collapse/expand.

Goal

The target user is a developer who doesn't know git submodules well. They should understand the screen and act safely without reading a manual. At any moment the screen should answer three questions:

1. What is wrong? What does this state mean, in plain words?
2. What can I do about it? Which key fixes it?
3. What will this key do? What happens to my work, and can I undo it?

Today the tool answers (1) partly (the issue lines in the detail pane) and (3) well after a key is pressed (loss question, flash). It hardly answers (2), and it answers (3) only by trying. Most items below move the answers from "after pressing" to "before pressing".

Findings this is based on

From a walkthrough on the make-fixture.sh superproject (2026-10-24):

• x restore and X hard restore don't say the target ("to the pin"), the scope (the submodule and everything below it) or how they differ. "Hard" suggests "discards my changes", but both do that. The real difference, staged pins, can't be guessed.
• X drops a staged pin without asking (restored libs/staged to the committed pins), one Shift away from x.
• f fetch, / filter and ! problems only appear only in ?. The detail pane says fetched never but gives no hint how to fetch. ! is the most useful view for many submodules, and nothing points to it.
• The words in the tree (off pin, off target, staged, ●, ·1, ↓2) and on the spine (pin, tip, you, base) are explained nowhere in the UI.
• u update pin on the superproject actually fast-forwards the current branch; the label stays the same.
• The palette is static: u is offered when it can't do anything, and the user finds out from a flash.
• Mismatched words: the footer says "fold", the help "collapse/expand"; space toggle doesn't say what it toggles.
• Good, and worth keeping: questions only when something would be lost, the loss listed exactly, flashes that say why and suggest another key.

Overview

Effort: S = hours, mostly labels and docs; M = a day or two, new logic in existing components; L = several days, new UI or new provider calls. Impact: how much it helps the target user's main flows (understand state, fix a submodule, find problems, stay safe).

#	Item	Effort	Impact	Flow
1 ✓	Clear names for restore and hard restore	S	High	fix, safe
2 ✓	Ask before X drops staged pins	S	High	safe
3 ✓	Show /, !, f in the footer	S	High	find
4 ✓	Status legend in ?	S–M	High	understand
5 ✓	Groups with titles in the full help	S	Medium	understand
6 ✓	Plain-word fixes for wording	S	Low	understand
7 ✓	u label for the superproject	S	Medium	fix
8 ✓	Fetch hint at fetched never / old fetches	S	Medium	understand
9	Next step for each issue in the detail pane	M	Highest	understand, fix
10	Palette that fits the selection	M	High	fix
11 ✓	First-start hint	S	Medium	understand
12	Undo hint after a restore, switch or update	M	Medium	safe
13	Action menu on enter	M–L	High	fix, understand
14	"What would happen" preview	L	Medium	safe

Quick view by quadrant:

	Low effort	Medium effort	High effort
High impact	1, 2, 3, 4	9, 10, 13
Medium impact	5, 7, 8, 11	12	14
Low impact	6

Items

Low effort

1. Clear names for restore and hard restore. S · High The labels should give target and difference without the docs. Proposal: x restore to pin, X restore, unstage pins. In the full help, longer: x restore to pin (with everything below), X restore to committed pins, drop staged ones. The question lines already use "to the committed pins"; keep the same words everywhere. Alternative: rename the action to "reset". Rejected for now: git reset moves branches, which restore never does (D23). Docs: ux-guide key reference, actions.md "Keys and palette", README.

2. Ask before X drops staged pins. S · High Amends D30 ("alone they don't make it ask"). A staged pin is a decision the user made, and X sits next to x. If X would drop at least one staged pin, ask: Restore src/app to the committed pins? Unstages 2 pins. y restore · n cancel. The loss is already counted, so only the trigger changes. D30's argument (the commit stays in the submodule) holds for an expert, not for someone who doesn't know where to find it again.

3. Show /, !, f in the footer. S · High Proposal: / filter • ! problems • f fetch after the navigation keys, before the global keys. The existing rule drops keys from the left group's end when the footer is too narrow, so narrow terminals lose them first and nothing else changes. While problems only is on, the footer could read ! all (the action the key does now). r reload stays in ?.

4. Status legend in ?. S–M · High The full help gets a second block, "What the words mean", with one line per status word and symbol, using the same colors as the tree: off pin the checkout is not the commit the parent records, staged, ●, ↑n ↓n, ·k, and the spine roles (pin, tip, you, base, target). Wording comes from state-model.md; the explanations the detail pane already uses are a good source. Layout: below the key columns if there is room, otherwise ? pages between keys and legend (? more).

5. Groups with titles in the full help. S · Medium The help columns are already grouped, but without titles. Add short titles on top: Move, Selected submodule, All repositories, App. Then it is clear that x acts on the selection and f on everything.

6. Plain-word fixes. S · Low

• Footer fold → collapse/expand; ⇧←→/HL fold all → H/L all.
• space toggle → space open/close.
• c copy path → say which path (copy path is fine if it is the relative path; check).
• Header pin staged vs tree staged: one word.

7. u label for the superproject. S · Medium With the header selected the palette says u pull (fast-forward), since that is what it does (D29). Labels that change with the selection need item 10's mechanism, but this one is simple on its own: one check for the header.

8. Fetch hint. S · Medium fetched never (and an age above a threshold, e.g. a day) gets a muted · f fetches. Users who don't know that the arrows (↓2) are only as fresh as the last fetch otherwise trust old numbers.

11. First-start hint. S · Medium On start, the footer's flash line shows ? explains keys and states until the first key. No config file, no state: it is shown every start, and it is just a muted line. Makes item 4 discoverable.

Medium effort

9. Next step for each issue in the detail pane. M · Highest Each issue line ends with what to do about it, as keys:

off pin    checkout is not the pin        x back to pin · b record a branch
changed    3 files changed                commit outside, or x discard
missing    not initialized                x restore
off target pin is not on origin/main      b switch branch

A pin that is only behind (↓2, no issue) gets the same kind of hint on its Ref line: u update pin.

This is the single biggest step for the target user: they no longer need to know what to do, only to read. Layering: which action resolves which issue is meaning, not looks, so it belongs in internal/submodule (e.g. a Remedies() on the issue, returning action kinds) and the words in theme. It must agree with what the actions really allow (e.g. u only when behind and not ahead, D29), which item 10 needs anyway.

10. Palette that fits the selection. M · High Amends actions.md ("the palette is static"). The palette keeps the same keys in the same places (muscle memory), but:

• keys that can't do anything for the selection are drawn muted (u when up to date, b on a missing submodule); pressing them still flashes why;
• the key that item 9 recommends for the most severe issue is highlighted. The checks for u already exist as flash reasons; they are cheap and need only the status, so this is a matter of calling them for the palette too. Restore stays always active (it is idempotent).

12. Undo hint after a restore, switch or update. M · Medium The success flash names the old commit when a repository moved: restored src/app (was 1a2b3c4). A flash only lasts a moment, so the detail pane could keep previous 1a2b3c4 until the next reload. For a user who doesn't know git reflog, this is the difference between "lost" and "recoverable". No new provider call if the SHA is taken before the action.

13. Action menu on enter. M–L · High enter on a row opens a small popup (reusing the branch popup's frame) listing the actions for this submodule, each with one line of explanation and its key; the recommended one first and selected. enter runs it, esc closes. Users who know the keys never need it; users who don't need no memory at all. enter is unused in the tree today.

High effort

14. "What would happen" preview. L · Medium In the action menu (13), the selected entry shows the effect before running it: moves the pin e510d9b → 906f119 (2 commits), discards 3 changed files. The loss check exists, but it is async git work, so it runs when the entry is selected, with a spinner. Valuable, but the loss question already covers the dangerous cases, so this comes last.

Order

1. Labels and safety (1, 2, 3, 5, 6, 7): only labels, docs and one question trigger. Fixes the worst risk (X) and the hidden keys at once.
2. Explain the screen (4, 8, 11): the legend and the hints that point to it.
3. Guide to the fix (9, 10): issue → key, and a palette that agrees. Needs a decision on where remedies live (layering).
4. Menus and previews (12, 13, 14).

How to check

Give someone who hasn't used submarine the fixture (make-fixture.sh) and these tasks, without the docs:

• Find every submodule that needs attention.
• Get ui up to date with its branch.
• Put core back where the superproject wants it.
• Find out whether the arrows are current.
• Explain what staged on libs/staged means.

Note keys tried, wrong actions and questions asked. Run it before phase 1 and after each phase.

Open questions

• Item 1: are "restore to pin" / "restore, unstage pins" the right words, or should X move under a different key that is not one Shift away?
• Item 2: ask for every dropped staged pin, or only for the selection's own?
• Item 9: are external actions (commit outside submarine) good hints, or only keys?
• Item 13: does enter stay free for something else (e.g. opening a shell in the submodule)?