--- 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 ` (KiCad 8+) and `kicad-cli pcb drc ` (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 ` 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.