Skip to content

Commit 8a752a2

Browse files
DavisSylvesterclaude
DavisSylvester
and
claude
committed
docs(ui-plan): universal per-element workflow + KB preflight
Codifies the build process that converged full-stack-dashboard at 34/37 into a universal pattern that every future page must follow. New: docs/ui-plan/04-per-element-workflow.md §1 Hard rules (8 non-negotiables) §2 Order of build (atoms → Panels → features → layout → whole-page) §3 Per-element loop (describe → build → verify → diagnose → log → fix) §4 Iteration log format (JSONL object schema) §5 When an element is "done" (Stage C + KB + build gate) §6 Escalation & budget exhaustion rules §7 Enforcement layers §8 First-run preflight — KB loaded BEFORE any code is written so iteration 1 can pass when motifs are already in the KB §9 Applying to a new page Updated codegen.md prompt: - Preflight mandatory: read KB + 04-per-element-workflow.md first. - KB Prevention hints inlined verbatim into the prompt so they are in context even without a prompt loader. - First-iteration quality bar: with KB loaded, target 1–3 iterations, not 20+. Double-digit iteration counts mean the KB has missing knowledge → open a new KB entry, don't just grind. Updated 00-plan.md §9 to point at 04-per-element-workflow.md as the universal workflow. Persistent memory added: feedback_universal_workflow.md — carries the rule across sessions. Indexed in MEMORY.md. Why this matters: AlarmStats took 20 iterations on the first run because KB §1 and §2 did not exist yet. Now that they do, the same failure modes cost 0 iterations. The preflight step ensures this knowledge is actually loaded into context when a new element starts, instead of being re-discovered. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 77dfe8c commit 8a752a2

3 files changed

Lines changed: 293 additions & 1 deletion

File tree

‎docs/prompts/codegen.md‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,36 @@ You are an expert Angular developer who generates precise, production-ready Angu
22

33
## Hard constraint — Panel Model Fidelity Corrections KB
44

5-
If the target UI uses the Panel Model Pattern (any reference under `docs/ui-plan/examples/`), you MUST load `docs/knowledge-bases/panel-model-fidelity-corrections.md` before writing code and apply every correction as a non-negotiable rule. Every entry has a **Prevention hint** in one sentence — treat each hint as an assertion you must satisfy before the generation is considered complete. Do not re-introduce a failure mode that the KB has already recorded and corrected. When you emit a component that matches a motif covered in the KB, cite the KB entry number in a comment at the top of the component's `.ts` file.
5+
If the target UI uses the Panel Model Pattern (any reference under `docs/ui-plan/examples/`), the first action on every run is to load `docs/knowledge-bases/panel-model-fidelity-corrections.md` and `docs/ui-plan/04-per-element-workflow.md`. Both documents encode corrections from past runs — applying them in iteration 1 is how the loop converges faster than re-learning every failure mode.
6+
7+
### Preflight checklist (mandatory before any code is written)
8+
9+
1. Read `docs/knowledge-bases/panel-model-fidelity-corrections.md` in full.
10+
2. For the component you are about to build, enumerate which KB entries apply based on the motifs present (ratio stats, segmented indicators, label strips, etc.). List them explicitly in a comment at the top of your plan.
11+
3. Read `docs/ui-plan/04-per-element-workflow.md` §1 (hard rules) and §3 (per-element loop).
12+
4. Confirm the run will follow §3: describe → build → verify → diagnose → log → fix → repeat.
13+
14+
### KB Prevention hints — inlined here so they are in context even without a loader
15+
16+
These are copied from the KB. The KB remains authoritative; if you suspect drift, re-read the source file. Every bullet is a hard check the first emitted version of the component must satisfy.
17+
18+
- **§1 · AccentRule vs. ActivityIndicator.** Before calling any repeating horizontal motif an `AccentRule`, count the segments. If N > 1 or the segments differ visually (filled vs outlined, colored vs muted), it is an `ActivityIndicator` (or `SegmentedBar` / `TickGroup`), not an `AccentRule`.
19+
20+
- **§2 · Stat split-label alignment + segment fill contrast.** Ratio `Stat` (with a denominator) must lay out its numeral row and split-label row in a **single shared CSS grid** — never two sibling grids. `ActivityIndicator` outlined segments must be truly hollow (transparent interior, visible border, not opacity-dimmed fill) and segment height must be ≥ 3 px for border-fill distinction to be visible.
21+
22+
- **§3 · No "verified" claim without Stage C pass.** Never write "verified," "matches the reference," "renders correctly," or "passes visual validation" in commit messages, summaries, or reports unless a concrete Stage C pass percentage below 10 % is attached. If Stage C was not run for any reason, say so explicitly.
23+
24+
### When you emit a component
25+
26+
- At the top of the `.ts` file, cite the KB entry numbers you applied:
27+
```ts
28+
// KB §1, §2 — applied: split-label Stat + 4-segment ActivityIndicator
29+
```
30+
- Do not re-introduce a failure mode the KB has already corrected. If you are tempted to, read the entry again.
31+
32+
### First-iteration quality bar
33+
34+
With the KB + workflow loaded, the first emitted version of a component should pass Stage C (≤ 10 % pixel mismatch) when its motifs are covered by existing KB entries. Converging in 1–3 iterations is the target. Double-digit iteration counts on a single atom indicate the KB has missing knowledge — record that as a new KB entry, don't just grind iterations.
635

