# Rules and pitfalls

> Reference · https://spoletta.com/docs/rules

The app refuses a board or a setup file that breaks one of the rules below, and says why. Some mistakes break no rule but still don't work; they are listed after the rules, each with its fix.

## Links

-   A process and the objects it links to are on the same board. A flow process's inner processes may also link to its interface objects.
-   A process other than a human one yields a given object at most once.
-   Only an agent's or a person's output link lists states to decide between. An agent's output link names either one state or several to decide between, never both.
-   A person's output link never names a single state: it lists the states to decide between, or none (an entry).
-   A condition only goes on an input link from a state.
-   Instrument and consumption are only for input links, never for a person. Only one process may consume a given object.
-   A person is taken only by a human process, and never makes up another object.
-   A state a link names must be one of that object's states.
-   A process tells its objects apart by name, so no two objects it takes may share a name, nor two it yields. Names are compared as the file names a script finds in `$INPUTS`: *Jira Ticket* and *Jira\_Ticket* are the same. It may take one object and yield another of the same name, such as a ticket in and the updated ticket out. Linking, renaming and importing refuse a clash; on a board saved before, a step taking two objects of one name fails.
-   A [query](https://spoletta.com/docs/procedural-links.md#looking-up-stored-records) goes only on an agent's or script's input link to a stored or shared object. It is the process's only link taking that object, names no state and consumes nothing. It takes 1 to 100 records, 20 if not set.

## Processes

| Rule | Allowed |
| --- | --- |
| On failure | Only from an agent, script or Sentry process, never to itself |
| Next | Never to itself; connections stay within one flow |
| Procedures | A procedure can't, directly or through others, run its own flow |
| Rounds | 1 to 20 |
| Timeout | 1 to 86400 seconds |
| Retries | 0 to 5 |
| Needs (quorum) | At least 1 |
| Sentry | Organization and project are slugs: letters, digits, - and \_ |
| Thinking | One of the listed levels: off, minimal, low, medium, high, xhigh, max |

## Objects

-   Part names don't clash with their owner's attribute names, and parts don't loop.
-   A copy's name, states, attributes and parts come from its source; a different name is refused.
-   A file attribute can't be filled in by a person.
-   Only an object's own attributes can be unique, not those it inherits. Uniqueness only takes effect once the object stores what runs generate, or shares its records.
-   Only a struct's object can [share its records](https://spoletta.com/docs/structs.md#shared-records), and it needs a unique attribute first. A shared object's copy can't also store what runs generate.

## Mistakes that break no rule

| Mistake | Fix |
| --- | --- |
| A first agent takes an object nothing produces, and gets it empty. | Start with a person filling it in, or a script or Sentry step fetching it. [Objects](https://spoletta.com/docs/objects.md) |
| A reviser takes the object it revises plainly, so it waits for it before ever writing it. | Take it in the send-back state, and split writer from reviser. [Review loops](https://spoletta.com/docs/loops.md) |
| A process with an event link is expected to write the first version too. | It runs only on its events, from the start or a next: make it the start or split it. [What happens in a run](https://spoletta.com/docs/engine.md) |
| Branches rejoin without a quorum or condition links, so the join never runs. | Set Needs on the join, or branch with conditions. [Branches and decisions](https://spoletta.com/docs/branches.md) |
| A script or Sentry step is expected to decide a state. | Give the states rules. [States and rules](https://spoletta.com/docs/states.md) |
| A last state without a rule is meant as a catch-all; it never matches. | Give it a rule that always holds. [States and rules](https://spoletta.com/docs/states.md) |
| An agent reviewer reaches its rounds and fails the run. | Add an on-failure handler to it. [Handling failure](https://spoletta.com/docs/failures.md) |
| Two runs of the flow working on shared records take the same record at once. | No run claims a record: don't let the working flow's runs overlap. [Shared records](https://spoletta.com/docs/structs.md#shared-records) |
| A carried-over cursor has a unique attribute, so a run that leaves it as it was ends as a duplicate. | Leave the cursor's attributes not unique. [Stored objects](https://spoletta.com/docs/objects.md#stored-objects) |
| Two objects on one board share a name, and every reference needs a key. | Name things apart. |
| A scheduled flow starts with a person filling something in, and waits every time. | Start it with a script or Sentry step. [Schedules](https://spoletta.com/docs/schedules.md) |
| A next connection is used where data should flow; it passes nothing, and is not followed out of a person. | Link the second process to the first one's output. [Procedural links](https://spoletta.com/docs/procedural-links.md) |
| A procedure is expected to work on the caller's branch. | It has its own workspace; do that work in the caller. [Procedures](https://spoletta.com/docs/procedures.md) |

> **Read the OPL:** Most of these show up as a missing or surprising sentence in the flow's [OPL](https://spoletta.com/docs/opl.md). Read it before the first run.