kicad

Files (82)

• SKILL.md
• config-reference.md · references/
• datasheet-verification.md · references/
• deep-review.md · references/
• design-intent.md · references/
• diff-analysis.md · references/
• file-formats.md · references/
• gerber-parsing.md · references/
• manual-gerber-parsing.md · references/
• manual-pcb-parsing.md · references/
• manual-schematic-parsing.md · references/
• net-tracing.md · references/
• oshwa-certification.md · references/
• output-schema.md · references/
• pcb-layout-analysis.md · references/
• pdf-schematic-extraction.md · references/
• report-generation.md · references/
• schematic-analysis.md · references/
• standards-compliance.md · references/
• supplementary-data-sources.md · references/
• what-if.md · references/
• README.md · review/
• deep_review.example.json · review/fixtures/
• design_context.example.json · review/fixtures/
• review_annotations.example.json · review/fixtures/
• design_context.md · review/prompts/
• deep_review.schema.json · review/schemas/
• design_context.schema.json · review/schemas/
• review_annotations.schema.json · review/schemas/
• _mini_jsonschema.py · review/scripts/
• build_review_plan.py · review/scripts/
• deep_review_gate.py · review/scripts/
• merge_annotations.py · review/scripts/
• run_phase4_exercise.py · review/scripts/
• validate_review.py · review/scripts/
• .gitignore · scripts/
• README.md · scripts/
• analysis_cache.py · scripts/
• analyze_gerbers.py · scripts/
• analyze_pcb.py · scripts/
• analyze_schematic.py · scripts/
• analyze_thermal.py · scripts/
• analyzer_envelope.py · scripts/
• bus_resolver.py · scripts/
• capability_mode.py · scripts/
• check_report_sections.py · scripts/
• cross_analysis.py · scripts/
• cross_verify.py · scripts/
• detection_schema.py · scripts/
• detector_helpers.py · scripts/
• diff_analysis.py · scripts/
• domain_detectors.py · scripts/
• __init__.py · scripts/envelopes/
• cross_analysis.py · scripts/envelopes/
• gerber.py · scripts/envelopes/
• pcb.py · scripts/envelopes/
• schematic.py · scripts/envelopes/
• thermal.py · scripts/envelopes/
• export_issues.py · scripts/
• fab_release_gate.py · scripts/
• …and 22 more

SKILL.md (first lines)

# KiCad Project Analysis Skill

## Related Skills

| Skill | Purpose |
|-------|---------|
| `bom` | BOM extraction, enrichment, ordering, and export workflows |
| `digikey` | Search DigiKey for parts (prototype sourcing) |
| `mouser` | Search Mouser for parts (secondary prototype source) |
| `lcsc` | Search LCSC for parts (production sourcing, JLCPCB) |
| `element14` | Search Newark/Farnell/element14 (international sourcing, reliable datasheets) |
| `jlcpcb` | PCB fabrication & assembly ordering |
| `pcbway` | Alternative PCB fabrication & assembly |
| `spice` | SPICE simulation verification of detected subcircuits |
| `emc` | EMC pre-compliance risk analysis — consumes schematic + PCB analyzer output |

**Handoff guidance:** Use this skill to parse schematics/PCBs and extract structured data. Hand off to `bom` for BOM enrichment, pricing, and ordering. Hand off to `digikey`/`mouser`/`lcsc`/`element14` for part searches and datasheet fetching. Hand off to `jlcpcb`/`pcbway` for fabrication ordering and DFM rule validation. **Always run `spice`** for simulation verification during design reviews when any SPICE simulator is installed (check with `which ngspice ltspice xyce`). **Always run `emc`** for EMC pre-compliance risk analysis during design reviews when both schematic and PCB analysis are available. These are not optional — skipping them leaves value-computation errors and EMC risks undetected.

**Before analysis:** When the user asks to analyze or review a KiCad project, check whether a `datasheets/` directory exists in the project. If not, and DigiKey API keys are available (`DIGIKEY_CLIENT_ID`), offer to sync datasheets first: "I can download datasheets for your components before analysis — this enables pin-level verification and decoupling validation against manufacturer specs. Want me to sync them?" If the user declines or no API keys are set, proceed without datasheets — the analysis works without them but datasheet verification findings won't be available.

