KiCadRoutingTools: Skill for Claude Code

Diagnose Routing Failures

When this skill is invoked with a board file and routing log file(s), root-cause the failures and produce a targeted retry command. Routing runs should always be captured with 2>&1 | tee /tmp/<step>.txt so the logs are available.

Step 1: Parse the Structured Outputs

JSON summary

grep "JSON_SUMMARY" /tmp/route_output.txt | sed 's/.*JSON_SUMMARY: //' | python3 -m json.tool

Key fields:

• failed_single: failed single-ended net names — nets with NO result at all
• open_single: nets that KEPT a result whose copper still leaves pads disconnected (non-multipoint only; a multipoint shortfall is already the pad deficit). Always read this alongside failed_single — a board can ship open copper with failed_single: [], so a run is only clean when both are empty. These nets also appear by name in failed_multipoint.
• terminal_restores: {net: outcome} for rip victims restored at terminal failure. full is the only success; full_open restored copper that never covered every pad, and stub kept only the escape stubs — both ship broken and are worth reporting as failures with a distinct cause (the reroute failed and the pre-rip copper could not be fully put back).
• stacked_copper: same-net duplicate copper KiCad's DRC will never flag. Not a routing failure, but if present, say so — it is invisible to every other check. It is censused before the plane finalize; route.py's end-of-run dedup (#162) then removes exact same-span copies, so read check_weird on the output for what shipped.
• close_same_net_vias (#1414): same-net via pairs this run laid under the drill hole-to-hole floor (check_drc VIA-DRILL-HOLE); different_net_crossings (#1375): different-net tracks crossing on one layer among the run's copper (a short; check_drc SEGMENT-CROSSING). Both ship despite failed 0: say so.
• failed_multipoint: nets with unconnected pads, including pad coordinates
• blockers: per still-failed net, the run's LAST frontier blocking analysis (#409): {net, stage, blocked_by: [{net, blocked_count, unique_cells, track_cells, via_cells, near_target_cells, near_source_cells}], more?} — "net X failed BECAUSE nets Y,Z wall it off" as data. A net boxed in by PRE-EXISTING copper gets an entry with stage: "preexisting" whose blocked_by items carry only {net, preexisting: true}. Key absent when no failed net has an attributable blocker.
• boxed_in: per failed net whose search died almost at once with nothing rippable — {net, verdict: "boxed_in_static", iterations, geometry: {grid_step, clearance, track_width, via_diameter}}. Static obstacles (neighbouring pads + clearance), not congestion: the lever is a finer grid or smaller clearance/track, unless geometry is already at the floor.
• fanout_dropped: per failed net with a ball its fanout never escaped — {net, pad, component, plane_like, pads} (#652). The fix is upstream of this step: re-run the fanout for that net, or, when plane_like, the plane.
• sealed_by_snpc: per failed net whose last legal via site was closed by this run's own --same-net-pad-clearance (#907) — {net, pad, same_net_pad_clearance, required_surround_mm, escape_reach_mm, aperture}. Re-run with --same-net-pad-clearance 0 (a via then placed in a pad is stamped filled+capped, #962), or widen the channel in placement.
• multipoint_pads_connected vs multipoint_pads_total: connection success rate. Derived from the final-board union-find (the same check check_connected.py uses), so it credits pads reached via planes/zones, fanout stubs, and rip-up/retry reroutes and agrees with check_connected.py (issue #184).
• pad_pairs_connected / pad_pairs_total: pad-pair routability tallies (#409 follow-up; PRR = connected/total downstream). Per graded multi-pad net: connected = |pads| − pad components from the same final-board union-find, total = |pads| − 1 (clamped so a net whose pads are invisible to the union-find grades as connected). Population: the routing scope after already-routed filtering, pre-existing rippable nets the run graded, and disturbed coverage-gate nets. NOT reconcilable with multipoint_edges_* (those count component-MST edges — pre-existing copper joins terminals first, so there are fewer edges than pad pairs). Each summary's are computed before the final reconciliation, like blockers; the merged document (--json-out, JSON_SUMMARY_MIN) takes a still-broken net's tally from the end-of-run re-grade of the shipped board, so a net broken after the last summary is listed too (#1309). Counted per outer board outline (#479): a gap between two outlines is neither a routable pair nor an open one.
• pad_pairs_open: per net shipping a pair deficit: {net, pairs_connected, pairs_total, outcome, open_subtype}, sorted by net; key absent when none. outcome is always "open" today — route.py runs no DRC, so a route-time failure is definitionally an open; shorts are check_drc.py's domain and the field exists so a DRC-integrated emitter can add "short" without a schema break. (Distinct namespace from route_diff pair_reports.outcome.) open_subtype: collision_refused (left open because restoring the ripped track would collide — a short was averted, #134), coverage_gate (disturbed out-of-scope net shipping broken), unrouted (scope net, no result at all), partial (routed a result but left pads disconnected). Join with blockers on net for cause + outcome per failed net.