Skip to content

hashgraph-online/awesome-codex-plugins / plugins/aklofas/kicad-happy/skills/kicad

Analyze KiCad projects and PDF schematics: schematics, PCB layouts, Gerbers, footprints, symbols, netlists, and design rules. Reviews designs for bugs, traces nets, cross-references schematic to PCB, extracts BOM data, checks DRC/ERC, DFM, power trees, and regulator circuits. Every finding carries a confidence label and evidence source with trust_summary rollup. Analyzes PDF schematics from dev boards, reference designs, eval kits, and datasheets. Supports KiCad 5–10. Use whenever the user mentions .kicad_sch, .kicad_pcb, .kicad_pro, PCB design review, schematic analysis, PDF schematics, reference designs, Gerber files, DRC/ERC, netlist issues, BOM extraction, signal tracing, power budget, DFM, or wants to understand, debug, compare, or review any hardware design. Also for "check my board", "review before fab", "what's wrong with my schematic", "is this ready to order", "check my power supply", "verify this circuit", OSHWA certification readiness, or any electronics/PCB design question.

FileKindSize
SKILL.mdskill md79.1 KB
references/config-reference.mdmarkdown19.1 KB
references/datasheet-verification.mdmarkdown16.5 KB
references/deep-review.mdmarkdown9.7 KB
references/design-intent.mdmarkdown5.6 KB
references/diff-analysis.mdmarkdown17.6 KB
references/file-formats.mdmarkdown15.1 KB
references/gerber-parsing.mdmarkdown33.5 KB
references/manual-gerber-parsing.mdmarkdown24.5 KB
references/manual-pcb-parsing.mdmarkdown17.2 KB
references/manual-schematic-parsing.mdmarkdown12.8 KB
references/net-tracing.mdmarkdown12.0 KB
references/oshwa-certification.mdmarkdown4.5 KB
references/output-schema.mdmarkdown33.4 KB
references/pcb-layout-analysis.mdmarkdown27.3 KB
references/pdf-schematic-extraction.mdmarkdown15.2 KB
references/report-generation.mdmarkdown56.3 KB
references/schematic-analysis.mdmarkdown63.9 KB
references/standards-compliance.mdmarkdown33.5 KB
references/supplementary-data-sources.mdmarkdown12.5 KB
references/what-if.mdmarkdown19.5 KB
review/README.mdmarkdown4.1 KB
review/fixtures/deep_review.example.jsonconfig1.2 KB
review/fixtures/design_context.example.jsonconfig388 B
review/fixtures/review_annotations.example.jsonconfig707 B
review/prompts/design_context.mdmarkdown4.9 KB
review/schemas/deep_review.schema.jsonconfig3.3 KB
review/schemas/design_context.schema.jsonconfig2.2 KB
review/schemas/review_annotations.schema.jsonconfig1.9 KB
review/scripts/_mini_jsonschema.pyscript6.6 KB
review/scripts/build_review_plan.pyscript2.3 KB
review/scripts/deep_review_gate.pyscript27.3 KB
review/scripts/merge_annotations.pyscript7.0 KB
review/scripts/validate_review.pyscript2.6 KB
scripts/.gitignoreother13 B
scripts/README.mdmarkdown23.4 KB
scripts/analysis_cache.pyscript42.1 KB
scripts/analyze_gerbers.pyscript90.9 KB
scripts/analyze_pcb.pyscript7.4 KB
scripts/analyze_schematic.pyscript6.7 KB
scripts/analyze_thermal.pyscript48.5 KB
scripts/analyzer_envelope.pyscript15.5 KB
scripts/capability_mode.pyscript10.2 KB
scripts/check_report_sections.pyscript10.6 KB
scripts/cross_analysis.pyscript69.4 KB
scripts/cross_verify.pyscript23.1 KB
scripts/design_intent.pyscript13.5 KB
scripts/detection_schema.pyscript26.0 KB
scripts/detector_helpers.pyscript15.2 KB
scripts/diff_analysis.pyscript23.5 KB
scripts/diff_engine.pyscript47.2 KB
scripts/domain_detectors.pyscript260.5 KB
scripts/envelopes/__init__.pyscript0 B
scripts/envelopes/cross_analysis.pyscript5.9 KB
scripts/envelopes/gerber.pyscript16.1 KB
scripts/envelopes/pcb.pyscript25.9 KB
scripts/envelopes/schematic.pyscript23.1 KB
scripts/envelopes/thermal.pyscript7.4 KB
scripts/export_issues.pyscript27.6 KB
scripts/fab_release_gate.pyscript29.8 KB
scripts/finding_schema.pyscript25.7 KB
scripts/gen_output_schema_md.pyscript9.2 KB
scripts/inputs_builder.pyscript4.0 KB
scripts/kicad_core/__init__.pyscript0 B
scripts/kicad_core/classify.pyscript32.5 KB
scripts/kicad_core/cli.pyscript4.2 KB
scripts/kicad_core/coords.pyscript2.0 KB
scripts/kicad_core/diagnostics.pyscript1.9 KB
scripts/kicad_core/executables.pyscript1.0 KB
scripts/kicad_core/fields.pyscript5.9 KB
scripts/kicad_core/fileio.pyscript5.4 KB
scripts/kicad_core/hotloop.pyscript3.1 KB
scripts/kicad_core/instances.pyscript5.7 KB
scripts/kicad_core/model.pyscript4.8 KB
scripts/kicad_core/netnames.pyscript19.1 KB
scripts/kicad_core/netquery.pyscript6.7 KB
scripts/kicad_core/pairing.pyscript1.9 KB
scripts/kicad_core/parts.pyscript28.9 KB
scripts/kicad_core/passives.pyscript10.0 KB
scripts/kicad_core/pdn.pyscript1011 B
scripts/kicad_core/project.pyscript43.2 KB
scripts/kicad_core/render.pyscript2.7 KB
scripts/kicad_core/sexp.pyscript12.6 KB
scripts/kicad_core/textvars.pyscript5.4 KB
scripts/kicad_core/token_cache.pyscript2.2 KB
scripts/kicad_core/values.pyscript14.1 KB
scripts/kicad_types.pyscript15.1 KB
scripts/lifecycle_audit.pyscript6.7 KB
scripts/lifecycle_engine.pyscript52.8 KB
scripts/lookup_detectors.pyscript29.9 KB
scripts/lookup_helpers.pyscript3.0 KB
scripts/methodology_gerbers.mdmarkdown23.1 KB
scripts/methodology_pcb.mdmarkdown22.2 KB
scripts/methodology_schematic.mdmarkdown43.1 KB
scripts/netlist_queries.pyscript4.2 KB
scripts/output_filters.pyscript16.8 KB
scripts/output_io.pyscript5.3 KB
scripts/pcb/__init__.pyscript0 B
scripts/pcb/assembly.pyscript58.3 KB
scripts/pcb/connectivity.pyscript27.7 KB
scripts/pcb/copper.pyscript61.0 KB
scripts/pcb/dfm.pyscript56.9 KB
scripts/pcb/geometry.pyscript59.5 KB
scripts/pcb/pipeline.pyscript30.3 KB
scripts/pcb/presentation.pyscript24.3 KB
scripts/pcb/reader.pyscript87.1 KB
scripts/pcb/routing.pyscript53.5 KB
scripts/project_config.pyscript23.1 KB
scripts/risk_summary.pyscript3.1 KB
scripts/run_id.pyscript1.7 KB
scripts/schema_codec.pyscript5.0 KB
scripts/schematic/__init__.pyscript0 B
scripts/schematic/audits.pyscript56.0 KB
scripts/schematic/bom_stats.pyscript6.1 KB
scripts/schematic/connectivity.pyscript62.9 KB
scripts/schematic/erc_pins.pyscript8.4 KB
scripts/schematic/hierarchy.pyscript21.5 KB
scripts/schematic/ic_analysis.pyscript21.4 KB
scripts/schematic/legacy_reader.pyscript49.4 KB
scripts/schematic/net_analysis.pyscript75.5 KB
scripts/schematic/pipeline.pyscript72.2 KB
scripts/schematic/presentation.pyscript20.9 KB
scripts/schematic/reader.pyscript64.7 KB
scripts/schematic/system_analyses.pyscript126.9 KB
scripts/signal_detectors.pyscript248.0 KB
scripts/summarize_findings.pyexecutablescript17.4 KB
scripts/validation_detectors.pyscript75.3 KB
scripts/what_if.pyscript68.4 KB