**If you see a `DS-001` finding in the analyzer output** (severity `high`, detector `audit_datasheet_coverage`), the review cannot make any verified claim. Stop and either (a) run the datasheet sync via `digikey` / `mouser` / `lcsc` / `element14` (whichever has credentials/stock), (b) populate MPNs on the BOM parts, or (c) state explicitly in the report that every pin-level, electrical, and regulator finding is *consistency only* — do not use the words "verified", "confirmed", or "per datasheet" anywhere. `DS-002` (datasheets missing but MPNs set) and `DS-003` (partial MPN coverage) are softer variants with the same implication for the parts they cite.

## Design Review Contract

When the user asks for a **design review**, **complete report**, **ready-to-fab assessment**, or anything equivalent, do not stop at running one or two analyzers and summarizing their findings. A design review in this skill has a stricter contract:

1. Read the full workflow in this `SKILL.md`, not just the analyzer command sections.
2. Read `references/report-generation.md` before writing the report.
3. Run every applicable analyzer for the files present in the project, then say explicitly which ones were and were not run.
4. Perform raw-file and datasheet cross-verification before claiming anything is "verified".
5. Triage likely analyzer false positives before elevating them into blockers.
6. If a required step could not be done, state it as a review gap, not as silent omission.

Treat this as the minimum bar. Analyzer JSON alone is not the final review.

### Minimum Review Checklist

For a full design review, explicitly account for each item below in the report:

- `datasheets/` present, synced, or verification gap stated
- `analyze_schematic.py`
- `analyze_pcb.py --full`
- `cross_analysis.py`
- `analyze_emc.py`
- SPICE simulation when any simulator is installed
- `analyze_thermal.py` when both schematic and PCB JSON exist
- `analyze_gerbers.py` when fabrication outputs exist
- lifecycle audit when network access and MPN coverage allow it
- prior review / prior run delta check
- raw schematic/PCB spot-verification elevated to full verification for critical parts
- explicit report sections for blockers, verification basis, false positives, and skipped analyses

If an item is not applicable, say why. If it was skipped, say why. If it failed, say how that limits confidence.

### Common Review Failure Modes

These are the failure modes this contract is meant to prevent:

- Stopping after schematic + PCB + EMC output and calling it a complete review
- Reporting analyzer findings without checking whether they are expected layout artifacts
- Claiming "verified" without direct datasheet evidence or structured extraction evidence
- Omitting thermal, lifecycle, prior-review delta, or gerber checks without disclosure
- Writing a report that lacks a verdict, blockers table, verification basis, or skipped-analysis notes
- Reading only the first part of this skill and missing the design-review workflow later in the file

## PDF Schematic Analysis

This skill also handles **PDF schematics** — reference designs, dev board schematics, eval board docs, application notes, and datasheet typical-application circuits. Common use cases:

- Analyze a manufacturer's reference design to understand the circuit
- Extract a subcircuit (power supply, USB interface, sensor front-end) to incorporate into your own KiCad design
- Compare a PDF reference design against your own schematic
- Extract a full BOM from a PDF schematic
- Validate component values in a PDF against current datasheets

**Workflow:** Read the PDF pages visually → identify components and connections → extract structured data → translate to KiCad symbols and nets → validate against datasheets.

For the full methodology — component extraction, notation conventions, net mapping, subcircuit extraction, KiCad translation, and validation — read `references/pdf-schematic-extraction.md`.

For deep validation of extracted circuits against datasheets (verifying values, checking patterns, detecting errors), use the methodology in `references/schematic-analysis.md`.

## Analysis Scripts

This skill includes Python scripts that extract comprehensive structured JSON from KiCad files in a single pass. Run these first, then reason about the output.

Read analyzer JSON output directly rather than writing ad-hoc extraction scripts. The JSON schema has specific field names (documented below and in `references/output-schema.md`) that are easy to get wrong in custom code. To extract a specific section: `python3 -c "import json; d=json.load(open('file.json')); print(json.dumps(d['key'], indent=2))"`.

**When the JSON surprises you** — an AttributeError, unexpected shape, field
returning `None` that "should" have a value — stop and run `--schema` before
writing a second extraction attempt. It prints the exact field names and
types for every top-level key:

```bash
python3 <skill-path>/scripts/analyze_schematic.py --schema
python3 <skill-path>/scripts/analyze_pcb.py --schema
python3 <skill-path>/scripts/analyze_gerbers.py --schema
```

