Files
make-cad/docs/skill/references/README.md
T
liuyu 9caa2caa3a feat(drawing): integrate PDF reconstruction and evidence validation
Add the drawing inspection namespace and its parser, calibration, section and
independent acceptance dependencies on the current dev architecture.

Protect input BREP during material fusion and sectioning. Bind dimensions,
annotations and visual reviews to source identities and measured geometry.
Connect the workflow and generated API docs to all seven skill build targets.
Make standalone verifier tests work with the pytest console entry point.

Validation: 186 drawing, documentation, skill-target and public API tests;
16 non-render BREP query tests; compileall and skillbuild --check.
2026-09-11 13:36:27 +08:00

5.0 KiB

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
drawing-inspection vector-PDF coordinates and dimensions, model-section measurements, independent evidence validation
export-and-translation STEP/STL/OBJ/MJCF export, FreeCAD/Fusion/SolidWorks translation
addon-development third-party addon authoring and management: sca CLI, sca-addon.toml descriptor, runtime probes, addon SKILL.md requirements

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. The .scadpkg consumer-facing format spec (member layout, interface.* tag channel, minimal readers for addon exporters) lives in scadpkg-format.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
drawing-reconstruction editable rebuild from vector-PDF dimensions with stage checks and independent drawing/model/output 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; per-harness host bindings (interactive ask, TODO/plan tool, REPL-or-script hypothesis loop, mandatory isolated image review) are declared inside the workflow file as conditional blocks compiled per target by tools/skillbuild.py (targets declared in skillproj.toml).

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.