---
name: kicad-port
description: "Project skill for porting the Raspberry Pi CM5IO reference design into this custom CM5 carrier board. Use this skill on EVERY schematic/PCB task in this repo: editing .kicad_sch, defining or changing pinouts and nets, adding/removing circuit blocks, or verifying a design change. It encodes the source-of-truth for CM5 pins, the s-expression editing rules, and the MANDATORY verify loop (kicad-cli ERC + kicad-happy analyzer + diff-vs-reference). Always consult this skill before editing any KiCad file here, and run the verify loop after."
---

# CM5 Carrier — Port Workflow

We are building a custom Raspberry Pi **CM5 carrier board** by porting the official
**CM5IO reference design**. Work is currently in the **schematic / pinout phase**.

This is a **diff-from-reference** project: every change starts from a known-good reference
and must stay electrically defensible against it. Claude is the *editor* (surgical s-expr
text edits); the tooling below is the *verifier*. Never edit without verifying.

## Source of truth (consult before any pin/net decision)

1. `cm5-datasheet.pdf` — authoritative CM5 module pinout, power sequencing, pin reservations.
2. `CM5_Carrier_Pinout_BOM.md` / `CM5_Carrier_Design.md` — this board's intended pin map and BOM.
3. `refs/CM5IO.kicad_sch` (+ `CM5_GPIO`, `CM5_HighSpeed`, `PCIe-M2` sub-sheets) — the reference
   schematic we port FROM. Hierarchical design; sub-sheets are referenced by UUID.

If a pin assignment disagrees between the datasheet and any other doc, **the datasheet wins** —
flag the discrepancy, don't silently pick one.

## S-expression editing rules (footguns)

KiCad `.kicad_sch` / `.kicad_pcb` files are s-expression text — readable and Edit-able.
But:

- **NEVER hand-edit or hand-invent UUIDs.** Copy-pasting a symbol/sheet block as text and
  reusing its UUID corrupts the schematic (KiCad treats duplicates as the same object).
  If you need a new instance, generate a fresh UUID:
  `python3 -c "import uuid; print(uuid.uuid4())"`
- **Hierarchical nets:** a net can carry multiple labels across sheets (the analyzer's `LB-001`
  finding). Prefer one canonical label style per cross-sheet net; don't rename one half.
- **Power nets need a driver:** every power rail needs a power symbol or `PWR_FLAG`, or ERC fails.
- After ANY structural edit, re-run the verify loop below. A passing Edit is not a passing design.
- Coordinate edits through git. Another (context-free) agent may touch these files; commit small,
  review diffs, never blind-overwrite a sheet you didn't just read.

## The verify loop (MANDATORY after every schematic change)

`python3` here is Homebrew 3.14 (the kicad-happy scripts require Python ≥ 3.10).
Scripts live under `~/.claude/skills/kicad/scripts/` (symlinked from `kicad-happy/`).

```bash
SCH=path/to/your.kicad_sch          # the file you changed
KSCR=~/.claude/skills/kicad/scripts

# 1. KiCad's own ERC (the hard gate — must be clean before commit)
kicad-cli sch erc --exit-code-violations --output /tmp/erc.json --format json "$SCH"
#    non-zero exit => fix or revert before proceeding.

# 2. kicad-happy structural review (catches what ERC won't: decoupling gaps,
#    connector ground ratios, protocol/voltage mismatches, multi-label nets)
python3 $KSCR/analyze_schematic.py "$SCH" --text          # human-readable
python3 $KSCR/analyze_schematic.py "$SCH" -o /tmp/head.json   # machine-readable

# 3. Diff against the committed reference baseline to see what your change moved
python3 $KSCR/diff_analysis.py analysis/baseline/cm5io.json /tmp/head.json --text
```

Treat new WARN/ERROR findings in step 2/3 as regressions to justify or fix — not noise.

## Optional deeper checks

- **SPICE** (`spice` skill): validates analog subcircuits (regulator feedback dividers, RC/LC
  filters, crystal load caps). Requires a simulator on PATH — **`ngspice` IS installed**
  (`/opt/homebrew/bin/ngspice`) and the loop is validated end-to-end on the reference
  (8 subcircuits pass, incl. the 5V→3.3V buck feedback divider). Run after the analyzer:
  `python3 ~/.claude/skills/spice/scripts/simulate_subcircuits.py <analysis.json> -o sim.json`.
- **Datasheets** (`datasheets` skill): extract CM5 / IC specs from PDFs so analyzer findings are
  `datasheet-backed` rather than `heuristic`. Start with `cm5-datasheet.pdf`.

## Schematic hygiene checklist (before declaring a sheet done)

- [ ] All nets named — no auto-generated `Net-(R1-Pad1)` names in the final design
- [ ] Power rails ALL_CAPS (`+3V3`, `+5V`, `GND`); active-low uses `n` prefix (`nRESET`, `nCS`)
- [ ] `PWR_FLAG` on every power net with no explicit driver
- [ ] No-connect markers on all intentionally unconnected pins
- [ ] Hierarchical port names match the nets they carry
- [ ] Reference designators follow convention (U/R/C/L/D/Q/J/SW/F/TP/BT), annotated by block
- [ ] Title block filled (project, rev, date, author, one-line description)
- [ ] Design notes added for non-obvious choices (pull-up values, protection ratings, placement)
- [ ] **ERC passes with zero errors** (step 1 above)

## Reference shelf (not wired into the loop)

- `MCP-KiCad/` — MCP server over `pcbnew` (SWIG). PCB/fabrication only, Linux/flatpak-first.
  Ignore until layout phase, and even then prefer `kicad-cli pcb` over it.
- `kicad-claude-toolkit/` — greenfield "circuit-as-Python → PCB" generator + IPC bridge.
  Built for new designs, not porting. Only its `schematic-hygiene` guidance (folded in above)
  is relevant now.