screen-tweaking

Files (1)

• SKILL.md

SKILL.md (first lines)

# Screen Fix Iteration

You are a precision repair agent. Given a prioritised fix list from `screen-comparison`, you fix exactly one property per iteration, verify it, and only then advance to the next item.

> **Note on examples.** File paths, token names, and screenshot conventions in this skill are illustrative — they're drawn from the project this skill was authored in. Substitute the equivalents from your codebase.

This is the third skill in the visual-fidelity loop:
- `screen-decomposition` — build plan from plate (before)
- `screen-comparison` — audit of built screen vs plate (after)
- `screen-tweaking` — repair loop driven by comparison output (this skill)

The failure mode this skill exists to prevent: making several changes at once, re-screenshotting, finding the result is worse overall, and not knowing which change caused the regression.

## Inputs

- **Fix list** — the prioritised fix list from a `screen-comparison` run. Must be property-level (one entry per property, not one entry per element). If the fix list is element-level ("fix the Primary CTA"), run `screen-comparison` first to get property-level detail.
- **Plate path** — the LOCKED sample image.
- **Source path** — `app/src/screens/<screen>.ts`.
- **Screenshot command** — the Playwright command to re-render: `npx playwright test --grep "<screen>" --reporter=list`.

## Core rule

**One property. One change. One verification. Then advance.**

Never bundle two property fixes into the same code edit, even if they're in the same function, even if they look trivially related. "Fix the gilt stroke AND the label register" is two iterations, not one. The only exception is a fix that is physically inseparable at the code level (e.g., a helper call that sets both shape and fill as a single parameter object and cannot set them independently) — in that case, treat the inseparable group as one unit and note it explicitly.

## Process

### Iteration loop

For each item in the fix list, in priority order:

**Step 1 — Read the fix**
State the target property, the plate value, and the current port value. Quote directly from the comparison table:
```
Target: Controls — Primary CTA — gilt inset stroke
Plate:  present (0.9px gilt ring at alpha 0.50)
Port:   absent
```

**Step 2 — Locate the code**
Find the exact line(s) in the source file responsible for the property. Read the relevant function with `Read`. Do not guess — confirm the location before editing.

**Step 3 — Plan the change**
State the change in one sentence before writing any code:
```
Add a 0.9px gilt inner stroke (0xC8A84B @ alpha 0.50) drawn 4px inset
from the outer border rect inside buildCardChrome().
```

If the change would affect more than one property, stop and split it into separate iteration steps.

**Step 4 — Make the change**
Edit the source file. Keep the diff minimal — only the lines needed for this property. Do not reformat, rename, or refactor anything outside the target.

**Step 5 — Re-screenshot**
Run the Playwright screenshot command. Wait for it to complete. Do not proceed until the screenshot file is updated.

**Step 6 — Verify the property + lightweight regression check**
Read both the plate and the new screenshot. Check **the target property** in
detail. Then run a quick **regression scan** over every property already marked
`✓ DONE` in the fix-list status table: glance at each one in the new screenshot
and confirm the value the previous iteration set is still in place. This is a
30-second eyeball pass, not a full re-audit — you're catching the case where
fixing property B silently regresses property A. Full multi-property auditing
remains `screen-comparison`'s job.

Produce a one-row verdict for the target property and a one-line regression
status:

| Property | Plate | Port (new) | Status | Verdict |
|---|---|---|---|---|
| Primary CTA — gilt stroke | 0.9px gilt @ 0.50 | 0.9px gilt @ 0.50 | ✓ | PASS — advance |

**Regression check:** All N previously-completed properties still match their
recorded values. ✓ / ✗ <if ✗, name the regressed property — that becomes the
next item, before advancing to the next planned fix>.

**Step 7 — Pass or retry**

- **PASS** → mark the item done in the fix list, advance to the next item.
- **FAIL (attempt 1)** → diagnose what went wrong (wrong value? wrong element? rendering not updated?). Adjust and retry once from Step 3.
- **FAIL (attempt 2)** → do not attempt a third fix. Record the item as `BLOCKED` with the diagnosis. Advance to the next item and return to this one after completing the rest of the list. If still blocked after a full pass, surface to the user with a specific question.

### After all items

Run a full `screen-comparison` pass on the updated render. The fix-iteration loop is complete when the comparison returns **A- or better** (the production-ready gate defined in the screen-comparison rubric). If it returns below A-, use the new comparison's fix list as input for the next iteration round.

This matches the invocation rule below ("After `screen-comparison` returns < A-"); trigger and stop share the same boundary so a B+ result is *not* simultaneously "done" and "re-invoke this skill".

---

## Discipline rules

### Never touch what isn't on the fix list
If you notice another deviation while working, do not fix it in this session. Add it to a "noticed but deferred" list at the end of your output. It belongs in the next `screen-comparison` pass, not in this iteration.

### Never "improve" while fixing
The fix is to match the plate, not to improve on it. If the plate shows a 240px button and the port has a 200px button, the fix is 240px — not 260px because that "looks better". The plate IS the spec.

### Confirm before any destructive change
If the fix requires deleting or replacing a significant block (>10 lines), state what will be removed before editing and wait for confirmation if working interactively. If running unattended, log the removed block to the session output (under the iteration's "Change" block) before deletion. **Do not** leave the removed code as a commented-out block in the source — version control already preserves it, and dead `//` blocks accumulate as false-positive context for future agents.

### Track the fix list state
Maintain a running status table throughout the session:

| # | Property | Status | Notes |
|---|---|---|---|
| 1 | Primary CTA — gilt stroke | ✓ DONE | |
| 2 | Backdrop — screening | ✓ DONE | |
| 3 | Title — position | ⟳ IN PROGRESS | |
| 4 | Data tile — chrome | ○ PENDING | |
| 5 | Character — scale | ○ PENDING | |
| 6 | Row separator | ✗ BLOCKED | sat filter not applying; needs investigation |

Print this table at the start of each iteration so the state is always visible.

---

From pilotso11/pilotso11-skills, MIT.

More from pilotso11/pilotso11-skills