mech-ai/tools/model-diagnostics/BrepFaultProbe/LESSONS.md

BrepFaultProbe Lessons

This file records the failure patterns that have already appeared in this project.

1. Do not require explicit labels when the geometry can be inferred

The sleeve-removal b case failed at first because the judge only accepted edges explicitly tagged as push_face.

Correct rule:

• accept explicit labels when present
• also infer the same feature from B-rep structure
• treat explicit labels as strong evidence, not the only evidence

2. Keep candidates separate from decisions

*_candidate is evidence, not a final answer.

If the pipeline mixes candidate evidence with final template matching, the judge will drift into false negatives or false positives.

3. Outer frame is not a functional feature

For 2D sketch graphs, the outer frame can be a valid drawable loop, but it does not by itself mean the image contains a meaningful machine-design feature.

Always separate:

• background outer frame
• actual functional loops
• inferred feature loops such as holes, slots, bosses, and ports

4. Image and model must share a canonical middle form

Raw raster edges and true section edges are not directly comparable.

The stable comparison point is:

• vertices
• drawable edges
• paths
• loops
• regions
• relations
• dimensions

5. Hatch lines are annotations

Section hatches must be excluded from drawable contour edges.

If they are treated as normal edges, the sketch graph becomes noisy and the loop/path matcher starts inventing structure.

6. One sample is not enough

A rule that works on one positive case may still fail on:

• unrelated cases
• weak candidates
• cases with no explicit role tags
• cases whose functional feature is expressed by a different geometric cue

Always verify at least:

• a positive case
• a negative case
• an unrelated case
• a weak/noisy case

7. Current open risk

b has been upgraded to infer push-face evidence from B-rep topology.

c and d still depend more on explicit region semantics, so they can repeat the same failure mode if the upstream extractor does not label them clearly enough.

8. Textbook image rules must name the exact measurable geometry

Failure pattern:

• A textbook rule says a "diameter" should be larger, but the drawing contains many diameters.
• If the extracted knowledge only says boss_diameter > cover_diameter, the B-rep pipeline may measure the wrong diameter, such as an inner hole, register-fit diameter, bearing-seat bore, bolt hole, or bolt-circle diameter.

Correct rule:

• The knowledge chunk must explicitly define the compared geometry by position and boundary role.
• Use terms such as mounting-side outer contour, maximum outer diameter, cast boss outer boundary, and minimum boundary margin.
• Also list excluded diameters when they are plausible distractors.

For Chapter 18.2.1, the rule is:

• compare the end cover mounting-side flange outer boundary or maximum outer diameter
• against the cast housing boss/recess/allowance-region outer boundary or maximum outer diameter
• require the housing cast boss boundary to contain the cover flange boundary with casting-position-error allowance
• do not compare the cover inner hole, register-fit diameter, bearing-seat bore, bolt holes, or bolt-circle diameter

Every image-to-rule extraction should preserve this level of specificity so model-side B-rep facts can be selected without ambiguity.