Visual Fix

Point at the UI. Fix the right source.

Visual Fix is an Agent Skill for targeted frontend repairs. Give it a screenshot, a pointed region, visible text, a route, or a plain-language symptom. It traces the rendered element to maintained source code, shows the exact patch and affected scope, waits for approval, then verifies the result with the strongest evidence the project supports.

"On mobile, this pricing card cuts off the button."

Screenshot / route / visible anchor
              ↓
Rendered element → component → winning style
              ↓
Exact change plan and affected scope
              ↓
Approval → minimal patch → visual or static verification

What it handles

• Layout, spacing, sizing, alignment, overflow, and responsive breakpoints
• Color, typography, borders, shadows, and visibility
• Component-state visual mismatches
• Differences between a current and target screenshot

Visual Fix works on an existing, accessible codebase. Broad redesigns, feature development, backend failures, and bitmap editing belong in other workflows.

Supported input

Input	Useful context
Plain-language symptom	Route or a unique visible anchor
Current screenshot	Route, component label, or nearby text when the screen repeats elements
Screenshot with a pointed region	What the region should look like
Current and target screenshots	Which image is current, plus route and viewport
Route, selector, test id, or component name	The visible defect and expected result

Visual Fix asks only for missing evidence that prevents reliable localization.

Product contract

1. Establish the target

It identifies one visible issue, the expected result, and the relevant route, state, and viewport.

2. Capture a read-only baseline

It reads project instructions, checks the worktree, finds the source of truth, and records whether the target can be reproduced. Existing user changes remain untouched.

3. Locate from rendered evidence

It traces the visible element through the route and component tree to the maintained style or markup. The result includes current file and line evidence, related source, confidence, and affected scope.

Located
- Primary: src/components/ProductGrid.tsx:42, ProductGrid
- Related: src/styles/products.css:18
- Evidence: `.grid` controls the repeated spacing visible between the cards
- Confidence: high

4. Diagnose the actual cause

It connects the symptom to inspected code. When evidence supports one cause, it presents one. When the source remains ambiguous, it shows a small set of falsifiable hypotheses instead of guessing a CSS value.

5. Ask for approval on the exact plan

Change plan
- Files: src/components/ProductGrid.tsx:42
- Current: gap: 8px
- Proposed: use the existing space-4 token (16px)
- Scope: ProductGrid on /catalog and /search
- Preserving: card padding, mobile column count, unrelated routes
- Verification: targeted test, lint, screenshots at 390 x 844 and 1280 x 800
- Risk: medium; the component is shared by two routes

Selecting a diagnosis does not authorize an edit. A plan that expands to another file, dependency, lockfile, generated artifact, or route requires renewed approval.

6. Apply and verify

It makes the smallest approved patch, inspects the diff, runs relevant checks, and renders the same route and viewport when possible. Completion reports use one evidence label:

• Verified visually
• Verified statically
• Unable to verify visually
• Verification failed

A clean diff or passing test never gets presented as visual proof.

Install

The Skills CLI can install Visual Fix for supported coding agents.

npx skills add cucuwang/visual-fix --skill visual-fix

Install globally for a specific agent:

npx skills add cucuwang/visual-fix --skill visual-fix -g -a claude-code
npx skills add cucuwang/visual-fix --skill visual-fix -g -a codex

Claude Code can invoke the installed skill as /visual-fix. Codex can select it with $visual-fix or activate it from a matching request. See the official Codex skills documentation for Codex discovery and invocation behavior.

Try it locally

Clone the repository and validate the skill package and scenarios:

make test

The evaluation harness uses only the Python standard library. Its fixtures cover spacing, overflow, and responsive alignment. Each scenario declares the user evidence, expected route and source location, accepted root causes, target markers, and the invariant that localization remains read-only until approval.

Regenerate the demo image from its local HTML fixture with a Chromium-compatible browser:

python3 scripts/capture_demo.py

Repository structure:

skills/visual-fix/
├── SKILL.md
├── agents/openai.yaml
└── references/
evals/
├── README.md
└── fixtures/
scripts/
└── evaluate.py

Migration from grill-me-fix

The product and skill name changed because the original name emphasized questioning while the actual job is precise UI localization and repair.

• Skill invocation changes from /grill-me-fix to /visual-fix.
• The canonical skill directory changes to skills/visual-fix.
• Reinstall the skill after the repository rename so the previous installation does not remain as a separate command.

The repository rename will preserve GitHub redirects. Installed skill directories are local copies or links and still require migration.

Contributing

See CONTRIBUTING.md. Contract changes should include a fixture or evaluation update, and demo evidence must come from a reproducible route and viewport.

Acknowledgments

The original grill-me-fix experiment was inspired by mattpocock/skills/grill-me. Visual Fix keeps the useful habit of clarifying intent while giving the project its own UI-localization contract.

License

MIT. See LICENSE.