Design process: section by section

A design that passes every per-part check can still be wrong as an assembly: contents outside the container that should hold them, subassemblies that only touch by coincidence, boxes where a mechanism should be, and nobody who looked. This process makes the design declared (what touches, holds, moves and fastens what), measured (the gates), justified (a decision with the alternatives rejected for each part) and reviewed (a separate reviewer with a checklist), one section at a time.

References: docs/dossier.md (the YAML and the build-script declarations), docs/gates.md (what each gate measures), docs/review-packet.md (the packet and the checklist), docs/design-process-plan.md §5 (why).

Before you start

• Track it, as if the session could end any minute (token budgets, crashes): one GitHub issue per section or piece of work, a feat/ branch pushed at once, a draft PR with Closes #N. Commit and push at least every 30 minutes, WIP commits included, and leave a checkpoint comment on the issue: done, next, what is running and where. The cad-work-tracking skill of the cad-agent agent kit spells this out, where it is installed.
• Long runs go off the shared machine (cad-agent all, the gates on a large assembly, FEA, CFD): run them detached on a compute host and record host role, command, log and done marker in the issue (the cad-remote-runs skill, where installed). Where agents share a workstation, one niced job at a time.
• Set CAD_AGENT_ACTOR to your session id. Builds record it; a reviewer's sign-off is refused when it equals the build's.

The loop, per section

1. Frame the section: no geometry yet

