Does screen-decomposition work? 4 cases x 4 arms x 5 Haiku runs

screen-decomposition holds the principles for organizing everything a project has into layered screens. They don't depend on the medium. cli-engineer keeps only what those principles look like in a terminal. minimal-ux-flow loads the new skill wherever it organizes screens. Nothing is written until you say yes; then it goes to ~/projects/my-skills/screen-decomposition/.

What moves into screen-decomposition

Each rule is written without terminal words. Your quotes move with the rule they justify.

# Principle Today in cli-engineer
1 Every convention is a first bet. What decides is what this project's screens help its user do, and what keeps everything easy to reach ("the 3 columns are just a suggestion ...") "How to think about it", first paragraph
2 Write the real-world scenario first: who reaches for it, at what moment, to do what (conceptual-modeling) Step 2
3 List every thing the user of the scenario would want to reach, with its technical form and where it is defined; what already exists counts and is never written twice; a part the owner decided is unused, abandoned or for another kind of user stays off the map (added after the first draft mapped the UI's abandoned Leads in 5 of 5 runs) Step 3
4 Group by what the user is trying to do, not by file type or data type Step 4, first sentence
5 Name things in the project's own words (README, code), never an invented word; one word per thing Column table, "Take the noun from the project's own words"
6 A tree of nouns: each noun is one screen deeper "The help is a map, not an index"
7 Every screen opens with where you are (the path of nouns) and one plain sentence naming what you're looking at. The top screen has no path, only the sentence. A menu is not a place, so it is never part of the path ("to every screen a plain english sentence ...") The breadcrumb paragraphs
8 Every item: its name, its technical form, and what it's for. That line starts with the verb of what using it does, from the verbs the industry already uses, then the project's noun ("i'm missing the verb ...") Column table
9 The top screen stays short, whatever the project's size. A list that grows too long goes behind an earlier screen, and that split is the user's call: ask first ("how to know to decompose a huge list ...") "When a list gets reasonably too long"
10 A thing goes on one screen, and on a second only when the user reaches for it from there too, worded for that screen (tightened after the first draft repeated lines word for word). Your approved codebot map shows ops/OPERATIONS.md in Live and in Docs ("Opens the runbook: install, back up, restore, ..." and "Opens the runbook: running, updating, guests, ..."), and .data/integration/ and supabase/ twice each the same way New. It names what the approved map already does
11 The map comes from one source, the same one the code uses, and a test fails when a thing has no entry cli-best-practices.md "Help is generated from the same source"; step 8, "every thing in the inventory has a row"
12 The output is the map: every screen (its path, its sentence, its items) plus the open questions for the user. A CLI or a UI is built from it New. It names the hand-off

What stays in cli-engineer

  • The grammar of help: it comes last, it refers to the noun just before it, <project> help is the table of contents, and help before a noun exits 1 and names the right form ("help always refers to the n-th noun").
  • The terminal forms of the principles: the breadcrumb drawn as codebot › qa, three columns with OSC 8 links, plain markdown when piped.
  • The facade, aliases and clash checks; shell wiring; building the script; errors and exit codes; both reference files.
  • Steps 1 and 5 to 9. Steps 2 to 4 become "Decompose by screen-decomposition", which yields the map; step 5 draws that map as help screens.

What changes in minimal-ux-flow

  • Step 2, grouping screens "by the data they touch and by the user's own words", and step 6, "Fix the words", load screen-decomposition for those rules instead of stating them separately.
  • Its step 11 checks stay as they are. They are the phone forms of the same principles (the one h1, Back naming where it goes, four or fewer visible places, the real tab bar).

How it's proven

The playground (design.md): arm 1 runs today's text and arm 2 runs the new text on the same cases, 5 runs each. The cut-down cli-engineer must do no worse on codebot and workstation. The UI case must improve.