references/output-schema.md

View on GitHub
# Analyzer JSON Output Schema

**Generated from envelope dataclasses. Do not hand-edit.**
Regenerate: `python3 skills/kicad/scripts/gen_output_schema_md.py`

Source-of-truth modules:
- `skills/kicad/scripts/analyzer_envelope.py` — shared primitives (TrustSummary, Finding, BySeverity, ...)
- `skills/kicad/scripts/envelopes/*.py` — per-analyzer envelopes (schematic, pcb, gerber, thermal, cross_analysis)
- `skills/emc/scripts/emc_envelope.py` — EMC envelope

For the authoritative machine-readable JSON Schema Draft 2020-12, use `--schema` on any analyzer:

```bash
python3 skills/kicad/scripts/analyze_schematic.py --schema
python3 skills/kicad/scripts/analyze_pcb.py --schema
python3 skills/kicad/scripts/analyze_gerbers.py --schema
python3 skills/kicad/scripts/analyze_thermal.py --schema
python3 skills/emc/scripts/analyze_emc.py --schema
python3 skills/kicad/scripts/cross_analysis.py --schema
```

Schema versions (`schema_version`; the "v1.4" labels below) are separate from the plugin version.

v1.4 schema-break notes:
- Output of `--schema` is real JSON Schema Draft 2020-12 (prior: descriptive-string dict).
- `schema_version` bumped 1.3.0 → 1.4.0 on every analyzer.
- `trust_summary.by_confidence` aggregate key renamed: `datasheet-backed` → `datasheet_backed`. Per-finding `confidence` VALUE stays `datasheet-backed`.

## Contract Tiers

Every analyzer envelope is organized into three tiers. Consumers can
rely on Tier 1 shapes; Tier 2 is analyzer-specific and best read via
the declared dataclass types; Tier 3 is compatibility residue slated
for removal and should not be written against in new code.

### Tier 1 — Standardized envelope (stable across v1.4)

Present on every analyzer output. Shape locked by the shared primitives
in `analyzer_envelope.py`. Breaking changes bump the analyzer's
`schema_version`.

- `analyzer_type` — `const` string discriminator naming the analyzer.
- `schema_version` — `const` string matching the semver.
- `summary` — per-analyzer roll-up (`total_findings`, `by_severity`,
  analyzer-specific counts). Inner shape is analyzer-specific but the
  top-level key is Tier 1.
