---
name: freecad-model-validation
description: Validate FreeCAD documents, generated solids, assemblies, and exported STEP or STL artifacts with explicit expectations and machine-readable evidence. Use after creating or editing CAD geometry, before accepting an agent-generated model, when an export must be round-tripped, or when a visually plausible model may still have invalid topology, wrong dimensions, hidden intersections, unusable access, or unsaved inspection state.
license: MIT
metadata:
  dev.v-san.skills: |-
    origin: original (personal skill)
    version: '0.1'
    changeDate: '2026-08-12'
    authors:
      - Vladimir Rogozhin
    dependsOnSkills:
      - freecad-scripts
    requires:
      dependencies:
        - FreeCAD 1.0+ (FreeCAD 1.1+ recommended)
        - Python 3.11+
---

# FreeCAD Model Validation

Turn “the model looks right” into a layered report. Use `freecad-scripts` for FreeCAD API details and this skill for the validation protocol and claims.

## Validation protocol

1. Define expectations before inspecting the result: intended objects, units, bbox dimensions and tolerances, solid count, minimum volume, mating levels, forbidden intersections, and required access paths.
2. Snapshot the document name, active object, visibility, camera, and save path. Do not save temporary inspection state over the user's document.
3. Recompute and inspect document errors before geometry checks.
4. Run `scripts/validate_document.py` inside FreeCAD against the active document. Pass an expectation mapping when exact dimensions or counts are known.
5. Apply the evidence ladder in [validation-playbook.md](references/validation-playbook.md): topology, dimensions, fit, assembly, export round-trip, use/maintenance, then physical evidence.
6. Validate exported artifacts by reopening them in a scratch document and rerunning the geometry checks. An exporter returning without error is not an export validation.
7. Capture only the views that answer a diagnostic question. Restore normal visibility and camera state; do not save after temporary inspection unless requested.
8. Return one report following [report-schema.md](references/report-schema.md). Separate observed facts, expected values, checks, assumptions, and untested risks.
9. Reconcile later evidence by scope and level. A relevant failed physical prototype overrides an earlier geometry or analytic `candidate`; retain both reports and record the supersession instead of deleting the earlier result.

## Claim discipline

- A valid closed solid with expected bbox is a geometry pass, not proof of assembly fitness.
- Zero nominal intersection does not establish printable clearance or tolerance robustness.
- A CAD joint or fully constrained assembly does not prove physical retention.
- A linear FEM result is evidence only after mesh, material, contacts, boundary conditions, and convergence are justified.
- Use `pass`, `fail`, `warning`, and `not_tested`; never turn missing evidence into a pass.
- Treat a screenshot and a successful tool call as observations, not as substitutes for recompute, state, topology, dimensional, or physical checks.

## Practical FreeCAD rules

- Prefer a single generator script, one execution, a compact report, then read-back of saved properties.
- Read properties back from FreeCAD; do not assume assigned values survived unit/property coercion.
- Use `App::PropertyDistance` for signed coordinates and offsets; reserve `App::PropertyLength` for non-negative sizes.
- For dense imported STL, prefer facet or lightweight reference-envelope analysis before BRep booleans.
- Make diagnostic screenshots the last optional step; numerical checks are primary.

## Resources

- `scripts/validate_document.py` — FreeCAD-runtime validator with no non-stdlib dependency.
- `scripts/reconcile_evidence.py` — preserve and reconcile geometry, analytic, FEM, coupon, and physical reports for one explicit scope.
- [validation-playbook.md](references/validation-playbook.md) — evidence ladder and export/use checks.
- [report-schema.md](references/report-schema.md) — stable machine-readable report contract.
- [provenance.md](references/provenance.md) — sources and design influences.