wiki-vault/Sources/Dev/2026-05-28-ui-poc-process-learnings.md

created	path	project	tags	type
2026-05-28	Sources/Dev	execution-journal	claude-code dispatch automation python	session-notes

Outcome

Distilled a set of repeatable workflow patterns from a UI proof-of-concept session (trellis-dashboard, 2026-05-28). The originating session-note is Sources/Homelab/2026-05-28-trellis-dashboard-ui-iteration.md; this note pulls the patterns out so they're discoverable independent of the project that surfaced them. Intended as a working reference for future Dispatch sessions that involve web UI work, multi-pass iteration, or any deploy that touches a main-protected repo.

Topics Covered

• Definition-of-done bar for UI changes (headless vs headed verification)
• Iteration cadence for proof-of-concept web work (recommend ↔ ship loop)
• Branch / PR / deploy choreography for repos with branch protection
• Streamlit-specific gotchas that recur across projects
• a-review's audit envelope when scope touches deploy config
• Cowork home-dir mirror availability (Lovebug-specific operational note)

Key Learnings

1. Browser walkthrough is the definition of done for UI work, not an extra round. Headless curl and Streamlit health endpoints return 200 even when widgets are broken, empty, or misrendering. The default deliverable for UI changes should include a headed browser session (Claude-in-Chrome / Playwright) that clicks through each interaction the change affects. Bake this into the initial task prompt rather than asking for it as a follow-up; otherwise the first round can "ship" something that doesn't actually work end-to-end.

2. For proof-of-concepts, build in a deliberate "recommend → ship → recommend → ship" loop. After the first deploy, while the codebase is still in working memory, ask for UX/UI improvements before closing the session. Compound iteration runs cheap (no re-discovery cost) and produces higher-quality outcomes than a single-pass build. Make the recommendation pass a named step in the workflow, not an afterthought. Concrete proof-point: on the trellis-dashboard session this pattern produced eight high-value follow-on additions in a single tight loop with no extra recon.

3. Plan PR-flow upfront for repos with main-branch protection. Discovering a denied push mid-deploy adds friction. The working pattern: feature branch → push → rebuild container from the worktree (compose project name keeps managing the same container) → PR-merge as a separate manual step. Specify this in the initial prompt so the code session never tries to git push main first.

4. Streamlit cross-view navigation needs st.segmented_control, not st.tabs(). st.tabs() cannot be programmatically activated, which breaks any feature that switches views from a click in another view. Use st.segmented_control (Streamlit 1.40+) backed by st.session_state for any UI with cross-section navigation. Worth knowing before starting any Streamlit work that involves jumping between sections — saves a mid-build rewrite.

5. Worktree-based deploys break when .env only lives in the main checkout. Any deploy that requires a gitignored .env will fail from a worktree until the file is copied in. Either commit a .env.example and document the copy step, or design deploys around a shared secrets path (Vault, Ansible-managed, etc.). Worth checking before assuming a worktree build will "just work."

6. a-review's audit envelope should extend to deploy/infra config when the diff touches it. A clean diff over application code can ship right past an exposure in the Traefik / Authentik / compose layer. When the scope of a change includes anything in deploy/, point a-review at the full deploy config, not just the lines that changed. Caught a real Authentik bypass on the trellis-dashboard session that would otherwise have stayed hidden.

7. Don't reflex-assume the home-dir bind-mount mirror exists for every repo. Cowork code tasks prefer /home/herbyadmin/dev-projects/... for trust reasons, but the mirror isn't populated for every repo. Quick check before spawning; fall back to /opt/projects/... if not present. (Lovebug-specific operational note.)

Follow-ons

• When opening any new UI/web task, include "headed browser walkthrough verifying each interaction" in the definition of done in the initial prompt
• When opening any new task touching deploy/ or Traefik config, explicitly include the deploy layer in a-review's scope
• When opening any task on a main-protected repo, default the prompt to PR-flow (feature branch + worktree-build deploy + manual merge)
• Consider whether this note should eventually be promoted to a Wiki topic-landing or synthesis page — its content is meant to outlive a single session and may be referenced from future plans