name	kicad
description	>-

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:

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).

Schematic Analyzer

python3 <skill-path>/scripts/analyze_schematic.py <file.kicad_sch> --analysis-dir analysis/
python3 <skill-path>/scripts/analyze_schematic.py <file.kicad_sch> --analysis-dir analysis/ --compact
python3 <skill-path>/scripts/analyze_schematic.py <file.kicad_sch> --output analysis.json  # one-off, no cache

Outputs structured JSON (~60-220KB depending on board complexity) with:

• Components & BOM: inventory with reference, value, footprint, lib_id, type classification, MPN, datasheet; deduplicated BOM with quantities
• Nets: full connectivity map with pin-to-net mapping, wire counts, no-connects
• Detected subcircuits (pattern-matched circuits — all emitted as findings[] entries with matching Det.* detectors; use get_findings(data, Det.POWER_REGULATORS) etc. to fetch):
  • Power regulators — LDO/switching/inverting topology, Vout estimation via datasheet-verified Vref lookup (~60 families) with heuristic fallback and fixed-output suffix parsing, vref_source (lookup/heuristic/fixed_suffix) and vout_net_mismatch fields
  • Voltage dividers, RC/LC filters (cutoff frequency), feedback networks, crystal circuits (load cap analysis, IC pin-based detection)
  • Op-amp circuits (configuration, gain, integrator/compensator), transistor circuits (net-name-aware load classification: motor/heater/fan/solenoid/valve/pump/relay/speaker/buzzer/lamp; FET level shifter topology)
  • Bridge circuits (H-bridge, 3-phase, cross-sheet detection), protection devices (ESD/TVS), current sense, decoupling analysis
  • Domain-specific: RF chains, RF matching networks, BMS, Ethernet (BFS PHY-to-connector tracing), HDMI/DVI interfaces, memory interfaces, key matrices (net-name and topology-based), isolation barriers, addressable LED chains (WS2812/SK6812/APA102), battery chargers (TP4056/MCP73831/BQ2404x), motor drivers (A4988/TMC2209/DRV8301), ESD protection coverage audit, debug interfaces (SWD/JTAG with MCU tracing), power path (load switches/ideal diodes/USB PD controllers), ADC signal conditioning (external ADCs + voltage references with anti-aliasing cross-ref), reset/supervisor circuits (voltage supervisors/watchdogs/RC reset networks), clock distribution (clock generators/PLLs/oscillator output tracing), display/touch interfaces (SSD1306/ILI9341/ST7789/FT6236/GT911), sensor fusion (IMU/environmental/magnetometer with interrupt validation and bus clustering), level shifters (IC-based + discrete BSS138 with supply domain mapping), audio circuits (amplifiers/codecs with I2S/class-D detection), LED driver ICs (PWM/matrix/constant-current), RTC circuits (battery backup/crystal pairing), LED lighting audit (current limiting validation), thermocouple/RTD interfaces (MAX31855/MAX31865), power sequencing validation (power tree/enable chain/PG daisy chain analysis)
• IC pinout analysis: pin-level connectivity, IC function classification (3-tier: library prefix, part number keywords, description fallback)
• Power analysis: PDN impedance (1kHz–1GHz with MLCC parasitics), power budget, power sequencing (EN/PG chains), sleep current audit (resistive paths + regulator Iq with EN detection), voltage derating, inrush estimation
• Design analysis: ERC warnings, power domains, bus detection (I2C/SPI/UART/CAN/RS-485 with COPI/CIPO/SDI/SDO), differential pairs (suffix-pair matching for USB/LVDS/Ethernet/HDMI/MIPI/PCIe/SATA/CAN/RS-485), cross-domain signals (voltage equivalence), BOM optimization, test coverage, assembly complexity, USB compliance
• Quality checks: annotation completeness, label validation, PWR_FLAG audit, footprint filter validation, sourcing audit, property pattern audit, generic transistor symbol detection (flags Q_NPN_*/Q_PNP_*/Q_NMOS_*/Q_PMOS_* symbols with datasheet availability check)
• Structural: MCU alternate pin summary, ground domain classification, bus topology, wire geometry, spatial clustering, pin coverage, hierarchical label validation

