skidl-circuit-preengineering

name	skidl-circuit-preengineering
description	Generate reviewable circuit artifacts using SKiDL with versioned outputs, ERC validation, optional SPICE simulation, graph generation, and KiCad handoff. Intended for engineering acceleration and human-reviewed circuit pre-design.

SKiDL Circuit Pre-Engineering Skill

This skill generates reviewable electronic circuit artifacts using SKiDL. It must produce versioned source code, ERC reports, netlists, optional SPICE artifacts when applicable, graph outputs, and a human-review handoff report.

This skill does not certify a circuit as production-ready. Final approval must be performed by a qualified engineer.

When To Use

Use this skill for electronic circuit pre-engineering tasks where the user wants structured SKiDL source, ERC-visible connectivity, KiCad handoff artifacts, reusable circuit blocks, or early SPICE checks.

Do not use it as the sole authority for safety-critical, high-voltage, regulated, medical, automotive, aerospace, or production-release approval.

Required Workflow

1. Clarify design intent, constraints, power rails, interfaces, active devices, and expected outputs.
2. Identify the primary chips/modules and exact part numbers needed for the design.
3. Search the internet for official or authoritative datasheets for those primary parts.
4. Capture datasheet source URLs, document revision/version, access date, and extracted constraints in datasheet_traceability.md.
5. Create a project directory with versioned output directories such as project_name/v1/.
6. Select the closest template from templates/.
7. Select symbols and footprints that exist in the local KiCad installation.
8. Verify selected symbols and footprints using kicad-cli before handoff.
9. Generate SKiDL source in the version directory.
10. Run ERC and fix all ERC errors.
11. Fix ERC warnings when appropriate, or document them in erc_waivers.md.
12. Name all intentional nets, including configuration straps and no-connect pads.
13. Generate a KiCad-compatible netlist.
14. Run netlist hygiene checks before handoff.
15. Generate graph artifacts when Graphviz is available.
16. Decide SPICE applicability using docs/06-spice-policy.md.
17. Generate or run SPICE only for blocks where meaningful models exist.
18. Generate spice_applicability.md for every project.
19. Generate handoff_report.md with assumptions, artifacts, datasheet traceability, ERC status, KiCad component verification status, netlist hygiene status, SPICE status, and human review checklist.
20. Present artifact paths, validation status, source references, and limitations to the user.

Required Outputs

Every versioned design directory must contain:

• Versioned SKiDL source, for example motor_driver_v1.py
• Netlist output, for example motor_driver_v1.net
• ERC report, for example motor_driver_v1.erc
• Datasheet traceability report, datasheet_traceability.md
• ERC waiver log, erc_waivers.md
• KiCad component verification report, kicad_component_verification.md
• Netlist hygiene evidence in the handoff report
• SPICE applicability report, spice_applicability.md
• Engineering handoff report, handoff_report.md

When applicable, also include:

• Graph output, for example .dot, .svg, or .png
• SPICE deck or simulation results, for example .spice, .raw, .csv, or plot image

Safety Constraints

• Never claim generated circuits are production-ready.
• Do not design around active ICs/modules without checking current official or authoritative datasheets when internet access is available.
• Prefer manufacturer datasheets over distributor mirrors, blogs, forum posts, or copied PDFs.
• Every datasheet-derived design choice must be traceable to a URL, document title, revision/version, and accessed date.
• Every active IC must have local decoupling capacitors unless intentionally waived.
• LEDs require current-limiting resistors.
• Inductive loads require flyback or clamp protection.
• Digital inputs must not float.
• Power entry, ground, and externally driven rails must be explicit and documented.
• Symbols and footprints must be selected from the local KiCad installation for KiCad handoff designs.
• Footprints must be specified using existing KiCad footprint library entries verified by kicad-cli.
• If kicad-cli is unavailable, do not claim KiCad component verification passed; document it as a handoff blocker or limitation.
• Anonymous auto-generated nets such as N$1 are not allowed in handoff artifacts.
• Intentional unused physical pads must be represented as explicit named no-connect nets such as NC_J3_A6 or NC_U1_10, or explicitly marked no-connect in a way that survives KiCad handoff without “No net found” warnings.
• Configuration straps and mode-setting pins must use descriptive net names such as USB_ILIM_CFG, not anonymous temporary names.
• Datasheet pinout, package, thermal, EMC, safety, and regulatory review remain human responsibilities.

Validation Gates

Before handoff:

• No ERC errors remain.
• ERC warnings are fixed or documented.
• KiCad symbols and footprints are verified with kicad-cli, or the handoff report clearly states verification is blocked.
• Primary chip/module datasheets are cited in datasheet_traceability.md, or the report clearly states why research is blocked.
• Netlist hygiene checks find no anonymous N$ nets and no KiCad “No net found” warnings.
• Required artifacts exist in the version directory.
• No generated output is written to the skill or workspace root.
• SPICE is either executed for applicable blocks or explicitly marked not applicable.
• handoff_report.md includes human review checklist items.

Reference Lookup Rules

Read only the files needed for the current task:

• Workflow overview: docs/03-workflow.md
• Engineering rules: docs/04-engineering-rules.md
• ERC policy: docs/05-erc-policy.md
• SPICE policy: docs/06-spice-policy.md
• Datasheet traceability policy: docs/12-datasheet-traceability-policy.md
• KiCad handoff: docs/07-kicad-handoff.md
• KiCad component policy: docs/10-kicad-component-policy.md
• Netlist hygiene policy: docs/11-netlist-hygiene-policy.md
• Limitations: docs/09-limitations.md
• SKiDL syntax: references/01-skidl-core-syntax.md
• Parts, pins, nets, buses: references/02-parts-pins-nets-buses.md
• Subcircuits: references/03-subcircuits.md
• ERC and drive levels: references/04-erc-and-drive-levels.md
• SPICE: references/05-spice-simulation.md
• KiCad netlist: references/06-kicad-netlist-handoff.md
• Graph generation: references/07-graph-generation.md
• AI generation guidelines: references/08-ai-generation-guidelines.md
• KiCad CLI component lookup: references/09-kicad-cli-component-lookup.md
• KiCad netlist hygiene: references/10-kicad-netlist-hygiene.md
• Datasheet research: references/11-datasheet-research.md

Use references/upstream-skidl-examples/ as a local upstream example archive when a concrete SKiDL pattern is needed.