Things to avoid: AI, templates & handoff

Most of these are cheap to avoid up front and expensive to unpick later. Rules marked Fails silently give no error, the app builds and runs, but the defect only shows up in the customer's output, or never shows up at all.

Pages, fields & names

• Don't put 40+ fields on one question page. Cap pages at 10–15 fields, use show if to hide what isn't relevant rather than asking users to skip past it.
• Don't mix client details, billing, and staffing on one page. Group by theme and name the page what it collects, put explanations in a static Note field, not a separate Info page.
• Don't always reach for the specialized field type. Default to short text for anything touching a data table, it's the most flexible input for a table key, expression, or filter.
• Don't leave blocks on generic titles. Title every block with what it does, "Gate: litigation matters only" lets the flow be read from the block list alone.
• Don't ship variable 4 or field_27. Name for the thing instead, ClientFullName, RetainerAmount, and hold one convention across the app.
• Don't put special characters in app or variable names. Letters, numbers, and underscores everywhere, !, @, &, and / in an entity name measurably degrade extraction accuracy.

AI extraction

• Don't use freeform output to extract a set of fields. Use extract for anything structured, one scalar variable per entity, usable directly.
• Don't pack 15–20 entities into one block. Use 4–7 per background page, 10 hard maximum, accuracy falls off past 10 with no warning.
• Don't give every AI action its own block. Put independent actions in one block as multiple triggers, they fire concurrently instead of running five times as long.
• Don't leave temperature at its default. Set temperature: 0.0 every time, reproducibility beats variety in legal work.
• Don't use one model everywhere. Fails silently, mini models return undefined on arithmetic. Match the model to the block.
• Don't tell the model to return blank when it can't find a field. Return a fixed token like not_found instead, predictable enough to branch on.
• Don't rely on the entity name to explain what you want. Write a definition for anything not self-evident, "base rent excluding CAM charges, as a plain number."
• Don't ignore size limits at either end. Fails silently, an oversized document errors downstream; an undersized max_tokens truncates while reporting success.