47 lines
4.7 KiB
Markdown
47 lines
4.7 KiB
Markdown
---
|
|
created: '2026-05-28'
|
|
path: Sources/Dev
|
|
project: execution-journal
|
|
tags:
|
|
- claude-code
|
|
- dispatch
|
|
- automation
|
|
- python
|
|
type: 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 |