Supports modern .kicad_sch (KiCad 6+) and legacy .sch (KiCad 4/5). Hierarchical designs parsed recursively.

Legacy format: For KiCad 5 legacy .sch files, the analyzer parses .lib files (cache libraries and project libs) to populate pin data. Pin-to-net mapping, signal analysis, and subcircuit detection all work when .lib files are available. Coverage is typically 92–100% — components whose .lib files are missing (standard KiCad system libs not in the repo) will lack pin data. Built-in fallbacks cover 40+ common symbols (R, C, L, D, LED, transistors, MOSFETs, crystals, switches, polarized caps, connectors up to 20-pin, resistor packs) with mil-based pin offsets and automatic wire-snap correction for version-mismatched pin positions.

Supplementary Data for Legacy Designs

When analyze_schematic.py returns incomplete data (components with missing pins due to unavailable .lib files), use additional project files to recover full analysis capability. The most valuable source is the .net netlist file, which provides explicit pin-to-net mapping that closes any remaining gaps.

For detailed parsing instructions, data recovery workflows, and a priority matrix of supplementary sources (netlist, cache library, PCB cross-reference, PDF exports), read references/supplementary-data-sources.md.

Verify analyzer output against reality. The analyzer can silently produce plausible-looking but incorrect results — wrong voltage estimates, missing MPNs, wrong pin-to-net mappings. These don't cause script errors; they just produce bad data that flows into your report. In testing across multiple boards, every project had at least one misleading analyzer output. Cross-reference against the raw .kicad_sch file:

