design-review

Design Review

When to use

• Before exporting a netlist or generating a BOM
• After skidl-coder finishes a circuit
• User says "review the circuit", "design review", or "check the design"
• Invoked via /skidl-ee:design-review [circuit_name]

Inputs

• circuits/<circuit_name>.py — SKiDL source
• SPEC.md — captured design requirements
• architecture/ folder (if present) — block diagram and net plan
• pipeline_state.json — current pipeline status

Procedure

Run these three checks (in parallel where possible):

1. Electrical Rules (ERC)

• Spawn the erc-reviewer agent (it applies the erc-rules skill automatically)
• Receive erc_report.md with pass/fail verdict

2. Architecture Sanity

• Re-read SPEC.md and architecture/ folder
• Check:
  • All functional blocks present in the circuit?
  • Power budget realistic?
  • Net plan complete and consistent with code?
  • Known design risks (decoupling, protection, EMI) addressed?

3. SKiDL Code Quality

• Read current circuits/*.py file(s)
• Verify using the .claude/rules/skidl-syntax.md rules:
  • Every part has ref, value, and footprint?
  • @subcircuit used for repeated blocks?
  • Decoupling caps named C_DECOUP_*?
  • NC on all intentionally unused pins?
  • Net naming: UPPERCASE power rails, camelCase signals?
  • ERC() call present in __main__?

4. Footprint Validation

• Run: python3 .claude/scripts/validate-footprints.py circuits/<circuit_name>/ (or .py for monolithic)
• Every missing footprint is a HIGH severity finding — it will cause KiCad import errors
• For each missing footprint in the report:
  • If the script suggests close matches → recommend the corrected string
  • If no standard library match exists → generate a custom footprint:
    1. Read the datasheet mechanical drawing from datasheets/<MPN>_SUMMARY.md or PDF
    2. Run .claude/scripts/generate-footprint.py with pad positions and sizes
    3. Update the circuit code to reference ProjectLocal:FootprintName
• Do not mark review complete until footprint validation exits 0

Output

Write outputs/design_review.md using this structure:

# Design Review — <circuit_name>

## Summary
ERC: PASS/FAIL | Architecture: OK/Issues | Code: OK/Issues
Severity: <count> HIGH, <count> MEDIUM, <count> LOW issues

## Findings
(sorted HIGH → MEDIUM → LOW)

| # | Severity | Area | Issue | Suggested Fix |
|---|----------|------|-------|---------------|
| 1 | HIGH | ERC | Two OUT pins on net VCC | Add series resistor |
...

Validation

• Every HIGH-severity finding must include a specific SKiDL fix snippet
• Update pipeline_state.json with review_status after writing the report
• If HIGH severity issues found → offer to auto-fix by spawning skidl-coder with the report
• If no issues → declare circuit ready for BOM/netlist export
• Do not mark review complete until all three checks have been run