Files
make-cad/docs/skill/references
NiJingzhe b496530363 feat(helix): handedness parameter for right/left helices
make_helix_redge/make_helix_rwire/helical_sweep_rsolid accept
handedness='Right'|'Left'. The kernel negates the u component of the
cylinder 2-D line, mirroring the winding while keeping the ascent
direction: sampled chirality asserts +5 turns CCW (right) vs -5 turns
CW (left) with identical rise, length, and sweep volume.

FreeCAD: Part::Helix stays the right-handed path; left-handed helices
materialize through Part.makeHelix(..., lefthand=True) since Part::Helix
cannot express mirrored winding via placement (rotations preserve
chirality).
2026-09-04 05:36:27 +08:00
..

Skill Documentation Structure

This directory is the task-routed skill layer. It sits between the SDK's generated

docs/skill/
  domains/       stable, reusable capability modules
  workflows/     goal-oriented compositions of domains
  discipline/    mechanical modeling knowledge and invariants

Layering

SKILL.md (router: load order, routing, execution discipline)
→ workflows/<scenario>.md        what to run, in what order
→ domains/<capability>.md        capability boundaries and API groups
→ discipline/<topic>.md          why: modeling reasoning and invariants
→ docs/api|stdlib|core/          exact signatures (auto-generated)

Load top-down and only what the current task triggers. No task reads the whole API index up front.

Domains

Domain Owns
requirement-refinement request → brief (dimensions, units, datums, validation targets)
part-modeling single-solid parts: primitives, profiles, features, booleans, transforms
sketch-and-features declarative constrained sketches and promotion
assembly-and-product parts, placements, connectors, constraints, @part/@assemble, cache, .scadpkg
standard-parts stdlib gears, ring gears, racks, cycloidal discs, bearings
step-inspection STEP/BREP evidence, comparison, reconstruction evaluation
export-and-translation STEP/STL/OBJ/MJCF export, FreeCAD/Fusion/SolidWorks translation

Cross-cutting capabilities — QL grounding, semantic tags, GraphSession replay, units/tolerances, incremental validation — are not routing targets; each workflow pulls them in as conditions require. Verified QL selection patterns for operation outputs (extrude-family slots, boolean seam curves, seam fillets) live in ql-playbook.md.

Workflows

Workflow Scenario
single-part-modeling one physical part from brief to validated solid — sketch tier by default, std parts first
assembly-product-build multi-part product or mechanism with connectors/constraints and package capture; stdlib gears/bearings live here
step-reconstruction editable rebuild from a target STEP with tiered acceptance
export-and-translation downstream formats from a validated package

Each workflow states: goal/scope, task decomposition (required/optional domains, artifacts, validation gates, repair routes), ordered steps with the domain/discipline/API references to load, failure routes, and deliverables. single-part-modeling is additionally role-structured: five roles (requirement confirmer → master planner → verifier planner ⇄ detail modeling planner & builder → exporter), with Roles 3 and 4 looping per stage before the next stage is allowed. Each role owns a disk artifact and an exit gate; omp host bindings (todo tool, persistent python REPL, mandatory subagent image review) are declared inside the workflow file.

Discipline

Modeling reasoning and invariants, independent of any single API: mechanical-modeling (construction strategy), requirement-and-cad-brief (input precedence, drawings), datums-and-coordinate-systems, feature-ordering (operation order and boolean tool geometry), assembly-positioning (mating/motion intent), geometric-validation (validity vs volume, incremental grounding, spec-driven measurement), failure-and-repair (failure classes and the repair loop), manufacturing-boundaries (defaults and what geometry never proves).

Authoring rules

  • Domain files say what a capability owns, when to use it, when to route elsewhere, and which API pages to read — they do not restate signatures.
  • Workflow files compose domains; they never duplicate discipline content.
  • Discipline files state reasoning and invariants; they avoid CLI- or tool-specific detail that belongs in domains/workflows.
  • Every references/... path written here must exist in the packaged skill.
  • Reading an API page is an action with an output: before the first call of any API, note its signature, return type, and documented failure modes — one line each in the working notes. A method name absent from the page does not exist, however plausible it looks. Non-SDK dependencies (Gmsh, CalculiX, VTK, FreeCAD scripting) are not covered by SDK pages: check their own documentation before the first call.