1. Component count — grep for (symbol (lib_id blocks, subtract power symbols. Must match analyzer count exactly.
2. Pin-to-net mapping — verify the analyzer's pin-to-net mapping against the raw schematic for each component. Read the symbol block, trace wires/labels to confirm connections. Cross-reference IC pin assignments against the manufacturer's datasheet pin table. This is the highest-value verification step — a wrong pin mapping produces a non-functional board and is invisible to DRC/ERC.
3. Physical correctness (not just consistency) — consistency checks (schematic=PCB=analyzer all agree) are necessary but not sufficient. They only confirm the design is internally coherent — not that it matches the real-world part. The most dangerous case: a transistor symbol encodes a pinout assumption (like Q_NPN_BEC = pin 1=B, 2=E, 3=C) that doesn't match the actual part. Everything passes consistency checks, but the board is wrong. To catch this:
   • For transistors (BJT/MOSFET) in SOT-23, SOT-223, TO-252 and similar packages, the KiCad lib_id suffix encodes a pin ordering assumption. SOT-23 BJTs exist in at least 6 pinout variants (BEC, BCE, EBC, ECB, CBE, CEB); SOT-23 MOSFETs in GDS, GSD, SGD, DSG. If no MPN is specified, there's no way to verify the assumption — flag this as a critical ambiguity.
   • When an MPN is specified, verify the symbol's pin-to-pad assignment against the datasheet's pinout diagram for that specific package.
   • This principle extends beyond transistors — any component where multiple pin orderings exist for the same package (voltage regulators with different pin assignments, connectors with vendor-specific pinouts) needs MPN-level verification.
   • When verification isn't possible, assess plausibility. Not all unverified choices carry equal risk. Some align with strong conventions (the most common SOT-23 NPN pinout is BCE; 2N2222 in SOT-23 is almost always BCE); others go against convention or are genuinely ambiguous (SOT-23 MOSFETs have no dominant standard). When an MPN is missing and you can't verify, use domain knowledge — typical pinouts for that device type and package, manufacturer conventions, what the majority of parts in that category do — to assess whether the assumed pinout is likely correct, unusual, or a coin flip. Report the confidence level: "matches the most common convention" is different from "could go either way." This same reasoning applies to passive values (is 4.7kΩ a typical pull-up value for this bus?), circuit topologies (is this a standard application circuit?), and component selection (is this part commonly used for this purpose?).
4. Net trace — trace power rails and critical signal nets end-to-end through wires/labels. Verify the analyzer's pin list is complete for each net.
5. Regulator Vout — check the vref_source field. "lookup" means datasheet-verified (~60 families); "heuristic" means it's a guess that needs manual verification. The vout_net_mismatch field flags estimated Vout differing >15% from the output rail name voltage.
6. Hierarchical connectivity — on multi-sheet designs, verify sub-sheet connections are reflected in the net data.

See references/schematic-analysis.md Step 2 for the full verification checklist. If the script fails or returns unexpected results, see references/manual-schematic-parsing.md for the complete fallback methodology.

PCB Layout Analyzer

python3 <skill-path>/scripts/analyze_pcb.py <file.kicad_pcb> --analysis-dir analysis/
python3 <skill-path>/scripts/analyze_pcb.py <file.kicad_pcb> --analysis-dir analysis/ --proximity  # add crosstalk analysis
python3 <skill-path>/scripts/analyze_pcb.py <file.kicad_pcb> --output pcb.json --schematic analysis/schematic.json  # one-off; cross-ref + power-rail auto-detect

Outputs structured JSON (~50-300KB depending on board complexity) with:

• Core: footprint inventory (pads, courtyards, net assignments, extended attrs, schematic cross-reference), track/via statistics, zone summaries, board outline/dimensions, routing completeness
• Zones & copper presence: zone outline vs filled polygon bounding boxes, fill ratio, cross-layer copper presence at every pad (which components have zone copper on the opposite layer and which don't), same-layer foreign zone detection
• Via analysis: type breakdown (through/blind/micro), annular ring checks, via-in-pad detection, BGA/QFN fanout patterns, current capacity, stitching via identification, tenting
• Signal integrity: per-net trace length, layer transition tracking (ground return paths), trace proximity/crosstalk (with --proximity)
• Power & thermal: current capacity per net, power net routing summary, ground domain identification (AGND/DGND), zone stitching via density, thermal pad detection and via counting
• Manufacturing: placement analysis (courtyard overlaps, edge clearance), decoupling cap distances, DFM scoring (JLCPCB standard/advanced tier), tombstoning risk (0201/0402 thermal asymmetry), thermal pad via adequacy, silkscreen documentation audit

Add --full to include individual track/via coordinates, per-segment trace impedance (microstrip Z0 from stackup), pad-to-pad routed distances, return path continuity analysis, and via stub lengths. The --full output feeds the spice skill's parasitic extraction (extract_parasitics.py) for PCB-aware simulation. Supports KiCad 5 legacy format.

Zone fills must be current. The copper presence analysis uses KiCad's filled polygon data, which is computed when the user runs Edit → Fill All Zones (shortcut B) and stored in the .kicad_pcb file. If the board was modified after the last fill, the filled polygon data may be stale and the copper presence results will be inaccurate. When reviewing copper presence data, note whether the fill_ratio seems reasonable — a zone with 0 filled area or is_filled: false likely hasn't been filled.

Zone outline ≠ actual copper. The zone outline_bbox is the user-drawn boundary; filled_bbox is where copper actually exists after clearances, keepouts, and priority cuts. The copper_presence section shows which components have zone copper on the opposite layer — use this for capacitive touch pad isolation, antenna keep-out, and thermal analysis instead of inferring copper presence from zone outlines.

Copper-sensitive components need deeper checks. For capacitive touch pads and antennas, confirming "no opposite-layer copper" is necessary but not sufficient. The copper absence could be accidental — one zone refill after a routing change could add copper and kill touch sensitivity or detune the antenna. Check for explicit keepout zones (rule areas) that enforce the copper-free area as a DRC rule. Also measure same-layer GND clearance around touch pads and compare against the controller's app note minimum. For touch pads, compare trace lengths across all pads — significant asymmetry shifts baseline readings per channel. Report physical details (pad size, position, clearance, trace width/length) for all copper-sensitive components. See references/pcb-layout-analysis.md → Copper-Sensitive Components for the full checklist.

Verify after every run: Confirm footprint count and board outline dimensions against the raw .kicad_pcb file. Verify pad-to-net assignments for IC footprints against the schematic's pin-to-net mapping — this catches library footprint errors where pad numbering doesn't match the symbol pinout. If the script fails, see references/manual-pcb-parsing.md for the fallback methodology.

PCB Rich Format and Assembly Checks

All PCB analysis sections now produce findings with the rich format (detector, rule_id, category, severity, confidence, summary, recommendation, report_context). Additionally, 7 new assembly/DFM checks run automatically:

• FD-001: Fiducial marker presence (>= 3 per SMD side)
• TE-001: Test point coverage across signal nets
• OR-001: Passive component orientation consistency
• SK-001: Silkscreen text overlapping exposed pads
• VP-001: Via-in-pad without tenting (--full mode)
• BV-001: Via clearance from board edges (--full mode)
• KO-001: Keepout zone violations
• CP-001: Same-layer foreign zone under a component. Severity is warning when the foreign zone is a non-ground net or the component has no GND pad; severity is info when the foreign zone is GND and the component has a GND pad (the common case of a bypass cap sitting over the ground pour — expected layout, not a clearance issue).

Cross-Domain Analysis

After running both schematic and PCB analyzers, run the cross-domain analyzer. Point --schematic and --pcb at the current run's JSON files and pass --analysis-dir analysis/ so the result lands inside the same run folder and the manifest tracks it:

# Recommended: integrate into the current run
python3 <skill-path>/scripts/cross_analysis.py \
    --schematic analysis/<run_id>/schematic.json \
    --pcb analysis/<run_id>/pcb.json \
    --analysis-dir analysis/

# One-off (bypasses the cache)
python3 <skill-path>/scripts/cross_analysis.py \
    --schematic schematic.json --pcb pcb.json --output cross_analysis.json

Checks: CC-001 connector current capacity, EG-001 ESD protection gaps, DA-001 decoupling adequacy, XV-001..003 schematic/PCB sync. PCB JSON optional.

Mechanical cross-verify (PCB vs schematic geometry): python3 <skill-path>/scripts/cross_verify.py --help.

Connectivity Graph (--full mode)

When --full is used with the PCB analyzer, the output includes a connectivity_graph section with per-net copper connectivity analysis via union-find over pads, tracks, vias, and zone fills. This enables deterministic plane split detection and return path validation in cross_analysis.py. The top-level keys of connectivity_graph are net names themselves — e.g., cg['GND'], cg['Net-(D2-K)'], cg['+3V3'] — not a per_net wrapper. Each net entry shows island count, component-to-island mapping ({component:pad: island_id}), gap locations, and disconnected pad pairs.

Gerber & Drill Analyzer

# Recommended: integrate into the current run
python3 <skill-path>/scripts/analyze_gerbers.py <gerber_directory/> --analysis-dir analysis/

# One-off
python3 <skill-path>/scripts/analyze_gerbers.py <gerber_directory/> --output gerber.json

Outputs: layer identification (X2 attributes), component/net/pin mapping (KiCad 6+ TO attributes), aperture function classification, trace width distribution, board dimensions, drill classification (via/component/mounting), layer completeness, alignment verification, pad type summary (SMD/THT ratio). Add --full for complete pin-to-net connectivity dump. ~10KB JSON.

The gerber analyzer produces a findings list with rich format findings: GR-001 missing layers, GR-002 alignment issues, GR-003 drill problems, GR-004 paste aperture mismatches, GR-005 open board outlines.

If the script fails or returns unexpected results, see references/manual-gerber-parsing.md for the complete fallback methodology for parsing raw Gerber/Excellon files directly.

All scripts output JSON to stdout by default. Prefer --analysis-dir analysis/ to integrate output into the run-folder convention described in "Analysis Cache Convention" below — every analyzer in a single session then co-locates inside the same analysis/<run_id>/ folder and is tracked by the manifest. Use --output file.json only for one-off runs where you don't want the result cached. Add --compact for single-line JSON.

Analyzer JSON is worth keeping — these are expensive to regenerate (large schematics take time). --analysis-dir preserves every run and is the form downstream tools (diff_analysis, what_if) expect. They're not worth committing to git, but don't delete them between analysis steps.

Harmonized Output Format

All analyzers produce a uniform output envelope:

{
    "analyzer_type": "schematic|pcb|emc|cross_analysis|thermal|gerber|lifecycle|spice",
    "schema_version": "1.4.0",
    "summary": {
        "total_findings": 42,
        "by_severity": {"error": 3, "warning": 15, "info": 24}
    },
    "findings": [
        {"rule_id": "...", "detector": "...", "severity": "...", "confidence": "...", "evidence_source": "...", "summary": "...", ...}
    ],
    "trust_summary": {
        "total_findings": 42,
        "trust_level": "high|mixed|low",
        "by_confidence": {"deterministic": 20, "heuristic": 18, "datasheet_backed": 4},
        "by_evidence_source": {"datasheet": 4, "topology": 10, "heuristic_rule": 18, ...},
        "provenance_coverage_pct": 96.5
    }
}

The findings list is the single authoritative source for all findings. Use finding_schema.get_findings() or finding_schema.group_findings() to filter by detector, rule prefix, or category. Detector names are available as constants in finding_schema.Det. Severities are error, warning, or info; confidence is deterministic, heuristic, or datasheet-backed.

All analyzers support --text for human-readable output, --analysis-dir for integrated run-folder output (preferred), and --output for writing to a specific file verbatim (one-off). When both are passed, the explicit --output path wins — pick one form per invocation.

Stage and Audience Filtering

All analyzers support --stage and --audience flags:

Stages: schematic, layout, pre_fab, bring_up Audiences: designer (default), reviewer, manager

# Show only layout-relevant findings for a reviewer
python3 <skill-path>/scripts/analyze_pcb.py board.kicad_pcb --stage layout --audience reviewer --text

# Manager summary of schematic review readiness
python3 <skill-path>/scripts/analyze_schematic.py design.kicad_sch --audience manager --text

# Pre-fab checklist for cross-domain analysis
python3 <skill-path>/scripts/cross_analysis.py -s sch.json -p pcb.json --stage pre_fab --text

JSON output always includes all findings. --stage adds stages and in_active_stage fields to each finding plus a stage_filter summary. audience_summary is always computed with designer/reviewer/manager views. --text output respects both flags.

Generated Files

Analysis outputs are stored in analysis/ with timestamped run folders managed by analysis_cache.py. The manifest (analysis/manifest.json) tracks all runs.

File Type	Location	Regenerable?	Commit to git?
Analyzer JSON	analysis/<timestamp>/*.json	Yes (expensive)	Configured by track_in_git in .kicad-happy.json (default: no)
Manifest	analysis/manifest.json	Yes	Always (tracked by default)
Design review report	User-chosen path	Yes	Optional

When creating design reviews, check the manifest for prior runs. If auto_diff is enabled and prior runs exist, automatically diff current vs previous using diff_analysis.py and include the delta in the "Previous Review Delta" section.

See also the bom skill's cleanup section for datasheets, order CSVs, and backups.

Analysis Cache Configuration

The analysis section in .kicad-happy.json controls the shared analysis output directory:

{
  "analysis": {
    "output_dir": "analysis",
    "retention": 5,
    "auto_diff": true,
    "track_in_git": false,
    "diff_threshold": "major"
  }
}

Field	Default	Description
output_dir	"analysis"	Analysis directory path, relative to project root
retention	5	Max unpinned runs to keep. 0 = unlimited
auto_diff	true	Auto-include delta section in design reviews
track_in_git	false	When false, JSONs gitignored but manifest tracked
diff_threshold	"major"	Severity that triggers new timestamped folder: minor, major, breaking

All fields are optional. Missing fields use defaults.

Output JSON Schema Quick Reference

Schematic analyzer top-level keys:

analyzer_type, schema_version, summary, findings, trust_summary,
file, kicad_version, file_version, title_block, statistics,
bom, components, nets, subcircuits, ic_pin_analysis, transistor_pin_analysis,
design_analysis, connectivity_issues, hierarchy_context, hierarchy_warning, net_classifications, rail_voltages

Optional (present when non-empty): pdn_impedance, sleep_current_audit, power_budget, power_sequencing, bom_optimization, test_coverage, assembly_complexity, usb_compliance, inrush_analysis, sheets (multi-sheet only), missing_info, bom_lock, project_settings

Key nested structures:

• statistics: {total_components, unique_parts, dnp_parts, total_nets, total_wires, total_no_connects, component_types, power_rails, missing_mpn, ...}
• bom[]: {reference, references[], value, footprint, mpn, manufacturer, datasheet, quantity, dnp, ...}
• components[]: {reference, value, footprint, lib_id, lib_name, type, category, mpn, datasheet, dnp, in_bom, parsed_value, ...}
• nets{net_name}: {pins[], wires, labels[], ...} — each pin: {component, pin_number, pin_name, pin_type, ...} (NOT ref or pin)
• subcircuits[]: IC-neighborhood groupings ({center_ic, ic_value, neighbor_components, ...}), NOT a categorized detection index — see the JSON field cheat sheet at the top of this file.
• Detected subcircuits live in findings[] — power regulators, voltage dividers, RC/LC filters, feedback networks, opamp/transistor/bridge/crystal circuits, current sense, decoupling, protection, buzzer/speaker, Ethernet/HDMI/memory interfaces, RF chains/matching, BMS, key matrices, isolation barriers, addressable LED chains, and design observations all emit as findings with matching Det.* detectors. Use get_findings(data, Det.POWER_REGULATORS) etc. to fetch them. The pre-v1.3 signal_analysis wrapper and its top-level detection lists are gone.

PCB analyzer top-level keys:

analyzer_type, schema_version, summary, findings, trust_summary,
file, kicad_version, file_version, statistics, layers, setup,
nets, net_name_to_id, board_outline, component_groups, footprints,
tracks, vias, zones, keepout_zones, connectivity, net_lengths

Optional: power_net_routing, decoupling_placement, ground_domains, layer_transitions, silkscreen, board_metadata, dimensions, groups, net_classes, dfm_summary, placement_density, copper_presence_summary, board_thickness_mm, trace_proximity (with --proximity). Sections previously at top level (thermal_analysis, thermal_pad_vias, tombstoning_risk, placement_analysis, current_capacity, copper_presence, dfm) are now in findings[]. With --full, the output also includes a connectivity_graph section (see "Connectivity Graph" above).

Key nested structures:

• net_lengths is a list (not dict): [{net, net_number, total_length_mm, segment_count, via_count, layers{}}, ...] sorted by length descending
• power_net_routing is a list: [{net, track_count, total_length_mm, min_width_mm, max_width_mm, widths_used[]}, ...]
• footprints[]: {reference, value, footprint, layer, pads[], sch_path, sch_sheetname, sch_sheetfile, connected_nets[], ...}
• statistics: {footprint_count, copper_layers_used, smd_count, tht_count, zone_count, via_count, routing_complete, ...}

Gerber analyzer top-level keys:

analyzer_type, schema_version, summary, findings, trust_summary,
directory, generator, layer_count, statistics, completeness, alignment,
drill_classification, pad_summary, board_dimensions, gerbers, drills

Workflow: When analyzing a KiCad project, scan the project directory for all available file types and run every applicable analyzer — not just the one the user mentioned. A complete analysis uses all the data available. Use --analysis-dir analysis/ on all analyzers to share a single run folder tracked by the manifest. For one-off runs without cache tracking, use --output file.json instead.

Before starting the workflow below for a design review: read references/report-generation.md. The report structure, verification basis rules, skipped-analysis disclosure, and false-positive triage expectations there are part of the review workflow, not optional polish added at the end.

1. Scan the project directory for .kicad_sch, .kicad_pcb, .kicad_pro, gerber directories, and .net/.xml netlist files.
2. Sync datasheets (see Datasheet Acquisition below) — this is a prerequisite for verification, not optional. Without datasheets, all subsequent verification is reduced to internal consistency checks — confirming the design agrees with itself, not that it's correct. Run the sync before reading any analyzer output. If sync fails or no API keys are available, use fallback methods (Datasheet property URLs, individual downloads via digikey skill, ask the user). If critical IC datasheets can't be obtained, note this prominently in the report as a verification gap.
3. Run the core analyzers. If the schematic exists, run analyze_schematic.py. If the PCB exists, run analyze_pcb.py --full. If gerbers exist, run analyze_gerbers.py. Run them in parallel when possible.
4. Run cross-domain analysis — when both schematic and PCB analysis exist, run cross_analysis.py --schematic sch.json --pcb pcb.json. This catches dangerous cross-domain bugs (connector current vs trace width, ESD gaps, decoupling adequacy, schematic/PCB sync).
5. Run EMC pre-compliance — when both schematic and PCB analysis exist, run python3 <emc-skill-path>/scripts/analyze_emc.py --schematic sch.json --pcb pcb.json (the script lives in the emc skill — not under this skill's <skill-path>). This is required during design reviews, not optional. The EMC skill runs 44 rule checks covering ground plane integrity, decoupling, switching harmonics, PDN impedance, diff pair skew, ESD paths, and more. Include results in the EMC section of the report.
6. Run SPICE simulation — first run which ngspice ltspice xyce. If any simulator is installed, SPICE is required before writing the report. Hand off to the spice skill: python3 <spice-skill-path>/scripts/simulate_subcircuits.py sch.json. This validates filter frequencies, divider ratios, opamp gains, and more against actual simulation results. SPICE takes <1 second on most boards and catches value-computation errors (wrong resistor ratio, wrong cap for cutoff frequency) that no static analyzer finds. If both schematic and PCB analysis exist, run python3 <spice-skill-path>/scripts/extract_parasitics.py pcb.json --output parasitics.json (needs the --full PCB JSON) and pass --parasitics parasitics.json — a path argument, not a bare flag — for high-impedance circuits (>100K feedback dividers, LC filters, RF matching networks). Include results in the Simulation Verification section of the report. Output schema: top-level keys are summary, simulation_results, workdir, total_elapsed_s, simulator. Each entry in simulation_results[] has: subcircuit_type, components (list of refs, e.g. ["R5", "C3"]), reference (joined refs, e.g. "R5/C3"), status (pass/warn/fail/skip), expected (dict of metric values), simulated (dict of measured values), delta (dict of error percentages).
7. Run thermal analysis — when both schematic and PCB analysis exist, run analyze_thermal.py --schematic schematic.json --pcb pcb.json. Estimates junction temperatures from package θJA and board thermal via correction. Include results in the Thermal Hotspot section of the report.
8. Run lifecycle audit (when network access and MPNs are available) — invoke via analyze_schematic.py --lifecycle flag. Checks component obsolescence status via distributor APIs. Include results in the Component Lifecycle section of the report, or note "Lifecycle audit not performed — [reason: no API keys / no network / no MPNs]."
9. Read the .kicad_pro project file directly (it's JSON) for design rules, net classes, and DRC/ERC settings.
10. Check for prior design reviews — scan the project directory for existing review files (*review*.md, *design-review*.md). If found, read the most recent one. If auto_diff is enabled and prior runs exist, run diff_analysis.py on current vs previous run and include the delta in the "Previous Review Delta" section.
11. Verify each output against the raw files and datasheets before using the data in your report.
12. Produce a unified report covering schematic analysis, PCB layout analysis, cross-domain findings, EMC risk assessment, simulation verification, thermal hotspots, and cross-reference findings. See references/report-generation.md for the report template.
13. Disclose all review gaps explicitly — if thermal, lifecycle, gerber, datasheet extraction, or prior-review delta were not performed, add a short "Not performed / limits" section to the report instead of omitting them silently.

The more data sources you combine, the more confident the analysis. A schematic-only review misses layout issues; a PCB-only review misses design intent. Always use everything available.

Analysis Depth

Default to thorough analysis unless the user asks for a quick review. The reason: the bugs that kill boards are the ones that look correct at a glance. A spot-check might confirm 5 ICs are correct while the 6th has pins 3 and 4 swapped — and that's the one that kills the board. Thoroughness principles:

• Verify all components, not a sample. Pin-to-net errors on "simple" parts (reversed diode, wrong resistor in a divider, connector with wrong pin ordering) are just as fatal as swapped IC pins. Cover the full design.
• Use datasheets as ground truth — not KiCad library symbols. The analyzer, raw schematic, and KiCad library files all tell you what the design says — only the manufacturer's PDF datasheet tells you what it should say. A library symbol with a wrong pin mapping is the most dangerous class of bug precisely because everything is internally consistent: schematic, PCB, and analyzer all agree, but the board doesn't work. Verifying a pin assignment against the .kicad_sym file is circular — it's the source of the potential error. Download datasheets before starting verification (see "Datasheet Acquisition" below), open the actual PDF for each IC, extract the pin function table, and cite page/section numbers when reporting verification results.
• Assess plausibility, not just verifiability. When something can't be verified (missing MPN, missing datasheet), don't stop at "unverified." Use domain knowledge to assess whether the design choice aligns with common conventions or looks unusual. A 10kΩ I2C pull-up is unremarkable; a 100Ω I2C pull-up warrants a closer look even without a datasheet to check against. An SOT-23 NPN with BCE pinout matches the most common convention; one with CEB is unusual enough to flag. The goal is to distinguish "unverified but probably fine" from "unverified and suspicious." This applies to pinouts, passive values, circuit topologies, and component selection.
• Think beyond what the analyzer detects. The analyzer only finds patterns it's programmed for. When a section has no automated data, consider whether that's because the design doesn't need it (fine — say so briefly) or because the analyzer can't detect it (reason about it manually). Not every section needs a paragraph — "Not applicable: battery-powered, no mains input" is sufficient. But don't let empty data create blind spots in areas that matter for the specific design.

Datasheet Acquisition

Before the Deep Review pass, check availability: the extraction cache (datasheets/extracted/) is the fast path; PDFs on disk (datasheets/) are the fallback — read them directly. If parts have neither, offer to sync datasheets (digikey / lcsc / mouser / element14 skills) before reviewing without them. Extractions carry a quality flag — low-quality facts come back flagged, not hidden; decide whether to trust them or re-read the PDF.

Datasheets are what separate a consistency check from a correctness check. Without them, you can confirm the design agrees with itself — but not that it matches the real-world parts. Obtain datasheets early in the workflow.

Automated sync (preferred): Run datasheet sync scripts early in the workflow. They download datasheets for all components with MPNs into a shared datasheets/ directory with an manifest.json manifest. Run the preferred source first; if some parts fail, try others — they share the same directory and skip already-downloaded files.

python3 <digikey-skill-path>/scripts/sync_datasheets_digikey.py <file.kicad_sch>
python3 <lcsc-skill-path>/scripts/sync_datasheets_lcsc.py <file.kicad_sch>
python3 <element14-skill-path>/scripts/sync_datasheets_element14.py <file.kicad_sch>
python3 <mouser-skill-path>/scripts/sync_datasheets_mouser.py <file.kicad_sch>

DigiKey is best (direct PDF URLs). element14 is reliable (no bot protection). LCSC works for LCSC-only parts. Mouser is a last resort (often blocks downloads).

Check for existing datasheets: Before downloading, look for:

• <project>/datasheets/ with manifest.json (from a previous sync)
• <project>/docs/ or <project>/documentation/
• PDF files in the project directory whose names contain MPNs
• Datasheet property URLs embedded in the KiCad symbols

Fallback methods when automated sync isn't available or misses parts:

1. Use the Datasheet property URL from the schematic symbol — many KiCad libraries include direct PDF links
2. Use the digikey skill to search by MPN and download individual datasheets
3. Use web search to find the manufacturer's datasheet page
4. Ask the user — if a critical component's datasheet can't be found automatically, tell the user which parts are missing and ask them to provide the datasheets. Don't silently skip verification because a datasheet wasn't available. Example: "I couldn't find datasheets for U3 (XYZ1234) and U7 (ABC5678). Can you provide them? I need them to verify the pinout and application circuit."

Structured datasheet extraction (for large designs or repeated reviews): Pre-extract datasheet specs into cached JSON for faster, more consistent pin verification. This is especially valuable for designs with 10+ ICs where re-reading PDFs from scratch each time is slow.

python3 <skill-path>/scripts/datasheet_page_selector.py <pdf_path> --mpn <mpn> --category <category>

After reading the selected pages and producing an extraction JSON, score and cache it using datasheet_score and datasheet_extract_cache modules. Extractions are stored in datasheets/extracted/<MPN>.json and reused across reviews. The datasheets skill owns the full extraction pipeline (schema, page selection, scoring rubric, consumer API) — see skills/datasheets/SKILL.md and its reference guides.

What to extract from each datasheet (note page/section/figure/equation numbers for citations):

• Pin function table (pin number → name → function)