How I work with AI

---
name: schematic-review
description: Runs a full, independent two-reviewer design review of a KiCad schematic before PCB layout. Exports the netlist, ERC, BOM, pin list and datasheet text, then Claude and OpenAI Codex each review the whole schematic separately against the datasheets and design intent, and Claude verifies and merges both sets of findings into one ranked report (found by both / Codex only / Claude only). Never edits the schematic. Use when the user asks for a schematic review, design review, second opinion on a schematic, to check a schematic before layout, or to "panel" or "scour" a schematic for errors, even if they don't name the skill.
---

# Schematic Review

Two reviewers with different blind spots go over the same schematic independently, then their findings are
checked and merged. The goal is real errors found before copper, not a long list: every finding must be
verified against the netlist or a datasheet before it reaches the user. The review never changes the design;
fixes happen only after the user agrees to each one.

## 1. Gather the inputs
Find, and confirm with the user if anything is missing or ambiguous:
- the KiCad project folder (the one with the `.kicad_pro`)
- the pin list / intended netlist and the BOM (often `.xlsx`)
- the datasheets folder (PDFs)
- the design-intent document (architecture doc, requirements)

Tell the user that footprints that are not assigned yet will not be reported as errors.

## 2. Export everything to text
Run (creates the review folder; inside a git repo use `<git-dir>/schematic-review/` so it isn't committed):
```bash
python3 ~/.claude/skills/schematic-review/prepare.py <kicad_project_dir> <out_dir> \
  --xlsx <pin_list.xlsx> <bom.xlsx> --datasheets <datasheets_dir>
```
Outputs: `connections_by_part.txt` (every part, value, symbol, footprint, each pin → net — the ground truth),
`nets.txt`, `erc.rpt`, `schematic.pdf`, the spreadsheets as text, and `datasheets_txt/` (PDF text via macOS
PDFKit). Image-only PDFs come out empty: note them, and read those as images if they matter.

Also run the drawing check (missing junction dots at T-points and where 3+ wire ends meet):
```bash
python3 ~/.claude/skills/schematic-review/junction_check.py <kicad_project_dir>
```

## 3. Start Codex first, in the background (independent review)
**Cost check before launching.** A frontier model at max effort can run 20+ minutes and use a lot of credits.
Tell the user the model and effort and get a yes. Defaults:
- `gpt-6-astra` at `high` effort for a full review (good depth, much cheaper than max)
- `max` only if the user explicitly asks for the deepest pass
- `gpt-6-luna` at `medium` if credits are tight

Check the model list in `~/.codex/models_cache.json` if a model name fails. Write a prompt file that gives
Codex: the product summary, the input paths above, "do not report missing footprints", the checklist in
section 4, and this output format: `## Summary`, then numbered `### N. [critical|high|medium|low] title` with
Where / Problem / Evidence (datasheet + page, netlist lines, maths) / Fix / Confidence, then `## Checked and OK`.
Do NOT give Codex Claude's findings (independence matters). Launch:
```bash
nohup npx --yes @openai/codex@0.160.0 exec -m <model> -c model_reasoning_effort=<effort> -s read-only \
  --ephemeral --ignore-user-config --skip-git-repo-check -C <repo> -o <out_dir>/codex_review.md - \
  < <out_dir>/codex_prompt.md > <out_dir>/codex.log 2>&1 &
```
Then wait for it with a background loop (`while kill -0 <pid>; do sleep 20; done`) so you are notified when
it ends. If the user asks to stop it, kill it and salvage its interim conclusions from `codex.log`: the lines
after each `codex` marker are its progress notes, and often already contain its main findings.

## 4. Claude's own review (while Codex runs)
Read `connections_by_part.txt` and `nets.txt` in full, then go block by block, checking against the datasheet
text (grep the big ones) and citing page/section:
1. **Symbols:** every pin number of every custom symbol vs the datasheet pinout; library symbols for parts with
   multiple package variants.
2. **Nets vs intent:** each net against the pin list and design doc; wrong or swapped pins, floating inputs,
   unused pins handled per datasheet (NC vs tie).
3. **Power:** input protection, charger settings (do the maths), battery connector polarity, regulator
   EN/caps/dropout/current budget, capacitance limits on rails (regulator Cout max, USB VBUS 10 µF), any pin
   that can see a rail above its absolute maximum, back-powering paths, sequencing.
4. **MCU:** supply mode, crystal load caps (show maths), reset, debug, USB, GPIO restrictions (low-frequency
   or high-drive pins), every GPIO's voltage.
5. **Each peripheral:** pull-ups/downs and their default state at reset, decoupling, address/strap pins
   (internal pull-ups tied low waste current), switch FET orientation and Vgs(th), LED currents from Vf
   (show maths), coil loads (flyback diode orientation, voltage rating, stuck-on current), bus rise time
   (pull-up × bus capacitance), shared lines.
6. **Standby budget:** leakage paths and parts that need a firmware state to reach their low-power current.
7. **ERC:** explain every message; distinguish real errors from false positives.
8. **BOM ↔ schematic:** references, values, quantities, DNP parts, designator collisions.

Then the **senior engineer pass**: the questions an experienced reviewer asks that a connection check misses.
9. **Faults, not just normal operation.** For every rail, ask "if any part on this rail shorts, what limits
   the current?" A regulator output has a current limit; a battery rail usually has nothing but the pack's own
   protection circuit. Work out the fault current case by case and, where nothing limits it, recommend a
   suitably rated protection device (often a resettable PTC fuse at the battery connector, sized for the peak
   load), and confirm the battery has a protection circuit. For every series resistor and switch, compute the power in a single fault (shorted
   load, switch stuck on): P = V² / R at the highest rail voltage, against the part's rating.
10. **Worst-case margins.** Do the headroom maths at the corners, not the typical point: empty battery (and
   the regulator in dropout), full battery, worst-case LED forward voltage, minimum logic-high voltages.
11. **Readable by someone else.** Report every result from `junction_check.py`; wires that cross near a
   junction; labels that could be misread; PWR_FLAG placement explained. A reviewer who can't follow the
   drawing will (rightly) question it, even when the netlist is correct.
12. **Anything a person touches or plugs in:** ESD on buttons and connectors, USB input protection,
   connector polarity marking.
13. **Defend every choice.** For each judgement call (which rail a load uses, firmware vs hardware debounce,
   pull-up values, load caps), write the one-line reason and the trade-off, so the user can answer a reviewer.

Write findings to `<out_dir>/claude_review.md` in the same format as Codex.

## 5. Compare, verify, debate
- Match findings into **found by both**, **Codex only**, **Claude only**.
- Verify every Codex-only finding yourself against the datasheet text or netlist before accepting it. Codex can
  be confidently wrong (it has invented pinouts before); mark each as confirmed, disputed (say why), or unclear.
- If there are real disagreements worth settling, offer a short second Codex round at lower effort that sees
  only the disputed items and both positions. Ask before spending credits on it.

## 6. Report to the user
A short summary (verdict, counts by severity, which models and effort were used), then three tables, most
severe first: Found by both / Codex only (verified) / Claude only. Each row: severity, finding in plain words,
evidence, suggested fix. Then a short "Checked and OK" list so the user sees the coverage. Save the merged
report as `<out_dir>/combined_review.md`.

Add a **"Questions a reviewer will ask"** section: for each judgement call from item 13, the likely question and
a plain-language answer the user can give, with the numbers behind it.

Finish by separating **hardware changes** from **firmware rules / documentation**, and ask which to apply.
Do not edit the schematic, symbols, BOM or pin list until the user agrees. When fixes are applied, re-run the
netlist and ERC to verify, and update the BOM/pin list with the reason for each change.