---
name: kicad-board-audit
description: >-
  Audit a KiCad board (.kicad_sch + .kicad_pcb) for design errors before fab:
  run real ERC/DRC via kicad-cli or the Adom desktop KiCad bridge, extract the
  pad-level netlist from the PCB file, then walk a checklist that catches what
  ERC cannot: floating mandatory pins (VCAP-type), supply pins tied to GND,
  wrong strap/boot-pin encodings, regulator feedback dividers computed with the
  wrong variant's VFB, missing pull-ups on open-drain buses, crystal load-cap
  math, impedance net-class misassignment, unrouted nets, keepout misconfig.
  Verify findings against datasheets/EVB schematics, deliver a severity-ranked
  report with fixes. Trigger words: audit board, board audit, review my board,
  board review, check my PCB, review this board for errors, kicad audit,
  schematic review, design review, pre-fab check, netlist review, run ERC,
  run DRC, find board errors, tapeout check.
user-invocable: true
---

# Audit a KiCad board

Given a KiCad project, find everything wrong, verify each suspicion against a
primary source, and deliver a severity-ranked report. Works on any board; the
checklist below is ordered by how often each step finds real bugs.

## 1. Run the real checkers first

- Local KiCad: `kicad-cli sch erc <root.kicad_sch>` (KiCad 8+) and
  `kicad-cli pcb drc <board.kicad_pcb>` (7+). The installed KiCad must be ≥ the
  file format version (check the `(version …)` header).
- Adom cloud container without KiCad: send the project to the user's desktop and
  use the KiCad bridge: `send_files` → `kicad_run_erc` / `kicad_run_drc`.
- Before trusting either result, read the project's silenced rules:
  `.kicad_pro` → `erc.rule_severities` and
  `board.design_settings.rule_severities`. Anything on `"ignore"` makes a
  clean pass hollow.
- DRC `unconnected_items` = unrouted copper, a fab blocker. Report those first.
- Group the rest of the DRC list by root cause before reporting; hundreds of
  violations usually collapse to a handful of causes (one bad footprint, one
  keepout flag, one via style).

## 2. Never trust a clean ERC

Three blind spots hide critical bugs behind a 0/0 ERC:

- **Symbol pin types.** `power_out` and `bidirectional` pins float silently.
  Classic: MCU VCAP pins with no capacitors. Board dead, ERC green. List every
  unconnected pin from the PCB side and judge each yourself.
- **Mistyped power pins.** A custom symbol will happily let a supply pin sit on
  GND without complaint. Trust the datasheet pin table, not the symbol.
- **Placeholder values.** `Value` fields like "LED" or the symbol name mean an
  unorderable BOM and unverifiable load caps / LED currents.

## 3. Extract the pad-level netlist

The `.kicad_pcb` is the synced ground truth. `assets/kicad_netlist.py
<board.kicad_pcb>` prints: components (ref / value / footprint / DNP), per-net
pin lists with pin functions, pads with no net, and per-net routed length + via
count. Format gotchas it already handles: pad nets are `(net N "name")` before
v10 but `(net "name")` from v10, and the tokenizer must be quote-aware because
pin names contain parentheses. (Multi-instance hierarchical sheets store their
references in `(instances …)` blocks, so don't diagnose "missing from schematic"
from the default Reference property.)

## 4. Electrical audit: walk the netlist per IC

- **Power pins.** Every supply pin on the right rail. Traps: pins named
  `*COM` / `E_*` that read like grounds but are supplies ("common **block**
  supply", not "common"); supply pins left floating; one 100 nF per VDD pin
  plus bulk.
- **Mandatory passives.** Core/VCAP caps, bias and reference resistors
  (EXTRES / ISET / RBIAS): exact value *and* tolerance from the datasheet,
  because sibling parts differ (6.04 k vs 12.1 k is a real trap).
- **Resets.** Every reset pin needs a defined source (RC, supervisor, or GPIO)
  meeting the documented supplies-stable-to-release time. Straps latch on the
  reset rising edge, so a floating reset also breaks strap latching.
- **Straps / boot pins.** Build the full table (pin, pull, latched value) and
  check each row against the datasheet encoding table, never intuition. Wrong
  MODE encodings that half-work (e.g. advertise only one speed) are common.
- **Regulators.** Recompute every feedback divider with the exact orderable
  variant's VFB; siblings differ (0.6 / 0.763 / 0.8 V). Check LDO dissipation
  ((Vin−Vout)×I vs package θJA) and compare rail sizing to the vendor EVB.
- **Chip-to-chip buses.** Verify pin-direction mapping end to end. PHY/MAC-mode
  function swaps are the classic crossover: confirm against the vendor EVB
  schematic, never the pin names. Open-drain buses (MDIO, I2C, IRQ) need
  pull-ups. Series terminations belong at the driver end.
- **Crystals.** Caps from the crystal's CL: CL = C1·C2/(C1+C2) + 2–5 pF stray.
  Require a real MPN in the Value field.
- **Connectors.** Shield/tab pins bonded to GND, unused pins terminated per
  datasheet, input protection on power entries.

## 5. Layout audit: scriptable from the file

- **Net classes.** List the class patterns and confirm every
  controlled-impedance net matches one. A net matching no pattern silently
  gets Default (classic: USB D+/D−). Then check each class's geometry gives the
  interface's required impedance on this stackup (USB 90 Ω, Ethernet pairs
  100 Ω).
- **Diff pairs.** Intra-pair skew from the script's per-net lengths.
- **Vias.** Every via style vs the board's min drill / annular constraints;
  mixed styles are the usual violation source.
- **Keepouts.** Check the allow-flags: a keepout drawn around a part but set to
  disallow *pads* flags the part's own pads.
- **Zones.** Plane layers and intended voids present; delete leftover
  auto-placement zones, dangling stubs, one-layer vias.

## 6. Verify before reporting

Every suspicious finding gets a primary source: datasheet, vendor hardware
design checklist, or EVB schematic. Check Adom wiki component pages and
`*-usage` skills first; they encode the exact variant (a "wrong" divider is
how the 0.763 V-VFB variant looks when you assume 0.6 V). For multi-IC boards,
fan out one research agent per major IC with numbered questions; require quoted
evidence and a confidence level. Anything unconfirmed stays flagged "verify
against datasheet", never asserted.

## 7. Report

Severity-ranked: **Critical** (won't work / won't fab) → **High** (works wrong
or marginal) → **Medium** (fix next spin) → **Low** (advisory). Each finding:
refs + pin numbers, why (with source), and one concrete fix. Include a
**verified-correct** section for cleared suspicions so the next reviewer
does not re-flag good design.