kicad-workflow

name	kicad-workflow
description	Use when editing KiCad schematics or PCBs — adding/removing/modifying symbols, wires, labels, or footprints, or validating changes (ERC, netlist, DRC, baseline diff). Stage-1 functional workflow; pair with `kicad-tool` for commands. For visual/score polish use `kicad-sch-cleanup-loop` instead.

KiCad Workflow

Editing process for KiCad files: planning, sequencing, validating. Owns the how/when; commands and CLI shape live in kicad-tool — read it first via the Skill tool. Project-specific facts (top-level path, sheet inventory, stackup, partitioning) live in the consuming repo's hardware/ docs.

File types

File	Approach
.kicad_sch	kicad-tool sch query / sch edit
.kicad_pcb	kicad-tool pcb edit when available; otherwise minimal local S-expr edits
.kicad_pro	JSON edit only when needed; minimal
.kicad_prl	Do not edit unless explicitly asked
.kicad_sym	Keep in sync with the schematic's embedded lib_symbols when changing custom symbols (sch edit symbol add-pin does this automatically)

If sch edit / pcb edit lacks a write subcommand, extend kicad-tool first. Raw Edit/Write on .kicad_sch/.kicad_pcb is the last resort and requires explicit user approval.

Wire delete / replace — audit mid-span taps first

A wire can carry connections anywhere along its length — junctions, perpendicular wire endpoints, pin endpoints, label anchors — not only at its two endpoints. Endpoint-only stub replacement orphans mid-span taps; ERC misses it (the leftover junction keeps the count parity-clean).

Before any sch edit wire delete / replace:

1. Query the wire bbox with about 0.01 mm margin (sch query region).
2. Enumerate every tap.
3. Ensure the replacement reconnects each tap.
4. Validate via baseline-diff — its removed_nodes check is what actually catches this.

Stage 1 workflow

This skill is stage 1: functional editing. Score / layout cleanup is stage 2 (kicad-sch-cleanup-loop).

0. Plan and get approval (mandatory)

Bird's-eye self-check, three zoom levels — one sentence each:

• Board: does this change fit the project's critical path now, or should it wait?
• Sheet: what function does the region serve, and will the change ripple style-wise into a follow-up pass?
• Local: what does the area look like when done; what alternative framing might the request really mean?

Then state and wait for approval:

1. Goal — what the design should do (design terms, not "add wires").

2. Problem — what's missing/wrong, citing specific symbols/nets/pins (via sch query).

3. Approach — proposed change + alternatives + why this one. Smallest unit that meets the goal.

4. Placement — for each new/moved symbol, which existing symbol or net it should sit near and why. Apply project electrical-design rules (grouping, partitioning, decoupling near supply pins).

5. Layout sketch (ASCII art) — required — show both the current and proposed local layout side-by-side. Coordinates are supplementary; the sketch is the primary artifact for the user to spot orientation/topology issues before any edit runs.

   The sketch must show incident topology, not just symbol bodies: every wire stub off each drawn symbol, every junction in the bbox, every mid-span tap on shown wires. Distinguish real T-taps (perpendicular endpoint or co-located junction) from co-linear continuations (same-axis adjacent endpoint — not a tap). When adding to a group, copy one existing member's stubs into the proposed sketch (else the new pin↔rail stub gets forgotten and ERC fails unconnected). When deleting a wire, list every tap on it in the current sketch and how each is reconnected in the proposed.

   Current:                Proposed:
        VCC                     VCC
         │                       │
         ●── U2.VCC               ●── U2.VCC
                                  │
                                 ─┴─ C99 100nF
                                  │
                                  ●── GND
   

Skip only if (a) the user gave an exact single action ("move R5 to 100,50"), or (b) running under an autonomous-iteration context the user explicitly invoked. When in doubt, plan and wait.

1. Pre-edit baseline

Routine edits — one-shot validate is enough:

kicad-tool sch validate <top> --sheet <edited-child>

Non-trivial structural edits (wire delete/replace, hierarchy changes) — snapshot a baseline first to confirm connectivity, not just "ERC still passes":

kicad-tool sch validate <top> --save-baseline tmp/baseline   # before
kicad-tool sch validate <top> --baseline tmp/baseline        # after

Baseline diff exits non-zero on regression (new ERC errors, removed nets, removed nodes from existing nets).

2. Edit (functional)

Smallest change satisfying the request. Always pass --dry-run first via sch edit / pcb edit, then re-run without it.

Scope of stage 1: connectivity, nets, symbols, pins, values, hierarchy, ERC correctness. Do not chase sch inspect score, collisions, or wire-corner counts here — that is stage 2.

To spawn a new symbol instance: sch edit symbol add <sch> <lib_id> <REF> <X,Y> clones an existing same-lib_id sibling (unit 1, unmirrored) so lib_symbols stays consistent. For a lib_id that isn't yet embedded, pass --lib-file <library.kicad_sym> to import the definition and synthesize a fresh instance. For follow-up tweaks use sch edit symbol set-property (Value / Footprint / MPN) and sch edit symbol move (rotation / position).

To replace an existing symbol with a different lib_id (no direct command exists): sch edit symbol delete <REF> then sch edit symbol add <new_lib_id> <REF> <X,Y> [--lib-file ...]. Pin layout differs, so re-route the wires afterwards.

If the new edit happens to introduce obvious local mess (overlapping label, crossing wire) that blocks reading the diff, fix only that local mess. Anything broader belongs to the cleanup loop.

3. Validate

Re-run the validate / baseline command from step 1. When running stages individually:

• ERC / Netlist: always against the top-level (hierarchical ERC propagates into children). Never on a child sheet directly.
• Inspect: each edited sheet.
• PCB DRC: only when the board was edited; schematic parity is included by default.

4. Review

• Existing ERC violations are not failures; new ones are. Intentional new violations (e.g. a deliberately-dangling test label) are acceptable — call them out in the report.
• Netlist diff: visual-only edits should differ only in path/header metadata. For electrical edits, summarize the intended changes.
• Successful CLI exit ≠ correctness. ERC parity + expected netlist diff + score check (when relevant) = high confidence.
• git diff review: confirm Sheetfile references, net names, and that custom symbol changes appear in both embedded lib_symbols and the standalone .kicad_sym.
• A worse sch inspect score is acceptable in stage 1 if connectivity is correct; do not chase it here.

5. Hand off to stage 2 (visual cleanup)

Stage 1 ends once ERC and netlist are correct. If the user wants score/layout tightening on the edited sheet, hand off to kicad-sch-cleanup-loop with the sheet path.

Board changes

For .kicad_pcb:

• Keep stable: layers, setup, setup.stackup, Edge.Cuts, title block — unless the task explicitly targets them.
• High-risk fields: net, footprint, segment, via, zone.
• Run pcb drc after board edits; schematic/board parity is always included, and zones are always refilled + saved (kicad-cli does not refill on its own; stale fill = wrong report). Note it rewrites the .kicad_pcb. Read the resolved report path it prints (default is CWD-relative) and check the report's Created on line for freshness.
• Document known KiCad CLI limitations separately from true DRC violations.

Project-specific stackup and domain-separation rules live in the consuming repo's hardware/pcb/ docs.

Report format

ERC: pass (or: exit=N, same as before edit)
Netlist: intended changes only (or: identical / path-only diff)
Inspect: total=<score> collisions=<count>
PCB DRC: pass

On failure, include the failing stage, report path, and the first actionable issue:

FAIL: New ERC violation
  See tmp/erc.rpt
  First: ...