design-iteration

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Design Iteration

Work in focused rounds:
observe → change → render → inspect → present → record feedback.

## Operating rules

- Use explicit user feedback as the authority for LIKED and REJECTED decisions.
  Never turn your own aesthetic judgment into a user preference.
- Preserve active liked details. Do not reintroduce active rejected treatments
  in the same scope without explicit reconsideration.
- Scope preferences narrowly: element, property, viewport, and interaction state.
  Rejecting one composition does not imply rejecting every technique it uses.
- Keep visual inspection, functional verification, and user approval separate.
- Default to one presented round, then wait for feedback. Produce multiple
  alternatives or autonomous rounds only when requested, within a stated limit.
- Follow project instructions and avoid unrelated redesigns or refactors.
- Close every round by shipping it: when the round's changes are presented,
  stage only your own files and commit and push them in the same session
  without waiting for an explicit request — the repo stays current with
  every presented round, and feedback that follows (including a rejection)
  opens the next round and its own commit. Pushing is not approval: keep
  presenting for liked/rejected verdicts, and stop and report failures,
  conflicts, or missing authentication instead of forcing a delivery
  operation.

## Persistent state

Use the project's existing iteration directory if one exists. Otherwise use:

- `.agent/iterations/design/<task-slug>/ledger.md`
- `.agent/iterations/design/<task-slug>/artifacts/R<nnn>/`

Reuse a stable task slug across sessions. Allocate IDs from existing records;
never restart numbering or overwrite an earlier round's artifacts.

The ledger is the historical source of truth. Optional summaries are derived
views and must not replace it.

## Visual baseline is mandatory — screenshots are usually possible

Before claiming NOT VISUALLY VERIFIED, actually hunt for a browser: check
Playwright's cache (`~/Library/Caches/ms-playwright/chromium-*/chrome-mac/
Chromium.app/Contents/MacOS/Chromium` on macOS), puppeteer-core candidates,
`CHROME_PATH`. A headless Chromium there + `puppeteer-core` is enough: boot
the dev server (`npm --prefix <app> run dev -- --port <port> --strictPort`,
run from the app package, not the workspace root — wrong cwd = 404), wait
for `networkidle2` + a settle delay, `page.$(selector).screenshot(...)`,
then READ the PNG with the Read tool and inspect the actual image. Record
the shot path as the round's artifact. "No browser" is a last-resort
finding, not a default excuse — an unverified round the owner cannot see
is a wasted round.

## Round procedure

1. **Resume and reconcile**
   Read the brief, relevant implementation, references, and existing ledger.
   Append any new explicit feedback before planning another round.
   Reconstruct active preferences, applying explicit supersession events.
   Ask only about blocking ambiguities or unresolved preference conflicts.

2. **Establish the visual baseline**
   Inspect the current rendered result at the relevant viewport and state.
   Preserve the screenshot or supplied reference.
   For a new design, render the first candidate as the initial baseline.
   Record concrete observations rather than unsupported judgments.

3. **Choose a focused hypothesis**
   State the desired improvement and the small set of changes intended to
   produce it. Identify which liked details must remain unchanged and which
   rejected details the round addresses.
   Avoid changing several unrelated design dimensions at once.

4. **Implement and inspect**
   Render the changed result. Compare before and after using matching viewport,
   scale, content, and interaction state; disclose unavoidable differences.
   Inspect the actual image, not merely the source code.
   Check relevant hierarchy, spacing, typography, contrast, overflow, responsive
   behavior, and interaction states.

   When code changes, use `code-iteration` if available; otherwise run relevant
   project checks. Passing code checks does not establish visual approval.

   If rendering or image inspection is unavailable, mark the result
   `NOT VISUALLY VERIFIED`. Provide provisional work if useful and request the
   missing screenshot or access. Never invent visual observations.

5. **Present the round**
   Append the round record, then show or link the actual artifacts.
   Explain what stayed, what changed, and the main unresolved tradeoff.
   Ask a focused question inviting liked/rejected feedback.
   Do not describe the round as approved unless the user approved it.

6. **Record feedback and continue**
   Split mixed feedback into atomic decisions.
   Record explicit preferences from the brief or subsequent feedback, including
   their source and scope. Keep your recommendations outside preference records.
   Continue from the active ledger, not from memory.

   On explicit approval, stop redesigning and hand off the approved artifact,
   active constraints, verification status, and remaining implementation work.

## Append-only ledger

Append complete Markdown blocks using append operations. Never rewrite, delete,
sort, reformat, or silently correct existing records.

Use a round block like:

```markdown
## Round R001
- Goal: <specific improvement>
- Preserved preferences: <feedback IDs or none>
- Changes: <focused changes>
- Before: <artifact/reference>
- After: <artifact/reference>
- Visual inspection: <performed checks and observations, or NOT RUN>
- Code verification: <evidence reference, failures, or NOT RUN>
- Open question: <feedback needed>

From vasyapym/vasyapym.github.io, MIT.

More from vasyapym/vasyapym.github.io