---
name: visual-excellence
description: Drive a KiCad schematic to a professional, cosmetically clean state through a score → fix → render → verify loop using KiCad MCP Pro cosmetic tools.
---

# Visual Excellence Skill

Use this skill when an AI agent is asked to make a KiCad schematic *look*
professional — clean, readable, and conventionally drawn — not just electrically
correct. It closes the loop between measuring cosmetic quality, applying safe
fixes, and visually confirming the result.

This skill is specific to `oaslananka/kicad-mcp-pro` and should be kept
synchronized with `docs/tools-reference.generated.md`.

## When to use

- Post-capture cleanup before layout or review
- Preparing a schematic for a datasheet, report, or customer hand-off
- Whenever a sheet "works but looks rushed": off-grid parts, diagonal wires,
  colliding labels, sideways power symbols, inconsistent fonts

Do **not** use this skill to claim electrical correctness. Cosmetic fixes never
substitute for ERC, connectivity review, or human engineering approval. Run
`sch_visual_qa` / `run_erc` separately for correctness.

## The invariant you can rely on

Every cosmetic fixer treats **electrical connectivity as a hard invariant**. It
computes a coordinate-independent connectivity signature before and after the
change; a fixer that would alter any net is *refused* on apply and never writes.
So you can apply fixes without fear of silently breaking a net — but always
confirm with the render and the visual diff, and finish with an ERC pass.

## Required context

- Active project path and the schematic file(s)
- The target cosmetic score (default: 80/100)
- Whether you are allowed to modify the schematic (this skill mutates on
  `apply=true`; it needs write operating mode)

## Primary MCP tools

### Measure

- `sch_cosmetic_score` — 0–100 score with a per-category penalty breakdown and
  the `worst_category` to fix first (`grid`, `wiring`, `typography`,
  `orientation`, `layout_balance`, `readability`, `documentation`)
- `sch_visual_qa` — readability findings (overlaps, off-sheet, dense fanout)

### Fix (dry-run by default; pass `apply=true` to commit)

- `sch_align_to_grid` — snap off-grid symbols, labels, wires, junctions
- `sch_straighten_wires` — flatten almost-orthogonal wire segments
- `sch_resolve_label_overlaps` — flip label justify so text stops colliding
- `sch_normalize_power_orientation` — upright sideways power/ground symbols
- `sch_normalize_text_sizes` — normalise outlier fonts onto the dominant size

### See and verify

- `sch_render_png` — render the sheet so you can visually evaluate it
- `sch_render_visual_diff` — the exact before/after pixel delta of your last
  mutation, plus the list of changed objects
- `run_erc` — the electrical safety net after cosmetic edits

## The loop

Run this loop per sheet until the score meets the target or no fixer applies:

1. **Measure.** Call `sch_cosmetic_score`. If `cosmetic_score` ≥ target, stop —
   the sheet is clean. Otherwise read `worst_category`.
2. **Plan (dry run).** Call the fixer matching `worst_category` with the default
   `apply=false`. Read `connectivity_preserved` and the `changes` list.
   - `grid` → `sch_align_to_grid`
   - `wiring` → `sch_straighten_wires`
   - `readability` (label overlaps) → `sch_resolve_label_overlaps`
   - `orientation` → `sch_normalize_power_orientation`
   - `typography` → `sch_normalize_text_sizes`
3. **Decide.** If `connectivity_preserved` is `false`, do **not** apply — the fix
   would change a net. Report it and hand back to the human (or fix the
   underlying wiring first). If `true`, continue.
4. **Apply.** Call the same fixer with `apply=true`. A `refused` status means the
   invariant caught a connectivity change at commit time — treat it as step 3.
5. **See.** Call `sch_render_png` and evaluate the image against the rubric
   below. Call `sch_render_visual_diff` and confirm the red delta covers only the
   objects you intended to move.
6. **Re-measure.** Call `sch_cosmetic_score` again. Confirm the score rose and no
   new category regressed. Return to step 1.
7. **Guard.** After the loop, run `run_erc` to confirm the cosmetic pass left the
   design electrically intact.

Stop after a full pass where every applicable fixer reports `no_change`, even if
the score is still below target — the remaining gap needs human layout judgment,
not an automated fixer. Report what is left and why.

## Rubric — what "professional" looks like

Compare the sheet you render against these two reference renders (both are the
same three-resistor circuit):

- `reference/professional.png` — clean: parts aligned on a row, one horizontal
  wire, and readable `IN` / `MID` / `OUT` labels.
- `reference/rushed.png` — the same circuit drawn badly: the net labels collide
  into an unreadable blob, the wire runs diagonally, and the parts sit off-grid
  at uneven heights.

The `rushed` sheet is still electrically identical — this is exactly the class of
defect that ERC passes and cosmetic review must catch. When you evaluate a
`sch_render_png`, check for:

- **Grid** — parts and wires sit on a regular grid; nothing looks hand-nudged.
- **Orthogonal wiring** — wires run horizontally/vertically; no diagonals.
- **Legible labels** — net labels and reference designators do not overlap and
  read cleanly against nearby text.
- **Conventional symbols** — power up, ground down, no sideways power symbols.
- **Consistent typography** — one dominant font size across the sheet.
- **Balanced composition** — content spreads across the sheet rather than
  crowding one corner.
- **Complete title block** — title, revision, date, and company are filled in.

Judge the rendered image, not just the score: the score is a fast proxy, but the
render is the ground truth for readability.

## Guardrails

- Cosmetic ≠ correct. Never sign off electrical behavior from this skill.
- Prefer dry runs first; only apply once `connectivity_preserved` is `true`.
- If a fixer is refused, the underlying net topology needs a human — surface it,
  do not force it.
- End with `run_erc`; a clean cosmetic pass must also be a clean electrical one.