Prompting a model

A model that has never seen bimtex will write something that compiles on its first try. It will also, without any warning, write a house that is a box, on a site that is four-fifths empty, with a lot coverage figure that is double the real one.

Every failure on this page validated 0 errors, 0 warnings. That is the subject of this page.

The architecture, in four facts

Everything below is a consequence of these. Skipping them makes the rest read as an arbitrary list of rules.

1. One model. Every view is derived

You never draw a plan. You describe a building once, as a flat list of entities, and the compiler cuts every plan, elevation, section, axonometric, site plan and 3D scene out of that one description.

NDJSON entities → compile → solids + surfaces → every view
                       └──→ validate → diagnostics

The consequence you must internalise: you cannot fix a view. If the south elevation is wrong, nothing about the south elevation is editable. You change the model, and eight drawings move together.

2. Entities are semantic, not geometric

A room is an area with a use — it does not generate walls. A wall is declared by the side it is on, not by two coordinates. An opening names the wall it sits in and the rooms it joins. The compiler does the arithmetic: coordinates, ridge heights, wall pieces, stall placement, areas, travel distances.

This is why the language is small enough for a model to hold, and it is also why a mistake is usually a wrong reference rather than a wrong number.

3. Appearance is data, and it can never change a drawing

The def layer — lookdef, look, materialdef — describes how things look in 3D. It is interpreted, never executed: no code, no functions.

The boundary is a rule, not a convention:

If a drawing must show it, it is semantic. If only the 3D shows it, it is appearance.

An acceptance test compiles a dressed model and its undressed twin and compares every sheet. They must be identical.

So a lookdef cannot fix a single line of any drawing. If you are reaching for appearance to solve a drawing problem, you have diagnosed the wrong thing. Appearance is optional — 15-courtyard-estate carries no lookdef at all — so a model has to read correctly undressed.

4. "Blocking" means the drawings contradict each other

The validator has two kinds of finding, and confusing them wastes more time than any other single mistake.

A deck inside a setback draws perfectly. The building is nonconforming, not the drawing — and a variance application is a legitimate document. Read the severity before you rearrange a building around a warning.

What the checker cannot see

It finds contradictions: two things that disagree. Four things are therefore invisible to it, and they are where every real failure lives.

An absence. An entity anchored to the wrong parent drops out of the compile silently. Nothing is left to disagree with, so the report is clean — because the thing is not in the drawing at all.

A judgement. A box is a legal building. A house described as a massing prism compiles to two solids and passes everything.

A proportion. A 21 × 12 m building on a 40 × 30 m parcel is 21% coverage. No rule is broken. The axonometric is four-fifths empty ground.

A number that is wrong but consistent. A house counted twice reported 60% lot coverage where the truth was 30%. Both figures were internally consistent.

Eight practices

Grouped by what they buy you.

Fidelity — does it match the real thing

1. Pick the machine that matches the subject

There are two ways to describe a building and they differ by an order of magnitude:

The test is one question: is the drawing about it?

Yes → give it a footprint. This holds for existing work too — a building that names a footprint and carries existing: true gets real walls and a real roof, while the site plan still simplifies it to the dashed outline the convention wants.

No → a prism is right. A neighbour across the boundary is context; nobody is going to measure it.

An L-shaped or T-shaped building is several rectangular footprints, each with its own roof. ROOF_TYPES is flat · gable · hip · shed.

The largest fidelity gap we have measured came from this one choice: a permit drawing's existing dwelling, the biggest thing on the sheet, compiled to two solids and rendered as a parking deck.

2. Source first, model second

Name what you worked from, in the project header. A real building, a real jurisdiction, a real requirement sheet.

An invented dimension and a measured one look identical on the drawing and both pass the validator. The difference is that in three months nobody can tell which is which.

3. Do not write a dimension you did not measure

Every furniture type carries a real-world size taken from published standards. An authored w, d or height replaces it wholesale — including the part you were not thinking about.

A queen bed's height is the top of its headboard, not the mattress. Written as the mattress figure, the whole bed compiled to 58% of its height: a futon on the floor with a headboard behind it. A sink's height is the top of the tap, not the counter.

A number written to look precise is worse than none, because it silently overrides one somebody checked.

Looks — is it a drawing anybody wants to read

4. The parcel is the site the drawing is about

Not the largest rectangle that contains the building. Draw the land that is part of the story and stop.

And the ground is part of the building: an office of any size parks somewhere, a shop has a pavement. A building alone on a lawn is not a site plan.

5. Print the view that can refute you

Every view is blind to something. A plan will never show you a parapet. An axonometric from the south will never show you the north wall. A roof plan is the only thing that will tell you the coping is missing.

Before you print: name the thing you are least sure of, and print the view that would show that.

Printing the view you already believe is a way of spending money to feel better — and an image costs roughly ten times what the text costs. Parse errors and validation errors are already named precisely in text; a picture of them is redundant.

6. Author the section when the default would miss the point

An unauthored section falls at the default station. Cut through the servery, the stair, the double-height space. A section of an empty room is a wasted sheet.

Sense — is it a building

7. A clean report is not proof it is there

The tell is always the same and it is always visual: you added something and the picture did not change.

So the first time you add a kind of thing, open the one view that would show it and count them. A canopy you cannot see is a canopy that is not there.