- `trust_summary` — trust posture: `total_findings`, `trust_level`,
  `by_confidence`, `by_evidence_source`, `provenance_coverage_pct`,
  `bom_coverage` (schematic only).
- `findings` — `list[Finding]`. Actionable items with severity +
  recommendation.
- `assessments` — `list[Assessment]`. Informational measurements (no
  severity, no recommendation). Empty on analyzers with no assessment
  content today.
- `inputs` — `InputsBlock`. `source_files`, `source_hashes`, `run_id`,
  `config_hash`, `upstream_artifacts`.
- `compat` — `CompatBlock`. `minimum_consumer_version`,
  `deprecated_fields`, `experimental_fields`.
- `diagnostics` — `list[Diagnostic]`. Guarded failures that degraded
  the run (`source`, `exception`, `message`, `effect`); `[]` when
  nothing degraded.

### Tier 2 — Analyzer-specific body

Everything emitted by a given analyzer that is not listed in Tier 1.
Shape is declared by the per-analyzer envelope in `envelopes/*.py` or
`emc_envelope.py`. Typical Tier 2 keys include `statistics`,
`components`, `nets`, `bom`, `ic_pin_analysis`, `design_analysis`,
`bus_topology`, `placement_analysis`, `power_net_routing`,
`connectivity_graph`, EMC `test_plan` / `regulatory_coverage`, thermal
`thermal_score`, gerber `layers` / `drills` / `completeness`, etc.

Several Tier 2 fields are currently typed as loose `dict` or
`list[dict]`; the schema does not constrain their item shapes.

### Tier 3 — Compatibility residue

Empty for v1.4. The v1.4 clean break removed prior residue:

- `schematic.file`, `pcb.file` — removed; use `inputs.source_files[0]`.
- `thermal.thermal_assessments` — renamed to `thermal.assessments`
  (sibling to `findings`, not inside it).
- Descriptive-string `--schema` output — replaced by real JSON Schema
  Draft 2020-12.
- `trust_summary.by_confidence.datasheet-backed` key — renamed to
  `datasheet_backed` (hyphen removed only for the aggregate-count key;
  the per-finding `confidence` VALUE still uses `datasheet-backed`).
- Deprecated `summary.critical` / `.high` / `.medium` / `.low` / `.info`
  keys on thermal — removed in v1.4.

## SchematicEnvelope

