9caa2caa3a
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.
96 lines
5.0 KiB
Markdown
96 lines
5.0 KiB
Markdown
# Skill Documentation Structure
|
|
|
|
This directory is the task-routed skill layer. It sits between the SDK's
|
|
generated
|
|
|
|
```text
|
|
docs/skill/
|
|
domains/ stable, reusable capability modules
|
|
workflows/ goal-oriented compositions of domains
|
|
discipline/ mechanical modeling knowledge and invariants
|
|
```
|
|
|
|
## Layering
|
|
|
|
```text
|
|
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.
|