---
name: mechanical-constraint-analysis
description: Analyze six rigid-body degrees of freedom, unilateral contact directions, candidate escape motions, collision sweeps, and the evidence needed for form-closure or force-closure claims. Use when auditing whether pins, shoulders, lips, snap tabs, screws, friction, or preload physically retain a part; when a CAD assembly reports fully constrained but real hardware may still move; or when testing slide, lift, rotate, tilt, and pull scenarios before export.
license: MIT
metadata:
  dev.v-san.skills: |-
    origin: original (personal skill)
    version: '0.1'
    changeDate: '2026-08-12'
    authors:
      - Vladimir Rogozhin
    dependsOnSkills:
      - freecad-scripts
      - freecad-model-validation
    requires:
      dependencies:
        - Python 3.11+
---

# Mechanical Constraint Analysis

Audit physical retention without confusing solver constraints with manufactured contact. Use `freecad-scripts` for FreeCAD operations and `freecad-model-validation` for the surrounding evidence report.

## Workflow

1. Name the moving body, fixed environment, reference frame, candidate contacts, loads, friction assumptions, clearances, and compliant features.
2. Build the interface table described in [constraint-model.md](references/constraint-model.md). A contact normal must mean the reaction direction acting on the moving body.
3. Run `scripts/analyze_contacts.py` for a first-order screening of signed translations and rotations. Supply JSON following [scenario-schema.md](references/scenario-schema.md).
4. Treat every reported blocker as a contact that would resist an infinitesimal motion. Treat every unblocked direction as a concrete failure candidate.
5. Exercise failure scenarios: slide ±X/±Y/±Z, rotate ±Rx/±Ry/±Rz, lift an edge, tilt, and pull through attached wires or connectors.
6. For geometry-backed checks, run `scripts/motion_sweep.py` inside FreeCAD on copies of shapes. Use a coarse-to-fine sweep and record baseline intersection, first collision, minimum clearance, step size, and path limits.
7. Escalate evidence only when necessary: analytic contact screening, collision sweep, justified FEM, printed coupon, then physical test.
8. Return the claim level defined in [evidence-and-claims.md](references/evidence-and-claims.md): `not_retained`, `candidate`, or `inconclusive`.
9. Keep each physical part separate until every internal interface has its own scenario. Never fuse a retained part and its retainer into one moving body before checking their relative motion.

## Non-negotiable distinctions

- Assembly constraints describe an ideal kinematic model. They do not create contact normals, friction, preload, strength, or manufacturable geometry.
- Form closure requires geometry to block all finite escape motions; blocking the twelve signed basis twists is only a screening candidate, not a proof.
- Force closure additionally depends on friction and/or preload plus available contact forces. Without quantified assumptions, report it as inconclusive.
- Friction must not rescue an otherwise free design silently. State coefficient, preload, material pair, surface condition, and uncertainty.
- A nominally touching mesh does not establish sustained contact after FDM tolerances and deformation.

## Resources

- `scripts/analyze_contacts.py` — dependency-free contact-direction screening and JSON report.
- `scripts/motion_sweep.py` — FreeCAD-runtime translational collision sweep on shape copies.
- [constraint-model.md](references/constraint-model.md) — contact and DOF conventions.
- [scenario-schema.md](references/scenario-schema.md) — input/output examples.
- [evidence-and-claims.md](references/evidence-and-claims.md) — safe engineering claims.
- [provenance.md](references/provenance.md) — sources and local regression case.