Output of `python3 skills/kicad/scripts/analyze_schematic.py <file>.kicad_sch`.

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `analyzer_type` | `string` | yes | Always 'schematic'. |
| `schema_version` | `string` | yes | Semver. Value: '1.4.0'. |
| `inputs` | `InputsBlock` | yes | Source files, hashes, run_id, config_hash, upstream artifacts for this run. |
| `compat` | `CompatBlock` | yes | Schema compatibility metadata: minimum consumer version + deprecated/experimental field lists. |
| `diagnostics` | `list[Diagnostic]` | no | Guarded failures that degraded this run (section omitted, fallback model used). Empty when nothing degraded. |
| `summary` | `SchematicSummary` | yes | Roll-up summary (total + by_severity). |
| `trust_summary` | `TrustSummary` | yes | Trust posture rollup (confidence + evidence source + optional BOM coverage). |
| `kicad_version` | `string` | yes | KiCad generator version string, e.g. '9.0' or '5 (legacy)'. |
| `file_version` | `string` | yes | KiCad file format version string. |
| `title_block` | `TitleBlock` | yes | KiCad title block (title/date/rev/company/comments). |
| `statistics` | `Statistics` | yes | Component, net, and coverage counts. |
| `findings` | `list[Finding]` | yes | All findings (flat, rich-finding format). |
| `assessments` | `list[Assessment]` | yes | Informational assessments (empty for schematic at v1.4; reserved for future measurement-style records). |
| `bom` | `list[BomEntry]` | yes | Deduplicated BOM rows. |
| `components` | `list[dict]` | yes | Every non-power component as a dict. Shape is effectively open: reference/value/lib_id/footprint/datasheet/description/mpn/manufacturer/distributor SKUs/geometry/uuid/type/parsed_value plus internal bookkeeping (_sheet, pin_nets, pin_uuids). |
| `nets` | `dict[str, NetEntry]` | yes | Net connectivity map keyed by unique net key — the display name, sheet-qualified as /<sheet>/<name> when distinct nets share a bare name. |
| `subcircuits` | `list[dict]` | yes | IC neighbourhoods, one entry per IC: [{center_ic, ic_value, ic_mpn, ic_lib_id, neighbor_components: [{ref, value, type}], description}]; neighbours share a non-power, non-ground net with the IC. Not hierarchical sheets; detected circuits are in findings[]. |
| `ic_pin_analysis` | `list[dict]` | yes | Per-IC pin mappings. Each entry carries reference, value, type, lib_id, mpn, description, datasheet, function, total_pins, unconnected_pins, pins[], power_pins[], signal_pins[], decoupling_caps_by_rail. Covers type in {ic, connector, crystal, oscillator}; transistors live in transistor_pin_analysis[]. |
| `transistor_pin_analysis` | `list[dict]` | yes | Per-transistor pin mappings. Same shape as ic_pin_analysis entries but filtered to type=transistor (MOSFETs, BJTs, FETs). Lets bridge / half-bridge / gate-driver reviewers verify gate/source/drain wiring without reconstructing pin maps from nets[].pins[] by hand. |
| `design_analysis` | `dict` | yes | Design-level analyses: net_classification, power_domains, cross_domain_signals, bus_analysis (i2c/spi/uart/can), differential_pairs, erc_warnings, passive_warnings. |
| `connectivity_issues` | `dict` | yes | Connectivity issue lists: single_pin_nets, single_pin_net_findings, multi_driver_nets, unconnected_pins, power_net_summary. |
| `annotation_issues` | `dict` | yes | Annotation issue bag: duplicate_references, unannotated, missing_value, zero_indexed_refs. |
| `ground_domains` | `dict` | yes | Ground topology: ground_nets, multiple_domains, domains, optional star-ground note. |
| `bus_topology` | `BusTopology` | yes | Bus wire statistics: bus_wire_count, bus_entry_count, unresolved. May also carry aliases / detected_bus_signals (undeclared, shape varies). |
| `wire_geometry` | `dict` | yes | Wire-geometry summary: total_wires, total_length_mm, avg_length_mm, optional diagonal/short-wire callouts. |
| `simulation_readiness` | `dict` | yes | SPICE readiness rollup: total_components, likely_simulatable, needs_model, simulatable_percent, components_without_model. |
| `hierarchical_labels` | `dict` | yes | Label counts: global_label_count, hierarchical_label_count, optional unconnected_hierarchical or conflict warnings. |
| `placement_analysis` | `dict` | yes | Placement stats: bounding_box, clusters, grid_size. |
| `property_issues` | `dict` | yes | Property validation issues: missing/mismatched symbol properties (MPN, footprint, datasheet, value), blank description fields, non-ASCII character warnings. Keyed by issue category. |
| `sourcing_audit` | `dict` | yes | Sourcing audit: missing_mpn/digikey/lcsc lists, mpn_coverage, mpn_percent, total_bom_components. |
| `rail_voltages` | `dict[str, float \| null]` | yes | Per-net rail voltage (volts). Nulls permitted for ground or unresolved rails. |
| `labels` | `list[dict]` | no | Extracted label records. |
| `no_connects` | `list[dict]` | no | Extracted no-connect flag records. |
| `power_symbols` | `list[dict]` | no | Power symbol placements: [{net_name, x, y, lib_id, _sheet, _power_scope}]. |
| `pwr_flag_warnings` | `list[dict]` | no | PWR_FLAG warnings: [{net, message, pin_types}]. |
| `label_shape_warnings` | `list` | no | Label-shape mismatch warnings. |
| `footprint_filter_warnings` | `list` | no | Footprint filter warnings from lib_symbols. |
| `capability_mode_ref` | `dict \| null` | no | Pointer to canonical analysis/capability_mode.json run-level record. Shape: {source, run_id}. |
| `audience_summary` | `dict \| null` | no | Designer/reviewer/manager summary views; only present when output filters ran. |
| `design_intent` | `dict \| null` | no | Resolved design intent: approved_manufacturers, ipc_class, target_market, operating_temp_range, preferred_passive_size, product_class, test_coverage_target, expected_lifetime_years, detection_signals, source, confidence. |
| `project_config` | `dict \| null` | no | Copy of the resolved project block from .kicad-happy.json (when present). |
| `project_settings` | `dict \| null` | no | Selected KiCad project settings extracted from .kicad_pro (when present). |
| `bom_lock` | `dict \| null` | no | BOM lock verification: status, lock_pct, components_with_mpn, missing_mpn, etc. |
| `bom_optimization` | `dict \| null` | no | BOM optimization bag: single_use_passive_values, unique_value_counts, total_unique_footprints, consolidation_suggestions. |
| `missing_info` | `dict \| null` | no | Data-gap rollup: missing_mpn, missing_footprint, missing_datasheet, heuristic_vref. |
| `sleep_current_audit` | `dict \| null` | no | Sleep-current audit: rails, total_estimated_sleep_uA, realistic_total_uA, conditional_pull_up_uA, observations. |
| `test_coverage` | `dict \| null` | no | Test coverage audit: test_points, test_point_count, covered_nets, uncovered_key_nets, observations, optional debug_connectors. |
| `assembly_complexity` | `dict \| null` | no | Assembly complexity score and breakdown. |
| `power_budget` | `dict \| null` | no | Estimated power budget per rail. |
| `power_sequencing` | `dict \| null` | no | Power sequencing dependencies and warnings. |
| `power_sequencing_validation` | `dict \| null` | no | Validated power tree with provenance. |
| `pdn_impedance` | `dict \| null` | no | PDN impedance analysis per rail. |
| `usb_compliance` | `dict \| null` | no | USB compliance checks. |
| `inrush_analysis` | `dict \| null` | no | Inrush current estimation by rail. |
| `protocol_compliance` | `dict \| null` | no | Protocol compliance checks (I2C/SPI/UART/etc.). |
| `text_annotations` | `list \| null` | no | Text annotations extracted from the schematic. |
| `alternate_pin_summary` | `dict \| null` | no | Alternate-pin usage summary. |
| `pin_coverage_warnings` | `list[PinCoverageWarning] \| null` | no | Warnings about pin coverage gaps. Emitted when a placed symbol has fewer pins connected than the library definition expects. Present only when such warnings fire. |
| `instance_consistency_warnings` | `list \| null` | no | Multi-instance symbol consistency warnings. |
| `generic_symbol_warnings` | `list \| null` | no | Warnings about generic symbol usage without MPN. |
| `sheets` | `list \| null` | no | Hierarchical sheet list (multi-sheet only). |
| `sheets_parsed` | `int \| null` | no | Count of parsed sheets (legacy .sch). |
| `sheet_files` | `list[string] \| null` | no | Parsed sheet file paths (legacy .sch). |
| `legacy_analysis_quality` | `dict \| null` | no | Legacy .sch quality rollup: is_legacy_schematic, library_resolution, pin_source_coverage. |
| `hierarchy_context` | `dict \| null` | no | Not emitted: no analyzer path produces it. |
| `hierarchy_warning` | `string \| null` | no | Emitted when sub-sheet was detected without root. |
| `_redirected_from` | `string \| null` | no | Original filename when a sub-sheet was redirected to the project root. Emitted in JSON as '_redirected_from'. |
| `_stale_file_warning` | `string \| null` | no | Emitted when input file is not in the project sheet tree. Emitted in JSON as '_stale_file_warning'. |
| `net_classifications` | `dict \| null` | no | Per-net classification map promoted from signal_analysis (legacy alias of design_analysis.net_classification). |

