Chapter 04 · 5 min

How proposals get written

The repo scan, the evidence chain, and why a proposal can exist before any traffic does.

A proposal is an argument with citations. The engine is given the repository snapshot, the funnel and its conversion rates if there are any, and the history of past experiments in the workspace, and asked for hypotheses that would move a named metric. Every survivor passes a validator: it must cite files that exist, name a metric the workspace tracks, and not duplicate an experiment already run. Unsupported claims are cut.

Anatomy of a proposal

• Hypothesis — the change and the mechanism, in one paragraph.
• Evidence — what in the code and the data supports it.
• Code citations — file:line pairs the bot will change.
• Exposure step, primary metric, guardrail — where a session enters, what counts as success, what must not degrade.
• Estimated lift and prior confidence — the engine’s calibrated prior, shown as such. It is replaced by measured numbers the moment the experiment runs.

Why server-side proposals rank first

The free-shipping threshold in the demo is a constant in lib/shipping.ts. No visual tool can test it, because the number is not on the page until checkout. Trevo can, because it read the file. Pricing rules, ranking logic, API handlers and prompts are where a store’s leverage usually sits, so proposals that change them rank above proposals that move a button.

Before any traffic

Proposals do not need events. They need code. That is why the first three arrive minutes after the repository connects, and why the SDK is asked for afterwards: “like what it wrote? Install the SDK so Trevo can measure it.”