8. The numbers on the sheet are load-bearing

On a regulated drawing, check the derived figures, not only the geometry. Lot coverage is the number a plan checker computes and compares against the zoning maximum. Wrong in one direction it fails a compliant application; wrong in the other it passes a nonconforming one.

Writing the system prompt

One principle decides what goes in:

Spend tokens only where bimtex disagrees with the world. Where the two agree, the model already knows — your job is not to teach it, but to avoid switching it off.

How you switch it off

The same model, two openings:

None of that knowledge was added by the second prompt. The first one suppressed it.

What switches it on:

• A role and a purpose, not a schema. The single biggest lever.
• The trade's working order — outside in: parcel, footprint, storeys, entrance, the zoning of the plan; then walls, then openings, then furniture. Let it start from a dimension and it falls back into spreadsheet mode.
• Make it say what it read before it draws. "This is a corner site, so the entrance faces the junction." Saying it out loud engages spatial reasoning that silent generation skips.
• Say what the drawing is for — a planning submission, a client, a contractor. This is the strongest available control on how much is enough, and it is ordinary professional knowledge the model already has.
• License a hunch. "You notice things before you can name them" lets the model report unease instead of only what it can prove.

One honest limit: activation gets you competent. It does not get you specific — the model's architectural knowledge is an average, so it will produce a plausible generic building unless you give it a source. That is why practice 2 exists.

What you must actually tell it

Only the places where bimtex disagrees with the world. These are dangerous precisely because a model that understands buildings will get them wrong:

And one that has no worldly analogue and must simply be stated:

• grid and schedule produce no solids by design. They are annotation and reach the sheet — gridlines on the plan, a door schedule on its own sheet. Do not go hunting for their geometry, and do not "fix" them.

Notice what is not on these lists. An invalid materialdef enum, a door in no wall, a room nobody can reach — the validator names all of those precisely, in the terms the trade uses, with the repair. Spending prompt on them buys nothing. The list is short because it only contains what fails quietly.

What not to put in

• The wire format, by hand. It is generated. Call getSyntax() — one card, about 12,200 tokens, cacheable. A hand-copied schema rots the first time an entity changes. Better still, bind it to a tool: see Tool schemas.
• A numbered procedure. In an agentic loop, steps degrade into ticked boxes. A described person grows behaviours the procedure never listed.
• Anything the model already knows. Corridor widths, stair rises, which rooms want daylight, how far a kitchen sits from a service entrance.
• be careful, make it beautiful, follow best practices. Unfalsifiable, and they change no behaviour.

The test for any paragraph: name the failure it prevents. If you cannot, delete it. Every paragraph in the reference prompt below was written after watching a specific run go wrong.

A prompt you can copy

For a single-shot generation. For an agentic loop with tools, the shipped harness carries the same idea further — SYSTEM_PROMPT from bimtex/drafter (source: lib/drafter/prompt.mjs) adds habits about when to look, when to stop, and how to report a conflict, and the drafter loop wraps it in the gates that make those habits enforceable.

You are a drafter. You turn a brief into one bimtex model, and the compiler
derives every plan, elevation, section, axonometric and site plan from it. You
do not draw views — you describe the building, and the views follow.

Say what you read before you write anything: what the building is for, how many
rooms, where it is entered, which side the street is on. Where the brief is
silent on something a building cannot be without, choose, and say you chose.

You work outside in. Parcel, footprint, storeys, entrance, the zoning of the
plan — those first. Walls, then openings, then furniture. You never begin with
a dimension.

The defaults are researched, and the moment you write a number you own it.
Every type carries a real-world size taken from published standards, and an
authored w, d or height replaces it wholesale — including the part you were not
thinking about. Write a dimension when you measured something or the brief gave
it to you.

If the drawing is about a building — including an existing one — give it a
footprint, walls and a roof with a real pitch. A `building` with a width and a
depth and no footprint is a prism with a flat cap: it cannot carry a pitch, an
eave or an opening, and it is the right description only for a neighbour nobody
is going to measure.

The parcel is the site the drawing is about, not the largest rectangle that
contains the building. Draw the land that is part of the story and stop.

A clean report is not proof that something is there. The checker finds
contradictions; it cannot find an absence, because nothing is left to disagree
with. The tell is always visual — you added something and the picture did not
change. So the first time you add a kind of thing, look at the one view that
would show it, and count them.

These are the places bimtex disagrees with the world. Your instinct is right
about buildings and wrong about these:
  · a bed's height is the top of its headboard; a sink's is the top of its tap
  · a numeric `at` on an opening is its start, not its centre — prefer omitting
    it, which centres it
  · a lawn is a `landscape`; `paving.use` has no lawn
  · `coping.on` must name a parapet, not a wall — pointed at a wall it emits
    nothing and says nothing
  · a `room` is an area with a use; it generates no walls
  · a door's operation is swing, sliding, overhead or double-acting; `fixed`
    belongs to a window, and an unoperated hole is `kind:"opening"`
  · `grid` and `schedule` produce no geometry by design; they are annotation
    and reach the sheet

Everything else about buildings you already know — corridor widths, stair
rises, which rooms want daylight, where a WC may not open. Use it. None of it
is written down here because none of it needs to be.

Where to go next