b123d-repair

Repair Invalid Geometry with build123d (b123d-repair)

Use this skill when validate() or the export() gate reports FAIL on a shape — an imported STEP that arrives broken, or a solid your own construction damaged — and the goal is a watertight, manifold, BRepCheck-valid solid that passes the export gate without changing the geometry beyond the defect itself.

Every recipe here was proven on a real defective part; each entry says when it applies, when it fails, and what to try next. Work the ladder in order — the cheap fixes first — and verify every attempt with the export gate, not validate() alone (Step 2 explains why).

This skill is deliberately an agent-authored repair workflow, not an automatic healer. The MCP server should help you write better build123d/OCP code by answering:

• validate() / export() — is the current or written shape structurally acceptable?
• locate_gate_defects() — where is the failing face, edge, or mesh defect?
• find_bored_bosses() — when a failed edit involved extending a bored boss, which bore/cap candidates exist, and whether the cap is split across several faces?
• repair_advice() — which field-proven, generic repair/edit recipe fits this defect and requested goal, with acceptance checks and stop conditions?
• this repair skill — which generic repair pattern fits that defect class?

The geometry-changing repair itself should be explicit code in execute(), with named variables, printed measurements, save_snapshot() / rollback points, and a visible volume/bbox/gate audit. Do not delegate the repair to an opaque MCP tool that silently manipulates the B-rep and returns a shape; that prevents the agent from reasoning about design intent and makes benchmark success hard to distinguish from accidental geometry surgery.

Step 0 — Diagnose before cutting

Do not apply repairs blind. First identify the defect class and its location.

1. Read the gate output precisely. The FAIL reason names the class, and the class picks the recipe:
   • B-rep is not well-formed (BRepCheck failed) → a malformed face (usually unorientable, zero-area, or reversed) — Step 1, rungs 1-4.
   • N open edge(s) — not watertight → unsewn/missing faces — rungs 4-5.
   • N non-manifold edge(s) → an edge shared by 3+ faces — usually a coincident-face construction defect; prefer re-construction (Step 4) over surgery.
   • mesh open edge(s) / mesh non-manifold / face(s) failed to tessellate with brep_valid: true → a mesh-only defect (a ~zero-area unmeshable face, or a self-touch) — rung 5.
   • face(s) failed to tessellate at a finer mesh deflection with brep_valid: true → a tolerance-sensitive mesh-only defect: the face meshes at the default gate deflection but fails when a downstream consumer asks for a finer mesh — rung 5, using the re-patch/re-sew variant.
   • vertex(es) where a tessellated edge endpoint misses its BREP vertex with brep_valid: true → a mesh-only defect too, but a different one from the two above: a previously-patched/healed face's boundary is topologically closed (so BRepCheck and even mesh open edge(s) can both read clean) but geometrically off-vertex by a fraction of a millimetre — rung 5, using its re-patch-at-tighter-tolerance variant, not the drop-and-sew one.
2. Get coordinates. locate_gate_defects() returns the failing edge/face's 3D position and B-rep identity — repair that exact spot, never chase the defect blind. Read its top-level diagnosis block too: primary_kind, diagnostic_classes, and repair_families tell you which rung to try first, while each defect's next_step says what explicit execute() repair to write and reminds you to verify the written STEP with export(). If the defect belongs to a known hard pattern, call repair_advice() with the gate output as error_text, the requested edit as goal, and the defect coordinates as context. Use the returned recipe as a checklist for your own execute() code; do not treat it as a geometry-mutating tool.
3. Localize the face when BRepCheck is the failure — build ONE analyzer over the whole solid, not one per face (locate_gate_defects() itself runs out-of-process specifically because per-face BRepCheck work "can run for minutes on a complex part"; reconstructing an analyzer per face inside execute() on a large import risks the same timeout):