## PCBEnvelope

Output of `python3 skills/kicad/scripts/analyze_pcb.py <file>.kicad_pcb`.

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `analyzer_type` | `string` | yes | Always 'pcb'. |
| `schema_version` | `string` | yes | Semver. Value: '1.4.0'. |
| `inputs` | `InputsBlock` | yes | Source files, hashes, run_id, config_hash, upstream artifacts for this run. |
| `compat` | `CompatBlock` | yes | Schema compatibility metadata: minimum consumer version + deprecated/experimental field lists. |
| `diagnostics` | `list[Diagnostic]` | no | Guarded failures that degraded this run (section omitted, fallback model used). Empty when nothing degraded. |
| `summary` | `PCBSummary` | yes | Roll-up summary (total + by_severity). |
| `trust_summary` | `TrustSummary` | yes | Trust posture rollup (confidence + evidence source). |
| `kicad_version` | `string` | yes | KiCad generator version string, e.g. '9.0'. |
| `file_version` | `string` | yes | KiCad file format version string (e.g. '20241228'). |
| `findings` | `list[Finding]` | yes | All PCB findings (flat list). |
| `assessments` | `list[Assessment]` | yes | Informational assessments (empty for PCB at v1.4). |
| `statistics` | `PCBStatistics` | yes | Board/component/net counts and routing rollup. |
| `setup` | `PCBSetup` | yes | Board setup block (thickness, soldermask, etc.). |
| `board_outline` | `BoardOutline` | yes | Edge.Cuts outline geometry + bounding box. |
| `connectivity` | `Connectivity` | yes | Routing completeness rollup. |
| `tracks` | `Tracks` | yes | Track summary + optional detailed arrays under --full. |
| `vias` | `Vias` | yes | Via summary + optional detailed array under --full. |
| `nets` | `dict[str, string]` | yes | Net ID (as string) -> net name. |
| `net_name_to_id` | `dict[str, int]` | yes | Net name -> integer net ID. Reverse of nets. |
| `layers` | `list[dict]` | yes | Layer stackup entries: [{number, name, type, alias}]. |
| `footprints` | `list[dict]` | yes | Every placed footprint. Fields include reference, value, library, footprint, layer, x, y, angle, type, mpn, manufacturer, description, pad_count, courtyard, courtyard_poly, pad_nets, connected_nets, sch_path, sheetname, sheetfile. |
| `zones` | `list[dict]` | yes | Copper zones: [{net, net_name, layers, clearance, min_thickness, thermal_gap, thermal_bridge_width, outline_points, outline_area_mm2, is_filled, outline_bbox}]. |
| `keepout_zones` | `list[dict]` | yes | Keepout zones: [{name, layers, restrictions, bounding_box, area_mm2, nearby_components}]. |
| `net_classes` | `list[dict]` | yes | Net class definitions: [{name, clearance, track_width, via_diameter, via_drill}]. |
| `net_lengths` | `list[dict]` | yes | Per-net track length rollup: [{net, net_number, total_length_mm, segment_count, via_count, layers}]. |
| `component_groups` | `dict[str, ComponentGroup]` | yes | Refdes prefix -> {count, references}. |
| `silkscreen` | `dict` | yes | Silkscreen rollup: board_text_count, refs_visible_on_silk, refs_hidden_on_silk, documentation_warnings[], fab_notes_completeness, silkscreen_completeness. |
| `dfm_summary` | `dict` | yes | DFM rollup: dfm_tier, metrics, violation_count. |
| `project_settings` | `dict` | yes | Selected settings extracted from .kicad_pro: source, net_classes, design_rules; custom_rules from .kicad_dru, with custom_rules_error (KiCad's parse message) when KiCad would refuse the file and so applies none of its rules. |
| `design_rule_compliance` | `dict` | no | Design rule compliance: compliant, rules_checked, rules_source; empty dict when project_settings missing or compliance not computed. |
| `board_thickness_mm` | `float \| null` | no | Board thickness (mm) used by the current-capacity check: the setup thickness, or 1.6 when the file gives none. Present only when current-capacity findings exist. |
| `board_metadata` | `dict` | no | Board metadata bag (paper size, title block fragments, etc.); empty dict when no metadata extracted. |
| `power_net_routing` | `list[dict]` | no | Power net routing rollup: [{net, track_count, total_length_mm, min_width_mm, max_width_mm, widths_used}]; empty list when no power routing detected. |
| `power_net_resolution` | `dict` | no | Power/ground net classification actually used: {power: [net names], ground: [net names], source: 'cli'\|'schematic'\|'heuristic'}. source reflects how power rail overrides were resolved — explicit --power-rails, rails auto-read from --schematic, or name heuristics alone. |
| `ground_domains` | `dict` | no | Ground topology: domain_count, domains[], multi_domain_components. Always emitted; domain_count=0 is meaningful (no ground domain found). |
| `placement_density` | `dict` | no | Placement density: board_area_cm2, front_density_per_cm2, optional back_density_per_cm2; empty dict when density not computed. |
| `capability_mode_ref` | `dict \| null` | no | Pointer to canonical analysis/capability_mode.json run-level record. Shape: {source, run_id}. |
| `audience_summary` | `dict \| null` | no | Designer/reviewer/manager summary views; only present when output filters ran. |
| `design_intent` | `dict \| null` | no | Resolved design intent: product_class, ipc_class, target_market, operating_temp_range, preferred_passive_size, test_coverage_target, approved_manufacturers, expected_lifetime_years, detection_signals, confidence, source. |
| `project_config` | `dict \| null` | no | Copy of the resolved project block from .kicad-happy.json (when present). |
| `connectivity_graph` | `dict \| null` | no | Per-net connectivity graph (island map). Emitted only in --full mode. |
| `connectivity_graph_error` | `string \| null` | no | Present when --full connectivity graph construction failed; downstream cross-analysis checks that need it were skipped. |
| `pad_to_pad_distances` | `dict \| null` | no | Pad-to-pad routing distances keyed by 'R1.2-D1.1' style endpoints. Emitted only in --full mode. |
| `reference_plane_changes` | `list[dict] \| null` | no | Places where a signal trace's reference plane changes from one ground or power plane net to another (a split between plane nets); [] when none. Emitted in --full mode on boards with zone fills, with return_path_continuity. A plane net counts only where it holds over about 2 mm of trace (across segment ends), so a pad-sized island is not a change. Items: net, layer, reference_layer, net_a and net_b (the two plane nets, an unordered pair: net_a sorts first), x, y (mm, the midpoint between the two bounding samples or the segment junction), sample_points ([[x, y] over net_a, [x, y] over net_b], the nearest samples on either side). |
| `return_path_continuity` | `list[dict] \| null` | no | Nets whose traces lose their reference plane for part of their length; [] when checked and no net is under 95 % coverage. Emitted in --full mode on boards with zone fills. Items: net, total_trace_mm, samples_checked, samples_with_reference_plane, reference_plane_coverage_pct, gap_note; worst first. |
| `thermal_analysis` | `dict \| null` | no | Not in CLI output: its zone-stitching entries move to findings[] and its pad scan to thermal_pad_scan. |
| `thermal_pad_vias` | `dict \| null` | no | Not in CLI output: its entries move to findings[] (detector analyze_thermal_pad_vias). |
| `trace_proximity` | `dict \| null` | no | Trace proximity / crosstalk analysis (--proximity). |
| `copper_presence` | `dict \| null` | no | Not in CLI output: its entries move to findings[] (detector analyze_copper_presence) and its opposite-layer summary to copper_presence_summary. |
| `tombstoning_risk` | `dict \| null` | no | Not in CLI output: its entries move to findings[] (detector analyze_tombstoning_risk). |
| `decoupling_placement` | `list[dict] \| null` | no | Decoupling capacitor placement audit, one entry per IC with capacitors nearby; emitted only when non-empty. Items: ic, value, layer, nearby_caps, closest_cap_mm, gnd_only_caps (optional), category ('esd_bypass' for ESD/TVS ICs). nearby_caps items: cap, value, distance_mm, shared_nets, same_side; nearest first, within 10 mm, sharing a non-ground net. |
| `decoupling_proximity` | `list[dict] \| null` | no | Capacitor-to-IC proximity pairs; emitted only when non-empty. Items: ic_ref, cap_ref, distance_mm, cap_value, same_side, shared_nets. |
| `switching_loop_areas` | `list[dict] \| null` | no | Switching-regulator hot-loop areas; emitted with --schematic, for switching topologies only, and only when non-empty. Items: regulator_ref, regulator_value, inductor_ref, cap_ref, method ('pad'), area_mm2 (null when not estimated), loop_pads and vertices_mm (the input-cap supply, regulator supply, SW, inductor SW, regulator ground and input-cap ground pads, in loop order; absent when the pads are not resolved), estimate ('pads_unresolved', or 'degenerate': area under 1 mm2 across a reach of 2 mm or more, the pads in a line or the loop crossing itself so its lobes cancel; optional). |
| `current_capacity` | `dict \| null` | no | Not in CLI output: its entries move to findings[] (detector analyze_current_capacity). |
| `placement_analysis` | `dict \| null` | no | Not in CLI output: courtyard overlaps and edge-clearance entries move to findings[], density to placement_density. |
| `dfm` | `dict \| null` | no | Not in CLI output: violations move to findings[] (detector analyze_dfm), the rest to dfm_summary. |
| `layer_transitions` | `list \| null` | no | Signal nets routed on more than one copper layer, when any are (power and ground nets are not listed). Items: net, net_number, copper_layers, layer_count, via_count, and via_positions (only when the net has vias). |
| `dimensions` | `list \| null` | no | Dimension annotations, when the board has any. Items carry only the keys the file provides, among: value_mm, layer, type (KiCad 8+), text, endpoints. |
| `groups` | `list \| null` | no | Board groups, when the board has any. Items: name, member_count. |
| `thermal_pad_scan` | `list \| null` | no | Thermal-pad via scan, one finding-shaped record per pad (the standard finding fields: severity, confidence, evidence_source, summary, description, components, nets, pins, recommendation, report_context) plus: component, pad, pad_size_mm, pad_area_mm2, net, nearby_thermal_vias, standalone_vias, footprint_via_pads, layer, detector, rule_id, category. |
| `copper_presence_summary` | `list \| null` | no | Components grouped by the opposite-layer nets they sit over. Items: opposite_layer_nets (comma-joined names), component_count, components. |

## GerberEnvelope

Output of `python3 skills/kicad/scripts/analyze_gerbers.py <gerber_dir>/`.

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `analyzer_type` | `string` | yes | Always 'gerber'. |
| `schema_version` | `string` | yes | Semver. Value: '1.4.0'. |
| `inputs` | `InputsBlock` | yes | Source files, hashes, run_id, config_hash, upstream artifacts for this run. |
| `compat` | `CompatBlock` | yes | Schema compatibility metadata: minimum consumer version + deprecated/experimental field lists. |
| `diagnostics` | `list[Diagnostic]` | no | Guarded failures that degraded this run (section omitted, fallback model used). Empty when nothing degraded. |
| `summary` | `GerberSummary` | yes | Roll-up summary (total + by_severity). |
| `trust_summary` | `TrustSummary` | yes | Trust posture rollup (confidence + evidence source). |
| `directory` | `string` | yes | Resolved absolute path of the scanned gerber directory. |
| `layer_count` | `int` | yes | Layer count derived from gbrjob or filename heuristic. |
| `statistics` | `GerberStatistics` | yes | File / draw / flash / hole totals. |
| `completeness` | `Completeness` | yes | Expected-vs-found layers and drill presence. |
| `alignment` | `Alignment` | yes | Cross-layer alignment report. |
| `drill_classification` | `DrillClassification` | yes | Vias / component / mounting hole breakdown. |
| `pad_summary` | `PadSummary` | yes | Aperture-function rollup (SMD / via / TH / heatsink). |
| `findings` | `list[Finding]` | yes | All gerber findings (flat list). |
| `assessments` | `list[Assessment]` | yes | Informational assessments (empty for gerber at v1.4). |
| `board_dimensions` | `BoardDimensions` | yes | Physical board dimensions (from gbrjob or edge cuts). |
| `generator` | `string \| null` | no | Generator string (e.g. 'Pcbnew 10.0.1-...'); null if no GenerationSoftware tag and no gbrjob info. |
| `gerbers` | `list[dict]` | no | Per-gerber-file summary. Each item: {filename, layer_type, units, aperture_count, draw_count, flash_count, region_count, x2_attributes, x2_component_count, x2_net_count, x2_pin_count, aperture_analysis}. |
| `drills` | `list[dict]` | no | Per-drill-file summary. Each item: {filename, type, units, hole_count, layer_span, tools (T# -> {diameter_mm, hole_count, aper_function}), x2_attributes}. |
| `drill_tools` | `dict[str, dict]` | no | Aggregated tool map keyed by 'Xmm' diameter label with value {diameter_mm, count, type}. |
| `trace_widths` | `TraceWidths \| null` | no | Trace width rollup; omitted when no conductor apertures were observed. |
| `component_analysis` | `ComponentAnalysis \| null` | no | X2 component attribute rollup; omitted when no X2 component data in the gerber stream. |
| `net_analysis` | `NetAnalysis \| null` | no | X2 net attribute rollup; omitted when no X2 net data in the gerber stream. |
| `job_file` | `dict \| null` | no | Parsed .gbrjob contents: project_name, vendor, generator, layer_count, board_width_mm, board_height_mm, board_thickness_mm, creation_date, finish, stackup, design_rules, expected_files. Omitted when no .gbrjob present. |
| `zip_archives` | `list[dict] \| null` | no | Zip archive sweep; each entry: {filename, size_bytes, modified (when the file stat succeeds), total_files, gerber_files, drill_files, other_files, newest_member_date (when any member date parses), vs_loose_files (loose_files_newer \| archive_newer \| same_age), age_delta_hours (unless same_age), error (when the archive cannot be read)}. Omitted when no .zip files in the directory. |
| `connectivity` | `list[dict] \| null` | no | Flat pin-to-net list from X2 attributes (--full only). Each item: {ref, pin, pin_name, net}. |
| `capability_mode_ref` | `dict \| null` | no | Pointer to canonical analysis/capability_mode.json run-level record. Shape: {source, run_id}. |
| `audience_summary` | `dict \| null` | no | Designer/reviewer/manager summary views; only present when output filters ran. |

## ThermalEnvelope

Output of `python3 skills/kicad/scripts/analyze_thermal.py --schematic ... --pcb ...`.

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `analyzer_type` | `string` | yes | Always 'thermal'. |
| `schema_version` | `string` | yes | Schema semver. Value: '1.4.0'. |
| `inputs` | `InputsBlock` | yes | Source JSON inputs, sha256s, run_id, plus upstream artifact metadata (schematic, pcb). |
| `compat` | `CompatBlock` | yes | Schema compatibility metadata: minimum consumer version + deprecated/experimental field lists. |
| `diagnostics` | `list[Diagnostic]` | no | Guarded failures that degraded this run (section omitted, fallback model used). Empty when nothing degraded. |
| `summary` | `ThermalSummary` | yes | Roll-up summary of thermal analysis. |
| `findings` | `list[Finding]` | yes | All thermal findings: TS-001..005, TP-001..002. |
| `assessments` | `list[Assessment]` | yes | TH-DET entries — per-component junction-temperature estimates. Informational (not findings). |
| `trust_summary` | `TrustSummary` | yes | Trust posture rollup. |
| `elapsed_s` | `float` | yes | Wall-clock analysis time in seconds. |
| `missing_info` | `ThermalMissingInfo \| null` | no | Emitted when any component used default thermal params. |
| `skipped_components` | `list[ThermalSkipped] \| null` | no | Power components (regulators) that could not be assessed for power dissipation. Present only when non-empty; see summary.components_skipped for the count. |
| `capability_mode_ref` | `dict \| null` | no | Pointer to canonical analysis/capability_mode.json run-level record. Shape: {source, run_id}. |

## EMCEnvelope

Output of `python3 skills/emc/scripts/analyze_emc.py --schematic ... --pcb ...`.

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `analyzer_type` | `string` | yes | Always 'emc'. |
| `schema_version` | `string` | yes | Semver. Value: '1.4.0'. |
| `inputs` | `InputsBlock` | yes | Source JSON inputs, sha256s, run_id, plus upstream artifact metadata (schematic, pcb). |
| `compat` | `CompatBlock` | yes | Schema compatibility metadata: minimum consumer version + deprecated/experimental field lists. |
| `diagnostics` | `list[Diagnostic]` | no | Guarded failures that degraded this run (section omitted, fallback model used). Empty when nothing degraded. |
| `target_standard` | `string` | yes | Target EMC standard key (e.g. 'fcc-class-b', 'cispr-class-b', 'cispr-25'). |
| `summary` | `EMCSummary` | yes | EMC roll-up summary (counts + risk score). |
| `findings` | `list[Finding]` | yes | All EMC findings. |
| `assessments` | `list[Assessment]` | yes | Informational assessments (empty for EMC at v1.4). |
| `trust_summary` | `TrustSummary` | yes | Trust posture rollup (confidence + evidence source). |
| `elapsed_s` | `float` | yes | Analysis wall-clock time in seconds. |
| `per_net_scores` | `list[PerNetScore]` | yes | Per-net EMC risk score rollup, sorted worst-first. |
| `test_plan` | `TestPlan` | yes | Pre-compliance test plan: frequency band priority, interface risk ranking, probe point suggestions. |
| `regulatory_coverage` | `RegulatoryCoverage` | yes | Coverage matrix vs. applicable standards for the target market. |
| `category_summary` | `dict[str, CategorySummaryEntry]` | yes | Category label -> {count, max_severity, severities, suppressed_count}. |
| `board_info` | `BoardInfo` | yes | Board-level rollup (dimensions, layer count, crystal + switching frequencies, ...). |
| `capability_mode_ref` | `dict \| null` | no | Pointer to canonical analysis/capability_mode.json run-level record. Shape: {source, run_id}. |
| `audience_summary` | `dict \| null` | no | Designer/reviewer/manager summary views. Present whenever findings[] is non-empty (the analyzer always builds this when findings exist). |
| `stage_filter` | `dict \| null` | no | Stage-filtered findings rollup. Present only when --stage is passed. |

## CrossAnalysisEnvelope

Output of `python3 skills/kicad/scripts/cross_analysis.py --schematic ... --pcb ...`.

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `analyzer_type` | `string` | yes | Always 'cross_analysis'. |
| `schema_version` | `string` | yes | Semver. Value: '1.4.0'. |
| `inputs` | `InputsBlock` | yes | Source JSON inputs, sha256s, run_id, plus upstream artifact metadata (schematic, pcb). |
| `compat` | `CompatBlock` | yes | Schema compatibility metadata: minimum consumer version + deprecated/experimental field lists. |
| `diagnostics` | `list[Diagnostic]` | no | Guarded failures that degraded this run (section omitted, fallback model used). Empty when nothing degraded. |
| `elapsed_s` | `float` | yes | Analysis wall-clock time in seconds. |
| `summary` | `CrossAnalysisSummary` | yes | Roll-up summary (total + by_severity). |
| `findings` | `list[Finding]` | yes | All cross-domain findings. |
| `assessments` | `list[Assessment]` | yes | Informational assessments (empty for cross-analysis at v1.4). |
| `checks_run` | `list[CheckRun]` | yes | Manifest of which cross-analysis checks executed this run, in call order. Distinguishes 'ran and found nothing' from 'skipped for lack of required input' — see CheckRun. |
| `trust_summary` | `TrustSummary` | yes | Trust posture rollup (confidence + evidence source). |
| `capability_mode_ref` | `dict \| null` | no | Pointer to canonical analysis/capability_mode.json run-level record. Shape: {source, run_id}. |
| `audience_summary` | `dict \| null` | no | Designer/reviewer/manager summary views. Added by apply_output_filters whenever findings[] is non-empty. |
| `stage_filter` | `dict \| null` | no | Stage-filtered findings rollup. Present only when --stage is passed. |

## Diagnostic

One entry of the Tier 1 `diagnostics` list, shared by every envelope.

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `source` | `string` | yes | Where the guard sits: '<module>.<function>'. |
| `exception` | `string` | yes | Exception class name, e.g. 'KeyError'. |
| `message` | `string` | yes | str(exception), truncated to 200 characters. |
| `effect` | `string` | yes | What the run did instead, e.g. 'power_rails config not applied'. |
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall