---
name: design_wizard
description: >
  Interactive circuit design wizard — a guided, step-by-step console workflow
  that takes users from a blank slate to a quote-ready KiCad project. Covers
  requirements capture, AI-driven IC selection, research-backed BOM assembly,
  manufacturing preferences, schematic generation, and PCB layout guidance.
  Trigger on phrases like "new design", "start a project", "design wizard",
  "circuit wizard", "help me design", "I want to build", "new board",
  "new circuit", or "walk me through".
---

# Circuit Design Wizard

An interactive, console-level question-and-answer workflow that hand-holds
users through the full Circuit Weaver pipeline — from vague idea to
quote-ready KiCad outputs.

> **Disambiguation:** This is the **step-by-step guided** wizard with human-in-the-loop control at every step. For **automatic same-agent** design orchestration (faster, less manual prompting), use `/circuit-weaver`. For **analyzing existing KiCad files**, use `/kicad`.

**About this skill:** This is the **manual, step-by-step guide** with human-in-the-loop control. Compare with:
- **`/circuit-weaver` skill** — Automatic, same-agent orchestration for IC research and design assembly; supports `fast` vs `normal` research depth, and uses `sonar-pro` when configured and compatible, otherwise native web tooling
- **`circuit-weaver design-wizard` CLI** — Offline interactive wizard (no agents, works standalone, good for learning)

**How this skill works:** You (the AI agent) drive a multi-step conversation.
At each step you ask the user targeted questions, summarize what you learned,
and then proceed. Never skip a step without telling the user why. Use the
`AskUserQuestion`-style conversational pattern throughout — present numbered
options, suggest defaults, and let the user confirm or override.

---

## Output Formatting Rules

When presenting CLI command output to the user, follow these rules for clarity:

| Command | Success Output | Error Output |
|---------|---|---|
| `validate` | `"Validation passed: X errors, Y warnings"` or full categories if issues exist | List each error with code + message |
| `apply-patch` | `"Added [ref] ([template_type]) to design.yaml"` | List errors from patch validation |
| `scaffold` | Print the generated YAML snippet | Report error with details |
| `generate` | `"Generated N files to [output_dir]"` with file list | Report generation failure reason |
| `export-jlcpcb` | `"JLCPCB export: [bom_rows] rows, [missing_lcsc] need manual lookup"` | Report export error |
| `cost-bom` | Print formatted BOM table with totals | List pricing lookup failures |

Never output raw JSON unless the user explicitly requests `--json` flag. Present human-readable tables and summaries instead.

---

## Step -1 — Auto-Detection (ALWAYS RUN FIRST)

Before starting, scan the current directory for existing projects:

```bash
python -m circuit_weaver discover --json
```

If projects are found, present them and ask whether the user wants to:
1. Continue/modify an existing project (load its design.yaml and skip to the relevant step)
2. Start a fresh design (proceed to Step 0)

If no projects are found, proceed directly to Step 0.

---

## Step 0 — Welcome & Orientation

Greet the user and explain what the wizard will cover:

```
Welcome to the Circuit Weaver Design Wizard.

I'll walk you through building a new circuit design from scratch:

  Step 1  Requirements & goals
  Step 2  IC selection & research
  Step 3  BOM assembly & sourcing preferences
  Step 4  Schematic generation
  Step 5  Design review checkpoint
  Step 6  Confidence & simulation check
  Step 7  PCB layout guidance & next steps

You can pause, go back, or skip any step. Let's start.
```

Ask: **Do you have an existing YAML spec or are we starting fresh?**

- If they have a spec, load it and skip to the step that makes sense.
- If starting fresh, proceed to the experience check below.

### 0a. Experience Level Calibration

Before diving in, gauge the user's background so you can adjust depth and
pacing throughout the wizard. Ask:

- **How would you describe your electronics experience?**
  1. **Beginner** — I've used dev boards (Arduino, Raspberry Pi) but never
     designed a custom PCB
  2. **Intermediate** — I've designed 1-3 boards, comfortable reading
     schematics, done basic soldering
  3. **Advanced** — I regularly design boards, familiar with KiCad, understand
     signal integrity and DFM
  4. **Professional EE** — Just get me to a YAML spec fast, I know what I'm doing

Adapt behavior based on their answer:

| Level | Wizard behavior |
|-------|----------------|
| Beginner | Explain every concept briefly as it comes up. Suggest safe defaults aggressively. Flag anything that needs manual EE judgment. Link to the `ee` skill reference for learning. |
| Intermediate | Explain non-obvious trade-offs. Suggest defaults but invite overrides. Skip basic definitions. |
| Advanced | Lead with options, not explanations. Compact summaries. Skip obvious defaults. |
| Professional | Minimize chatter. Present choices as tables. Allow batch answers. Offer to jump directly to YAML spec editing. |

Store the experience level and reference it throughout — don't re-ask.

---

## Step 1 — Requirements Definition

**Goal:** Capture enough context to make informed IC and topology decisions.

Ask these questions **one group at a time** — don't dump them all at once.
After each answer, acknowledge and summarize before moving on.

### 1a. Purpose & Application

Ask:
- What does this circuit/board need to do? (e.g., "battery-powered IoT sensor",
  "USB-powered motor controller", "audio amplifier with Bluetooth")
- What is the end-use environment? (consumer, industrial, automotive, hobby)
- Any size or form-factor constraints? (e.g., "fits in a 50x30mm enclosure")

### 1a-mech. Mechanical & Enclosure Integration

If the user mentioned an enclosure or physical constraints, dig deeper:
- Is there an existing enclosure this board must fit inside? (dimensions, mounting pattern)
- Any fixed connector positions? (e.g., "USB port must be on the left edge")
- Height restrictions? (component height limit from enclosure lid)
- Mounting method? (screw holes, snap-fit tabs, standoffs, adhesive)
- Board-to-board stacking? (if part of a multi-board system)
- Cable routing constraints? (which edges have cable egress)

For beginners: explain that connector placement and mounting holes are best
decided now — moving them after PCB layout is expensive rework.

Record all mechanical constraints — they feed directly into Step 7 (PCB layout)
for board outline and keep-out zone generation.

### 1b. Features & Interfaces

Ask:
- What external interfaces are needed? (USB, SPI, I2C, UART, Ethernet, WiFi,
  BLE, CAN, analog I/O, GPIO, display, buttons, LEDs, etc.)
- What sensors or actuators? (temperature, pressure, IMU, motor, relay, etc.)
- How many of each? Any specific models or preferences?

### 1c. Power & Electrical Requirements

Ask:
- What is the primary power source? (USB 5V, battery type/voltage, wall adapter,
  PoE, solar, etc.)
- What voltage rails do you need? (3.3V, 1.8V, 5V, 12V, etc.)
- Estimated current budget per rail? (rough is fine — "under 500mA" works)
- Any battery charging requirements?

### 1c-validate. Power Budget Sanity Check

**Do this immediately after collecting power requirements.** Don't wait until
IC selection — catch impossible power trees now.

Using the `ee` skill reference formulas, run a quick power budget:

```
=== Power Budget Estimate ===

Source: USB 5V (500mA USB 2.0 or 3A USB-C PD)

Rail         Voltage   Est. Current   Power
---------------------------------------------
VDD_3P3      3.3V      350 mA         1.16 W
VDD_1P8      1.8V       50 mA         0.09 W
VMOT        12.0V      800 mA         9.60 W
---------------------------------------------
Total load                            10.85 W
Source capacity (USB 5V @ 3A)         15.00 W
Headroom                               4.15 W (27%)  OK

Conversion losses (~85% buck efficiency):
  Total input draw ≈ 12.76 W → 2.55 A @ 5V   OK (under 3A)
```

**Flag problems early:**
- Total load exceeds source capacity → stop and renegotiate requirements
- Headroom < 15% → warn about thermal margins
- Battery runtime math: capacity_mAh / avg_draw_mA = runtime_hours
- If battery-powered, estimate runtime and ask if it's acceptable

For beginners: explain why we check this now ("if the power math doesn't add
up, no amount of clever IC selection will fix it").

### 1d. Goals & Constraints

Ask:
- Target unit cost at volume? (or "doesn't matter, it's a prototype")
- Target production volume? (1-off prototype, 10 units, 1000+, etc.)
- Timeline or deadline?
- Regulatory or certification needs? (FCC, CE, UL, automotive, medical, etc.)
- Any must-use or must-avoid components/vendors?

### 1e. Comparable Products or Reference Designs

Ask:
- Are there existing products, dev boards, or reference designs that do
  something similar? (e.g., "like an Adafruit Feather but with CAN bus")
- Any open-source hardware projects to draw from?
- Datasheets or app notes you've already found?

### Summary Gate

After collecting all answers, present a structured **Requirements Summary**:

```
=== Requirements Summary ===

Project:       [name]
Application:   [description]
Environment:   [consumer/industrial/etc.]
Form factor:   [constraints]

Interfaces:    [list]
Sensors:       [list]
Actuators:     [list]

Power source:  [description]
Voltage rails: [list with estimated currents]
Battery:       [charging? type?]

Volume:        [quantity]
Budget:        [target cost or "prototype"]
Certifications: [list or "none"]

Comparables:   [list]
```

Ask: **Does this look right? Anything to add or change?**

Iterate until the user confirms.

### Summary-risk. Complexity & Risk Flags

After the user confirms the requirements summary, automatically scan for
design areas that are harder than average. Present any flags found:

```
=== Complexity Flags ===

  ⚠ HIGH-SPEED DIFFERENTIAL: USB 3.x or Ethernet requires controlled-
    impedance routing and a 4-layer stackup. This adds PCB cost and
    requires careful layout — it can't be fully autorouted.

  ⚠ RF / ANTENNA: WiFi/BLE with a PCB antenna or external antenna
    needs RF matching and ground plane management. Expect manual
    tuning and possibly a VNA for validation.

  ⚠ MIXED-SIGNAL: Combining analog sensors with digital/switching
    circuits requires careful ground partitioning and power filtering.
    Layout matters more than schematic here.

  ⚠ HIGH CURRENT (>2A per rail): Power traces need width calculations,
    thermal relief, and possibly copper pours. May need thermal vias
    under regulator pads.

  ⚠ BATTERY + CHARGING: Adds a charging IC, protection circuit, and
    fuel gauge considerations. Safety implications for Li-ion/LiPo.

  ✓ No certification flags for hobby/prototype use.
```

Only show flags that apply. For each flag:
- Explain what it means in plain language (especially for beginners)
- State whether Circuit Weaver can handle it automatically or if it needs
  manual EE work
- Ask if the user wants to proceed, simplify, or get more details

If no flags apply, say so: "This design is straightforward — no special
complexity concerns."

### Summary-test. Test & Debug Strategy

Before moving to IC selection, ask about testability. Many users forget this
and regret it when the board arrives and they can't debug it.

Ask:
- **Debug interface:** Do you need SWD/JTAG header for MCU debugging?
  (Suggest: yes, even for prototypes — it's a $0.20 header that saves hours)
- **Serial console:** UART header for debug logging?
  (Suggest: yes, expose TX/RX/GND on a 3-pin header)
- **Power LEDs:** LED on each voltage rail to confirm power is up?
  (Suggest: yes for prototypes, DNP for production)
- **Test points:** Exposed pads on critical nets for oscilloscope probing?
  (Suggest: at minimum on power rails and clock signals)
- **Spare GPIO:** Break out 2-4 unused MCU pins to a header for rev2 features?
  (Suggest: yes — costs nothing and enables future flexibility)

For beginners: explain why each matters. "An LED on your 3.3V rail costs
$0.02 and immediately tells you if power is working when you first plug in."

For professionals: present as a compact checklist, defaults all yes, let them
trim.

Add confirmed debug/test features to the requirements summary.

---

## Step 2 — IC Selection & Research

**Goal:** Use AI reasoning to identify the primary ICs, then kick off
research to validate and enrich selections before BOM construction.

### 2a. AI-Driven IC Reasoning

Based on the requirements summary, reason through the design and propose
primary ICs for each functional block:

- **MCU / processor** — Match peripherals, memory, package, ecosystem
- **Power management** — Buck, boost, LDO, charger ICs based on rails and source
- **Communication ICs** — WiFi/BLE modules, Ethernet PHY, CAN transceivers, etc.
- **Sensor ICs** — Match specifications to requirements
- **Driver ICs** — Motor drivers, LED drivers, display drivers
- **Protection** — ESD, overcurrent, reverse polarity

For MCUs specifically, also consider the **firmware & software ecosystem**:
- **Toolchain:** Arduino, ESP-IDF, STM32CubeIDE, Zephyr RTOS, PlatformIO, etc.
- **SDK maturity:** Is the SDK well-documented? Active community? Stable releases?
- **Debugger support:** SWD/JTAG support, compatible probes (J-Link, ST-Link, etc.)
- **RTOS compatibility:** FreeRTOS, Zephyr, NuttX — if real-time is needed
- **Language support:** C/C++, MicroPython, Rust, CircuitPython
- **OTA update capability:** If the device needs field updates

Ask the user: **What's your firmware development preference?** (Arduino IDE,
PlatformIO, vendor SDK, or "whatever is easiest"). Factor this into MCU choice —
a technically superior MCU with a bad SDK is worse than a modest one with
great tooling.

For each proposed IC, explain **why** it was chosen:

```
=== Proposed IC Selection ===

MCU: ESP32-S3-WROOM-1 (N16R8)
  Why: WiFi + BLE built-in, sufficient GPIO for your sensor array,
       large community, good availability, JLCPCB basic part

Power: TPS563200 (5V→3.3V buck, 3A)
  Why: Wide input range covers USB 5V with margin, high efficiency
       at your current draw, SOT-23-6 keeps it small

Sensor: BME280
  Why: Temp + humidity + pressure in one package, I2C, matches your
       environmental monitoring requirement

[... etc for each block ...]
```

Ask: **Do these selections look reasonable? Want me to research alternatives
for any of them?**

### 2b. Parallel Research Jobs

For each confirmed IC, kick off research to gather:

1. **Datasheet review** — Verify pinout, electrical specs, recommended circuit
2. **Application circuit** — Extract reference design from datasheet
3. **Availability check** — Stock at DigiKey, Mouser, LCSC (use distributor skills)
4. **Alternative parts** — At least one pin-compatible or functional alternative
5. **Known issues** — Errata, common design pitfalls, community reports

Use the `digikey`, `mouser`, and `lcsc` skills to search for parts and check
stock. Use the `ee` skill for any calculations (power budgets, filter values,
thermal checks).

Present research results per IC:

```
=== Research: ESP32-S3-WROOM-1 ===

Sourcing:
  DigiKey:  In stock (2,400+ units), $3.15 @ qty 1
  Mouser:   In stock (800+ units), $3.22 @ qty 1
  LCSC:     In stock (JLCPCB basic), $2.85 @ qty 1

Reference circuit: See datasheet Section 4.2
  - Requires 3.3V rail, 500mA peak during TX
  - 10uF + 100nF decoupling on VDD
  - EN pin needs RC delay (10k + 1uF)
  - USB D+/D- need 22R series resistors

Alternatives:
  - ESP32-C3-MINI-1: Cheaper, single-core, fewer GPIO (if you can trim pins)
  - STM32WB55: ST ecosystem, better low-power, no WiFi (BLE only)

Known issues:
  - GPIO 12 must be LOW at boot (strapping pin)
  - ADC2 unavailable when WiFi active
```

### 2b-thermal. Thermal Checks on Power Components

For every power IC (buck, boost, LDO, charger, motor driver), run a thermal
sanity check using the `ee` skill formulas:

```
=== Thermal Check: TPS563200 (3.3V buck) ===

Input:  5V @ ~380mA (estimated input draw)
Output: 3.3V @ 350mA
Efficiency: ~88% (from datasheet at this load point)
Power dissipated: Pin - Pout = 1.90W - 1.16W = 0.74W

Package: SOT-23-6 (θJA ≈ 150°C/W without copper pour)
Junction temp: 25°C + 0.74W × 150°C/W = 136°C  ← OVER LIMIT (125°C max)

With recommended copper pour (θJA ≈ 55°C/W):
Junction temp: 25°C + 0.74W × 55°C/W = 65.7°C  ← OK (59°C margin)

→ Copper pour under this IC is MANDATORY. Flag for PCB layout.
```

**Flag thermal problems immediately:**
- Tj > 100°C → warn, suggest copper pour or heatsink requirement
- Tj > Tj_max → stop, suggest a different package or IC
- LDO with large Vin-Vout drop at high current → calculate Pdiss and flag
- Motor drivers → check Rds(on) × I² heat at operating current

For beginners: explain that "the chip has to get rid of the power it wastes as
heat, and small packages can only dump so much heat into the board."

### 2b-leadtime. Lead Time & Availability Reality Check

After gathering stock data for all ICs, present a consolidated availability
summary:

```
=== Supply Chain Summary ===

Part                    DigiKey    Mouser     LCSC       Lead Time
--------------------------------------------------------------------
ESP32-S3-WROOM-1        2,400+     800+      In stock    Immediate
TPS563200               5,200+     3,100+    In stock    Immediate
BME280                  150        0          In stock    ⚠ Low stock
DRV8833                 0          0          42 units    ⚠ 16 weeks

⚠ DRV8833: Out of stock at major distributors. Lead time 16+ weeks.
  Options:
  1. Use alternative: TB6612FNG (pin-compatible, in stock)
  2. Order from LCSC now (42 remaining)
  3. Wait for restock (check distributor ETAs)

⚠ BME280: Low stock at DigiKey (150 units). Order soon or identify
  alternative (BMP280 if humidity not needed, SHT40 for better accuracy).
```

**Flag any part with:**
- Zero stock at all checked distributors → blocker, must find alternative
- Stock < 2× order quantity → warn about ordering soon
- Lead time > 4 weeks → warn, ask if timeline allows it
- NRND (Not Recommended for New Design) or EOL status → blocker

Ask after presenting all research: **Any ICs you want to swap or dig deeper on?**

### 2c. Subcircuit Template Matching

Check which of the confirmed blocks map to existing `circuit_weaver` subcircuit
templates (there are 30+ in `src/circuit_weaver/subcircuits/`):

- buck, boost, buck_boost, ldo, charge_pump, power_mux
- usb, ethernet, can_transceiver, rs485_transceiver
- motor_driver, relay_driver, led_driver, display_driver
- crystal_oscillator, clock, i2c_bus, opamp, audio_amplifier
- sensor_frontend, current_sense, battery_monitor, battery_charger
- mosfet_switch, driver, protection, adc, dac

Report which blocks have templates and which will need custom definition:

```
Template matches:
  [x] Power: buck (TPS563200)         -> subcircuits/buck.py
  [x] Power: ldo (TLV75533)           -> subcircuits/ldo.py
  [x] Sensor: sensor_frontend (BME280) -> subcircuits/sensor_frontend.py
  [x] Comms: usb (USB-C)              -> subcircuits/usb.py

Custom blocks needed:
  [ ] MCU: ESP32-S3 — will use component_db + manual pin mapping
  [ ] Custom analog frontend — no matching template
```

---

## Step 3 — BOM Assembly & Sourcing Preferences

**Goal:** Build the BOM with user input on manufacturing, vendors, and budget.

### 3a. Manufacturing Intent

Ask:
- **Where do you plan to manufacture?**
  - Hand-solder prototype at home
  - JLCPCB (economic or standard assembly)
  - PCBWay
  - Local PCB house (specify)
  - Other (specify)

- **Assembly level?**
  - Bare PCB only (you solder everything)
  - Partial assembly (fab places SMD, you do through-hole)
  - Full turnkey assembly

- **PCB specs?**
  - Layer count preference? (2-layer is cheapest, 4-layer for complex designs)
  - Any controlled impedance needs? (USB, Ethernet, RF)
  - Board thickness? (standard 1.6mm unless specified)
  - Surface finish? (HASL is cheapest, ENIG for fine-pitch)

### 3b. Vendor & Sourcing Preferences

Ask:
- **Preferred distributors?** (or "whatever is cheapest")
  - DigiKey (fast US shipping, best for prototypes)
  - Mouser (similar to DigiKey, good international)
  - LCSC (cheapest, best for JLCPCB assembly)
  - No preference / mix-and-match

- **Budget constraints?**
  - Target BOM cost per board?
  - Maximum spend for this prototype run?
  - Number of boards for first run?

- **Part preferences?**
  - Prefer JLCPCB basic parts where possible? (cheaper assembly fee)
  - Prefer automotive-grade parts?
  - Any approved vendor list (AVL) to follow?
  - Preferred passive sizes? (0402 for density, 0603 for hand-solder, 0805 for easy rework)

### 3c. Real Spec Assembly (Scaffold + Apply-Patch Workflow)

Build the YAML spec incrementally using the CLI commands:

**Step 1: Scaffold the first block**

Identify the primary power source and scaffold the first IC:

```bash
circuit-weaver scaffold --template buck --ref U1 --output design.yaml
```

This creates a minimal spec with the first power block. Present the output to the user and confirm it looks reasonable before proceeding.

**Step 2: Add blocks iteratively with apply-patch**

For each additional IC, create a patch JSON file and apply it:

```bash
# patch_u2_ldo.json
{
  "upsert_blocks": [
    {
      "id": "U2_ldo",
      "section": "power",
      "kind": "template",
      "template_type": "ldo",
      "ref": "U2",
      "params": {
        "vin": 3.3,
        "vout": 1.8,
        "vin_net": "VDD_3P3",
        "rail_name": "VDD_1P8"
      }
    }
  ]
}

# Apply the patch
circuit-weaver apply-patch design.yaml patch_u2_ldo.json --output design.yaml
```

For each new block, present ONLY the newly-added components (from `diff.added_blocks`). Do NOT show the full updated spec — it's too verbose.

```
=== Block Added: U2 LDO ===

U2  TLV75533  1.8V → 3.3V LDO, 500mA
  Bypass caps: C2, C3 (100nF on input/output)
  Enable pulled to VDD_3P3

Ready for next block? (or 'done' to move to validation)
```

Repeat this for each IC until all blocks are added.

**Step 3: Cost Estimation (Optional)**

Once all blocks are added, generate an estimated BOM cost at target quantities:

```bash
circuit-weaver cost-bom design.yaml --qty 1,10,100
```

Present the pricing summary (prices by quantity break), noting any parts without LCSC codes that need manual sourcing.

---

## Step 4 — Schematic Generation

**Goal:** Generate the KiCad schematic and set expectations for what comes out.

### 4a. Pre-Generation Review

Before generating, confirm the YAML spec with the user:

```
I'm about to generate the KiCad schematic from this spec:

  Project:    [name]
  Sheets:     [estimated count] (1 top-level + N sub-sheets)
  Components: [count] active + [count] passive
  Power tree: [description]
  Buses:      [I2C, SPI, UART, etc.]

Output directory: [path]
```

Ask: **Ready to generate? Any last changes?**

### 4b. Generate & Validate

Run the generation pipeline:

```bash
# Generate artifacts
circuit-weaver generate [spec.yaml] --output [output_dir]

# Validate the generated output
circuit-weaver validate [spec.yaml]
```

Report results:

```
=== Generation Results ===

Files created:
  [x] project.kicad_sch          (top-level schematic)
  [x] power.kicad_sch            (power sheet)
  [x] digital.kicad_sch          (MCU + peripherals)
  [x] project_report.md          (design report)
  [x] placer_hints.json          (PCB placement guide)

Validation:
  Structural:      PASS (12/12 checks)
  Electrical:      PASS (8/8 checks)
  Implementation:  PASS (6/6 checks) [or WARN with details]
  Presentation:    PASS (4/4 checks)
```

### 4c. What's Automated vs. Manual

**Be explicit about what the user still needs to do.** This is critical for
setting expectations:

```
=== What's Done vs. What You'll Finish ===

DONE (generated automatically):
  - All symbol placements with correct pin mappings
  - Power connections and decoupling capacitors
  - Net labels for all buses (I2C, SPI, UART, etc.)
  - Hierarchical sheet structure
  - Support passives (pull-ups, bypass caps, RC filters)

YOU'LL FINISH IN KICAD (~10-20% of the schematic work):
  - Review net label names for clarity
  - Adjust component positions for readability
  - Add any project-specific notes or annotations
  - Verify pin assignments match your physical layout intent
  - Run ERC and resolve any remaining warnings
  - Fine-tune sheet aesthetics (alignment, spacing)

Open the schematic:
  kicad [output_dir]/[project].kicad_sch
```

---

## Step 5 — Design Review Checkpoint

**Goal:** Catch expensive mistakes before committing to PCB layout. This is
the cheapest place to find problems — a schematic fix costs minutes, a PCB
respin costs weeks and dollars.

### 5a. Automated Review

Run the generated schematic through the validation tools:

```bash
# Full schematic validation
circuit-weaver validate [spec.yaml] --enhanced --verbose

# Full confidence report (validation + simulation + thermal + DFM + cross-reference)
circuit-weaver confidence [spec.yaml] --run-sims -o [output_dir]/confidence_report.html
```

**Confidence Report:** The `confidence` command aggregates all available checks
into a single 0-100 score with a readiness classification (ready_for_fab /
needs_review / not_ready). Present the terminal output to the user. If an HTML
output path was given, mention the HTML file for detailed review in a browser.

Parse the validation report (categories level=error or level=warning) and present a structured review summary:

```
=== Design Review ===

Power Tree:
  [x] All rails have valid sources
  [x] Decoupling caps on every IC power pin
  [x] Enable pins properly connected
  [ ] ⚠ No bulk capacitor on 3.3V rail — recommend 10-47µF near source

Connectivity:
  [x] All MCU peripheral pins connected to intended targets
  [x] I2C bus has pull-ups (4.7kΩ to 3.3V)
  [x] SPI bus CS lines properly assigned
  [ ] ⚠ UART TX/RX — verify TX→RX crossover (pin names can be ambiguous)

Protection:
  [x] USB VBUS has overcurrent protection
  [ ] ⚠ No ESD protection on USB data lines — recommend TVS diode
  [ ] ⚠ No reverse polarity protection on power input

Debug & Test:
  [x] SWD header connected
  [x] UART debug header connected
  [x] Power LEDs on all rails
```

### 5b. Human Review Guidance

Tell the user what to check manually in KiCad:

```
=== Manual Review Checklist ===

Open the schematic in KiCad and verify:

  [ ] Pin assignments match your physical layout intent
      (e.g., I2C on pins closest to the sensor)
  [ ] Net names are meaningful (not just NET_001)
  [ ] No unintended connections (zoom in on dense areas)
  [ ] All ICs have correct pin-1 orientation markers
  [ ] Power flags on all power nets (avoids ERC warnings)
  [ ] Footprint assignments are correct for your sourced parts
      (SOT-23-3 vs SOT-23-5 is a common mistake)

If this is for a real product, consider having another engineer
review the schematic before proceeding to layout.
```

### 5c. Review Gate

Ask: **Have you reviewed the schematic and are you satisfied with it?**

- If issues found → help fix them, re-generate if needed, re-validate
- If satisfied → proceed to confidence check (Step 6)
- If they want peer review → suggest they share the .kicad_sch and come back

Do not let beginners skip this step. For advanced users, a quick "looks good,
moving on" is fine.

---

## Step 6 — Confidence & Simulation Check

**Goal:** Run all available checks in one pass to produce a single readiness
score before the user invests time in PCB layout.

### 6a. Run Confidence Dashboard

**This step runs automatically after the review gate passes. Do not skip it.**

```bash
# Run confidence report with simulations
circuit-weaver confidence [spec.yaml] --run-sims -o [output_dir]/confidence_report.html

# For enhanced validation (includes cross-reference audit)
circuit-weaver validate [spec.yaml] --enhanced --verbose
```

The confidence dashboard aggregates:
1. **Electrical validation** — all 14 checks (decoupling, enable pins, power budget, thermal, SI)
2. **Circuit simulation** — power supply transient/AC analysis via ngspice
3. **Thermal analysis** — junction temperature vs Tj_max for all power ICs
4. **Cross-reference audit** — spec vs schematic, BOM completeness, duplicate refs
5. **ERC** — KiCad electrical rule check (if KiCad CLI installed)

### 6b. Present Results

Show the confidence score and readiness to the user:

```
Score:      82/100 (B)
Readiness:  NEEDS REVIEW

Sections:
  [OK] Electrical Validation     90/100 (A)
  [OK] Simulation                75/100 (C)
  [OK] Thermal Analysis         100/100 (A)
  [--] Signal Integrity            N/A (skipped)
  [--] Manufacturing (DFM)         N/A (skipped)
  [OK] Cross-Reference Audit     85/100 (B)
  [--] ERC/DRC                     N/A (skipped)
```

**Interpretation guidance:**
- **ready_for_fab** (80+, no blockers): "Your design looks solid. Proceed to PCB layout."
- **needs_review** (60-80): "Design works but has issues worth addressing first."
- **not_ready** (<60 or blockers): "Fix the blockers before investing in PCB layout."

For beginners: explain what each section means and why the score matters.
"This score tells you how confident we are that the circuit will work correctly
when you build it. A higher score means fewer surprises when the board arrives."

### 6c. Address Action Items

If blockers or high-priority action items exist, walk through each one:

1. Present the action item with context
2. Offer to fix it (loop back to the relevant step: Step 2 for IC changes, Step 3 for passives)
3. Re-run confidence after fixes to verify improvement

Ask: **Want to address any of these items before moving to PCB layout?**

If the user wants to proceed despite issues, note the decision in the log.

**Log:** `[Step 6] Confidence: {score}/100 ({grade}), readiness: {readiness}`

---

## Step 7 — PCB Layout Guidance & Next Steps

**Goal:** Guide the user into the PCB phase with clear expectations about
what can be scripted vs. what requires manual KiCad work.

### 7a. PCB Kickoff — Automated Layout Assistance

The generated PCB file has initial component positions. Before manual routing,
run the automated layout tools:

```bash
# 1. Optimize placement (simulated annealing for thermal/SI/DFM)
circuit-weaver optimize-placement [spec.yaml] -o [output_dir]

# 2. Generate interactive placement viewer (HTML with thermal heatmap)
circuit-weaver placement-viewer [spec.yaml] -o [output_dir]/placement.html

# 3. Optional: Export editable SVG placement (for Inkscape/CorelDRAW editing)
circuit-weaver generate [spec.yaml] -o [output_dir] --svg-placement
```

Present results:

```
=== PCB Layout Preparation ===

Automated steps completed:
  [x] Placement optimized (thermal + SI + DFM scoring)
  [x] Interactive viewer: output/placement.html
  [x] Placement PCB: output/main_placement.kicad_pcb

Open placement.html in a browser to review component positions,
net connections, and thermal heatmap before routing.

WHAT YOU'LL DO IN KICAD:
  - Board outline and edge cuts
  - Fine-tune placement for routing convenience
  - Route traces (power first, then signals)
  - Ground/power planes and zone fills
  - Silkscreen labels and polarity markers

WHAT WE CAN HELP WITH:
  - Trace width suggestions (use /ee skill)
  - Layer stackup recommendation (2-layer vs 4-layer)
  - Autorouting of non-critical nets (see 7c below)
```

If mechanical constraints were captured in Step 1a-mech, incorporate them now:
- Board outline matches enclosure dimensions
- Mounting holes at specified positions
- Connectors placed on specified edges
- Height-restricted zones marked as keep-outs

### 7b. SVG Placement Editor (Optional)

For users who want to visually drag components in an editor before routing:

```bash
# Export placement as editable SVG
circuit-weaver generate [spec.yaml] -o [output_dir] --svg-placement

# User edits output/placement.svg in Inkscape...

# Import edited positions back into KiCad PCB
circuit-weaver import-placement output/main_placement.kicad_pcb --svg output/placement.svg
```

For beginners: "This lets you drag components around in a drawing program and
we'll update the PCB file automatically."

### 7c. Routing Guidance

Based on the design:

- Identify critical nets that need manual routing (power, USB, high-speed)
- Suggest trace widths for power vs signal nets (use `ee` skill calculations)
- Recommend layer stackup if 4-layer
- Identify candidates for autorouting (non-critical signal nets)

**Autorouting with Freerouting (Optional)**

If the user has Freerouting installed, offer to auto-route the PCB:

```bash
circuit-weaver autoroute output/[project].kicad_pcb -o output/routed.kicad_pcb
```

**Note:** Freerouting must be installed separately. Best for non-critical signal
nets — power and high-speed traces should be routed manually. For detailed
autorouting workflow options, see the `/autoroute` project-skill.

### 7d. DFM Check (Recommended Before Ordering)

Run DFM checks against the target manufacturer:

```bash
# Check against JLCPCB rules (default)
circuit-weaver check-dfm output/main_placement.kicad_pcb

# Check against PCBWay rules
circuit-weaver check-dfm output/main_placement.kicad_pcb --profile pcbway
```

If DFM issues are found, present them and offer to fix (adjust trace widths,
via sizes, clearances).

#### Related Project-Skills

For advanced PCB workflows beyond what the wizard covers:
- `/kicad_pcb_place` — constraint-based placement with pcbnew API integration
- `/autoroute` — detailed Freerouting workflow with DSN/SES file management
- `/kicad_pinmap` — pin-to-net audit and verification
- `/kicad_hierarchy` — hierarchical schematic sheet management
- `/kicad_gen` — programmatic schematic generation for large ICs (BGAs)

### 7e. Manufacturing Checklist

Based on Step 3 manufacturer choice, present the final checklist:

```
=== Pre-Order Checklist ===

  [ ] Confidence score >= 80 (circuit-weaver confidence design.yaml --run-sims)
  [ ] DFM check clean (circuit-weaver check-dfm board.kicad_pcb)
  [ ] ERC clean in KiCad
  [ ] DRC clean in KiCad
  [ ] BOM exported (use /bom skill)
  [ ] Gerbers exported and visually inspected
  [ ] CPL (component placement list) generated for assembly
  [ ] Design rules match manufacturer minimums
  [ ] Silkscreen readable, polarity marked
  [ ] Test points accessible
  [ ] Board dimensions verified against enclosure
```

Reference the `jlcpcb` or `pcbway` skill for manufacturer-specific DFM rules.

### 7f. Revision Planning & Future-Proofing

Before the user commits to fabrication, help them think about the next revision.
This is especially valuable for beginners who don't realize rev1 is almost never
the final board.

```
=== Revision Planning ===

This is Rev 1 of your design. Here's how to set yourself up for Rev 2:

Version tracking:
  - Add "Rev 1.0" and the date to the silkscreen
  - Tag this point in git: git tag -a v1.0 -m "Rev 1.0 sent to fab"
  - Keep your YAML spec, generated files, and BOM CSV committed

Built-in flexibility (already in your design):
  [x] Spare GPIO broken out to header (Step 1 test strategy)
  [x] Debug UART accessible
  [x] SWD header for firmware development

For Rev 2, common changes to plan for:
  - Component swaps based on testing results
  - Layout tweaks for signal integrity or thermal issues
  - Additional features from your "nice to have" list
  - Cost optimization (swap extended JLCPCB parts for basic ones)

For future revisions, keep your YAML specs in git so you can diff changes.
```

Ask: **Ready to order, or do you want to add any future-proofing features
before we finalize?**

---

## Conversation Style Guide

Throughout the wizard, follow these principles:

1. **One topic at a time.** Don't ask 10 questions in one message. Group 2-3
   related questions, wait for answers, acknowledge, then move on.

2. **Suggest sensible defaults.** "For a prototype, I'd suggest 0603 passives
   and HASL finish — does that work?" is better than "what passive size and
   surface finish do you want?"

3. **Show your reasoning.** When recommending an IC or topology, briefly
   explain why. Users learn from this and catch bad assumptions early.

4. **Summarize before proceeding.** At each step boundary, show what you
   captured and ask for confirmation before moving to the next step.

5. **Save progress.** After Steps 1 and 2, offer to save a draft YAML spec
   so the user doesn't lose work if the session ends. After Step 3, the
   spec should be saved to disk.

6. **Be honest about limitations.** If the engine can't handle something
   (e.g., a very unusual topology), say so and suggest the manual path.

---

## Related Skills

| Skill | Used in step | Purpose |
|-------|-------------|---------|
| `ee` | 1, 2, 7 | Calculations: power budget, filter values, thermal, trace widths |
| `digikey` | 2, 3 | Part search, stock check, datasheets |
| `mouser` | 2, 3 | Alternative sourcing |
| `lcsc` | 2, 3 | Production sourcing, JLCPCB parts |
| `bom` | 3 | BOM export and order file generation |
| `kicad` | 4, 5 | Schematic analysis, validation, and design review |
| `jlcpcb` | 3, 7 | DFM rules, assembly ordering |
| `pcbway` | 3, 7 | Alternative fab DFM rules |
| `sim` | 6 | Circuit simulation (SPICE power/signal analysis) |
| `kicad_pcb_place` | 7 | Advanced constraint-based PCB placement |
| `autoroute` | 7 | Freerouting PCB autorouting workflow |
| `kicad_validate` | 5, 6 | Cross-reference validation audit |
| `kicad_pinmap` | 5 | Pin-to-net audit and verification |

---

## Resuming a Wizard Session

If the user returns and says "continue my design" or "where were we":

1. Look for a saved YAML spec in the project directory
2. Determine which step was last completed based on spec completeness:
   - Has requirements but no ICs → resume at Step 2
   - Has ICs but no sourcing data → resume at Step 3
   - Has full spec but no generated files → resume at Step 4
   - Has generated schematics but no review → resume at Step 5
   - Has reviewed schematics → resume at Step 6 (confidence check)
   - Has confidence report → resume at Step 7 (PCB layout)
3. Summarize the current state and confirm with the user before proceeding