**JSON field cheat sheet** — the most common mistakes when reading analyzer
output by hand:

| What you want | Correct path and field | Common mistake |
|---------------|-----------------------|----------------|
| Pins on a net | `nets[<name>].pins[].component / .pin_number / .pin_name / .pin_type` | `ref`, `pin`, `type`, `number` |
| Unnamed-net pretty display | `nets[<name>].display_name` — when set, a `Ref.PinName` hint for an `__unnamed_N` net whose only named IC pin tells the story (e.g. `__unnamed_36 → U1.VBOOT`). Absent means the analyzer couldn't disambiguate. | Ignoring `display_name` and pasting raw `__unnamed_36` into the report |
| IC pin map | `ic_pin_analysis[]` is a **list** of IC entries; each has `.reference` and `.pins[]` with `.pin_number / .pin_name / .pin_type / .net / .connected_to[]`. Scope: `type` in `{ic, connector, crystal, oscillator}` only. | Treating it as `{ref: {...}}` or `pins[].number` |
| Transistor pin map | `transistor_pin_analysis[]` — **separate** list for `type=transistor` (MOSFETs, BJTs, FETs), same per-entry shape as `ic_pin_analysis[]`. Use this for half-bridge / gate-driver pin verification. | Looking inside `ic_pin_analysis[]` for `Q1` — transistors are not there |
| Detected circuits | Every pattern-matched circuit (power regulators, RC filters, crystal oscillators, bridges, …) lives in `findings[]` — filter with `finding_schema.get_findings(data, Det.POWER_REGULATORS)` etc. **Do not read from `subcircuits[]`**: that's an IC-neighborhood grouping (`{center_ic, ic_value, neighbor_components, …}`), not a categorized detection index | Looking for `subcircuits.power_regulators`, `subcircuits.rc_filters`, or any `subcircuits[type]` key — these never existed in v1.3 output |
| Zone net | `pcb.zones[].net` is an **integer net ID**, not a string. Use `f"{net!r}"` or convert first | `f"{net:20s}"` — crashes with `ValueError: Unknown format code 's' for object of type 'int'` |
| Zone layer | `pcb.zones[].layers` (plural) is the canonical layer list. `zones[].layer` (singular) is reserved/None on multi-layer zones — always read `.layers`. | Reading `zones[].layer` and getting `None` |
| Footprint position | `pcb.footprints[].x / .y` at top level (no `.position` wrapper) | `footprints[].position.x` |
| Per-pad net info on a footprint | `pcb.footprints[].pad_nets{pad_number: {net, pin}}` is a dict keyed by pad number. `connected_nets[]` gives the deduped list of nets touching the footprint. | `footprints[].pads[]` — that key does not exist in the output |
| Tracks summary | `pcb.tracks` is a **dict** (the `Tracks` envelope): `{segment_count, arc_count, layer_distribution{}, width_distribution{}}`. Only `--full` populates the inner `tracks.segments[]` and `tracks.arcs[]` arrays. Segment fields: `{x1, y1, x2, y2, width, layer, net}` — `net` is an **int** id (map via top-level `nets` / `net_name_to_id`). | `for t in tracks: ...` without `--full` — `tracks` is the summary dict, not a list; `seg.get("x")` / `seg.get("start")` — wrong keys, and `.get()` defaults turn them into silent-0.0 bugs |
| Power net routing | `pcb.power_net_routing` is a **list** of per-net entries `[{net, track_count, total_length_mm, ...}, ...]`, not a dict keyed by net. | `power_net_routing["VCC"]` → TypeError |
| Findings | `findings[]` flat list — each has `rule_id`, `detector`, `severity`, `summary`, `report_context`. Filter with `finding_schema.get_findings(data, Det.*)` or `group_findings(data)` | Looking for keyed dicts like `signal_analysis.power_regulators[]` (pre-v1.3 format, removed) |

This prevents format-string bugs and wrong field names. Use f-strings or `json.dumps()` for output formatting — never `%s` with non-string types. See `references/output-schema.md` for the full schema with common extraction patterns.

In all commands below, `<skill-path>` refers to this skill's base directory (shown at the top of this file when loaded).

From aklofas/kicad-happy, MIT.

More from aklofas/kicad-happy