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

ModelDiagnosticVerifier Lessons

This file records diagnosis failures and the rule that prevents repeating them.

Failure 2026-06-19: 装配体2.SLDASM was wrongly diagnosed as problem

Context:

• 装配体2.SLDASM is the textbook b pass case for the tight-fit sleeve disassembly rule.
• The correct diagnosis is pass because the sleeve has an exposed axial push face, matching image example b.

Root cause:

• SectionBrepExtractor produced the important feature in SketchGraph.Dimensions, not in SketchGraph.Relations.
• The verifier consumed section relations but ignored dimension-derived candidates.
• Therefore external_push_access stayed incomplete and the final decision became problem.

Corrected behavior:

• SketchGraph.Dimensions is now read.
• exposed_sleeve_end_height_candidate with role exposed_push_face_candidate can be promoted to model evidence.
• The promoted evidence satisfies the b_external_push_access image 2D structure template.

Promotion rule currently used:

exposed_sleeve_end_height_candidate
+ target sketch edge belongs to a sleeve
+ height is meaningful
=> exposed_axial_push_face
=> outside_accessible_force_path
=> owned_by(push_face, sleeve_material)
=> force_direction_parallel_to_axis(push_face, sleeve_axis)
=> can_push_or_strike(outside, push_face)
=> adjacent_to_outside(push_face, outside)

Rules To Prevent Repeating This Failure

1. A model-side 2D structure instance is not only relations

• A model-side 2D structure instance is not only relations.
• It must also consume dimensions, roles, anchors, and candidate annotations when they are produced by the extractor.
• A candidate can be promoted to pass evidence only through an explicit promotion rule.

2. Candidate is not failure

Failure pattern:

• Treating an incomplete pass template as absent too early makes the final rule report problem.
• In mechanical diagnosis, candidate evidence should remain visible in the result so the missing bridge can be debugged.

Correct rule:

• Keep candidate, found, and missing separate.
• Only final decision uses found; debugging output must preserve candidates and missing relations.

3. Image template relations must map to model evidence names

Failure pattern:

• Image template requires external_push_access.
• Model evidence may expose lower-level facts such as exposed_sleeve_end_height_candidate.
• If there is no mapping, the verifier appears to "not understand" a correct model.

Correct rule:

• Every pass evidence type needs a model-evidence promotion path.
• Do not rely only on literal relation name equality.

4. Merge duplicate sources before diagnosis

Failure pattern:

• When section evidence and structural evidence are both loaded, the same component or scene can appear twice.
• Duplicate scenes make reports noisy and can mask which evidence actually caused a decision.

Correct rule:

• Merge components by component id.
• Merge scenes by (sceneType, target, host).
• Preserve stronger confidence and union of evidence labels.

5. Do not let encoding damage classification

Failure pattern:

• Some older code had mojibake Chinese tokens for component classification.
• Correct Chinese names such as 套筒 can be missed if only garbled tokens remain.

Correct rule:

• Keep component category inference robust:
  • use normal Chinese terms
  • use English aliases
  • prefer metadata from extractors when available
  • avoid depending on name classification when B-rep evidence already identifies owner/category

Development Checklist For Each New Fault Rule

Before trusting a new rule, check all items below.

• Image side has a semantic rule and at least one image 2D structure template for every pass/problem example.
• Each pass template lists both structure relations and required model evidence.
• Every required model evidence item has a documented extraction or promotion path.
• The model verifier consumes all extractor layers used by that path: components, contacts, section edges, section relations, dimensions, regions, roles, and annotations.
• The report shows found, candidate, and missing for both model evidence and 2D structure relations.
• Known positive and known negative examples are tested before generalizing the rule.
• A problem result is not accepted until the missing evidence chain has been inspected.