# Instruction patterns

> This section covers the verbs and prepositions a document is written with.

Page: PAG · Patterns
Canonical: https://banes-lab.com/pag/patterns#instruction-patterns

This section is stop 26 of 102 in the learning route. Previous: [16 - When rules collide](https://banes-lab.com/disciplined-methodology/plan/when-rules-collide.md). Next: [02 - From intent to structure](https://banes-lab.com/pag/patterns/intent-to-structure.md). It builds on [01 - Writing a first document](https://banes-lab.com/pag/guide/getting-started.md).

This section covers the verbs and prepositions a document is written with. Each verb carries a [semantic contract](https://banes-lab.com/records/arch/semantic-contracts.md), and a document relies on that contract rather than on what a particular tool happens to do; a read, for example, leaves its source unchanged whichever tool performs it. [A1·a input verbs](https://banes-lab.com/pag/patterns#instruction-patterns-panel-a) lists what each input verb promises about its source, [A1·b output verbs](https://banes-lab.com/pag/patterns#instruction-patterns-panel-b) what each output verb promises about its result, and [A1·c control verbs](https://banes-lab.com/pag/patterns#instruction-patterns-panel-c) what each control verb promises about its effects. [A1·d three readers](https://banes-lab.com/pag/patterns#instruction-patterns-panel-d) shows who a contract serves, and [A1·e the prepositions](https://banes-lab.com/pag/patterns#instruction-patterns-panel-e) declares the relations the prepositions carry between the operands. A verb's contract together with its preposition is the whole meaning of a line.

### Verbs and their contracts

A verb with no stated guarantee means whatever the model completes it as. A document says process the items, the model reads, filters, writes and deletes under that one word, and the reviewer cannot say which of those the author meant. A verb the model has seen carry one guarantee across many contexts is likely to carry it into the completion; a verb used loosely carries every meaning it has ever had.

For this reason every line relies on its verb's contract and its preposition's relation, and a line whose behaviour breaks them is a defect in the line. The verb is chosen by the guarantee the line needs, rather than by the tool that will perform it. In practice, a read is used when the source must survive, an extract when its meaning must, a find when only existence matters, a filter when order must hold, and an execute when a side effect is the point. The operands are bound with the preposition that names their relation, and the guarantee is relied on downstream.

To check this, read a line and state what it promises about its source and its result. A line whose promise you cannot state uses its verb loosely, and the repair is the verb whose guarantee matches the intent. A contract is a promise the grammar makes about the intent; whether the model or the tool executing the line keeps it is what [verification](https://banes-lab.com/records/arch/verification.md) is for.

A contract promises one of three things: what happens to the source, what the result is, or what effects the line may have. Two contracts carry the most weight. An execute may have side effects, and saying so is what keeps each of them from being a [hidden side effect](https://banes-lab.com/records/arch/hidden-side-effect.md). A report is a statement to a reader, never a state that anything later reads as the truth.

A line with the wrong preposition puts its operands in the wrong relation, and the model is asked to complete the relation it was given.

A1·a input verbs

```pag
READ <file> FROM <path> INTO <content>        # non-destructive · the source is unchanged
LOAD <settings> FROM <file>                    # acquisition with parsing
EXTRACT <fields> FROM <record> INTO <values>   # isolation · the source keeps its meaning
FIND <pattern> IN <scope> INTO <found>          # existence · boolean, non-invasive
GLOB "<pattern>" INTO <files>                  # discovery by shape
GREP "<term>" IN <path> INTO <matches>          # discovery by content
```

A1·b output verbs

```pag
WRITE <content> TO <file>                       # idempotent where it overwrites
CREATE <report> FROM <data> USING <template>     # a candidate set or an artifact
APPEND <item> TO <collection>                    # growth without retraction
REPORT <status>                                  # a statement to a reader, never a state

CONVERT <data> TO <format>
FILTER <items> TO <kept> WHERE <condition>       # removes, preserves order
MERGE <sources> INTO <target>
SPLIT <data> BY <delimiter> INTO <segments>
```

A1·c control verbs

```pag
VALIDATE <data> AGAINST <schema>                 # conformance
VERIFY <condition>                               # a boolean, non-modifying
ANALYZE <state> FOR <errors> INTO <found>        # deep examination, may delegate
COMPARE <actual> AGAINST <expected> INTO <diff>
RANK <candidates> BY <score> INTO <ordered>       # score-driven ordering

EXECUTE <command> WITH <params>                  # side effects possible
TASK "<objective>" WITH agent: <role> → <result>
SEND <message> TO <recipient>
AWAIT <response> INTO <result>
SET <state> = <value>                            # assignment · idempotent
LINK <source> TO <target>                        # a bidirectional association
```

A1·d three readers

```mermaid
flowchart TB
verb["A verb"]
guarantee["Its semantic contract · what it promises about the source and the result"]
reader["A reader relies on the contract"]
model["The model is asked to complete the pattern the contract names"]
check["A scan can hold the contract · a READ that mutates is a defect"]
verb --> guarantee
guarantee --> reader
guarantee --> model
guarantee --> check
```

A1·e the prepositions

```mermaid
flowchart LR
from["FROM · the origin"]
in["IN · the container searched"]
into["INTO · the destination bound"]
to["TO · the destination intended"]
using["USING · the mechanism"]
against["AGAINST · the reference"]
for["FOR · the purpose"]
with["WITH · the parameters"]
from ~~~ in ~~~ into ~~~ to
using ~~~ against ~~~ for ~~~ with
```

## Links to

- [Semantic Contracts](https://banes-lab.com/records/arch/semantic-contracts.md)
- [Verification](https://banes-lab.com/records/arch/verification.md)
- [Hidden Side Effect](https://banes-lab.com/records/arch/hidden-side-effect.md)

## Linked from

- [Why it works](https://banes-lab.com/pag/introduction/why-pag-works.md)
- [The loop](https://banes-lab.com/disciplined-methodology/start/the-loop.md)
