# Frontend Design Improvements Loop > Run repeatable single-track frontend-design benchmark loops for this repo. Use this when creating sequential experiment versions, tuning frontend-design SKILL.md instructions, running Codex from inside `experiments/version-X/` with the shared `prompt.md`, capturing full-page `/1.. /5` screenshots, and scoring outputs against Opus-with-skill reference sets. - Skill: `waishnav/frontend-design-improvements-loop` (Agent Skill, multi-file: 24 files) - Install (CLI): `npx skillmds@latest add waishnav/frontend-design-improvements-loop` - Raw SKILL.md: https://api.skillmd.com/api/skills/waishnav/frontend-design-improvements-loop/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: Waishnav (https://skillmd.com/u/waishnav) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/waishnav/frontend-design-improvements-loop --- # Frontend Design Improvements Loop Use this skill to run end-to-end benchmark iterations that improve `frontend-design` behavior through instruction tuning, not model weight tuning. ## Scope - Repository: `improved-frontend-skills-for-gpt` - Canonical prompt: repo root `prompt.md` (same prompt for every version) - Active version workspace: `experiments/version-X/` - Preferred raw baseline skill seed: global `$frontend-design` at `/home/waishnav/.agents/skills/frontend-design/SKILL.md` - Primary references: - `research/targetted-designs/` - `research/theo-screenshots-2k-clean/opus45_with_skill/` - `research/theo-screenshots-2k-clean/opus_iterations/` Read `references/opus_targets.md`, `references/mutation_axes.md`, and `references/experiment_topologies.md` before drafting a new version. ## Non-Negotiables 1. Never modify `prompt.md` unless explicitly asked. 2. Always run Codex in the target version folder (`-C experiments/version-X/...`). 3. Keep one mutation hypothesis per version. 4. Keep each version self-contained (`SKILL.md`, `t4-canvas/`, `README.md`, `CRITQUES.md`, `screenshots/`). 5. Do not delete previous versions. 6. New versions must be isolated by default: do not inherit prior `t4-canvas` implementation unless explicitly requested. 7. Run one active experiment at a time (strict sequential loop; no parallel sibling branches). 8. Carry forward only one prioritized critique into the next mutation. 9. Keep `SKILL.md` portable: no experiment/version labels or repo-specific benchmarking terms. ## Workflow ### 1) Choose baseline and one mutation hypothesis - Baseline is the latest completed `experiments/version-*`. - Pick one mutation axis only (see `references/mutation_axes.md`). - Read the previous version `CRITQUES.md` and pick exactly one highest-impact issue to target. - Write the hypothesis in the new version README before implementation. ### 2) Create the next version - For true raw start (no version baseline), use: - `scripts/new_fresh_version.sh ` - Use `scripts/new_version_from_previous.sh `. - Default behavior is isolated: copy prior `SKILL.md`, create fresh empty `t4-canvas/`. - Legacy mode only when explicitly requested: `--copy-app`. - For raw baseline seeding from global frontend skill: use `--skill-source global`. ### 2b) Keep the loop sequential - Do not create sibling versions in the same iteration. - Do not run multiple mutation theses in parallel. - Complete critique and keep/drop decision for the current version before creating the next version. ### 3) Tune `frontend-design` skill instructions - Edit only `experiments/version-X/.agents/skills/frontend-design/SKILL.md`. - Keep constraints auditable and measurable. - Avoid vague language; use explicit guards and pass/fail criteria. - Apply one mutation change set only for this version. - Translate critique findings into generic rules; do not write benchmark- or version-specific wording inside `SKILL.md`. ### 4) Run Codex headlessly with canonical prompt - Use `scripts/run_headless_iteration.sh /prompt.md [run-label]`. - Optional reliability args: `[max-attempts] [retry-delay-sec]`. - This forces `codex exec` to run with cwd inside version folder and logs artifacts. - Prefer short, restartable runs over one giant run. ### 5) Capture screenshots for `/1.. /5` - Start the version app in `t4-canvas/`. - Use Playwright CLI to capture full-page screenshots for routes `/1` to `/5` in desktop/tablet/mobile profiles. - Preferred command: - `scripts/capture_screenshots.sh [base-url]` - Save under `experiments/version-X/screenshots//{desktop,tablet,mobile}.png`. ### 6) Critique and score - Score against rubric in `references/scoring_rubric.md`. - Compare against Opus reference sets (not generic web quality). - Write critique notes to `experiments/version-X/CRITQUES.md` after every run. - Record critique in a structured way: - issue - evidence - likely root-cause rule - proposed generic fix - Record: - wins - regressions - next mutation ### 7) Decide next action - If net gain: keep mutation and continue. - If mixed: keep only if rubric delta is positive on target dimensions. - If regression: revert mutation in next version and try a different axis. - In all cases, pick one next mutation only. ## Reliability Pattern For Long Runs - Design for 3-7 minute chunks per run. - Do not require tmux by default; run direct `codex exec` with artifact checkpoints. - Persist outputs every run: - `artifacts//events.jsonl` - `artifacts//stderr.log` - `artifacts//final.md` - If interrupted, continue with `codex exec resume --last` and continue from latest checkpoint. ## Deliverable Contract Per Version Each version must include: - `experiments/version-X/.agents/skills/frontend-design/SKILL.md` (mutation applied) - `experiments/version-X/README.md` with: - hypothesis - exact mutation - rubric score delta - next step - `experiments/version-X/CRITQUES.md` with expected-vs-output critique notes - `experiments/version-X/screenshots/1/{desktop,tablet,mobile}.png` ... `screenshots/5/{desktop,tablet,mobile}.png` ## Scripts - `scripts/new_fresh_version.sh` - `scripts/new_version_from_previous.sh` - `scripts/run_headless_iteration.sh` - `scripts/capture_screenshots.sh`