6krrt/plans/admin-work-framework.md

Admin UI Work Framework

Status: reference -- how admin work is scoped and reviewed

How to produce the class of result the c22bbae Controls relayout did — work so specific it stands alone as a learning input, written as rules the next page can apply, backed by evidence a fresh model can trust.

This framework is about the craft of touching the admin portal, not the visual styles (those live in admin-design-standards.md). Read the Standards doc first; this doc is the method.

Why this exists

Before c22bbae, the admin UI got "fixed" in ways that didn't transfer: a review category said "card is a single line of buttons," and a future page could easily re-produce the same dead column. The Controls relayout broke that pattern by turning each observed defect into a rule the next page can mechanically apply ("don't restate the control's own value," "single-line button strip goes full width"). The commit message is the artifact worth feeding a model: it spells out the three problems, why each fix is what it is, and the two consistency fixes — with enough context to stand alone.

The method (5 moves)

Move 1 — Diagnose at the surface, in the running browser

Look at the page as a user does: full viewport and at 800px, before and after a REFRESH_MS poll. Name the defect in one concrete sentence before you touch anything.

Good defect statements (from the real commit):

• "Operational Triggers is a single line of buttons but sat in a col-xl-6 next to a much taller card, so half that row is permanently empty."
• "Both settings panels used a 5/3/4 Bootstrap grid, which put the control mid-row at three different widths and spent a whole trailing column restating the value the control already displays."
• "Rows alternated switches and text inputs, which differ ~10px in natural height and read as ragged."

These are specific and falsifiable. "Fix the controls page layout" is not a diagnosis — it's a wish.

Move 2 — Extract the grammar, not the look

Don't record "Controls page uses grid-template-columns:minmax(0,1fr) auto 176px." Record the transferable principle behind it, plus the code as evidence:

A settings list is one CSS-grid row — key | meta | control — not Bootstrap .row/.col-*. A fixed control track is the point: every switch, input and select lands on the same right edge, so the eye scans one column.

Then back it with the exact CSS so a future page can copy it. Grammar lives at the level of "what column exists and why," not "which pixel value."

Rule templates that transfer:

• Do not add a column that restates the control's own value. The meta track is for facts the control cannot show.
• A card whose content is a single line of buttons goes full width with the buttons in .card-actions, not into a col-xl-6 beside a tall card.
• Rows with a switch next to a text input need a fixed min-height or they read as ragged.
• Boolean persisted-config controls use switches, matching runtime knobs — not bare checkboxes.

Move 3 — Keep old constraints load-bearing

Every change must be verified against the survival checklist (S1–S5) in admin-facelift.md and the learnings.md notepad:

• escapeHtml() on every interpolated string
• chart instance reuse (never .data.labels mutation on the verdict bar)
• renderWarnings inline placeholder rebuild
• saveAllConfig stays sequential (for...of await, no Promise.all)
• SSE status pill reflects real EventSource state

If your change touches any of these, call it out explicitly in the commit.

Move 4 — Prove it, not just observe it

A single fresh-load screenshot has missed canvas-reuse and selector bugs twice in this project. Minimum evidence bar for an admin page change:

1. python -m pytest — full suite (733 tests) green.
2. Playwright load at 1400px and 800px, plus one 30s+ idle past REFRESH_MS, with zero console errors (beyond the benign /favicon.ico 404).
3. The exact interaction under change exercised by hand (toggle, save, range).

Save the screenshots under plans/ (e.g. admin-controls-relayout.jpg).

Move 5 — Write the commit as the learning input

The commit message is documentation for the next model. Structure it as:

• The problem(s), each in one concrete sentence (Move 1).
• Why each fix is what it is — the reasoning, not just the change.
• Consistency fixes called out separately from the main change.
• Test changes explained (why the old assertion no longer held).

Follow with a git show <sha> that a fresh session can read and immediately apply.

Also update the Standards doc in the same commit

When the change teaches a new transferable rule, add it to plans/admin-design-standards.md in the same commit so doc and code can never drift. Write the new section in rule form ("Do not add a column that restates the control's own value"), not as a description of the one page. That is what makes it applicable to the next page.

Repository of what this produces

• plans/admin-design-standards.md — the accumulated grammar (settings rows, card-level layout, hard-won rules 1–10, data patterns).
• .omo/notepads/admin-facelift/learnings.md — the chronological record of every diagnosis/fix/QA, including the false-starts that were corrected.
• plans/*.md — the post-hoc audits that catch what the QA pass missed.
• Commit messages themselves — the highest-signal, standalone learning input.

When to use this framework

• Any visible change to admin/frontend/*.html or the /admin API surface.
• Any downstream admin page you might build (e.g. an Audit/Logs page, wiring in admin_schema.sql RBAC) — apply the grammar first, then the visuals.