Revising a definition

A definition is rarely right on the first pass, and it does not need to be. Revising it is the normal way you get from a first draft to something you trust.

Saying what is wrong

You revise a definition the same way you created it: by describing, in plain language, what should change. Say what is wrong or missing, and the definition is updated to reflect it.

• "The approval threshold should be $10,000, not $5,000."
• "Add a step that checks the vendor is on the approved list before matching the invoice."
• "A ticket tagged urgent should wait for a person even if it would otherwise complete automatically."

Each of these describes an outcome, not an edit to a document. You do not need to know how the underlying definition is structured to change it.

Deploying a change

A new authoring change creates new immutable Agent or Definition revisions. Select those exact revisions in a Release, submit a Deployment for the target Project Environment using its existing configuration head, wait for ready, and activate it. The Release and Deployment records preserve the revision pins that took effect. This is covered in more detail in Definitions.

If an activation turns out to be wrong, activate a previously known-good Deployment for the Environment according to its generation guard. Releases and Deployments remain immutable; changing authoring content never mutates the record of what was already promoted.

Deploy when little is in flight

An activation changes the rules an Environment runs under. Prefer to promote when there is little work in progress, and check the record afterwards for anything that was mid-flight, so you are not diagnosing a revision change and an unfinished run at the same time. Reading the record shows what to look at.

Tightening a rule versus adding an approval

Both narrow what an agent can do on its own, but they are different moves.

Tightening a rule changes the condition under which an operation completes automatically — lowering a threshold, adding a check that must pass first, narrowing the cases it applies to. Use this when the automatic path itself was too permissive.

Adding an approval keeps the operation available but inserts a person into the decision for some or all cases. Use this when the operation is fine in principle but the outcome matters enough, or is judgment-dependent enough, that someone should see it before it takes effect.

A rule that turns out to be too strict — blocking cases that should have gone through — is revised the same way: describe the case that should not have been refused, and the rule is loosened to allow it.

To see whether your rules are set correctly, watch the record of the runs they govern. See Reading the record.