UI Station Delivery

UI Station Delivery

When to use this

Any time you ship something a user operates with their own hands: a screen, a conversational flow, a form, an interactive station that runs from "press this" to "here is your result." This skill covers what you must do yourself before saying "it's done" or "please review it."

The core insight: whether a station works is not decided by ticking every box on its feature list; it is decided by whether a user can walk from the entry point all the way to the finish line. A fully green checklist with no next step halfway through is a broken station.

Core rules

Rule 1: The checklist proves it was built; the journey proves it works — ship neither alone

• Checklist: was each required part built? (an opening line, a button, three categories…) — this verifies existence.
• Journey: can a real user go from the entry action (upload / click / type) all the way to the finish action (produce / save / submit), with every step in between actually working? — this verifies usability.
• These are two different verifications and you need both. A green checklist ≠ usable. The most common failure: every part was built and every part is on screen, but the thing is visible but mute, or responsive but powerless — the station doesn't stand.

Rule 2: The self-check must walk the complete user journey, one path, all the way to the end

Before delivery, play the user yourself and walk from the entry point to the finish line without skipping a single step:

entry action → every intermediate state → … → finish action (a result actually in hand)

At each step, ask one question: "Right now, does the user know what comes next?"

• They pressed "all" → the system acknowledged it, but never told them what to press next? → a dead end; the station doesn't stand.
• They can see the list → but there is nowhere to say "I want this one, not that one"? → they cannot talk to it; the station doesn't stand.
• They reach the end → they press submit → no feedback at all about whether it worked? → the "now what?" dead end; the station doesn't stand.

If you cannot reach the finish line, you are not done. No matter how green the checklist is.

Rule 3: The precondition for "please review this" is that you walked the journey first, with evidence at every step

"Hand it to a human for final acceptance" has preconditions; finishing the checklist does not earn it:

• Precondition: you walked the complete journey yourself, and left evidence at every step (screenshots / recordings / step-by-step output) proving there is no dead end, no ghost element, no "now what?"
• If it does not walk, you may not label it "ready for review." Pushing something that cannot reach its finish line in front of a person means handing them holes you would have found by walking it once yourself.

Rule 4: A human's review is the final call, not a net for holes you would have caught by walking it yourself

Be clear about what a human review is and is not for:

• In scope (the final call): domain correctness (are the numbers and the logic right), operational reality (does this match how the work is actually done), and feel (is it smooth, is it comfortable) — only a human can judge these, no matter how many times you walk it.
• Out of scope (catching holes you would have hit yourself): dead ends, ghost elements, buttons that do nothing, journeys that never finish — you would have walked straight into these. Letting that class of hole reach a person is a defect in your delivery process, and it should be treated, recorded, and reviewed exactly like a bug that escaped to production (an escaped defect).

Rule 5: Delivery format = "the journey walks (N pieces of evidence) + one line of self-check results"

When you deliver a UI station, attach:

1. A journey statement: one path from entry to finish walks, with step-by-step evidence (how many screenshots, and which steps they correspond to).
2. One line of self-check results: X checklist items green + Y journey steps passing + the key invariants (no zombie processes / no ghost elements, for instance).
3. Have the reviewer audit journey completeness first (does this path really connect end to end, is a dead end hiding in it), and only then pass it to the decision-maker for the final call.

Rule 6: Screenshots guard behavior, rule tests guard the rules — you need both

An interactive station usually has a layer of pure rule logic (which words map to which intent: confirmation words, cancellation words, command keywords, fuzzy matches…). That layer is guarded by deterministic unit tests (node:test / pytest) enumerating the rule table row by row (every word, every match count, the fallback);

• The screenshot journey proves "typing 'confirm' really did press the confirm button" — the wiring connects.
• The rule unit tests prove "'ok', 'yes', and 'confirm' all count as confirmation, and 'gross margin' is never mistaken for one" — the rules themselves are right.
• These are different guarantees: screenshots can never enumerate every word, and unit tests cannot see whether the DOM is wired. Screenshots guards the rules (you broke one and the screenshot path happened not to touch it); unit tests wiring breaks and nobody knows. Delivery attaches both kinds of evidence.
• From the field: a conversational station with zero unit tests, held up by screenshots alone is debt — the rules have no regression net, and the next wording change breaks them silently.

