| name | pcb-review |
| model | claude-opus-4-7 |
| description | Comprehensive PCB design review — 8 domains, 100-point scoring, JLCPCB DFM rules, datasheet pin verification |
| disable-model-invocation | true |
| allowed-tools | Bash, Read, Grep, Glob, Agent |
PCB Design Review
Comprehensive design review of the PCB layout, analyzing 8 key domains like a senior PCB engineer would. Produces a scored report with actionable improvement suggestions.
Sources
- JLCPCB manufacturing rules:
.claude/skills/pcb-review/review-checklist.md
- JLCPCB blog best practices: trace angles, 3W rule, decoupling, impedance control, stackup
- Component datasheets:
hardware/datasheets/
- DFM reference:
.claude/skills/dfm-fix/dfm-reference.md
Steps
1. Run automated checks
cd /Users/pierrejonnycau/Documents/WORKS/esp32-emu-turbo
python3 scripts/pcb_review.py
python3 scripts/verify_dfm_v2.py
python3 scripts/verify_polarity.py
python3 scripts/verify_dfa.py
python3 scripts/validate_jlcpcb.py
python3 scripts/verify_bom_cpl_pcb.py
python3 scripts/verify_jlcpcb_capabilities.py
python3 scripts/verify_stencil_aperture.py
python3 scripts/verify_drill_standards.py
BOM/CPL/PCB cross-check (verify_bom_cpl_pcb.py, 13 checks):
Verifies all designators match across BOM, CPL, and PCB. Checks footprint names
are JLCPCB-compatible, CPL rotations valid, positions match (with known correction
allowances), all LCSC part numbers present, and schematic field completeness.
JLCPCB capabilities (verify_jlcpcb_capabilities.py, 12 checks):
Two-tier cross-check against JLCPCB published manufacturing limits. FAIL = board
rejected, WARN = below recommended. Covers trace, via, THT, clearance rules.
Stencil aperture (verify_stencil_aperture.py, 6 checks):
IPC-7525 area ratio + aspect ratio for multiple stencil thicknesses (3-5mil),
paste powder type recommendation, fine-pitch component detail report.
Drill standards (verify_drill_standards.py, 6 checks):
ISO metric + JLCPCB common drill mapping, drill inventory count, IPC-2222
drill-to-pad ratio, via vs PTH appropriateness.
1b. Run extended verification suite (17 gap-coverage tests)
python3 scripts/verify_antenna_keepout.py
python3 scripts/verify_stackup.py
python3 scripts/verify_net_class_widths.py
python3 scripts/verify_bom_values.py
python3 scripts/verify_power_paths.py
python3 scripts/verify_copper_balance.py
python3 scripts/verify_decoupling_paths.py
python3 scripts/verify_usb_impedance.py
python3 scripts/verify_via_in_pad.py
python3 scripts/verify_thermal_relief.py
python3 scripts/verify_ground_loops.py
python3 scripts/verify_test_points.py
| Script | Checks | What it catches |
|---|
verify_antenna_keepout.py | 5 | Copper/traces in ESP32 antenna zone (kills WiFi/BLE) |
verify_stackup.py | 5 | Wrong nets on inner plane layers |
verify_net_class_widths.py | 5 | Power traces too narrow (fuse risk) |
verify_bom_values.py | 75 | Schematic value vs BOM mismatch (wrong part assembled) |
verify_power_paths.py | 19 | Missing copper path from source to IC VDD pin |
verify_copper_balance.py | 3 | Layer imbalance causing PCB warping |
verify_decoupling_paths.py | 11 | Cap too far or poorly routed to IC |
verify_usb_impedance.py | 4 | USB trace geometry wrong for 90ohm differential |
verify_via_in_pad.py | 3 | Vias inside SMD pads (solder wicking) |
verify_thermal_relief.py | 4 | Missing thermal relief on zone connections |
verify_ground_loops.py | 3 | Audio-digital ground coupling |
verify_test_points.py | 18 | Missing debug probe points |
verify_esd_protection.py | 6 | Missing TVS/series resistors on USB |
verify_strapping_pins.py | 6 | ESP32 boot pin conflicts |
verify_usb_return_path.py | 3 | GND via density near USB traces |
verify_sd_interface.py | 7 | SD card SPI completeness + card detect |
verify_power_resonance.py | 4 | Power plane LC resonance frequency |
1c. Run datasheet verification (electrical + physical)
python3 scripts/verify_datasheet_nets.py
python3 scripts/verify_datasheet.py
Datasheet net verification (verify_datasheet_nets.py, 246 checks):
Compares EVERY pad of EVERY component against the expected net from the datasheet.
Uses hardware/datasheet_specs.py as single source of truth (pin→net mapping).
- Catches: unconnected pads that should be connected, wrong net on a pad
- Example: USB-C pad 1 should be GND, shield pads should be GND, VBUS on all 3 pins
Datasheet physical verification (verify_datasheet.py, 29 tests):
Compares PCB footprint dimensions against datasheet mechanical drawings.
- Pin count per component (ICs, connectors, passives, switches)
- Pad pitch (0.5mm FPC, 1.27mm SOIC, 2.0mm JST, etc.)
- Pad span / body dimensions (catches wrong package, e.g. SOP-16 vs SOIC-16W)
- NPTH positioning hole count and drill sizes
- THT drill sizes (JST, USB shield tabs)
- Datasheet PDF presence in
hardware/datasheets/
1f. Run design intent adversary (cross-source consistency)
python3 scripts/verify_design_intent.py
Design intent verification (verify_design_intent.py, 362 checks):
Cross-checks GPIO assignments, net connections, and signal paths across ALL sources:
firmware (board_config.h), schematic config (config.py), datasheet specs, and actual PCB layout.
| Test | What it catches |
|---|
| T1-T3 | GPIO mismatch across sources, duplicate GPIO assignments |
| T4-T5 | Missing signal endpoints, orphan nets (0-1 pad connections) |
| T6-T7 | Broken power chain (VBUS→+5V→+3V3), missing GND connections |
| T8 | Button circuit incomplete (no switch or no MCU connection) |
| T9-T11 | Reserved/invalid GPIO usage, strapping pin conflicts |
| T12-T16 | Signal chain breaks: display, audio, SD, USB paths |
| T17-T18 | Missing pull-ups, net naming issues |
| T19 | Pin electrical type conflicts (multi-output on same net) |
| T20 | ESP32-S3 IO MUX validation (GPIO range, PSRAM/flash reserved) |
| T21 | I2C bus completeness (pull-ups, address conflicts) |
| T22 | Power rail decoupling completeness (8 caps on correct rails) |
1g. Run DRC Audit (electrical connectivity)
kicad-cli pcb drc \
--output /tmp/drc_audit_report.json \
--format json \
--severity-all --units mm --all-track-errors \
hardware/kicad/esp32-emu-turbo.kicad_pcb
CRITICAL step — catches issues that ALL custom scripts miss:
shorting_items: traces touching pads with wrong/no net (board malfunction)unconnected_items: broken signal paths (components not connected)via_dangling: orphan vias (wasted manufacturing, DFM warnings)clearance: real spacing violations below JLCPCB minimums
Our verify_dfm_v2.py runs KiCad DRC but only checks 3 of 9 violation types.
Test 43 (trace-pad clearance) auto-skips when pads lack net assignments.
This step fills that gap. See .claude/skills/drc-audit/SKILL.md for full methodology.
Classify shorting_items as:
- Real shorts (
"nets X and Y)") — CRITICAL, board will fail
- Pad-net bugs (
"nets X and )") — generator fix needed in _init_pads()
1d. Run ERC (Electrical Rules Check)
python3 scripts/erc_check.py --run
Runs KiCad native ERC on the hierarchical schematic. Categorizes 730+ violations:
- Generator artifacts (suppressed): grid alignment, wiring stubs, library symbols — inherent to Python-generated schematics
- Real issues: pin_not_connected, power_pin_not_driven, pin_to_pin conflicts
- Critical: pin_to_pin (output↔output) must be zero for production
1e. Run SPICE power supply simulation
python3 scripts/spice_power_check.py
Requires: ngspice (brew install ngspice)
Simulates IP5306 boost → AMS1117 LDO → ESP32 load:
- +5V rail ripple at 500kHz switching (must be < 150mV)
- +3V3 rail ripple under load steps (must be < 50mV)
- Decoupling cap effectiveness (C17, C27, C1, C19)
- ESP32 WiFi burst response (200mA → 350mA in 10µs)
1j. Run electrical review scripts
python3 scripts/verify_strapping_pins.py
python3 scripts/verify_decoupling_adequacy.py
python3 scripts/verify_power_sequence.py
| Script | Tests | What it catches |
|---|
verify_strapping_pins.py | 12 | Wrong boot state, GPIO45 VDD_SPI conflict, EN RC timing, pull-up skip |
verify_decoupling_adequacy.py | 25 | Insufficient capacitance per IC datasheet, missing HF bypass |
verify_power_sequence.py | 26 | Power chain topology, upstream/downstream ordering, GND continuity |
1k. Run connectivity and signal chain verification
python3 scripts/verify_component_connectivity.py
python3 scripts/verify_signal_chain_complete.py
| Script | Tests | What it catches |
|---|
verify_component_connectivity.py | 2 | BOM components with zero electrical connections (phantom parts) |
verify_signal_chain_complete.py | 53 | Nets that only connect to one endpoint (broken signal chains) |
1l. Run net classification and board config validation
python3 scripts/net_classifier.py --validate
python3 scripts/generate_board_config.py --check
| Script | What it catches |
|---|
net_classifier.py --validate | Net named "I2S_BCLK" on non-I2S GPIO, USB pins misused |
generate_board_config.py --check | Firmware board_config.h drifted from config.py master |
1m. Run schematic-to-PCB netlist diff
python3 scripts/verify_netlist_diff.py
Netlist cross-check (verify_netlist_diff.py, 4 checks):
Exports schematic XML netlist via kicad-cli, compares against PCB cache:
- Missing routes (schematic net not in PCB)
- Orphan PCB nets (PCB net not in schematic)
- Missing footprints (component in schematic but not PCB)
- Pin-to-net mismatches between schematic and PCB
1m2. Run schematic↔PCB/datasheet_specs sync guard (R4 class)
python3 scripts/verify_schematic_pcb_sync.py
Schematic/PCB/datasheet_specs.py sync (verify_schematic_pcb_sync.py):
Guards against the R4 class of bugs — schematic generator and PCB
generator are two independent Python code paths and can drift silently.
Three checks, all fail-loud (no soft-passes, no auto-skip):
| Check | Catches | R4 bug |
|---|
| A — ref coverage | BOM refs with no schematic symbol; schematic refs with no BOM entry | R4-HIGH-1 (USBLC6/R22/R23 in PCB but missing from schematic) |
| B — designator collision | Same ref used for two different component families across schematic and BOM (token-overlap heuristic) | R4-HIGH-2 (U4 was both ILI9488 module and USBLC6 TVS) |
| C — connector net coverage | Each connector in datasheet_specs.py must have its full expected net set appear in the sheet that wires it | R4-CRIT-1 (display.py docstring described a completely different FPC pinout than the PCB used) |
CRITICAL — this script must exit 0 before any PCB release. It is
the only guard that catches schematic↔PCB drift on the Python
generators. Never add suppressions; never edit the allowlist in the
script to make a real bug disappear. Fix the design side instead.
1n. Generate hardware test firmware (Phase 3 prototype)
python3 scripts/generate_hw_tests.py
Hardware test generator (20 tests in software/test/test_hardware.c):
Auto-generates ESP-IDF Unity test firmware from board_config.h:
- 12 button idle-HIGH tests (BTN_L internal pull-up)
- LCD D0-D7 walking-1 short detection
- SD SPI bus init + CMD0 probe
- I2S PDM TX silence test
- USB JTAG verification
- 3.3V power rail ADC check
- PSRAM 1MB pattern verify
2. Manual review against checklist
Read review-checklist.md and verify each domain:
| # | Domain (points) | Key checks |
|---|
| 1 | Power Integrity (15) | Trace widths for current, decoupling caps near ICs, GND/power planes |
| 2 | Signal Integrity (15) | Bus matching, USB diff pair, 3W rule, 45° traces, impedance |
| 3 | Thermal (10) | Thermal vias, EP pad connections, copper area, IC spacing |
| 4 | JLCPCB DFM (20) | Trace/pad/via spacing, mask bridge, copper-to-edge, fiducials, validate_jlcpcb.py |
| 5 | EMI/EMC (10) | GND plane continuity, return paths, decoupling strategy |
| 6 | Component Polarity (15) | Pin-1 vs datasheet, LED polarity, CPL rotation, BOM-CPL match |
| 7 | Mechanical (10) | Mounting holes, connector access, NPTH sizes, board outline |
| 8 | Documentation (5) | LCSC parts, gerbers, silkscreen, assembly variants |
3. Datasheet physical verification
python3 scripts/verify_datasheet.py
Automated cross-check of PCB vs datasheets (29 tests):
- Pin count per component (ICs, connectors, passives, switches)
- Pad pitch matches datasheet (0.5mm FPC, 1.27mm SOIC, 2.0mm JST, etc.)
- Pad span / body dimensions (catches wrong package, e.g. SOP-16 vs SOIC-16W)
- NPTH positioning hole count and drill size
- THT drill sizes (JST, USB shield tabs)
- Datasheet PDF presence in
hardware/datasheets/
3b. Manual datasheet verification (Domain 6)
For each IC/connector, read the datasheet from hardware/datasheets/ and verify:
- Pin 1 location matches footprint orientation
- Net assignments match datasheet pinout
- CPL rotation produces correct JLCPCB placement
- Passive component values match typical application circuit
4. Current capacity check (Domain 1)
Verify power trace widths against current requirements:
- VBUS/BAT+: up to 2.1A (IP5306 charger) → need ≥0.76mm (30mil)
- +5V: up to 1A → need ≥0.25mm (10mil)
- +3V3: up to 0.5A → need ≥0.13mm (5mil)
- LX (inductor): up to 2.1A pulsed → need ≥0.76mm (30mil)
1h. Run trace-through-pad overlap check
python3 scripts/verify_trace_through_pad.py
1h2. Run per-net copper connectivity check (R5-CRIT gate)
python3 scripts/verify_net_connectivity.py
CRITICAL HARD GATE (R6): walks the union-find over pads ∪ vias ∪
segments for every net and asserts single connected component. Catches
the R5-CRIT class of bugs where pad-net labels are correct but copper
is fragmented — L1.1 BAT+ inductor isolated (board can't boot on
battery), C17/C18 decoupling caps floating, button pull-ups never
connected, SW_BOOT non-functional, D1 menu diode anodes dangling,
BTN_L missing F.Cu→B.Cu via-in-pad at U1.26 (L shoulder button never
worked on v3.3). Run with --strict to bail on technical-debt
accepted fragmentations.
CRITICAL HARD GATE: any overlap means a copper trace physically shares
copper with an unnetted (or differently-netted) pad — a real short on the
manufactured board. Checks F.Cu and B.Cu. Catches issues that DRC
misses when pads have no net assignment (the v3.3 regression from commit
775e9fd, where _PAD_NETS entries for U2.3/4, U6.8/9, SW_PWR.4b/4d
were removed and left BTN_SELECT/GND/SD_MISO/BTN_R traces crossing
unnetted pads). Integrated into:
make release-prep (blocking dependency of release)make verify-all (parallel verification suite)make verify-trace-through-pad (standalone)/release, /release-prep, /full-release skills (hard gate)Stop hook .claude/hooks/stop-verify-dfm.sh (auto-runs after any
PCB edit and blocks Claude's response with exit 2 on failure)
1i. System health summary
Answer these 5 questions with data:
| Question | Check | Must be |
|---|
| Components positioned correctly? | verify_datasheet.py + verify_polarity.py | ALL PASS |
| No shorts or signal overlaps? | DFM 115/115 + DRC 0 real shorts + 0 trace-through-pad | ALL ZERO |
| Power stable? | spice_power_check.py | +5V ripple <150mV, +3V3 <50mV |
| Pinout matches datasheet? | verify_datasheet_nets.py | ALL PASS |
| All signals reach destination? | verify_design_intent.py | ALL PASS |
| Schematic ↔ PCB ↔ datasheet_specs agree? | verify_schematic_pcb_sync.py | PASS (R4 guard) |
If ANY check fails, stop and fix before generating the report.
5. Generate report
Format findings as:
## PCB Design Review Report
| # | Domain | Score | Key Finding |
|---|--------|-------|-------------|
| 1 | Power Integrity | ?/15 | ... |
| 2 | Signal Integrity | ?/15 | ... |
| 3 | Thermal | ?/10 | ... |
| 4 | JLCPCB DFM | ?/20 | ... |
| 5 | EMI/EMC | ?/10 | ... |
| 6 | Component Polarity | ?/15 | ... |
| 7 | Mechanical | ?/10 | ... |
| 8 | Documentation | ?/5 | ... |
| **TOTAL** | | **?/100** | ... |
### Top 5 Priority Fixes
1. ...
2. ...
6. Fix and re-verify
After making changes:
python3 -m scripts.generate_pcb hardware/kicad
python3 scripts/verify_dfm_v2.py
python3 scripts/verify_polarity.py
python3 scripts/validate_jlcpcb.py
Key Files
.claude/skills/pcb-review/review-checklist.md — Full scoring criteria + JLCPCB rules referencehardware/datasheets/ — Component datasheets for pin verificationscripts/pcb_review.py — Automated review scriptscripts/verify_dfm_v2.py — DFM verification (115 tests)scripts/verify_polarity.py — Polarity/pin assignment testsscripts/verify_dfa.py — Assembly verification (9 tests)scripts/verify_bom_cpl_pcb.py — BOM/CPL/PCB cross-check (10 tests)scripts/verify_datasheet.py — Datasheet vs PCB physical verification (29 tests)scripts/verify_datasheet_nets.py — Datasheet vs PCB net/pinout verification (259 checks)hardware/datasheet_specs.py — Single source of truth: pin→net mapping for all 30 componentsscripts/validate_jlcpcb.py — JLCPCB manufacturing validation (26 tests)scripts/verify_antenna_keepout.py — ESP32 antenna zone clearance (5 checks)scripts/verify_stackup.py — 4-layer stackup net verification (5 checks)scripts/verify_net_class_widths.py — Power/signal trace width enforcement (5 checks)scripts/verify_bom_values.py — BOM vs schematic value cross-check (75 checks)scripts/verify_power_paths.py — Power delivery path tracing (19 checks)scripts/verify_copper_balance.py — Layer copper distribution (3 checks)scripts/verify_decoupling_paths.py — Cap-to-IC path quality (11 checks)scripts/verify_usb_impedance.py — USB D+/D- impedance geometry (4 checks)scripts/verify_via_in_pad.py — Via-in-pad detection all SMD pads (3 checks)scripts/verify_thermal_relief.py — Zone thermal relief settings (4 checks)scripts/verify_ground_loops.py — Audio-digital ground coupling (3 checks)scripts/verify_test_points.py — Debug probe accessibility (18 checks)scripts/erc_check.py — ERC automation (KiCad native, artifact filtering)scripts/spice_power_check.py — ngspice power supply simulation (+5V/+3V3 ripple, load transient)scripts/verify_design_intent.py — Cross-source adversary (362 checks, T1-T22)scripts/verify_netlist_diff.py — Schematic-to-PCB netlist cross-check (4 checks)scripts/verify_schematic_pcb_sync.py — R4 sync guard: ref coverage, designator collisions, connector net coverage (schematic vs datasheet_specs.py vs CPL)scripts/net_classifier.py — Net function classifier with GPIO validationscripts/generate_board_config.py — Board config drift detection (config.py vs board_config.h)scripts/generate_hw_tests.py — ESP-IDF Unity test generator (20 tests)scripts/generate_pcb/routing.py — Trace routingscripts/generate_pcb/board.py — Component placementscripts/generate_pcb/jlcpcb_export.py — CPL/BOM export
