cadSet/designir-pipeline/skills/cad-experience-builder/references/llm-review-contract.md

LLM semantic review contract

Read the sanitized runs/review/semantic-batch.json, not raw STEP geometry. Maintain stable proposal identifiers when an existing candidate expresses the same method.

Write runs/review/experience-draft.json with this shape:

{
  "schema_version": "1.0",
  "draft_kind": "llm_generalized_experience_proposals",
  "proposals": [
    {
      "id": "constraint.part_family.shared_axis",
      "kind": "constraint",
      "scope": ["part_family"],
      "evidence_query": {
        "required_features": ["rotational_body", "central_passage"],
        "required_relations": ["dominant_axis_alignment"],
        "context_features": ["rotational_body", "central_passage"]
      },
      "guidance": "Preserve a shared axis across the participating feature roles.",
      "semantic_rationale": "The relationship remains meaningful when individual dimensions change.",
      "check": "Confirm that participating features retain their intended common axis."
    }
  ]
}

Allowed kinds are feature_motif, constraint, design_rule, validation_rule, failure_repair, dimensionless_distribution, and reconstruction_grammar, plus:

• parameter_naming: maps repeated final-B-Rep evidence to a canonical editable name such as plate_thickness, hole_spacing, bolt_circle_diameter, or rib_count;
• edit_strategy: defines the expected target change and preservation contract for a named semantic parameter.

These proposal kinds use evidence_query.required_parameters. A name is a reconstruction-system convention, never a claim that the STEP contained the source parameter. Distribution proposals also provide observation_name; the publisher computes the distribution from private evidence and never accepts values from the draft.

A reconstruction_grammar proposal must additionally contain symbolic, number-free reconstruction content:

{
  "id": "reconstruction.patterned_prismatic_part.primary",
  "kind": "reconstruction_grammar",
  "scope": ["patterned_prismatic_part"],
  "evidence_query": {
    "required_features": ["planar_dominant_body", "cylindrical_feature_network"],
    "required_relations": [],
    "context_features": ["planar_dominant_body"]
  },
  "guidance": "Build a datum-driven envelope before adding the passage network and repeated features.",
  "semantic_rationale": "The staged method transfers across dimensional variants while preserving feature relationships.",
  "reconstruction_grammar": {
    "parameter_roles": ["overall_long_span", "overall_middle_span", "overall_short_span"],
    "datum_roles": ["part_center", "primary_axis", "primary_transverse_plane"],
    "feature_roles": ["planar_dominant_body", "cylindrical_feature_network"],
    "relation_roles": [],
    "canonical_stages": [
      {
        "id": "establish_reference_frame",
        "operation": "define_datums",
        "feature_roles": [],
        "reference_roles": ["part_center", "primary_axis"]
      },
      {
        "id": "construct_primary_envelope",
        "operation": "extrude_profile",
        "feature_roles": ["planar_dominant_body"],
        "reference_roles": ["part_center", "primary_axis"]
      }
    ],
    "cardinality_classes": ["plane_dense", "cylinder_dense"],
    "validation_roles": ["closed_solid", "surface_mix_consistency"]
  }
}

Follow these rules:

• Require an evidence query composed only of semantic feature and relation tokens present in the sanitized batch.
• Use scopes to prevent unrelated part families from supporting a proposal.
• Use context_features to define the conditional population used for confidence, so a valid subtype method is not diluted by unrelated variants in the same broad family.
• Explain why a proposal transfers across dimensions and variants.
• Avoid dimensions, coordinates, source identifiers, face references, and numeric literals in prose.
• Do not infer build order or causal failure mechanisms from final geometry.
• Do not present inferred parameter names as recovered source parameters.
• Prefer specific editable names over generic span roles only when repeated geometric evidence supports the distinction.
• Treat canonical_stages as a recommended reconstruction order, never as a claim about the source CAD history.
• For reconstruction grammars, retain only roles and stages repeated by the scoped evidence. Do not insert family knowledge that the sanitized batch does not support.
• Prefer a small set of meaningful methods over every possible feature pair.
• Preserve earlier proposal IDs when evidence still supports the same meaning.
• Let the publisher calculate support and confidence; never claim them in the draft.