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.
• 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. Key absent when no failed net has an attributable (routed-copper) blocker.
• 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). Computed before the final reconciliation, like blockers. Single-outline semantics for now (a cross-outline split counts as open pairs).
• 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.