Write dossier/sections/<id>.yaml: its purpose, the requirements it serves (in project.yaml, each with the user's words as source.quote), the interfaces to its neighbours with a datum and an owner, and the parts it needs. An interface is a contract: the owner section changes the datum, the other side rebuilds.

Open questions become status: open decisions. If the model can answer one (a stack height, a screw length, a clearance), compute it and decide; ask the user only what the model cannot know. An open decision blocks sign-off.

2. Write each part's card with its geometry

The minimum card is three things, in the same commit as the code that makes the part:

- id: hopper
  function: Hold the ball store and funnel balls to the feed throat under gravity
  interfaces: [I7, I8, I9]
  decisions:
    - id: D41
      decision: Single-wall cone with a 55° floor
      why: balls roll at 35°; 55° clears the throat without a stirrer
      alternatives: [{option: stirrer paddle, rejected: adds a motor and a jam mode}]

Add the rest when it is known, not before: material with wall_mm when the process is chosen, fasteners when the joint is chosen, contains when the part holds something, loads when the analysis is set up, checks naming the gates and checks that verify it. Leave status: out: it is computed. The lint asks for what is missing.

3. Declare the geometry facts in the build script

Only the code knows which solid is the cavity, where an axis is, where each screw sits:

from cadagent.dossier import Axis, part, cavity, joint, fastener, assembly, build

@part("hopper", section="S3")
def hopper(p): ...
@cavity("hopper", "hopper_cavity")                  # always a declared solid; nothing is derived
def hopper_void(p): ...
joint("I9", "revolute", parts=("flap", "hopper"), axis=lambda p: Axis(p["pivot"], (0, 1, 0)), range_deg=(0, 70))
fastener("screw_m3x8", clamps="lid", into="insert_0", name="screw_0", via="I7", tool="hex 2.5",
         at=lambda p: [Axis(p["seat_0"], (0, 0, -1))], length_mm=8, thread_start_mm=3, min_engagement_mm=4)
assembly.step(3, fit="lid", direction="-Z", tool="hex 2.5", fasteners=["screw_0"])

Every part goes in exactly one assembly step with a direction; every fastener in the step that drives it. Model the bought part (the McMaster STEP, the mcmaster-parts skill) and the mating connector, not a bounding box. Keep one parameter authority (cad/parameters.json); never copy a number into the YAML that the build computes.

4. Build, gate and lint, and fix in order

cad-agent gates --build        # every gate that applies, then the dossier lint; exit 1 on a failure
cad-agent dossier              # the per-section status table and the lint findings

Fix in this order, rerunning after each group (a fix early in the list often clears findings later in it):

1. Loader and join errors (unknown-id, card-without-shape, shape-without-card, unknown-cavity): the declarations must agree before any gate means anything.
2. Connectivity: floating components and unrealised interfaces first; they are usually a part in the wrong place.
3. Containment: contents outside their cavity, contents in the container's wall.
4. Fasteners: seat, stack, holes, engagement, tip, length, then tool access.
5. Assembly access: coverage, then blocked insertions and tools at their steps.
6. Motion: collisions over each joint's range.
7. Wall, then the lint's status rules (decisions, traces, checks).

Then the standard part checks, which every project runs whether or not it has a dossier: cad-agent holes (every hole in every part clear of material: build features first and cut holes last) and the rest of cad-agent all. Walk docs/common-issues.md for the issues no check covers yet.

Never lower a threshold or widen a tolerance to pass. A finding that is not a defect becomes an explained exclusion: gates.free_parts (a loose item), gates.intended_overlaps (a heat-set insert, a press fit, a screw's thread envelope, which may name the fastener or an instance key) or gates.ignore_pairs (variants never fitted together), each with a reason. A verdict read as stale is not a pass: rerun the gates. A section is done with this step when cad-agent dossier shows it gated.

5. Render the section's review packet

cad-agent review-packet S3     # exports/review/S3/*.png and manifest.json

The packet is solid, opposite iso, x-ray, cuts through each cavity (side and plan), joint axis and fastener group, exploded along the steps, access views along the screws, each joint's range ends, and the findings at their witness points, captioned with the section and content hashes. Open every image before you use it: current, lit, showing the feature.

6. Critique it yourself, measurements first

Read the manifest's measurements and findings before the images. Then answer every question in checklist.questions (yes / no / unclear) from the views it names, and write the answers into the section's review: {self: ...} block with the view file each refers to. Do not answer a count, a gap, a wall or an engagement from an image: the gates measured those (checklist.measured_only). If an image and a measurement disagree, the measurement wins and the disagreement is a finding (a wrong declaration or a misleading view). Fix what you find and go back to step 4; do not hand over a section you would not sign.

7. Hand the section to a separate reviewer

Do not set reviewed or signed_off yourself, and never write a reviewer record: the lint refuses records by a part's builder or a named author, but it cannot tell who wrote a file, so this rule is yours to keep. Write the reviewer's bundle and hand it to an agent or person that did not build or write the section (plan §5.3, docs/dossier.md "The reviewer pass"):

cad-agent review-section S3     # exports/review-bundle/S3/: PROMPT.md, the section YAML, gates.json, status.json,
                                # packet/ (manifest + images), checklist.json, diff.patch, record-template.json

Exit 1 means something would refuse a sign-off today (blockers in bundle.json: a stale or missing packet, the section below gated, an open decision, a part built by unknown); fix it first unless you only want changes requested. Give the reviewer the bundle directory, not your conclusions. The reviewer follows PROMPT.md: answers every question yes, no or unclear with evidence and marks image-only answers, judges each decision justified, weak or missing_alternative, traces each requirement, writes findings with a severity, and submits:

CAD_AGENT_ACTOR=<reviewer> cad-agent review-section S3 --submit my-review.json   # --check validates only

That refuses stale hashes (the geometry changed since the bundle), a reviewer who built a part of the section or is named as its author, and, for a sign-off, an open decision or a stale packet; on success it writes dossier/reviews/<section>-<date>.json. Builds and reviews must run with CAD_AGENT_ACTOR set: each part records the actor that built its current geometry, so a reviewer who rebuilds unchanged geometry is still not its builder, but one who changes it is. Any change to a part's geometry voids the sign-off. Answer every reviewer finding: fix it and ask for a new review, or explain why it stands.

8. Report

One line per requirement touched (its status from exports/dossier-status.json), per gate, per open finding, per section with its status. Say what is not verified: CAD and simulation do not prove physical fit, strength, print quality or that a mechanism works.

For the agent that splits the work

Plan the sections from the requirements first, agree the interfaces between them, then hand one section per implementer with this skill and its section file; sections whose interfaces are agreed can be built in parallel. Run the reviewer pass on each section as it comes in and the full gates on the integrated assembly. Nothing is done while a finding is open, a verdict is stale or a section lacks its sign-off; cad-agent check fails while any section is below gated.