Rule 7: E2E tests touching real side-effect zones need structural isolation, not carefulness

The moment an E2E test writes persistent state (recipes / files / a database), it must write into an isolated temporary area rather than the real data area — and the isolation must be structural (an environment variable, an injected path pointing at tmp), not "be careful during testing and remember to restore it afterwards."

• Real-environment E2E (a real browser hitting a live server) cannot monkeypatch that separate process, so the live server must be started with a "test data directory" environment override (APP_DATA_DIR=<tmp>, for instance) so that from import time onward it cannot reach real data.
• "Restore it from git afterwards" is not isolation: that is defusing the mine after stepping on it, not avoiding the mine. Forget to restore once and you have polluted or overwritten real user data. The value of isolation is that touching real data is structurally impossible — it moves safety out of human discipline and into a mechanism.

Case files from this project (supporting evidence, not required for the general rules)

• "Visible but mute": the station doesn't stand: in one financial-reporting automation project, the first version of the multi-item reverse-engineering station rendered the list of items, surfaced all three categories faithfully, and had every checklist item green — but there was no conversation, so the user could look and not change anything → the decision-maker's own review came back red: "the station boundary is wrong; the minimum usable version must include the minimum conversation." A green checklist ≠ usable.
• "Responsive but powerless": the station doesn't stand: the second version added conversation (choices could be changed) but had no output exit — the user typed "all" → the system replied "15 items total" → and then there was no next thing. The decision-maker's review came back red: "the action exit dead-ends; the third property (you can act) is missing, so the station doesn't stand."
• A ghost element means you did not finish the walk: the single-item prompt was "showing through from behind" on the multi-item path — the old element had never been removed from the DOM, only covered. The decision-maker: "covering it with z-index is not a fix; show me the code diff that removes it." A ghost you see while walking should be fixed on the spot, not carried in front of a person.
• A delivery-process defect = an escaped defect: the decision-maker ruled that "a hole you would have found by walking it once, reaching human review" is a delivery-process defect, recorded on par with a bug that escaped to production — which is what forced the hard precondition "walk the complete journey and screenshot every step before handing it over."
• A conversational station with zero unit tests is debt (Rule 6): the multi-item reverse-engineering conversation station had only a screenshot journey and zero pytest/node tests — the rules (all / add-X-single-match / add-X-multi-match / drop-X / bare name / fallback / confirmation words / cancellation words) had no regression net. The morning review caught it and sent it back: the pure rules were extracted into a conversational rules module (the pure-rule layer) and pinned row by row with node:test, screenshots kept guarding browser behavior, and both now coexist.
• An E2E test overwriting a real recipe = an isolation defect (Rule 7): the save-flow E2E drove a real browser against a live server → went through the real data-write function → wrote into the real data directory and silently overwrote an existing recipe; at the time it was cleaned up with "restore it afterwards via git checkout." The root cause was that the live server ran with the production config (the conftest tmp isolation only applies to pytest). The fix: the config's recipe directory honors an APP_DATA_DIR environment override and the E2E starts the server with a tmp path — structurally out of reach of real recipes, not dependent on carefulness.
• Sister skills: when the walk hits something functionally broken, use systematic-debugging to find the root cause; the journey's "one line of self-check results + evidence" format echoes handoff-protocol's "one-line conclusion + auditable evidence"; "the checklist proves it was built, the journey proves it works" echoes verification-discipline's "should-be-there-but-isn't" (missing checklist items) and "never trust a self-report" (it must actually walk, not be claimed to walk); Rule 7's structural isolation echoes engineering-economy Rule 8, "test isolation prevents phantom stalls" — moving safety out of discipline and into a mechanism.