736
## Hard rule — Playwright validation after every component or element
837

‎docs/ui-plan/00-plan.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -393,6 +393,8 @@ Current `src/prompts/*.mts` files hold prompts as template literals. These are o
393393

394394
## 9. Visual Validation
395395

396+
**The universal workflow is [`04-per-element-workflow.md`](04-per-element-workflow.md).** Every page, every feature Panel, every atom goes through it — no exceptions. The workflow includes first-run KB preflight so an LLM with the KB loaded can converge in 1–3 iterations on motifs already covered.
397+
396398
**Hard rule (process):** after every component or element is created or modified, the full Stage A + Stage B + Stage C validation must run via `bun run scripts/verify.mts <example-id>`. Eyeballing a captured PNG is **not** validation. Stage C must produce a pass row in the report before the work is called done. See KB §3 — `docs/knowledge-bases/panel-model-fidelity-corrections.md`.
397399

398400
**Hard rule (output):** no component is marked complete until its rendered output matches the per-section "before picture" cropped from the reference design, within a strict tolerance on color, typography, spacing, borders, corner ticks, and iconography.

‎docs/ui-plan/04-per-element-workflow.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# Per-Element Workflow — How Every Page Gets Built
2+
3+
> **This is the universal build process.** Every page, every feature Panel, every atom goes through this workflow — no exceptions. Deviations constitute a KB-worthy incident.
4+
>
5+
> The workflow was proven on the `full-stack-dashboard` example (converged 34/37 regions at 10% threshold across 30 iterations). It is now codified for all future references.
6+
7+
---
8+
9+
## Table of Contents
10+
11+
1. [The Hard Rules](#1-the-hard-rules)
12+
2. [Order of Build](#2-order-of-build)
13+
3. [The Per-Element Loop](#3-the-per-element-loop)
14+
4. [Iteration Log Format](#4-iteration-log-format)
15+
5. [When an Element is "Done"](#5-when-an-element-is-done)
16+
6. [Escalation & Budget Exhaustion](#6-escalation--budget-exhaustion)
17+
7. [Enforcement](#7-enforcement)
18+
19+
---
20+
21+
## 1. The Hard Rules
22+
23+
1. **Describe before name.** Before declaring an atom for a region, write the literal pixel description (shape count, fill vs outline, color roles, alignment, repetition count). Read at native pixel size. Per [`02-decomposition-process.md`](02-decomposition-process.md) §2 preamble. Violations are how KB §1 shipped.
24+
25+
2. **Bottom-up build.** Atoms before Panels. Panels before features. Features before layout. Layout before whole-page verify. A feature Panel is never authored before its atoms exist and individually pass Stage C.
26+
27+
3. **Verify after every create or modify.** `bun run scripts/verify.mts <example-id>` is non-optional. If the element is a single atom, hit its preview on `/atoms`. If it is a feature Panel, hit the dashboard route. Per [`03-visual-validation.md`](03-visual-validation.md) + KB §3.
28+
29+
4. **10 % pixel-mismatch threshold.** Hard pass/fail line. Overrides only via per-region `tolerances.json` with a written reason.
30+
31+
5. **30-iteration budget per element.** If the element does not pass Stage C within 30 iterations, stop. Either escalate (§6) or record the failure state and move on with documented reason.
32+
33+
6. **Every iteration logged as an object.** Format in §4. Append to `visual-report/<example-id>/iterations.jsonl`. Empty iterations are not allowed — every fix gets a record.
34+
35+
7. **No "verified" claim without a pass row.** Codified in KB §3, enforced by `docs/prompts/codegen.md` and `docs/prompts/visual-fidelity.md`.
36+
37+
8. **KB first.** Before writing any code for an element, load `docs/knowledge-bases/panel-model-fidelity-corrections.md` and apply every Prevention hint relevant to the motif being built.
38+
39+
---
40+
41+
## 2. Order of Build
42+
43+
For any new reference / example, build in this order:
44+
45+
```
46+
1. reference.png committed
47+
2. decomposition.md authored (applies 02-decomposition-process.md)
48+
3. regions.json authored (applies 03-visual-validation.md §3.2)
49+
4. Stage A — bun run scripts/capture-before.mts <example-id>
50+
→ visual-baselines/<example-id>/*.png committed
51+
5. Overlay diagnostic — bun run scripts/overview-strip.mts
52+
→ visually confirm bboxes align with the reference
53+
6. Tokens + theme (pattern-level, reused across examples)
54+
7. Panel primitives (pattern-level, reused)
55+
8. Atoms — one at a time, each verified via /atoms preview route
56+
9. Feature Panels — one at a time, each verified via the dashboard route
57+
10. Layout (AppHeader, DashboardPage, routes)
58+
11. Whole-page verify — every region in regions.json, Stage C on all
59+
12. Per-failing-region fix loop — §3 per-element loop, budget 30 each
60+
```
61+
62+
**Invariant:** at every numbered step, the preceding step's artifacts exist and pass. Skipping ahead is a KB-worthy incident.
63+
64+
---
65+
66+
## 3. The Per-Element Loop
67+
68+
For each element (atom OR Panel OR feature OR whole page) the loop is:
69+
70+
```
71+
┌──────────────────────────────────────────────────────────────────┐
72+
│ 1. LOAD — KB prevention hints for this element's motif │
73+
│ │
74+
│ 2. DESCRIBE — literal pixel description of the reference region │
75+
│ (if atom: the per-atom baseline; if Panel: the panel bbox) │
76+
│ │
77+
│ 3. BUILD — write minimum viable .ts, .html, .scss │
78+
│ │
79+
│ 4. VERIFY — run scripts/verify.mts <example-id> │
80+
│ read the pass/fail row for THIS element's region(s) │
81+
│ │
82+
│ 5. DIAGNOSE — if fail: │
83+
│ a. examine visual-report/<id>/<region>.diff.png │
84+
│ b. compare baseline + actual crops at native pixel size │
85+
│ c. categorize drift: size, position, color, font, content │
86+
│ │
87+
│ 6. LOG — append iteration object to iterations.jsonl (§4) │
88+
│ │
89+
│ 7. FIX — one focused change per iteration │
90+
│ (never bundle multiple hypotheses into a single iteration — │
91+
│ you will not know which one moved the number) │
92+
│ │
93+
│ 8. REPEAT — from step 4 until pass OR budget exhausted │
94+
│ │
95+
│ 9. COMMIT — only after pass (or with escalation reason) │
96+
└──────────────────────────────────────────────────────────────────┘
97+
```
98+
99+
### 3.1 One hypothesis per iteration
100+
101+
If you change `font-size` and `padding` in the same iteration and the number drops, you don't know which helped. The log entry will say "changed 2 things" and future iterations can't build on the knowledge. **Rule: one named change per iteration.** If the change requires coupled edits (e.g. Stat grid + label grid share columns), count the couple as one hypothesis.
102+
103+
### 3.2 Verify is not a suggestion
104+
105+
The workflow pauses after step 4. Do not proceed past step 4 without observing the pass/fail row for the current element. No "looks right, moving on."
106+
107+
### 3.3 Diff image first
108+
109+
When a region fails, open `visual-report/<id>/<region>.diff.png` before thinking about the fix. The diff shows *where* pixels differ (usually as red ghosting of both baseline and actual overlaid). That picture names the class of drift — size vs position vs color vs font — which directs the fix.
110+
111+
---
112+
113+
## 4. Iteration Log Format
114+
115+
Every iteration appends one object to `visual-report/<example-id>/iterations.jsonl`. JSONL so it's append-only and diff-friendly.
116+
117+
Required fields:
118+
119+
```json
120+
{
121+
"iteration": 17,
122+
"dateTried": "2026-04-18T18:05:00Z",
123+
"element": "alarm-stats.online",
124+
"issue": "diff ghosting shows baseline numerals larger than 33px render",
125+
"proposedFix": "font-size 33→36px",
126+
"plan": ["edit stat.component.scss", "verify"],
127+
"result": {
128+
"pass": false,
129+
"regionsPassing": 2,
130+
"regionsTotal": 4,
131+
"perRegion": {
132+
"alarm-stats": 8.93,
133+
"alarm-stats.online": 13.39,
134+
"alarm-stats.alarms": 9.18,
135+
"alarm-stats.sla": 11.31
136+
},
137+
"delta": "online regressed (11.67→13.39) — 36 is too big; return to 33"
138+
}
139+
}
140+
```
141+
142+
Rules:
143+
- `iteration` — monotonic increasing, starting at 0 (initial state).
144+
- `dateTried` — ISO-8601, converted to absolute date.
145+
- `element` — the primary region id being worked on (for grouping).
146+
- `issue` — literal observation from the diff image or measurement.
147+
- `proposedFix` — single change, described concretely.
148+
- `plan` — ordered list of the exact operations.
149+
- `result.pass` — boolean, from Stage C.
150+
- `result.perRegion` — every failing region's mismatch %.
151+
- `result.delta` — one-sentence summary of what moved and why.
152+
153+
Iteration 0 is the baseline measurement (no fix applied yet). Subsequent iterations reference the delta from the previous result.
154+
155+
---
156+
157+
## 5. When an Element is "Done"
158+
159+
Three-part gate:
160+
161+
1. **Stage C pass** — the element's region(s) in `visual-report/<id>/summary.json` have `pass: true`.
162+
2. **KB check** — if the element matches a motif covered by a KB entry, the comment at the top of the `.ts` file cites the entry number.
163+
3. **ESLint + typecheck** — `bun run build` is clean.
164+
165+
Only after all three can the element be marked complete or the change committed with "verified" / "passes" language.
166+
167+
---
168+
169+
## 6. Escalation & Budget Exhaustion
170+
171+
After 30 iterations on a single element without pass, stop. Do not sneak a 31st. Instead:
172+
173+
### 6.1 Categorize the residual drift
174+
175+
- **Structural** — wrong atom, missing motif → open a KB entry, fix the pattern, retry.
176+
- **Sub-pixel text drift** — dominated by character x-offset in crops < 30 px tall → note in the iterations log that threshold is unachievable at this crop size with current fonts; document in KB.
177+
- **Baseline defect** — the `regions.json` bbox doesn't match the reference's actual content → fix the bbox and restart the budget (this is baseline authoring, not implementation).
178+
179+
### 6.2 Document the stop
180+
181+
Add a final iteration object with `"result.pass": false` and a `"budgetExhausted": true` field plus a `"residualCategory"` from the list above. The commit message must state "X of N regions pass; remaining failures are <category> with documented reason."
182+
183+
### 6.3 Do not lower the threshold to force a pass
184+
185+
10 % is the authoritative line. If budget exhausts and drift is legitimate, document it. If drift is structural, fix the pattern. **Do not raise the threshold to 15 % to ship.**
186+
187+
---
188+
189+
## 7. Enforcement
190+
191+
Multiple layers so skipping is hard:
192+
193+
| Layer | What it enforces |
194+
|---|---|
195+
| `docs/prompts/codegen.md` | Forbids "verified" language without a Stage C pass row; cites KB entry numbers in component source |
196+
| `docs/prompts/visual-fidelity.md` | Review treats every KB Prevention hint as a hard check |
197+
| `scripts/verify.mts` | Non-zero exit on any region failure → CI gate |
198+
| `docs/knowledge-bases/panel-model-fidelity-corrections.md` | Growing catalogue of past failures; every agent loads it before codegen |
199+
| Persistent memory (user memory system) | `feedback_playwright_after_every_element`, `user_model_preference` carry the rules across sessions |
200+
| This doc (`04-per-element-workflow.md`) | Single source of truth for the build order and loop |
201+
| Git pre-commit (planned) | Rejects commits that mention "verify" / "pass" in messages when the most recent `summary.json` shows failures |
202+
203+
If any of these layers is bypassed without a written reason, the workflow is broken — which is itself a KB entry.
204+
205+
---
206+
207+
## 8. First-Run Preflight — KB in context before any code
208+
209+
**Goal:** the first iteration on any new element should pass Stage C when its motifs are already covered by the KB. We do not re-discover known failures.
210+
211+
Before writing any code for an element, execute this preflight:
212+
213+
1. **Read the KB in full.** `docs/knowledge-bases/panel-model-fidelity-corrections.md` — every entry, not just the titles.
214+
2. **Enumerate applicable entries.** For the element you are about to build, list the KB entries whose motifs apply (ratio stats, segmented indicators, label strips, cyan pill tags, progress bars, etc.).
215+
3. **Inline the applicable Prevention hints.** Copy each hint verbatim into your working notes so they are in the same buffer as the code you are about to write.
216+
4. **Read §1 hard rules and §3 loop of this doc.** Confirm the build will follow them.
217+
5. **Cite KB entries in the `.ts` source.** A header comment like:
218+
```ts
219+
// KB §1, §2 — applied: <short rationale>
220+
```
221+
222+
The codegen prompt `docs/prompts/codegen.md` already encodes steps 1–5 as mandatory preflight; verify the prompt has not drifted.
223+
224+
### Why this matters
225+
226+
On the `full-stack-dashboard` first run, the AlarmStats sub-Panel took 20 iterations (0/4 → 4/4) because the `AccentRule` vs `ActivityIndicator` distinction and the Stat split-label grid constraint had not yet been codified. Once those became KB §1 and §2, the **same mistakes cost 0 iterations** on the next run — subsequent atoms converge in 1–3 iterations when their motif is covered.
227+
228+
If a new element takes double-digit iterations to converge, that is itself evidence the KB is missing knowledge. Open a new entry before closing the work.
229+
230+
---
231+
232+
## 9. Applying to a New Page
233+
234+
When a new page is added (e.g., a second reference under `examples/<new-id>/`), run:
235+
236+
```
237+
# 1. Author artifacts
238+
docs/ui-plan/examples/<new-id>/
239+
reference.png (committed)
240+
decomposition.md (applies 02-decomposition-process.md)
241+
regions.json (pixel-scan-verified bboxes)
242+
atoms-delta.md (proposals for new atoms)
243+
tuning-notes.md (observations)
244+
245+
# 2. Baselines
246+
bun run scripts/capture-before.mts <new-id>
247+
248+
# 3. Build each element following §3 loop
249+
# - atoms first, one at a time
250+
# - feature Panels next, one at a time
251+
# - layout last
252+
# each with its own iterations.jsonl entries
253+
254+
# 4. Whole-page verify
255+
bun run scripts/verify.mts <new-id>
256+
257+
# 5. Promote atoms / pattern updates from tuning-notes.md
258+
# (see 02-decomposition-process.md §8 feedback loop)
259+
```
260+
261+
No shortcuts. No bundled PRs that build multiple atoms without verifying each. No "tested the whole page at the end" as a substitute for per-element verification.

0 commit comments

Comments
 (0)