# === tier level-2 ===


# STE-Code Level -2 — distilled index

> ultra-minimal: the 14 core principles only

## Sub-documents

- 01-principles.md



## 01-principles.md

# Level -2 — Core Principles

Ultra-minimal STE-Code reference for LLMs that generate code documentation.
Use this when you write README, API docs, docstrings, comments, commit messages, or error text.
Every word must be either an approved word or a code-domain technical noun/verb (see the gate at the end).

## Rule 1.1 — Use approved words, or code-domain technical nouns/verbs
Every word must pass one gate: an approved word in the controlled terminology, a code-domain technical noun (e.g. `UserAuthenticator`), or a code-domain technical verb (e.g. `serialize`).
- Non-STE: Execute the script to do the task.
- STE: Run the script to do the task.

## Rule 1.2 — Use approved words only as their approved part of speech
A word approved as a noun is not a verb, and vice versa. Do not verb a noun.
- Non-STE: Query the database for user records.
- STE: Send a query to the database for user records.
- Non-STE: Static the variable.
- STE: Make the variable static.

## Rule 1.3 — Use approved words only with their approved meaning
An approved word keeps its controlled meaning. "run" = execute a program; "return" = send a value back from a function. Do not drift to general English.
- Non-STE: The background worker runs every night. (meaning "operates")
- STE: The background worker operates every night.

## Rule 1.4 — Use only the approved forms of verbs and adjectives
Use the verb and adjective forms listed in the controlled terminology (infinitive, -s, past, participle; base, comparative, superlative). Do not coin other forms.

## Rule 1.5 — Code-domain technical nouns are allowed in 19 categories
You may use a word not in the dictionary if it names a code concept in one of 19 categories (e.g. code components, data types, infrastructure, defects, network). Register it in the project glossary. Examples: `controller`, `array`, `Kubernetes`, `race condition`, `port 5432`.

## Rule 1.6 — A non-approved word is allowed only as a technical noun
A word not in the terminology fails unless it is (or is part of) a recognized code-domain technical noun.
- Non-STE: The handler processes each event. ("handler" alone is not approved)
- STE: The function processes each event.  — or — The event handler processes each event.

## Rule 1.7 — Do not use technical nouns as verbs
Keep technical nouns as nouns. Describe the action with an approved or technical verb.
- Non-STE: Cache the API responses. / Docker the application.
- STE: Store the API responses in the cache. / Containerize the application with Docker.

## Rule 1.8 — Use technical nouns approved in your project/domain
If your project, company, or domain already has an approved name for a component, use it. Do not invent a new name for something already named in the codebase.
- STE: The dashboard uses the `UserTable` component and the `FilterPanel` component.

## Rule 1.9 — When you pick a technical noun, keep it short
No approved name exists? Pick a noun that is short (≤ 3 words) and easy to understand. Add at most one or two adjectives only if needed.

## Rule 1.10 — No regional, slang, or jargon nouns
Do not use slang or ecosystem-only jargon as technical nouns. A word one subculture finds clear can be opaque to everyone else.
- Non-STE: Remove the cruft from the module.
- STE: Remove the unnecessary code from the module.

## Rule 1.11 — One technical noun per item, used consistently
Do not rename the same thing across the document. Always use the same code-domain technical noun for the same item; the source code is the source of truth.
- Non-STE: Start the session manager... call the AccountManager to verify a user.
- STE: Start the UserService... call the UserService to verify a user.

## Rule 1.12 — Code-domain technical verbs are allowed (categories)
You may use a verb not in the dictionary if it fits a technical-verb category (e.g. build, deploy, test, lint, compile, debug, clone, parse). Prefer an approved verb when one fits exactly.
- Non-STE: If you detect broken wires, repair them.
- STE: If you find broken wires, repair them.  (or use the technical verb "detect" when it is the precise term)

## Rule 1.13 — Do not use technical verbs as nouns
Use technical verbs only as verbs. Need a noun? Use an approved noun or a code-domain technical noun.
- STE: Enter your password.  (not "do the enter of your password")

## Rule 1.14 — American English spelling by default
Use American English spelling (color, fiber). Keep British spelling only inside quoted text (error messages, UI labels, code).

## The gate (apply to every sentence)
A word is allowed only if it is ONE of:
1. An approved word, used as its approved part of speech and approved meaning (Rules 1.1, 1.2, 1.3, 1.4).
2. A code-domain technical noun in one of 19 categories, kept as a noun and used consistently (Rules 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11).
3. A code-domain technical verb in a technical-verb category (Rule 1.12, 1.13).
4. Quoted text / a number used verbatim (Rule 1.14 exception).
There is no fourth category. When unsure, pick the shortest approved verb.


# === tier level-1 ===


# STE-Code Level -1 — distilled index

> minimal/core: 14 core principles + synonym table

## Sub-documents

- 01-principles.md
- 02-synonyms.md



## 01-principles.md

# Level -1 — Core Principles (Word Choice)

STE-Code is a controlled language for code documentation, adapted from
ASD-STE100 Simplified Technical English. This sub-document gives the 14 core
principles of Section 1 (words). They govern **which words you may use, in
which part of speech, and with which meaning**.

Scope of this slice: word choice only. Sentence, procedure, and description
rules live in later sections.

Three word sources are permitted, and only three:

1. Words approved in the STE-Code controlled terminology.
2. Code-domain technical nouns (names of real things in software).
3. Code-domain technical verbs (names of real operations in software).

Definitions used throughout:

- **Code-domain technical noun** — a noun term that refers to a specified
  concept in software development and is applicable to a subject field
  (for example `UserService`, `backup file`, API endpoint).
- **Code-domain technical verb** — a verb term that refers to a specified
  operation or process in software development (for example compile, lint,
  deploy, mock).
- **Controlled terminology** — the STE-Code word list (part 2). It replaces
  the STE dictionary.

## Quick index

| Rule | Principle |
|------|-----------|
| 1.1 | Use approved words, code-domain technical nouns, or code-domain technical verbs. |
| 1.2 | Use approved words only as the specified part of speech. |
| 1.3 | Use approved words only with their approved meanings. |
| 1.4 | Use only the approved forms of verbs and adjectives. |
| 1.5 | You may use words that fit a code-domain technical noun category. |
| 1.6 | Use an unapproved word only when it is (part of) a code-domain technical noun. |
| 1.7 | Do not use code-domain technical nouns as verbs. |
| 1.8 | Use the code-domain technical nouns approved in your project or field. |
| 1.9 | When you must choose a technical noun, choose a short and clear one. |
| 1.10 | Do not use regional, slang, or jargon words as technical nouns. |
| 1.11 | Do not use different technical nouns for the same item. |
| 1.12 | You may use verbs that fit a code-domain technical verb category. |
| 1.13 | Do not use code-domain technical verbs as nouns. |
| 1.14 | Use American English spelling unless official directives say otherwise. |

## The 14 principles

### Rule 1.1 — Use approved words, code-domain technical nouns, or technical verbs

Use words that are approved in the project controlled terminology, or that are
code-domain technical nouns, or that are code-domain technical verbs. Words
outside these three sources are not permitted.

The controlled terminology also lists words that are **not** approved, together
with approved alternatives. Your project glossary, API reference, and coding
standards are the normal home of your technical nouns and verbs.

- Approved verb: `use`.
- Code-domain technical noun: `cache`.
- Code-domain technical verb: `compile`.

### Rule 1.2 — Use approved words only as the specified part of speech

Each approved word carries one or more parts of speech. Use it only in those.

"Query" is an approved noun, but not an approved verb.

> **Do not write:** Query the database for all active users.
>
> **Write:** Do a query of the database for all active users.

Some words are approved as more than one part of speech; sentence position
shows the function. When an approved alternative has a *different* part of
speech, change the sentence construction — never force a word-for-word swap
that changes the meaning.

If a word you want is not in the controlled terminology:

1. Find the word in an English dictionary.
2. Find the best approved synonym.
3. Use that approved word, or rewrite the sentence with other approved words.

### Rule 1.3 — Use approved words only with their approved meanings

Each approved word has one specified meaning, often narrower than in standard
English. Do not borrow other senses.

- `follow` = "come after, go after" — use it for the sequence of steps.
- `obey` = "to do that which the procedures or instructions tell you".

Four-step check for every approved word you write:

1. Identify the part of speech in your sentence.
2. Look the word up in the controlled terminology for that part of speech.
3. Compare your intended meaning with the approved meaning.
4. If they differ, choose a different approved word or rewrite the sentence.

### Rule 1.4 — Use only the approved forms of verbs and adjectives

The controlled terminology gives each approved verb with its approved forms,
and each adjective with its comparative and superlative forms where they
apply.

`COMPILE (v), COMPILES, COMPILED, COMPILED`

| Infinitive / Imperative | Simple present | Simple past | Past participle (as adjective) |
|--------------------------|----------------|-------------|-------------------------------|
| (To) compile / Compile | Compile(s) | Compiled | Compiled |

Adjectives that form comparatives with "more" and "most" do not list those
forms, because "more" and "most" are themselves approved words.

### Rule 1.5 — You may use words that fit a code-domain technical noun category

A code-domain technical noun refers to a specified concept in software
development. The controlled terminology cannot list them all: each project and
subject field has its own. Take them from your project glossary, API
documentation, or terminology database.

STE-Code gives categories so that you can (a) select technical nouns for your
glossary and (b) use them correctly. A word qualifies as a code-domain
technical noun when it fits one or more of those categories — for example
computer science and information technology terms, database and storage
terminology, official documents and standards, numbers and units, quoted text,
professional roles, and environmental or operational conditions.

### Rule 1.6 — Use an unapproved word only when it is (part of) a technical noun

A word that is not approved may still be used when it fits a technical noun
category, or when it is part of a multi-word technical noun.

> **Do not write:** Make sure that the two handles at the base of the panel engage.
>
> **Write:** Make sure that the two handles at the bottom of the panel engage.

But `base` is permitted as a technical noun (mathematical and engineering
terms) — for example "base 16", "base class".

`backup` is not approved as a general word; its alternatives are "emergency
(n)" and "auxiliary (adj)". It **is** permitted as a code-domain technical
noun, and as part of the two-word technical noun `backup file`.

The same word can belong to different categories when it carries different
meanings in different contexts. Do not replace a word that is part of an
established technical noun: the replacement is no longer the approved term.

### Rule 1.7 — Do not use code-domain technical nouns as verbs

Use a technical noun only as a noun, or as an adjective inside another
technical noun. Rewrite the sentence instead of verbing it.

> **Do not write:** Database the results after the job finishes.
>
> **Write:** Write the results to the database after the job finishes.

In some contexts the same word is both a technical noun (rule 1.5) and a
technical verb (rule 1.12). That is permitted only when the word genuinely
fits both category systems.

> **See also:** Rule 1.5, Rule 1.12.

### Rule 1.8 — Use the code-domain technical nouns approved in your project or field

If your project, company, industry, or subject field already has an approved
name for a class, module, function, method, variable, component, or process,
use that name. These names live in your project glossary, API documentation,
coding standards, and — above all — in the source tree.

Do not invent your own name for something that already has one. The reader must
be able to search the repository for the word you wrote.

> **Do not write:** The account controller manages login and user profile operations.
>
> **Write:** The `AccountController` manages authentication and user profile operations.

### Rule 1.9 — Choose a short and clear technical noun

When no approved technical noun exists, select one that is short (not more than
three words) and easy to understand. Do not write a long descriptive phrase
where a short term is unambiguous. A line number, a code snippet, or an API
reference identifies the item, in the same way that an index number and an
illustration do in printed procedures. Add one or two adjectives only when the
reader needs them.

> **Do not write:** Call the asynchronous JavaScript XML HTTP request wrapper utility function (line 42) to get the serialized JSON payload from the remote application programming interface endpoint.
>
> **Write:** Call the `fetchUtility` function (line 42) to get the JSON data from the API endpoint.

### Rule 1.10 — Do not use regional, slang, or jargon words as technical nouns

Some words are used only inside one community or one technology ecosystem.
Readers from a different background, a different stack, or a different first
language will not understand them. Choose well-known words.

> **Do not write:** Remove all the cruft from the legacy module.
>
> **Write:** Remove all the unnecessary code from the legacy module.

### Rule 1.11 — Do not use different technical nouns for the same item

One item, one name, everywhere in the documentation. When the name changes
between sections, the reader cannot tell whether you mean one item or several.
The source of truth is the code: the class, function, module, table, resource,
environment variable, or configuration key as it is defined in the repository.

> **Do not write:**
>
> 1. Initialize the `UserService` class to start the session manager.
> 2. Call the authenticate method on the `AccountManager` to verify a user.
> 3. The `UserHandler` returns a session token.

> **Write:**
>
> 1. Initialize the `UserService` class to start the session manager.
> 2. Call the authenticate method on the `UserService` to verify a user.
> 3. The `UserService` returns a session token.

### Rule 1.12 — You may use verbs that fit a code-domain technical verb category

A code-domain technical verb refers to a specified operation or process in
software development. The controlled terminology cannot list them all. Take
them from your project glossary or terminology database, and obey the same verb
rules that apply to every other approved verb.

A verb qualifies when it fits one or more of these four categories:

| # | Category | Examples |
|---|----------|----------|
| 1a | Write and modify code | compile, concatenate, import, inject, instantiate, lint, minify, marshal, optimize, polyfill, refactor, resolve, shim, stub, substitute, tokenize, transpile, trace, vectorize |
| 1b | Test and verify code | assert, benchmark, debug, fuzz, instrument, mock, profile, snapshot, spy, stub, unit-test |
| 1c | Build and package | bundle, deploy, package, publish, release, tag, version |
| 1d | Manage dependencies | hoist, install, link, lock, pin, update, upgrade |
| 2a | Input and output processes | click, copy, cut, digitize, enter, paste, press, print, scan, swipe, tap, type |

### Rule 1.13 — Do not use code-domain technical verbs as nouns

Use technical verbs only as verbs. When you need a noun, find an approved noun
or a code-domain technical noun with the equivalent meaning.

> **Do not write:** Do a build of the project. The function does a parse of the input string.
>
> **Write:** Build the project. The function parses the input string.

When the API returns a named artifact — a `Build` object, a `Deployment`
resource — that noun is a code-domain technical noun (rule 1.5), not a misused
verb. A word may belong to both category systems, as `stub` does.

> **See also:** Rule 1.5, Rule 1.7, Rule 1.12.

### Rule 1.14 — Use American English spelling

Use the spelling given in the STE-Code controlled terminology, which is
American English. Use a different spelling only when a project specification,
style guide, contract, or other official directive requires it.

> **Do not write:** Initialise the variable before you use it in the loop.
>
> **Write:** Initialize the variable before you use it in the loop.

> **Do not write:** The log file shows the colour of each output line.
>
> **Write:** The log file shows the color of each output line.

Do not change the spelling inside quoted text — an error message, a code
comment, a user interface string. Keep it exactly as it appears:

> **Write:** The terminal shows the message `Colour profile not recognised`.

> **See also:** Rule 8.6 — Use quoted texts correctly.

## Application order (for generators)

1. Is the word approved? If yes, check part of speech (1.2), meaning (1.3), and
   form (1.4).
2. If not approved: is it a code-domain technical noun (1.5, 1.6) or technical
   verb (1.12)? Prefer the term already approved in the project (1.8), short
   and clear (1.9), free of jargon (1.10), and used consistently (1.11).
3. Never cross word classes: nouns are not verbs (1.7), verbs are not nouns
   (1.13).
4. Spell it in American English (1.14), except inside quoted text.



## 02-synonyms.md

# Level -1 — Synonym / Approved-Word Table

Minimal vocabulary layer of STE-Code. One meaning, one word. If a word appears in
the **Not approved** column, replace it with the word in the **Approved** column.

Scope rule (Rule 1.1 / Rule 1.5): a word is allowed if it is
1. approved in the controlled terminology (tables below), or
2. a code-domain technical noun (Rule 1.5 categories), or
3. a code-domain technical verb.

Nothing else. Do not invent synonyms.

---

## 1. Approved verbs

Use the approved verb in imperative steps and in descriptive prose. The
"Not approved" words are rejected for that meaning.

| Approved | Not approved | Meaning |
|---|---|---|
| use | utilize, leverage, employ | Apply an existing function, library, or component without changing its internals. |
| start | initiate, commence, bootstrap | Begin execution of a process, service, or background task. |
| stop | terminate, halt, kill | End execution of a running process or service in a controlled way. |
| show | display, render, present | Make a value, status, or result visible in the interface or in a log. |
| make | create, generate, produce | Build a new object, file, or data structure as the result of an operation. |
| get | retrieve, fetch, obtain | Read a value, record, or resource from a store, API, or cache. |
| set | configure, assign, establish | Assign a value to a variable, field, or configuration option. |
| check | verify, validate, ensure | Examine a condition or value to confirm it matches the expected result. |
| do | perform, execute, carry out | Run a defined operation or unit of work. |
| send | transmit, dispatch, forward | Transfer a message, request, or event over a channel. |
| remove | delete, eliminate, purge | Take out a file, record, or component so it is no longer present. |
| keep | retain, preserve, maintain | Hold a value, file, or resource in its current state. |
| add | append, insert, include | Put an extra element or field into a collection or configuration. |
| change | modify, alter, update | Make a controlled modification without replacing the whole item. |
| write | persist, save, store | Put data into a file, database, or output stream for later use. |
| read | load, parse, ingest | Obtain data from a file, stream, or input source. |
| connect | attach, link, associate | Establish a channel between two components, services, or endpoints. |
| close | shut, release, disconnect | End an open connection, file handle, or stream. |

### Verb examples

| Write this | Do not write this |
|---|---|
| Use the logger to record the request identifier before you return the response. | Leverage the logger to capture the request identifier prior to returning the response. |
| Start the worker process before the test suite connects to the message queue. | Commence the worker process prior to the test suite establishing a connection. |
| Stop the server before you change the configuration file. | Terminate the server prior to modifying the configuration file. |
| Make a backup copy of the database before you run the migration script. | Generate a backup copy of the database before you run the migration script. |
| Check that the response status is 200 before you parse the JSON body. | Validate that the response status is 200 prior to parsing the JSON body. |
| Set the timeout to thirty seconds before you open the network connection. | Configure the timeout to thirty seconds before establishing the network connection. |
| Use the built-in sort function to order the list before you print it. | Utilize the built-in sort function to order the list before printing it. |

---

## 2. Approved technical nouns

These are code-domain technical nouns (Rule 1.5). Use the approved name; do not
substitute a loose paraphrase.

| Approved noun | Not approved |
|---|---|
| AuthenticationService | login handler, auth component, credential service |
| CacheManager | cache store, memoization layer, buffer manager |
| Logger | log writer, event recorder, trace emitter |
| RateLimiter | throttle controller, request governor, flow regulator |
| HttpClient | request sender, web caller, rest client |
| Result<T, E> | either type, outcome wrapper, try result |
| ConfigMap | settings object, configuration holder, option store |
| TreeNode | node element, tree item, hierarchy unit |
| Payload | data bundle, message body, request content |
| ConnectionPool | socket group, session store, connection cache |
| BuildPipeline | compile flow, build chain, assembly process |
| MigrationScript | schema update, database patch, version step |
| DeployStep | rollout action, release task, push operation |
| IdleState | inactive mode, standby condition, dormant status |
| ErrorState | failure mode, fault condition, broken status |
| Middleware | request filter, interceptor piece, pipeline part |
| Plugin | add-on module, extension part, optional unit |
| Timeout | wait limit, expiry period, deadline value |
| AvailabilityZone | data region, server location, host area |
| LoggingSystem | trace framework, log facility, record subsystem |

---

## 3. Approved domain terms

One approved term for each subject field. The rejected column lists common
near-synonyms that must not be used for that concept.

| Approved term | Subject field | Not approved |
|---|---|---|
| orchestrator | containerization | scheduler, cluster manager, container manager |
| subnet | networking | network slice, IP range, address block |
| mock | testing | stub, fake, dummy object |
| telemetry | observability | instrumentation data, system signals, monitoring output |
| pipeline | CI/CD | build chain, workflow, job stream |
| index | database | lookup table, secondary structure, access path |
| authentication | security | auth, login check, identity confirmation |
| idempotency | distributed systems | repeat safety, retry proof, safe re-execution |
| autoscaling | cloud | elastic resize, self-adjust, dynamic capacity |
| hydration | frontend | client boot, attach behavior, re-render bind |
| rebase | version control | transplant, replay commits, restack |
| eviction | caching | purge rule, drop policy, clearance |
| broker | message queue | message hub, relay, dispatcher |
| pagination | API design | paged results, chunking, windowing |
| latency | performance | response delay, wait time, lag |
| rollout | deployment | push, ship, go-live |
| structured log | logging | plain log, text log, raw print |
| race condition | concurrency | timing bug, collision, concurrent fault |
| cipher | encryption | crypto scheme, codec, scrambler |
| alert | monitoring | warning, trigger, notification event |

---

## 4. Approved adjectives

Each adjective has one technical meaning. Use it only in that meaning.

| Adjective | Meaning |
|---|---|
| idempotent | The operation gives the same result when applied more than once, with no extra side effects. |
| immutable | The value cannot be changed after it is created. |
| atomic | The operation completes fully or not at all; no partial state is visible. |
| thread-safe | The code stays correct when more than one thread calls it at the same time. |
| asynchronous | The operation returns before the work completes; the result arrives later. |
| concurrent | More than one task makes progress in overlapping time. |
| deterministic | The same input always gives the same output. |
| deprecated | The item still works but must not be used in new code; it will be removed. |
| nullable | The value is permitted to be null or absent. |
| serializable | The value can be converted to a byte or text form and read back. |
| stateless | The component keeps no data between calls. |
| backward-compatible | Existing callers continue to work after the change. |
| read-only | The value can be read but not written. |
| recursive | The function or structure refers to itself. |
| monotonic | The value only increases, or only decreases, over time. |
| transitive | If A relates to B and B relates to C, then A relates to C. |
| volatile | The value can change outside the current thread of control. |
| hierarchical | The items are arranged as a tree of parents and children. |
| normalized | The data is stored in one canonical form, with no duplication. |
| incremental | The work is done in small steps that add to the previous result. |

Adjective examples:

> **Do not write:** Leverage an idempotent retry handler so a duplicate invocation will not create a redundant record.
>
> **Write:** Make the retry handler idempotent so a second call with the same input does not duplicate the record.

> **Do not write:** Utilize an immutable request context so concurrent threads will not overwrite shared values during processing.
>
> **Write:** Keep the request context immutable so concurrent threads cannot overwrite each other's values during one operation.

---

## 5. Technical-noun categories (Rule 1.5)

A word that is not in the tables above is still allowed if it belongs to one of
these nineteen code-domain technical noun categories.

1. **Code components, modules, and libraries** — class, controller, helper, hook, middleware, mixin, module, package, plugin, provider, repository, service, utility
2. **Computing devices and their components** — CPU, disk, GPU, keyboard, laptop, memory, monitor, mouse, printer, screen, server, smartphone, tablet, terminal
3. **Development tools and environments** — CLI, compiler, debugger, Docker, editor, IDE, Git, Jest, linter, loader, Prettier, terminal, test runner, TypeScript, webpack
4. **Data structures, types, and formats** — array, boolean, buffer, CSV, enum, hash map, integer, JSON, linked list, object, queue, stack, string, struct, tree, tuple, XML, YAML
5. **Infrastructure, deployment, and platforms** — AWS, CI/CD, container, deployment, Heroku, Kubernetes, load balancer, Node.js, pipeline, pod, production, staging, Vercel
6. **Systems and architectural components** — API gateway, authentication layer, caching layer, client, database layer, message broker, microservice, proxy, rate limiter, REST API, routing layer, server, WebSocket
7. **Mathematical and algorithmic terms** — Big O notation, binary search, coefficient, complexity, exponent, hash function, iteration, logarithm, matrix, recursion, regex, sorting algorithm, time complexity, traversal
8. **Interface elements and navigation** — button, checkbox, dialog, dropdown, footer, header, menu, modal, navigation bar, radio button, scrollbar, sidebar, tab, text field, toggle, tooltip
9. **Numbers, units of measurement, and time** — byte, gigabyte (GB), hertz (Hz), hour (h), kilobyte (KB), megabyte (MB), millisecond (ms), minute, nanosecond (ns), second (s), terabyte (TB)
10. **Quoted text** — `Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused`
11. **Professional roles, teams, and organizations** — administrator, backend developer, contributor, DevOps engineer, frontend developer, Google, maintainer, Microsoft, product owner, QA engineer, reviewer, scrum master, user
12. **Documents, API references, and standards** — API reference, changelog, code of conduct, contributing guide, diagram, figure, Getting Started guide, HTTP specification, note, paragraph, README, release notes, RFC, section, table, warning
13. **Runtime environments and operational conditions** — development, environment variable, garbage collection, heap, hot reload, live reload, memory leak, production, sandbox, stack trace, staging, test, thread, timeout, virtual machine
14. **Colors** — black, blue, cyan, gray, green, magenta, orange, red, white, yellow. Colors are adjectives, but STE-Code treats them as technical nouns. Do not use comparative or superlative forms (blacker, the reddest).
15. **Defects, errors, and faults** — assertion failure, bug, crash, deadlock, defect, exception, hang, infinite loop, memory leak, null pointer, race condition, regression, stack overflow, timeout, type error
16. **Computer science, information, and communication technology** — AI, algorithm, authentication, authorization, blockchain, containerization, cryptography, database, encoding, encryption, firewall, hashing, internet, machine learning, metadata, neural network, protocol, query, sandbox, schema, token, virtualization
17. **Legal and licensing terms** — Apache 2.0, BSD license, compliance, copyright, GPL, license, MIT license, open source, proprietary, terms of service, third-party, trademark, warranty
18. **Database and storage terminology** — connection pool, cursor, foreign key, index, migration, NoSQL, ORM, PostgreSQL, primary key, query, Redis, relation, row, schema, seed, SQL, SQLite, stored procedure, table, transaction, view
19. **Network and protocol terminology** — DNS, endpoint, HTTP, HTTPS, IP address, localhost, middleware, packet, port, request, response, route, socket

Record project-specific technical nouns in the project glossary or terminology
database before you use them in documentation.


# === tier level0 ===


# STE-Code Level 0 — distilled index

> baseline: core principles + short dictionary excerpt

## Sub-documents

- 01-principles.md
- 02-synonyms.md
- 03-dictionary.md



## 01-principles.md

# Level 0 — Core Principles

STE-Code Level 0 is the baseline. It collects the fourteen core principles that
govern controlled vocabulary in code documentation, plus a short dictionary
excerpt of code-domain technical terms. Everything below is faithful to the
STE-Code standard: no rules are invented, and every example stays inside the
code domain (no aerospace or other subject-field leakage).

The principles form a gate. Every word in every sentence of code documentation
must pass one of them: it is an approved word in the controlled terminology, a
code-domain technical noun, or a code-domain technical verb.

---

## The Fourteen Principles

**Rule 1.1 — Use words that are approved in the dictionary, technical nouns, or technical verbs.**
Use only vocabulary that is (a) listed in the controlled terminology, (b) a
code-domain technical noun such as `UserAuthenticator`, or (c) a code-domain
technical verb such as `serialize`. A sentence like
"Run the script to do the task" passes because `run` is an approved verb.

**Rule 1.2 — Use approved words only as the specified part of speech.**
A word approved as a noun must not be forced into verb service. Do not write
"Docker the app"; write "Use Docker to build the app." The technical noun
`query` stays a noun — use "Send a query to the database," not "Query the
database."

**Rule 1.3 — Use approved words only with their approved meanings.**
An approved verb keeps its controlled meaning. "The worker runs every night"
is correct only when you mean execute; if you mean manage, write "operates."

**Rule 1.4 — Use only the approved forms of verbs and adjectives.**
Use the approved inflection: `run / ran / run` for the verb, `large / larger /
largest` for the adjective — never unlisted variants.

**Rule 1.5 — You can use words that you can include in a code-domain technical noun category.**
Words outside the dictionary are allowed when they name a precise concept in one
of the nineteen code-domain categories — for example `Promise`, `User`, `ApiError`.

**Rule 1.6 — Use a word that is not approved in the dictionary, only when it is a code-domain technical noun or part of a code-domain technical noun.**
A non-approved word must be a registered code-domain technical noun (such as
`ValidationError`) or it is forbidden.

**Rule 1.7 — Do not use words that are technical nouns as verbs.**
"Cache the result" is wrong when `cache` is a noun; write "Keep the result in
the cache."

**Rule 1.8 — Use technical nouns that are approved in your project, company, industry, or subject field.**
Register project-specific nouns (`aws_instance`, `kubernetes_deployment`) in
your glossary and reuse them exactly.

**Rule 1.9 — When you must select a technical noun, use one which is short and easy to understand.**
Prefer `socket` over `realtime_notification_channel`; short nouns read faster.

**Rule 1.10 — Do not use regional, slang, or jargon words as technical nouns.**
"No worries" and "utilize" are not technical nouns; use `use` and `use` instead.

**Rule 1.11 — Do not use different technical nouns for the same item.**
One concept, one term. If your README says `auth middleware`, the API docs and
docstrings must say `auth middleware` — not `auth layer`.

**Rule 1.12 — You can use verbs that you can include in a technical verb category.**
Code-domain technical verbs (`map`, `filter`, `fold`, `reduce`, `compose`,
`curry`) are permitted even though they are not in the approved-word list.

**Rule 1.13 — Do not use technical verbs as nouns.**
"Refactor the module" is fine as a verb; do not write "The refactor of the
module" when `refactor` is a verb, not a noun.

**Rule 1.14 — Use American English spelling unless other official directives tell you differently.**
`color`, `center`, `initialize` — not `colour`, `centre`, `initialise`.

---

## Short Dictionary Excerpt (code-domain examples)

| Type | Example | Notes |
|------|---------|-------|
| Approved verb | `run`, `make`, `get`, `set`, `send` | General-purpose STE-Code verbs |
| Code-domain technical noun | `UserAuthenticator`, `Promise`, `aws_instance` | Registered in project glossary |
| Code-domain technical verb | `serialize`, `map`, `filter`, `refactor` | Permitted under Rule 1.12 |
| Adjective (approved) | `large`, `static`, `secure` | Use only as adjectives, never as verbs |

**Non-STE vs STE (canonical pair):**

> Non-STE: Query the database for user records.
> STE: Send a query to the database for user records.

> Non-STE: Docker the app and deploy to production.
> STE: Use Docker to make a container for the app. Deploy the container to production.

These fourteen principles, together with the dictionary excerpt, are the complete
Level 0 slice. They are the deterministic base from which higher tiers build.



## 02-synonyms.md

# Level 0 — Technical Noun Categories (Rule 1.5)

This is the Rule 1.5 slice of STE-Code Level 0: the **code-domain technical noun
categories**. It is the "approved-word / synonym table" for Level 0 — the short,
deterministic list of domain-specific terms you may use outside the approved-word
dictionary.

Everything below is faithful to the STE-Code standard. No categories or terms are
invented. Examples stay inside the code domain (no aerospace or other subject-field
leakage).

Rule 1.5 is the **gateway for all domain-specific vocabulary**. The approved-word
dictionary (Rule 1.1) cannot list every project's nouns, so STE-Code permits a word
outside the dictionary *only* when it names a precise concept in one of the nineteen
categories below. Use an approved word whenever one exists; use a code-domain
technical noun only when no approved word names the concept.

---

## How the gate works

A word is allowed in STE-Code documentation if it is **one** of:

1. **An approved word** — listed in the controlled terminology (Rule 1.1).
2. **A code-domain technical noun** — a word that fits at least one of the
   nineteen categories below and is registered in your project glossary (Rule 1.5).
3. **A code-domain technical verb** — a verb in the technical-verb category
   (Rule 1.12).

Any word that is none of these is **forbidden** by Rule 1.6. There is no fourth
category.

> Non-STE: The developer used the thing to get data from the storage layer and put it on the screen.
> STE: The frontend developer used the API client to get data from the database and show it on the UI.
> (`frontend developer` = category 11, `API client` = category 16, `database` = category 18, `UI` = category 8 — each names a precise concept.)

---

## The 19 Code-Domain Technical Noun Categories

The terms listed under each category are **examples only** — Rule 1.5 does not give
a full list. A word belongs in a category if it names a precise software concept.
Register every project-specific noun in your glossary before using it.

### 1. Code components, modules, and libraries
Software parts, packages, and reusable units of code.
`class`, `controller`, `helper`, `hook`, `middleware`, `mixin`, `module`, `package`, `plugin`, `provider`, `repository`, `service`, `utility`

### 2. Computing devices and their components
Hardware, devices, and physical computing resources.
`CPU`, `disk`, `GPU`, `keyboard`, `laptop`, `memory`, `monitor`, `mouse`, `printer`, `screen`, `server`, `smartphone`, `tablet`, `terminal`

### 3. Development tools, environments, and support equipment
Development tools, IDEs, build systems, and testing frameworks.
`CLI`, `compiler`, `debugger`, `Docker`, `editor`, `IDE`, `Git`, `Jest`, `linter`, `loader`, `Prettier`, `terminal`, `test runner`, `TypeScript`, `webpack`

### 4. Data structures, types, and formats
Data representation, storage structures, and file formats.
`array`, `boolean`, `buffer`, `CSV`, `enum`, `hash map`, `integer`, `JSON`, `linked list`, `object`, `queue`, `stack`, `string`, `struct`, `tree`, `tuple`, `XML`, `YAML`

### 5. Infrastructure, deployment, and platforms
Hosting, deployment, containerization, and runtime platforms.
`AWS`, `CI/CD`, `container`, `deployment`, `Heroku`, `Kubernetes`, `load balancer`, `Node.js`, `pipeline`, `pod`, `production`, `staging`, `Vercel`

---

### 6. Systems, subsystems, and architectural components
System design, architecture patterns, and their parts.
`API gateway`, `authentication layer`, `caching layer`, `client`, `database layer`, `message broker`, `microservice`, `proxy`, `rate limiter`, `REST API`, `routing layer`, `server`, `WebSocket`

### 7. Mathematical, algorithmic, and scientific terms
Algorithms, computational concepts, and mathematical formulas.
`Big O notation`, `binary search`, `coefficient`, `complexity`, `exponent`, `hash function`, `iteration`, `logarithm`, `matrix`, `recursion`, `regex`, `sorting algorithm`, `time complexity`, `traversal`

### 8. Interface elements and navigation
UI components, navigation controls, and layout elements.
`button`, `checkbox`, `dialog`, `dropdown`, `footer`, `header`, `menu`, `modal`, `navigation bar`, `radio button`, `scrollbar`, `sidebar`, `tab`, `text field`, `toggle`, `tooltip`

### 9. Numbers, units of measurement, and time
Quantitative data, measurements, and time-related information.
`byte`, `gigabyte (GB)`, `hertz (Hz)`, `hour (h)`, `kilobyte (KB)`, `megabyte (MB)`, `millisecond (ms)`, `minute`, `nanosecond (ns)`, `second (s)`, `terabyte (TB)`

### 10. Quoted text
Texts you cannot change in code documentation — error messages, code snippets, UI labels, log output.
`Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused`

---

### 11. Professional roles, teams, and organizations
Roles, individuals, organizations, and teams related to software development.
`administrator`, `backend developer`, `contributor`, `DevOps engineer`, `frontend developer`, `Google`, `maintainer`, `Microsoft`, `product owner`, `QA engineer`, `reviewer`, `scrum master`, `user`

### 12. Official documents, API references, and standards
Documentation types, standards, specifications, and their structural parts.
`API reference`, `changelog`, `code of conduct`, `contributing guide`, `diagram`, `figure`, `Getting Started guide`, `HTTP specification`, `note`, `paragraph`, `README`, `release notes`, `RFC`, `section`, `table`, `warning`

### 13. Runtime environments and operational conditions
Execution contexts, environment variables, and operating parameters.
`development`, `environment variable`, `garbage collection`, `heap`, `hot reload`, `live reload`, `memory leak`, `production`, `sandbox`, `stack trace`, `staging`, `test`, `thread`, `timeout`, `virtual machine`

### 14. Colors
Colors that identify color-related properties in code (CSS, terminal output, syntax highlighting).
`black`, `blue`, `cyan`, `gray`, `green`, `magenta`, `orange`, `red`, `white`, `yellow`
Colors are adjectives, but STE-Code identifies them as code-domain technical nouns. Comparative and superlative forms (for example, `blacker`, `the reddest`) are not permitted.

### 15. Defects, errors, and fault terminology
Types of software defects, errors, and malfunctions.
`assertion failure`, `bug`, `crash`, `deadlock`, `defect`, `exception`, `hang`, `infinite loop`, `memory leak`, `null pointer`, `race condition`, `regression`, `stack overflow`, `timeout`, `type error`

---

### 16. Computer science, information, and communication technology
Concepts, technologies, and architectures in computing and communication.
`AI`, `algorithm`, `authentication`, `authorization`, `blockchain`, `containerization`, `cryptography`, `database`, `encoding`, `encryption`, `firewall`, `hashing`, `internet`, `machine learning`, `metadata`, `neural network`, `protocol`, `query`, `sandbox`, `schema`, `token`, `virtualization`

### 17. Legal and licensing terms
Software licenses, legal documents, and compliance terminology.
`Apache 2.0`, `BSD license`, `compliance`, `copyright`, `GPL`, `license`, `MIT license`, `open source`, `proprietary`, `terms of service`, `third-party`, `trademark`, `warranty`

### 18. Database and storage terminology
Database concepts, storage systems, and data persistence.
`connection pool`, `cursor`, `foreign key`, `index`, `migration`, `NoSQL`, `ORM`, `PostgreSQL`, `primary key`, `query`, `Redis`, `relation`, `row`, `schema`, `seed`, `SQL`, `SQLite`, `stored procedure`, `table`, `transaction`, `view`

### 19. Network and protocol terminology
Networking concepts, protocols, and communication.
`DNS`, `endpoint`, `HTTP`, `HTTPS`, `IP address`, `localhost`, `middleware`, `packet`, `port`, `request`, `response`, `route`, `socket`, `SSH`, `TCP`, `TLS`, `UDP`, `URL`, `VPN`, `WebSocket`

---

## Using the categories (gateway rules)

- **Use an approved word whenever one exists.** A technical noun is the *exception*,
  not the default. Reach for `use`, not a jargon synonym, when an approved word fits.
- **Register every technical noun in your project glossary** before you use it. The
  glossary entry must give the term, its category or categories, its approved meaning
  in context, and an example sentence.
- **Use each noun only with its registered meaning** (Rule 1.3) and only as a noun or
  noun modifier (Rule 1.2). Do not turn a technical noun into a verb (Rule 1.7).
- **Prefer short, standard terms** (Rules 1.8, 1.9). Do not invent a new term when a
  standard one exists, and do not use regional or slang words as technical nouns
  (Rule 1.10).
- **One concept, one term** (Rule 1.11). If the README says `auth middleware`, the API
  reference and docstrings must say `auth middleware` — not `auth layer`.

The terms in each category are examples only. Rule 1.5 does not give a full list of
all possible code-domain technical nouns. When a term is a literal identifier, API
name, or exact string from code (a class name, function name, environment variable, or
error message), show it in backticks — for example, `UserRepository`, `NODE_ENV`,
`"404 Not Found"`.

These nineteen categories, together with the fourteen core principles and the
dictionary excerpt, complete the Level 0 slice. They are the deterministic base from
which higher tiers build.



## 03-dictionary.md

# Level 0 — Dictionary Excerpt (Approved / Unapproved)

This sub-document is the short dictionary excerpt that accompanies the fourteen
core principles in the Level 0 baseline of STE-Code. Together with
`01-principles.md`, it forms the complete deterministic base for code
documentation (API docs, commit messages, README sections, code comments).

The glossary is adapted from the ASD-STE100 Issue 9 dictionary (Part 2,
pages 149–434) and domain-adapted from aerospace to the code domain: aerospace
examples are replaced with code examples, while word alphabetization, the
STE/non-STE pair format, approved/unapproved status, and parts of speech are
preserved.

The full controlled terminology contains approximately 875 approved words and
1274 unapproved words. This Level 0 slice shows a short excerpt (the A entries)
plus the rules for reading any entry. Higher tiers bundle the complete
dictionary.

---

## How to Read This Dictionary

- **UPPERCASE words** are approved in STE-Code.
- **lowercase words** are not approved; use the listed STE alternatives instead.
- **(v)** = verb, **(n)** = noun, **(adj)** = adjective, **(adv)** = adverb,
  **(prep)** = preposition, **(conj)** = conjunction, **(pron)** = pronoun,
  **(art)** = article.
- **(TN)** = code-domain Technical Noun, **(TV)** = code-domain Technical Verb.
- Each entry shows the original rule text, a code-domain rewrite, and
  STE / non-STE code example pairs.
- An entry marked **UNNAPROVED** (lowercase) is forbidden; the entry lists the
  approved replacement(s) and example pairs that show the correction.

---

# A

## A (art) — APPROVED

Indefinite article. Use before a singular countable noun.

- Original: A FUEL PUMP IS INSTALLED IN ZONE 10.
- Code-domain: A CONFIG FILE IS INCLUDED IN THE ROOT DIRECTORY.

> STE: A config file is included in the root directory.
> Non-STE: Config files included in root directory.

---

## ABANDON (v) — UNNAPROVED

Not approved. Use **STOP (v)** or **TERMINATE (v)** instead.

- Original: GO (v), STOP (v). IF THERE IS A FIRE, IMMEDIATELY GO TO A SAFE AREA. / IF THE VALUES ARE INCORRECT, STOP THE TEST PROCEDURE.
- Code-domain: TERMINATE (v), STOP (v). IF THE BUILD FAILS, STOP THE DEPLOYMENT PIPELINE. / IF THE VALUES ARE INCORRECT, TERMINATE THE TEST RUN.

> STE: If the build fails, stop the deployment pipeline.
> Non-STE: If the build fails, abandon the deployment pipeline.

> STE: If the values are incorrect, terminate the test run.
> Non-STE: If the values are incorrect, abandon the test procedure.

---

## ABILITY (n) — UNNAPROVED

Not approved. Use **CAN (v)** instead.

- Original: CAN (v). ONE GENERATOR CAN SUPPLY POWER FOR ALL THE SYSTEMS.
- Code-domain: CAN (v). ONE CONFIGURATION CAN HANDLE REQUESTS FOR ALL THE ENDPOINTS.

> STE: One configuration can handle requests for all the endpoints.
> Non-STE: One configuration has the ability to handle requests for all the endpoints.

---

## Scope of This Slice

This excerpt covers the A entries only. The patterns it demonstrates — approved
articles, unapproved verbs replaced by approved verbs (ABANDON → STOP/TERMINATE),
and unapproved nouns replaced by modal verbs (ABILITY → CAN) — repeat across the
full A–Z dictionary bundled in higher STE-Code tiers.

For the gate that this glossary serves, see `01-principles.md` (the fourteen
core principles) and `02-synonyms.md`. A word is permitted in Level 0 only when
it is an approved word, a code-domain technical noun, or a code-domain technical
verb.


# === tier level1 ===


# STE-Code Level 1 — distilled index

> + doc templates (code review / PR feedback)

## Sub-documents

- 01-principles.md
- 02-synonyms.md
- 03-dictionary.md
- 04-templates.md



## 01-principles.md

# Level 1 — Core Principles (Words)

STE-Code Level 1 controls **which words you may use** in code documentation.
Every other level builds on it. This file is the LLM-facing form of Section 1
(Rules 1.1–1.14), plus ready-to-use document templates.

## Contract

Every word in code documentation must pass one of three gates:

1. It is **approved in the controlled terminology** (the STE-Code dictionary).
2. It is a **code-domain technical noun** (Rule 1.5 categories).
3. It is a **code-domain technical verb** (Rule 1.12).

If a word passes none of the three gates, it is forbidden. There is no fourth
category.

Scope: README files, API reference, docstrings, inline comments, commit
messages, error messages, test specifications, code review and PR feedback.

## Principle index (P1–P14)

| ID | Rule | Principle |
|----|------|-----------|
| P1 | 1.1 | Use words that are approved in the controlled terminology, code-domain technical nouns, or code-domain technical verbs. |
| P2 | 1.2 | Use approved words only as the specified part of speech. |
| P3 | 1.3 | Use approved words only with their approved meanings. |
| P4 | 1.4 | Use only the approved forms of verbs and adjectives. |
| P5 | 1.5 | You can use words that fit a code-domain technical noun category (19 categories). |
| P6 | 1.6 | Use a non-approved word only when it is a code-domain technical noun, or part of one. |
| P7 | 1.7 | Do not use words that are technical nouns as verbs. |
| P8 | 1.8 | Use technical nouns that are approved in your project, company, industry, or subject field. |
| P9 | 1.9 | When you must select a technical noun, use one which is short and easy to understand. |
| P10 | 1.10 | Do not use regional, slang, or jargon words as technical nouns. |
| P11 | 1.11 | Do not use different technical nouns for the same item. |
| P12 | 1.12 | You can use verbs that fit a technical verb category. |
| P13 | 1.13 | Do not use technical verbs as nouns. |
| P14 | 1.14 | Use American English spelling unless other official directives tell you differently. |

## P1 (Rule 1.1) — Approved words, technical nouns, technical verbs

In code documentation, use words that are approved in the project controlled
terminology, code-domain technical nouns, or code-domain technical verbs.

- A **code-domain technical noun** names a concept in software development
  (`UserAuthenticator`, `connection pool`, `stack trace`).
- A **code-domain technical verb** names an operation or process
  (`serialize`, `compile`, `deploy`).
- The controlled terminology also lists non-approved words with approved
  alternatives. Keep both lists in the project glossary.

Common substitutions:

| Do not write | Write |
|---|---|
| execute, invoke (prose) | run, call |
| generate, construct, instantiate | make |
| configure, assign | set |
| retrieve, fetch | get |
| transmit | send |
| delete, purge | remove |
| validate, verify, ensure | check |
| utilize, leverage, employ | use |
| initiate, commence, bootstrap | start |
| terminate | stop |
| unable to | cannot |
| invalid, malformed | not correct |
| maintain | keep |
| perform | do |
| optimize | make faster, make smaller |
| aggregate | collect |
| persists | continues |
| prior to | before |

Examples:

> **Non-STE:** To begin utilizing the build toolchain, you must first generate
> the distributable artifact, then execute the compiled binary to bootstrap the
> local development service.
>
> **STE:** Use the build tool to make the binary. Run the binary to start the
> local service.

> **Non-STE:** `Error: Unable to establish connection to the database. Please
> verify your credentials and retry.`
>
> **STE:** `Error: Cannot connect to the database. Check your credentials and
> try again.`

> **Non-STE:** `feat: implement JWT authentication middleware for API routes`
>
> **STE:** `feat: add JWT authentication middleware for API routes`

## P2 (Rule 1.2) — One part of speech per approved word

Each approved word has a specified part of speech. Use the word only as that
part of speech.

- "query" is an approved noun, not a verb → "Send a query to the database."
- "static" is an approved adjective, not a verb → "Make the variable static."
- Some words are approved as more than one part of speech ("call" is a verb and
  a noun). Sentence position shows which one you use.

| Violating form | Error | Write instead |
|---|---|---|
| Query the database / Cache the result / Queue the job / Log the error | Technical noun used as verb | Send a query / Keep the result in the cache / Put the job in the queue / Write the error in the log |
| Docker the app / Git the change / Terraform the VPC | Tool name used as verb | Use Docker / Save with Git / Use Terraform |
| Secure the endpoint / Empty the buffer | Adjective used as verb | Make the endpoint secure / Make the buffer empty |
| Static the variable / Ready the worker | Adjective used as verb | Make the variable static / Make the worker ready |
| Utilize the cache / Leverage the library | Unapproved verb | Use the cache / Use the library |
| Orchestrate the services / Facilitate the sync | Unapproved verb | Control the services / Help the sync |

If a word is not in the controlled terminology: find it in a standard English
dictionary, find the best approved synonym, then use the approved word or a
different sentence construction.

## P3 (Rule 1.3) — Approved meanings only

Each approved word has one or more approved meanings, often more restricted
than standard English. Do not use an approved word with a meaning it does not
have in the controlled terminology.

Check procedure for each word:

1. Identify the part of speech as you wrote it.
2. Look up the approved meaning for that part of speech.
3. Ask whether your sentence uses exactly that meaning.
4. If not, replace the word or restructure the sentence.

> **Sentence:** The background worker runs every night.
> The approved meaning of the verb "run" is "execute a program or command."
> The writer means "operates on a schedule" — the meaning does not match.
> **Rewrite:** The background worker operates every night.

## P4 (Rule 1.4) — Approved verb and adjective forms only

The controlled terminology gives each approved verb with its approved forms,
and each approved adjective with its comparative and superlative forms.

| Infinitive/Imperative | Simple present | Simple past | Past participle |
|---|---|---|---|
| (To) Compile / Compile | Compile(s) | Compiled | Compiled |

`FAST (adj) (FASTER, FASTEST)` — base, comparative, superlative.
Adjectives that form the comparative with "more" and "most" have no listed
forms, because "more" and "most" are approved words.

Do not invent forms such as "compilating" or "compilates."

> **Non-STE:** The compiler is compilating the source files every time you save.
>
> **STE:** The compiler compiles the source files each time you save.

## P5 (Rule 1.5) — The 19 code-domain technical noun categories

You may use a word that is not in the controlled terminology when you can put
it in one or more of these categories. The examples are not a full list.

| # | Category | Examples |
|---|---|---|
| 1 | Code components, modules, and libraries | class, controller, helper, hook, middleware, mixin, module, package, plugin, provider, repository, service, utility |
| 2 | Computing devices and their components | CPU, disk, GPU, keyboard, laptop, memory, monitor, mouse, printer, screen, server, smartphone, tablet, terminal |
| 3 | Development tools, environments, and support equipment | CLI, compiler, debugger, Docker, editor, IDE, Git, Jest, linter, loader, Prettier, terminal, test runner, TypeScript, webpack |
| 4 | Data structures, types, and formats | array, boolean, buffer, CSV, enum, hash map, integer, JSON, linked list, object, queue, stack, string, struct, tree, tuple, XML, YAML |
| 5 | Infrastructure, deployment, and platforms | AWS, CI/CD, container, deployment, Heroku, Kubernetes, load balancer, Node.js, pipeline, pod, production, staging, Vercel |
| 6 | Systems, subsystems, and architectural components | API gateway, authentication layer, caching layer, client, database layer, message broker, microservice, proxy, rate limiter, REST API, routing layer, server, WebSocket |
| 7 | Mathematical, algorithmic, and scientific terms | Big O notation, binary search, coefficient, complexity, exponent, hash function, iteration, logarithm, matrix, recursion, regex, sorting algorithm, time complexity, traversal |
| 8 | Interface elements and navigation | button, checkbox, dialog, dropdown, footer, header, menu, modal, navigation bar, radio button, scrollbar, sidebar, tab, text field, toggle, tooltip |
| 9 | Numbers, units of measurement, and time | byte, gigabyte (GB), hertz (Hz), hour (h), kilobyte (KB), megabyte (MB), millisecond (ms), minute, nanosecond (ns), second (s), terabyte (TB) |
| 10 | Quoted text | `Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused` |
| 11 | Professional roles, teams, and organizations | administrator, backend developer, contributor, DevOps engineer, frontend developer, Google, maintainer, Microsoft, product owner, QA engineer, reviewer, scrum master, user |
| 12 | Official documents, API references, and standards | API reference, changelog, code of conduct, contributing guide, diagram, figure, Getting Started guide, HTTP specification, note, paragraph, README, release notes, RFC, section, table, warning |
| 13 | Runtime environments and operational conditions | development, environment variable, garbage collection, heap, hot reload, live reload, memory leak, production, sandbox, stack trace, staging, test, thread, timeout, virtual machine |
| 14 | Colors | black, blue, cyan, gray, green, magenta, orange, red, white, yellow |
| 15 | Defects, errors, and fault terminology | assertion failure, bug, crash, deadlock, defect, exception, hang, infinite loop, memory leak, null pointer, race condition, regression, stack overflow, timeout, type error |
| 16 | Computer science, information, and communication technology | AI, algorithm, authentication, authorization, blockchain, containerization, cryptography, database, encoding, encryption, firewall, hashing, internet, machine learning, metadata, neural network, protocol, query, sandbox, schema, token, virtualization |
| 17 | Legal and licensing terms | Apache 2.0, BSD license, compliance, copyright, GPL, license, MIT license, open source, proprietary, terms of service, third-party, trademark, warranty |
| 18 | Database and storage terminology | connection pool, cursor, foreign key, index, migration, NoSQL, ORM, PostgreSQL, primary key, query, Redis, relation, row, schema, seed, SQL, SQLite, stored procedure, table, transaction, view |
| 19 | Network and protocol terminology | DNS, endpoint, HTTP, HTTPS, IP address, localhost, middleware, packet, port, request, response, route, socket, SSH, TCP, TLS, UDP, URL, VPN, WebSocket |

Colors are adjectives, but STE-Code identifies them as code-domain technical
nouns. Comparative and superlative color forms (blacker, the reddest) are not
permitted.

### Glossary registration (required)

Before you use a code-domain technical noun, add it to the project glossary
with: the noun term, its category or categories, its approved meaning in the
project context, and one correct example sentence.

### Grammar notes

- **Articles.** Use "the" for a specific instance, "a"/"an" for an indefinite
  instance, no article for plural general references.
- **Modifiers.** A technical noun can modify another technical noun
  ("Redis cache server"). Both nouns must belong to a recognized category.
- **Possessive.** Use `'s` only with category 11 (roles, teams, organizations).
  Write "the configuration of the Docker container", not
  "the Docker container's configuration".
- **Plurals.** Add a lowercase "s" with no apostrophe: `APIs`, not `API's`.
- **Capitalization.** Proper nouns keep their original form (`TypeScript`).
  Common technical nouns are lowercase unless they start the sentence.

### Edge cases

1. **Framework names that are also common words** (React, Vue, Swift, Go, Rust,
   Next, Nest) are technical nouns in category 3 or 5. Capitalize them, or use
   the full term ("the Swift language"), so they are not read as approved words.
2. **Code keywords** (`if`, `for`, `return`, `class`, `async`) are quoted text
   (category 10) when they appear in documentation. Status codes and literals
   must be quoted too: "return `500 Internal Server Error`".
3. **Abbreviations and acronyms** (API, JSON, SQL, HTTP, TLS) are technical
   nouns in categories 16, 18, or 19. Define each one at first use unless the
   audience universally understands it.
4. **Generated code and generated documentation** are exempt, because a machine
   produces them. Human-written comments inside generated files are not exempt.
5. **Project-specific internal names** (`PhoenixCache`) are technical nouns
   only when they are in the project glossary. Without registration they are
   non-approved words and violate P6.
6. **Numbers as technical nouns.** Version numbers, HTTP status codes, and port
   numbers are category 9 nouns or quoted text and must appear verbatim
   ("port 5432", "`404 Not Found`"), not "the default db port".

## P6 (Rule 1.6) — Non-approved words only as technical nouns

Use a word that is not approved only when it is a code-domain technical noun or
part of one.

- "handler" is not approved; the alternative is "function (n)".

> **Non-STE:** The handler processes each incoming event.
>
> **STE:** The function processes each incoming event.

But "handler" is permitted inside a compound technical noun (category 1):

> **STE:** The event handler processes each incoming event.

- "main" is not approved; the approved adjective is "primary".

> **Non-STE:** The main configuration has the latest values.
>
> **STE:** The primary configuration has the latest values.

## P7 (Rule 1.7) — Do not use technical nouns as verbs

Use a code-domain technical noun only as a noun, or as a modifier inside
another technical noun. Restructure the sentence with an approved verb.

> **Non-STE:** Database the user records before the migration.
>
> **STE:** Store the user records in the database before the migration.

Same pattern: "cache the result" → "keep the result in the cache";
"host the service" → "run the service" or "make the service available".

## P8 (Rule 1.8) — Use the technical nouns your project already approves

If your project, company, industry, or subject field has an approved name for a
class, module, function, method, variable, component, or process, use that
name. Do not invent a description for something that already has a name in the
codebase.

> **STE:** The dashboard page has a `UserTable` component and a `FilterPanel`
> component.

The reader must be able to find the exact element in the source tree from the
name you used.

## P9 (Rule 1.9) — Short, clear technical nouns

When you must select a code-domain technical noun, use one that is short (not
more than three words) and easy to understand. If a code snippet, line number,
diagram, or API reference already identifies the item, use the shortest
unambiguous term. Add one or two adjectives only when the reader needs them.

> **Non-STE:** Call the asynchronous JavaScript XML HTTP request wrapper utility
> function (line 42) to get the serialized JSON payload from the remote
> application programming interface endpoint.
>
> **STE:** Call the `fetchUtility` function (line 42) to get the JSON data from
> the API endpoint.

## P10 (Rule 1.10) — No regional words, slang, or jargon

Some technical words are used only inside one community or one technology
ecosystem. Readers from a different background, a different stack, or a
different first language cannot understand them. Select well-known words.

| Do not write | Write |
|---|---|
| cruft | unnecessary code |
| snag the repo | clone the repository |
| fire up / spin up | start |
| kick off | start |
| crunch the data | process the data |
| wonky, funky | not correct, known defect |
| hack | workaround |
| repo, K8s, TS (in prose) | repository, Kubernetes, TypeScript |
| thing, stuff | the exact technical noun |

> **Non-STE:** `"""Remove all the cruft from the legacy module."""`
>
> **STE:** `"""Remove all the unnecessary code from the legacy module."""`

## P11 (Rule 1.11) — One technical noun per item

Do not use different code-domain technical nouns for the same item. The source
of truth for the name is the code: the class, function, module, table,
resource, environment variable, or configuration key as the repository defines
it.

> **Non-STE:**
> 1. Initialize the UserService class to start the session manager.
> 2. Call the authenticate method on the AccountManager to check a user.
> 3. The UserHandler gives a session token that you send in later requests.

The repository defines one class, `UserService`. Use that name in all three
sentences. When the reader sees three names, the reader cannot know whether
there is one class or three.

## P12 (Rule 1.12) — The 4 code-domain technical verb categories

A code-domain technical verb names an operation or process in software
development. You may use a technical verb when you can put it in one of these
four categories. The examples are not a full list.

| # | Category | Sub-group | Examples |
|---|---|---|---|
| 1 | Development processes | Write and modify code | compile, concatenate, import, inject, instantiate, lint, minify, marshal, optimize, polyfill, refactor, resolve, shim, stub, substitute, tokenize, transpile, trace, vectorize |
| 1 | Development processes | Test and verify code | assert, benchmark, debug, fuzz, instrument, mock, profile, snapshot, spy, stub, unit-test |
| 1 | Development processes | Build and package | bundle, deploy, package, publish, release, tag, version |
| 1 | Development processes | Manage dependencies | hoist, install, link, lock, pin, update, upgrade |
| 2 | Computer processes and applications | Input and output | click, copy, cut, digitize, enter, paste, press, print, scan, swipe, tap, type |
| 2 | Computer processes and applications | User interface and application operations | clear, close, delete, deselect, disable, drag, drag and drop, enable, encrypt, erase, filter, hide, highlight, invalidate, maximize, minimize, navigate, open, save, scroll, select, show, sort, store, submit, toggle, validate, zoom in, zoom out |
| 2 | Computer processes and applications | System operations | abort, authenticate, authorize, boot, cache, communicate, configure, debug, deserialize, download, format, hydrate, initialize, install, load, log, manage, mount, process, reboot, render, retry, serialize, spawn, synchronize, throttle, update, upgrade, upload |
| 3 | Applicable subject fields | Algorithmic, mathematical, and data | aggregate, bisect, compute, concatenate, convert, count, decode, encode, escape, filter, hash, index, map, merge, normalize, parse, pipeline, precompute, recalculate, reduce, tokenize, transform, validate, verify |
| 3 | Applicable subject fields | Database and storage | backup, compact, flush, index, migrate, persist, query, replicate, restore, roll back, seed, shard, upsert, vacuum, write-ahead |
| 3 | Applicable subject fields | Network and communication | broadcast, connect, disconnect, establish, forward, handshake, intercept, listen, poll, proxy, reject, resolve, route, send, stream, timeout, tunnel, unsubscribe, webhook |
| 3 | Applicable subject fields | Security and authentication | authenticate, authorize, decrypt, decode, encode, encrypt, hash, revoke, salt, sanitize, sign, validate, verify |
| 4 | Legal and licensing terms | Legal and regulatory texts only | acknowledge, assign, comply with, conform to, disclose, enforce, explain, grant, inform, license, modify, notify, permit, regulate, sign, supersede, waive |

Constraints:

- If an approved verb gives the instruction or the information accurately, use
  the approved verb. Do not use a technical verb when approved words are enough.
- Use only technical verbs that are correct in your context. Do not use general
  or unclear technical verbs.
- Where possible, use an approved verb together with a code-domain technical
  noun instead of a technical verb.
- Technical verbs obey the same rules as other approved verbs (section 3).

## P13 (Rule 1.13) — Do not use technical verbs as nouns

Use a code-domain technical verb only as a verb. When you need a noun, use an
approved noun or a code-domain technical noun with the same meaning.

| Do not write | Write |
|---|---|
| Do a build of the project | Build the project |
| The function does a parse of the input string | The function parses the input string |
| Does a compile of the source files | Compiles the source files |
| `// A retry of the connection` | `// Retry the connection` |
| Addition of login endpoint | Add login endpoint |
| Compile of module 'auth' failed | Failed to compile module 'auth' |

Some words belong to a verb category (P12) and a noun category (P5) at the same
time. When the API returns a named artifact (a `Build` object, a `Deployment`
resource), the noun form is a technical noun, not a misused verb.

## P14 (Rule 1.14) — American English spelling

Use the spelling given in the controlled terminology (American English). Use a
different spelling only when a project specification, style guide, contract, or
other official directive requires it.

| Do not write | Write |
|---|---|
| colour | color |
| fibre | fiber |
| initialise | initialize |
| serialise | serialize |
| behaviour | behavior |
| centre | center |

Do not change the spelling inside quoted text. If an error message, a comment,
or a user interface shows British English spelling, keep it verbatim:

> **STE:** The terminal shows the message `Colour profile not recognised`.

## Application by documentation type

| Document type | What P1–P14 constrain most |
|---|---|
| README | Imperative verbs in setup steps; adjectives and adverbs in the overview. Tool, file, and command names are technical nouns. |
| API reference | Prose around parameters, return values, and error conditions. Function, type, and endpoint names are technical nouns (P5). |
| Docstrings and inline comments | The shortest approved verb. `NOTE:`, `WARNING:` are approved nouns; `FIXME:` is a technical noun. |
| Commit messages | The smallest approved vocabulary, imperative form: add, fix, remove, update, set, make, check, run. |
| Error messages | Approved words only, so non-native readers understand. "cannot", not "unable to"; "not correct", not "invalid". |
| Test specifications | Name the component under test and the condition with technical nouns from categories 1, 4, and 15. |
| Code review and PR feedback | Approved verbs in every request for change; one technical noun per item (P11); no jargon (P10). |

## Template — code review comment

```markdown
**File:** `<path>:<line>`
**Type:** defect | question | suggestion
**Principle:** P<n> (Rule 1.<n>)

**What I see:** <one sentence, approved verb, present tense>

**Why it is a problem:** <one or two sentences; name the defect with a
category 15 technical noun where one applies>

**What to do:** <imperative sentence that starts with an approved verb:
add, remove, change, set, make, check, move, rename, split>
```

Filled example:

```markdown
**File:** `src/auth/UserService.ts:42`
**Type:** defect
**Principle:** P11 (Rule 1.11)

**What I see:** The docstring calls this class `AccountManager`. The file
defines the class `UserService`.

**Why it is a problem:** Two names for one class. The reader cannot know
whether there is one class or two.

**What to do:** Change the docstring to use `UserService` in all sentences.
```

Rules for review comments:

- Start each request for change with an approved imperative verb.
- Use one sentence for one point. Do not join two points with "and".
- Name the file and the line. Do not write "this thing" or "the stuff above".
- Do not use slang ("nit", "wonky", "hacky", "LGTM") in the body of the
  comment. Write "small point", "not correct", "workaround", "I approve".
- Do not use a technical noun as a verb (P7) or a technical verb as a noun
  (P13) in your own feedback.

## Template — pull request description

```markdown
# <Imperative summary line, one approved verb first, 72 characters or less>

## What this change does

<One paragraph. Each sentence has one clause. Use approved verbs and
code-domain technical nouns. Name every component with the name the
repository uses.>

## Why

<The defect, the request, or the requirement. Name the defect with a
category 15 technical noun: race condition, memory leak, regression,
timeout, type error.>

## How to check it

1. <Imperative step, approved verb first.>
2. <Imperative step, approved verb first.>
3. <The result the reviewer must see.>

## Risk

<What can break. Name the affected component and environment
(development, staging, production).>

## Related

- Issue: #<n>
- Documents changed: <README | API reference | changelog | none>
```

Filled example:

```markdown
# Fix the timeout defect in the connection pool

## What this change does

The `ConnectionPool` class now closes each idle connection after 30 seconds.
The class writes one line in the log for each connection that it closes.

## Why

The pool kept idle connections open. The database refused new connections
after 100 idle connections. This caused a crash in production.

## How to check it

1. Start the service in the development environment.
2. Send 120 requests to the `/orders` endpoint.
3. Check the log. The log must show `closed idle connection` for each
   connection that the pool closes.

## Risk

A short timeout can close a connection that a slow query still uses. Set
`POOL_IDLE_TIMEOUT` to a larger value if the staging tests show this defect.

## Related

- Issue: #482
- Documents changed: changelog
```

## Template — PR review summary

```markdown
**Decision:** approve | request changes | comment

**Summary:** <One sentence. What the change does, in approved words.>

**Blocking points**
1. `<path>:<line>` — <imperative sentence>
2. `<path>:<line>` — <imperative sentence>

**Non-blocking points**
1. `<path>:<line>` — <imperative sentence>

**Checked:** <what you ran or read: tests, linter, documentation>
```

## Level 1 compliance checklist

Run this list on every document before you publish it.

1. Each word is an approved word, a code-domain technical noun, or a
   code-domain technical verb. (P1)
2. Each approved word is used as its specified part of speech. (P2)
3. Each approved word carries only its approved meaning. (P3)
4. Each verb and adjective uses an approved form. (P4)
5. Each non-approved word fits one of the 19 noun categories, or is part of a
   compound that does. (P5, P6)
6. No technical noun is used as a verb. (P7)
7. Each component uses the name the project glossary and the repository give
   it. (P8)
8. Each technical noun is short (three words or less) and clear. (P9)
9. No regional word, slang word, or jargon word appears. (P10)
10. One item has exactly one name in the whole document. (P11)
11. Each technical verb fits one of the four verb categories, and no approved
    verb could do the same work. (P12)
12. No technical verb is used as a noun. (P13)
13. All spelling is American English, except inside quoted text. (P14)
14. Every technical noun and technical verb you introduced is registered in the
    project glossary.





## 02-synonyms.md

# Level 1 — Technical Noun Categories (Rule 1.5)

This is the Rule 1.5 slice of STE-Code Level 1: the **code-domain technical noun
categories** — the "approved-word / synonym table" that lets you use precise
domain terms outside the approved-word dictionary.

Level 1 controls *which words you may use*. Every other level builds on it. This
file is the LLM-facing form of Rule 1.5 (one of the three word-gates in Section 1).
It is faithful to the standard: the nineteen categories and their example terms
are taken from the authoritative Rule 1.5 adaptation, not invented. All examples
stay inside the code domain.

## Rule 1.5 — what it permits

**Rule 1.5** You can use words that you can include in a code-domain technical
noun category.

A code-domain technical noun is a noun term that refers to a specified concept in
software development and is applicable to a subject field. The controlled
terminology does not include all code-domain technical nouns because there are
too many, and each project or subject field uses different technical nouns. You
can find many of these in your project glossary or terminology database.

STE-Code gives you a list of nineteen categories, with examples, to help you:
- Select code-domain technical nouns to put in your project glossary.
- Use code-domain technical nouns correctly.

You can use code-domain technical nouns in procedural and descriptive writing if
you can include them in one or more of these nineteen categories.

Rule 1.5 is the **gateway for all domain-specific vocabulary**. Without it, every
project noun (`repository`, `middleware`, `race condition`) would be forbidden and
documentation would be unusable. With it, a non-approved word is allowed *only*
when it names a precise concept in one of the nineteen categories below.

## The three-word gate (Rules 1.1, 1.5, 1.6)

Use an approved word whenever one exists. Use a code-domain technical noun only
when no approved word names the concept. These three rules form a gate with no
fourth category:

| Gate | Rule | Allows |
|------|------|--------|
| Approved word | 1.1 | A word listed in the controlled terminology (the dictionary). |
| Technical noun | 1.5 | A non-approved word that fits at least one of the 19 categories below **and** is registered in your glossary. |
| Technical verb | 1.12 | A verb in the technical-verb category (for example `build`, `deploy`, `test`, `lint`, `compile`, `debug`). |

Any word that passes **none** of these three gates is forbidden by Rule 1.6.

> Non-STE: The developer used the thing to get data from the storage layer and put it on the screen.
> STE: The frontend developer used the API client to get data from the database and show it on the UI.
> (`frontend developer` = category 11, `API client` = category 16, `database` = category 18, `UI` = category 8 — each names a precise concept; "thing", "storage layer", "screen" do not.)

## Glossary registration (required)

Before you use a code-domain technical noun in documentation, add it to the
project glossary or terminology database. The glossary entry must specify:
- The noun term.
- The STE-Code category (or categories) it belongs to.
- The approved meaning in the project context.
- An example sentence that uses the noun correctly.

A project without a glossary risks ambiguity: the same noun may mean different
things to different readers, which also violates Rule 1.11 (one term per concept).
Project-specific internal names (for example `PhoenixCache`, `Hammerhead subsystem`)
are permitted only after glossary registration; without it they are non-approved
words and violate Rule 1.6.

---

## The 19 code-domain technical noun categories

The terms under each category are **examples only** — Rule 1.5 does not give a
full list. A word belongs in a category if it names a precise software concept.
Register every project-specific noun in your glossary before using it. When a term
is a literal identifier, API name, or exact string from code (a class name,
function name, environment variable, or error message), show it in backticks —
for example `UserRepository`, `NODE_ENV`, `"404 Not Found"`.

### 1. Code components, modules, and libraries
Software parts, packages, and reusable units of code.
`class`, `controller`, `helper`, `hook`, `middleware`, `mixin`, `module`, `package`, `plugin`, `provider`, `repository`, `service`, `utility`

### 2. Computing devices and their components
Hardware, devices, and physical computing resources.
`CPU`, `disk`, `GPU`, `keyboard`, `laptop`, `memory`, `monitor`, `mouse`, `printer`, `screen`, `server`, `smartphone`, `tablet`, `terminal`

### 3. Development tools, environments, and support equipment
Development tools, IDEs, build systems, and testing frameworks.
`CLI`, `compiler`, `debugger`, `Docker`, `editor`, `IDE`, `Git`, `Jest`, `linter`, `loader`, `Prettier`, `terminal`, `test runner`, `TypeScript`, `webpack`

### 4. Data structures, types, and formats
Data representation, storage structures, and file formats.
`array`, `boolean`, `buffer`, `CSV`, `enum`, `hash map`, `integer`, `JSON`, `linked list`, `object`, `queue`, `stack`, `string`, `struct`, `tree`, `tuple`, `XML`, `YAML`

### 5. Infrastructure, deployment, and platforms
Hosting, deployment, containerization, and runtime platforms.
`AWS`, `CI/CD`, `container`, `deployment`, `Heroku`, `Kubernetes`, `load balancer`, `Node.js`, `pipeline`, `pod`, `production`, `staging`, `Vercel`

### 6. Systems, subsystems, and architectural components
System design, architecture patterns, and their parts.
`API gateway`, `authentication layer`, `caching layer`, `client`, `database layer`, `message broker`, `microservice`, `proxy`, `rate limiter`, `REST API`, `routing layer`, `server`, `WebSocket`

### 7. Mathematical, algorithmic, and scientific terms
Algorithms, computational concepts, and mathematical formulas.
`Big O notation`, `binary search`, `coefficient`, `complexity`, `exponent`, `hash function`, `iteration`, `logarithm`, `matrix`, `recursion`, `regex`, `sorting algorithm`, `time complexity`, `traversal`

### 8. Interface elements and navigation
UI components, navigation controls, and layout elements.
`button`, `checkbox`, `dialog`, `dropdown`, `footer`, `header`, `menu`, `modal`, `navigation bar`, `radio button`, `scrollbar`, `sidebar`, `tab`, `text field`, `toggle`, `tooltip`

### 9. Numbers, units of measurement, and time
Quantitative data, measurements, and time-related information.
`byte`, `gigabyte (GB)`, `hertz (Hz)`, `hour (h)`, `kilobyte (KB)`, `megabyte (MB)`, `millisecond (ms)`, `minute`, `nanosecond (ns)`, `second (s)`, `terabyte (TB)`

### 10. Quoted text
Texts you cannot change in code documentation — error messages, code snippets, UI labels, log output.
`Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused`

### 11. Professional roles, teams, and organizations
Roles, individuals, organizations, and teams related to software development.
`administrator`, `backend developer`, `contributor`, `DevOps engineer`, `frontend developer`, `Google`, `maintainer`, `Microsoft`, `product owner`, `QA engineer`, `reviewer`, `scrum master`, `user`

### 12. Official documents, API references, and standards
Documentation types, standards, specifications, and their structural parts.
`API reference`, `changelog`, `code of conduct`, `contributing guide`, `diagram`, `figure`, `Getting Started guide`, `HTTP specification`, `note`, `paragraph`, `README`, `release notes`, `RFC`, `section`, `table`, `warning`

### 13. Runtime environments and operational conditions
Execution contexts, environment variables, and operating parameters.
`development`, `environment variable`, `garbage collection`, `heap`, `hot reload`, `live reload`, `memory leak`, `production`, `sandbox`, `stack trace`, `staging`, `test`, `thread`, `timeout`, `virtual machine`

### 14. Colors
Colors that identify color-related properties in code (CSS, terminal output, syntax highlighting).
`black`, `blue`, `cyan`, `gray`, `green`, `magenta`, `orange`, `red`, `white`, `yellow`
Colors are adjectives, but STE-Code identifies them as code-domain technical nouns. Comparative and superlative forms (for example, `blacker`, `the reddest`) are not permitted.

### 15. Defects, errors, and fault terminology
Types of software defects, errors, and malfunctions.
`assertion failure`, `bug`, `crash`, `deadlock`, `defect`, `exception`, `hang`, `infinite loop`, `memory leak`, `null pointer`, `race condition`, `regression`, `stack overflow`, `timeout`, `type error`

### 16. Computer science, information, and communication technology
Concepts, technologies, and architectures in computing and communication.
`AI`, `algorithm`, `authentication`, `authorization`, `blockchain`, `containerization`, `cryptography`, `database`, `encoding`, `encryption`, `firewall`, `hashing`, `internet`, `machine learning`, `metadata`, `neural network`, `protocol`, `query`, `sandbox`, `schema`, `token`, `virtualization`

### 17. Legal and licensing terms
Software licenses, legal documents, and compliance terminology.
`Apache 2.0`, `BSD license`, `compliance`, `copyright`, `GPL`, `license`, `MIT license`, `open source`, `proprietary`, `terms of service`, `third-party`, `trademark`, `warranty`

### 18. Database and storage terminology
Database concepts, storage systems, and data persistence.
`connection pool`, `cursor`, `foreign key`, `index`, `migration`, `NoSQL`, `ORM`, `PostgreSQL`, `primary key`, `query`, `Redis`, `relation`, `row`, `schema`, `seed`, `SQL`, `SQLite`, `stored procedure`, `table`, `transaction`, `view`

### 19. Network and protocol terminology
Networking concepts, protocols, and communication.
`DNS`, `endpoint`, `HTTP`, `HTTPS`, `IP address`, `localhost`, `middleware`, `packet`, `port`, `request`, `response`, `route`, `socket`, `SSH`, `TCP`, `TLS`, `UDP`, `URL`, `VPN`, `WebSocket`

---

## Apply the categories by document type

Use the categories named here as your first-choice technical nouns for each kind
of documentation. Use an approved verb everywhere an approved word fits.

- **README files** — categories 1 (code components), 3 (development tools), 5 (infrastructure), 17 (legal). Example: "This package provides a `middleware` for `Express`." (`package` c1, `middleware` c1, `Express` c5.)
- **API documentation** — categories 6 (systems), 18 (database), 19 (network). Example: "The `GET /users/:id` route returns a `JSON` object with a user `struct`." (`route` c19, `JSON` c4, `struct` c4.)
- **Docstrings and inline comments** — categories 4 (data types), 7 (algorithms), 15 (defects). Example: "Traverse the binary search tree in-order and return a sorted `array`."
- **Commit messages** — categories 1 (code components), 15 (defects), 18 (database). Example: "Fix a `timeout` defect in the `connection pool` that caused a `deadlock` on `PostgreSQL`."
- **Error messages** — categories 13 (runtime), 15 (defects), 19 (network). Example: "Connection refused: the `TCP` `socket` on `port 5432` timed out after 30 seconds."
- **Test specifications** — categories 1 (code components), 4 (data types), 15 (defects). Example: "The test calls the `parseConfig` function with a `null pointer` and checks that it returns an `assertion failure`."

## Paradigm-specific guidance

Use the categories shown as your first-choice technical nouns for each paradigm.

- **Object-oriented (Java, C++, C#, Python classes)** — categories 1 (code components), 4 (data types), 6 (systems). Class, method, interface, and design-pattern names are technical nouns. Acceptable: "The `UserRepository` class extends the `BaseRepository` abstract class and implements the `IAuditable` interface." Do not write "The repo leverages the base to retrieve user data." (`leverage` is not approved; `repo` is a non-standard abbreviation — use `repository`.)
- **Functional (Haskell, Elixir, Clojure, Rust)** — categories 7 (algorithms), 4 (data types), 16 (computer science). Terms such as `monad`, `functor`, `closure`, `currying`, `pattern matching`, `recursion`, `immutability` are technical nouns. Acceptable: "The function returns an `Option` monad. Use pattern matching to extract the value." Do not write "The combinator stuff chains stuff together to make new stuff."
- **Procedural (C, Go, Bash)** — categories 4 (data types), 13 (runtime), 19 (network). Terms such as `pointer`, `struct`, `mutex`, `goroutine`, `channel`, `file descriptor`, `signal` are technical nouns. Acceptable: "The C function accepts a `pointer` to a `FILE` struct and returns an integer status code." Do not write "The script fires off a subprocess to crunch the numbers." (`fires off` → `starts`; `crunch` → `process`.)
- **Declarative (SQL, Terraform, Kubernetes YAML)** — categories 18 (database), 5 (infrastructure), 12 (official documents). `SELECT`, `JOIN`, resource, module, provider, pod, deployment, namespace are technical nouns; SQL keywords and YAML keys are quoted text (category 10) when referenced verbatim. Acceptable: "The `SELECT` statement uses an `INNER JOIN` on the `users` and `orders` tables." Do not write "K8s spins up a bunch of pods inside the thing." (`K8s` → `Kubernetes`; `spins up` → `starts`; `thing` → `namespace`.)
- **Systems programming (Rust ownership, C memory management)** — categories 13 (runtime), 4 (data types), 15 (defects). `ownership`, `borrow`, `lifetime`, `stack`, `heap`, `allocation`, `undefined behavior`, `segmentation fault` are technical nouns. Acceptable: "The Rust compiler enforces the ownership rules. The borrow checker prevents dangling pointers at compile time." Do not write "Rust's thingy stops you from shooting yourself in the foot with memory stuff."

---

## Edge cases

- **Framework names that are also common words** (`React`, `Vue`, `Swift`, `Go`, `Rust`, `Elm`, `Next`, `Nest`). When a framework name is also an approved word, the framework name is a code-domain technical noun (category 3 or 5) and does not follow the approved meaning. Always capitalize it to disambiguate: "Use the `React` framework to build the user interface" (not the verb *react*); "The `Go` compiler builds the binary" (not the verb *go*).
- **Code keywords in documentation.** Keywords (`if`, `else`, `for`, `while`, `return`, `class`, `def`, `fn`, `let`, `const`, `var`, `async`, `await`) are quoted text (category 10) when they appear in documentation. Use backticks. When you use them as English words in a sentence, they must follow approved meanings. Write: "If the request fails, return `500 Internal Server Error`." (not "return a 500" — `500` is quoted text or a category-9 noun and must appear verbatim).
- **Abbreviations and acronyms** (`API`, `JSON`, `SQL`, `HTML`, `CSS`, `HTTP`, `TCP`, `TLS`, `DNS`, `URL`). Permissible as technical nouns in categories 16, 18, or 19. Define each at first use unless universally understood: "The application programming interface (API) uses Hypertext Transfer Protocol Secure (HTTPS)." Then "The API returns a JSON response over HTTPS." Do not write "The API leverages HTTPS to transmit the payload" (`leverage`/`transmit`/`payload` are not approved — use `use`/`send`/`data` or define `payload` as a technical noun).
- **Generated code and auto-generated docs.** OpenAPI specs, protobuf stubs, migration files, JSDoc/Sphinx output are not required to follow STE-Code (a machine produces them). Any human-written comment, description, or annotation inside generated files must follow STE-Code. Write `// Workaround: clear the Redis cache when the heap reaches the limit.` Do not write `// this hack works around a funky TS bug` (`hack` → `workaround`; `funky` → `known defect`; `TS` → `TypeScript`).
- **Project-specific internal names.** Permitted under category 1 or 6 only after glossary registration. "The `PhoenixCache` layer stores frequently accessed data in memory." is acceptable *with* a glossary entry; without it, Rule 1.6 forbids the name.
- **Numbers as technical nouns.** A version (`Node.js 18`), HTTP status (`404`), or port (`port 5432`) is a category-9 noun or quoted text (category 10) when it is a fixed, named token, not a measured quantity. Write: "The service runs on `port 5432` and returns `404 Not Found` when the row is absent." Do not write "the default db port" or "a not found error."

## Grammar notes

- **Articles.** Use `the` for a specific instance, `a`/`an` for an indefinite instance, and no article for plural general references. "The `UserController` handles a request. The controller returns a response." / "Kubernetes pods run in a namespace."
- **Technical nouns as modifiers.** A technical noun can modify another noun to form a compound, if both belong to a recognized category. "The `Redis` cache server stores the session data." (`Redis` c18 modifies `cache server` c6; `session data` = `session` c13 + `data` c4.) Do not write "The thing layer processes the stuff queue."
- **Possessive form.** Permit `'s` only with category-11 nouns (roles, organizations). "The user's session data is encrypted." Use "of" or noun-as-modifier for all other categories: "The configuration of the `Docker` container is stored in a YAML file." Do not write "The `Docker` container's configuration…".
- **Pluralization.** Standard English rules. Acronyms take a lowercase `s` without an apostrophe. "The system uses two APIs and three SQL queries." Do not write "two API's and three SQL's".
- **Capitalization.** Proper-noun technical nouns (language names, company names, product names) keep their capitalization; common technical nouns use lowercase unless sentence-initial. "The `TypeScript` compiler checks the types. The controller handles the request." Do not write "the typescript compiler" or "The Controller".

## Cross-references

- **Rule 1.1 (Approved Words):** the dictionary of approved common-vocabulary words. Rule 1.5 is the exception that lets you use non-approved words as technical nouns.
- **Rule 1.2 (Part of Speech):** use a technical noun only as a noun or noun modifier; never as a verb.
- **Rule 1.3 (Approved Meanings):** use each technical noun only with the meaning registered in your glossary.
- **Rule 1.4 (Verb and Adjective Forms):** a word that is a technical noun may still have an approved verb form — use the verb form for actions and the noun form for naming concepts.
- **Rule 1.6 (Non-Approved Words):** forbids every non-approved word that is not a code-domain technical noun. Read Rules 1.5 and 1.6 together.
- **Rule 1.7 (Technical Nouns as Verbs):** a technical noun cannot be used as a verb (for example `host` is a noun; use `make available` or `run`).
- **Rule 1.8 (Standard Technical Nouns):** use widely accepted terms; do not invent one when a standard exists.
- **Rule 1.9 (Short Technical Nouns):** prefer short, clear technical nouns.
- **Rule 1.11 (One Term per Concept):** each technical noun refers to exactly one concept in your project.
- **Rule 1.12 (Technical Verbs):** `build`, `deploy`, `test`, `lint`, `compile`, `debug` and similar are permitted technical verbs — they are not technical nouns; do not confuse the two.

## Summary

Rule 1.5 is the gateway for all domain-specific vocabulary. It permits a word
outside the approved dictionary *only* when that word names a precise concept in
one of the nineteen code-domain categories above and is registered in your project
glossary. Follow it together with Rules 1.1 and 1.6: documentation then uses exactly
two kinds of words — approved STE-Code words for common vocabulary, and code-domain
technical nouns (plus technical verbs) for domain-specific concepts. There is no
third category.



## 03-dictionary.md

# Level 1 — Adapted Dictionary (A–Z excerpt)

A code-domain adaptation of the ASD-STE100 Issue 9 dictionary (Part 2, pp. 149–434).
It teaches the STE approval model for words: which words are approved, which are
not, and how to rewrite unapproved words into approved ones using code examples.

Use this slice when you write or review:
- API documentation and reference pages
- Commit messages and pull-request descriptions
- README sections and module/package overviews
- Inline code comments and docstrings

Scope note: this excerpt shows the entry format with a few canonical examples
(letter **A**). The complete approved (~875) and unapproved (~1274) word lists
are bundled at higher STE-Code tiers. Lower tiers use this curated sample to
learn the pattern; do not invent words beyond what the dictionary lists.

---

## How to read an entry

- **UPPERCASE words** are approved in STE-Code — you may use them.
- **lowercase words** are unapproved — replace them with the listed alternative.
  Unapproved status is also marked with the tag **UNNAPROVED** on the entry.
- Each entry carries a part-of-speech tag:
  `(v)` verb · `(n)` noun · `(adj)` adjective · `(adv)` adverb ·
  `(prep)` preposition · `(conj)` conjunction · `(pron)` pronoun · `(art)` article
- Code-domain technical tags:
  `(TN)` = code-domain Technical Noun (e.g. *config*, *endpoint*, *pipeline*)
  `(TV)` = code-domain Technical Verb (e.g. *deploy*, *build*, *parse*)
- Every entry shows three things:
  1. the original ASD-STE100 rule text,
  2. the same idea rewritten for code documentation,
  3. one or more STE / non-STE code-example pairs demonstrating the approved form.

### LLM guidance

When generating or reviewing code documentation, prefer UPPERCASE-approved words
and the verbs listed as alternatives for unapproved words (e.g. use `STOP`/`TERMINATE`
instead of `abandon`, `CAN` instead of `ability to`). Keep the approved form as
the short, direct sentence; the non-STE form is the longer, indirect phrasing to
avoid.

---

# A

## A (art)
Function word: indefinite article.
- **Original:** A FUEL PUMP IS INSTALLED IN ZONE 10.
- **Code-domain:** A CONFIG FILE IS INCLUDED IN THE ROOT DIRECTORY.
- **STE:** A config file is included in the root directory.
- **Non-STE:** Config files included in root directory.

## ABANDON (v) — UNNAPROVED
Not approved. Replace with `STOP` (v) or `TERMINATE` (v).
- **Original:** GO (v), STOP (v). IF THERE IS A FIRE, IMMEDIATELY GO TO A SAFE AREA. / IF THE VALUES ARE INCORRECT, STOP THE TEST PROCEDURE.
- **Code-domain:** TERMINATE (v), STOP (v). IF THE BUILD FAILS, STOP THE DEPLOYMENT PIPELINE. / IF THE VALUES ARE INCORRECT, TERMINATE THE TEST RUN.
- **STE:** If the build fails, stop the deployment pipeline.
- **Non-STE:** If the build fails, abandon the deployment pipeline.
- **STE:** If the values are incorrect, terminate the test run.
- **Non-STE:** If the values are incorrect, abandon the test procedure.

## ABILITY (n) — UNNAPROVED
Not approved. Replace with `CAN` (v).
- **Original:** CAN (v). ONE GENERATOR CAN SUPPLY POWER FOR ALL THE SYSTEMS.
- **Code-domain:** CAN (v). ONE CONFIGURATION CAN HANDLE REQUESTS FOR ALL THE ENDPOINTS.
- **STE:** One configuration can handle requests for all the endpoints.
- **Non-STE:** One configuration has the ability to handle requests for all the endpoints.

---

## Quick substitutions (from this excerpt)

| Unapproved (avoid) | Approved replacement | Example (STE) |
| --- | --- | --- |
| abandon (v) | STOP (v), TERMINATE (v) | If the build fails, stop the deployment pipeline. |
| ability (n) (as "has the ability to") | CAN (v) | One configuration can handle all the endpoints. |

When you see an unapproved word in source text, swap it for the approved verb and
keep the sentence short and direct. Approved articles such as **A** stay as-is.



## 04-templates.md

# Level 1 — Document Templates (Code Review / PR Feedback)

These templates apply STE-Code Level 1 (Rules 1.1–1.14) to the two document
types where controlled words matter most in day-to-day engineering work: code
review comments and pull request feedback.

Each template is a fill-in shape. Every word you add must pass one of the three
Level 1 gates:

1. It is approved in the controlled terminology (the STE-Code dictionary).
2. It is a code-domain technical noun (Rule 1.5, 19 categories).
3. It is a code-domain technical verb (Rule 1.12).

Identifiers, file paths, commands, and type names are technical nouns. Write
them in backticks and do not inflect them.

## Template selection

| Situation | Template |
|-----------|----------|
| One line or one hunk in a diff | T1 — Inline review comment |
| A defect the author must fix before merge | T2 — Blocking review finding |
| An optional improvement | T3 — Non-blocking suggestion |
| The summary you leave on the whole pull request | T4 — PR review summary |
| The description the author writes on the pull request | T5 — PR description |
| A reply to review feedback | T6 — Author response |

## Shared word rules for all templates

| Do not write | Write |
|--------------|-------|
| This looks a bit weird / smells off | This function returns `null` when the input list is empty. |
| Can we maybe just not do this? | Remove the call to `resetCache`. |
| It'd be great if you could refactor | Move the retry logic into `RetryPolicy`. |
| The code is broken | The `parseDate` function throws `TypeError` for an empty string. |
| We should probably handle errors | Catch `IOError` in `readConfig` and return a default value. |

Rules applied above: 1.1 (approved words only), 1.9 (short technical nouns),
1.10 (no slang or jargon), 1.11 (one noun per item).

## T1 — Inline review comment

Shape (three parts, in this order):

```
<observation>: one sentence, one subject, present tense.
<effect>: one sentence that gives the result of the observation.
<action>: one imperative sentence.
```

Example:

> The `getUser` function returns `undefined` when `id` is `0`.
> The caller in `UserController` then reads a property of `undefined`.
> Return `null` for an unknown `id`, and check the result in `UserController`.

Constraints:

- Use the imperative form for the action (Rule 5.3 style, applied at word level
  by Rule 1.4: approved verb forms only).
- Name the item with the same technical noun each time (Rule 1.11). Do not write
  `getUser`, then "the getter", then "that helper".
- Do not use a technical noun as a verb (Rule 1.7). Write "Send a request to the
  `/users` endpoint", not "Endpoint the request".

## T2 — Blocking review finding

```
**Finding:** <one sentence: what is wrong>
**Location:** `<path>:<line>` in `<symbol>`
**Cause:** <one sentence>
**Result:** <one sentence: what fails, and when>
**Required change:** <one imperative sentence>
```

Example:

> **Finding:** The `saveOrder` method does not validate the `quantity` field.
> **Location:** `src/orders/service.ts:142` in `OrderService.saveOrder`
> **Cause:** The method writes the request body to the database with no check.
> **Result:** A negative `quantity` value is written to the `orders` table.
> **Required change:** Reject a request when `quantity` is less than `1`.

Use "required change" for a defect. Do not use "must" as an intensifier in the
prose. The field label already gives the obligation.

## T3 — Non-blocking suggestion

```
**Suggestion (optional):** <one imperative sentence>
**Reason:** <one sentence>
```

Example:

> **Suggestion (optional):** Move the three retry constants into `RetryPolicy`.
> **Reason:** The same three values occur in `HttpClient` and in `QueueWorker`.

Mark the comment as optional in the first word. Do not use hedge words such as
"maybe", "perhaps", or "just" to signal that a comment is optional (Rule 1.10).

## T4 — PR review summary

```
**Decision:** Approve | Request changes | Comment
**Scope:** <one sentence: what the pull request changes>
**Blocking findings:** <count>
1. <one sentence each, with `path:line`>
**Optional suggestions:** <count>
1. <one sentence each>
**Verification:** <one sentence: what you ran or read>
```

Example:

> **Decision:** Request changes
> **Scope:** The pull request adds a rate limiter to the `/api/v1/login` route.
> **Blocking findings:** 1
> 1. `src/middleware/rateLimit.ts:58` — The limiter counts a failed request and
>    a successful request in the same bucket.
> **Optional suggestions:** 1
> 1. Give the `WINDOW_MS` constant a unit in its name.
> **Verification:** I ran `npm test` and read the diff in `src/middleware`.

Write the decision as one of the three approved values. Do not invent a fourth
value, and do not write the decision as a sentence.

## T5 — PR description (author)

```
## What
<one to three sentences. One subject in each sentence.>

## Why
<one to three sentences. Give the cause, then the result.>

## How
1. <imperative sentence>
2. <imperative sentence>

## Test
- <one sentence per check, with the command in backticks>

## Risk
<one sentence. Write "None." when there is no risk.>
```

Example:

> ## What
> This pull request adds a retry to the `PaymentClient.charge` method.
>
> ## Why
> The payment gateway returns `503` during a deployment. The current client
> fails the order on the first `503` response.
>
> ## How
> 1. Add a `RetryPolicy` class with three attempts and an exponential delay.
> 2. Call `RetryPolicy.execute` from `PaymentClient.charge`.
>
> ## Test
> - Run `npm test -- payment` to check the new unit tests.
> - Send a request to the sandbox gateway to check the delay values.
>
> ## Risk
> A retry can create a duplicate charge if the gateway accepted the first
> request. The client sends an idempotency key to prevent this result.

## T6 — Author response to feedback

```
**Comment:** <link or `path:line`>
**Response:** Done | Changed | Not changed
**Detail:** <one sentence>
```

Example:

> **Comment:** `src/middleware/rateLimit.ts:58`
> **Response:** Changed
> **Detail:** The limiter now counts only a failed request in the login bucket.

Use one of the three approved response values. Do not use "LGTM", "nit", "wontfix",
or other jargon labels (Rule 1.10).

## Approved verbs for review and PR text

Use these code-domain technical verbs in the action line of any template. Use
the base form for an instruction, and the third-person form for a statement of
fact.

| Verb | Use it for |
|------|-----------|
| add | New code, a new field, a new file |
| remove | Deleted code or a deleted field |
| replace | One item exchanged for another |
| move | Code relocated with no change in behavior |
| rename | A new name for the same item |
| return | The value a function gives back |
| throw / raise | An error the code emits |
| catch / handle | An error the code accepts |
| validate | A check on input |
| reject | A refused input or request |
| call | Invocation of a function or method |
| read / write | Access to a file, field, or record |
| log | A record written to the audit trail or log |
| test | A check that runs in the test suite |

Do not use a verb from this table as a noun (Rule 1.13). Write "The function
returns a value", not "The return of the function".

## Forbidden words in review and PR text

| Forbidden | Reason | Use instead |
|-----------|--------|-------------|
| nit, LGTM, WIP, PTAL, IMO | jargon (Rule 1.10) | the full template label |
| smelly, hacky, ugly, clean | subjective, not approved (Rule 1.1) | the concrete defect |
| stuff, thing, some code | not a technical noun (Rule 1.5) | the identifier in backticks |
| leverage, utilize | not approved (Rule 1.3) | use |
| behaviour, initialise, colour | British spelling (Rule 1.14) | behavior, initialize, color |
| we should maybe possibly | hedging (Rule 1.1) | one imperative sentence |

## Checklist before you post

1. Each sentence has one subject.
2. Each item has one name, used every time (Rule 1.11).
3. Each identifier is in backticks and is not inflected.
4. Each action is one imperative sentence.
5. No word from the forbidden table is present.
6. Spelling is American English (Rule 1.14).





# === tier level2 ===


# STE-Code Level 2 — distilled index

> + section-specific grammar rules

## Sub-documents

- 01-principles.md
- 02-synonyms.md
- 03-dictionary.md
- 04-templates.md
- 05-grammar.md



## 01-principles.md

# Level 2 — Core Principles (Section 1: Words)

Section 1 of STE-Code holds the fourteen word-level rules. Every word in code
documentation must pass one of three gates:

1. It is approved in the STE-Code controlled terminology.
2. It is a code-domain technical noun (Rule 1.5).
3. It is a code-domain technical verb (Rule 1.12).

There is no fourth category. Rule 1.6 forbids everything else.

| Rule | Statement |
|------|-----------|
| 1.1 | Use words that are approved in the controlled terminology, code-domain technical nouns, or code-domain technical verbs. |
| 1.2 | Use approved words only as the specified part of speech. |
| 1.3 | Use approved words only with their approved meanings. |
| 1.4 | Use only the approved forms of verbs and adjectives. |
| 1.5 | You can use words that you can include in a code-domain technical noun category. |
| 1.6 | Use a non-approved word only when it is a code-domain technical noun or part of one. |
| 1.7 | Do not use code-domain technical nouns as verbs. |
| 1.8 | Use code-domain technical nouns that are approved in your project, company, industry, or subject field. |
| 1.9 | When you must select a code-domain technical noun, use one which is short and easy to understand. |
| 1.10 | Do not use regional, slang, or jargon words as code-domain technical nouns. |
| 1.11 | Do not use different code-domain technical nouns for the same item. |
| 1.12 | You can use verbs that you can include in a code-domain technical verb category. |
| 1.13 | Do not use code-domain technical verbs as nouns. |
| 1.14 | Use American English spelling unless other official directives tell you differently. |

---

## Rule 1.1 — Use approved words, technical nouns, or technical verbs

In code documentation, use words that are approved in the project controlled
terminology, code-domain technical nouns, or code-domain technical verbs.

- A code-domain technical noun names a concept in software development
  (`UserAuthenticator`, connection pool, race condition).
- A code-domain technical verb names an operation or process in software
  development (serialize, compile, deploy).
- The controlled terminology also lists non-approved words with approved
  alternatives. Register project terms in the project glossary.

Common replacements:

| Do not write | Write |
|--------------|-------|
| execute, invoke (prose) | run, call |
| generate, construct | make |
| configure | set |
| retrieve, fetch | get |
| transmit | send |
| delete, purge | remove |
| validate, verify, ensure | check |
| utilize, leverage | use |
| initiate, bootstrap, commence | start |
| terminate | stop |
| unable to | cannot |
| invalid, malformed | not correct |
| prior to | before |
| at this time | now |
| persists | continues |

Examples:

> **Non-STE:** Execute the script to do the task.
>
> **STE:** Run the script to do the task.

> **Non-STE:** To begin utilizing the build toolchain, you must first generate the distributable artifact, then execute the compiled binary to bootstrap the local development service.
>
> **STE:** Use the build tool to make the binary. Run the binary to start the local service.

> **Non-STE:** `Error: Unable to establish connection to the database. Please verify your credentials and retry.`
>
> **STE:** `Error: Cannot connect to the database. Check your credentials and try again.`

Application by documentation type:

- **README** — approved imperative verbs in setup steps; approved adjectives in
  overview prose ("large" not "substantial", "usual" not "conventional").
- **API reference** — names stay as technical nouns; the prose around them uses
  approved words ("gives" not "resolves", "gives an error" not "rejects").
- **Docstrings and comments** — shortest approved word: "do" not "perform",
  "check" not "ensure", "make" not "construct".
- **Commit messages** — approved imperative verbs only: add, fix, remove,
  update, set, make, check, run. Not "implement" (use "add"), not "optimize"
  (use "make faster").
- **Error messages** — approved words only, no jargon or abbreviations that are
  not technical nouns.

---

## Rule 1.2 — Use approved words only as the specified part of speech

Each approved word has a specified part of speech in the controlled
terminology. Use the word only in that role.

- "Query" is an approved noun, not an approved verb.
- "Static" is an approved adjective, not an approved verb.
- Some words are approved in more than one role. "Call" is an approved verb
  (to call a function) and an approved noun (a function call). Position in the
  sentence shows which role applies.

When a word is not in the controlled terminology: find it in a standard
English dictionary, find the closest approved synonym, then use the approved
word or a different sentence construction. A replacement must not change the
meaning.

| Violating form | Error | Write |
|----------------|-------|-------|
| Query the database / Cache the result / Queue the job / Log the error / Index the record | Technical noun used as verb | Send a query / Keep the result in the cache / Put the job in the queue / Write the error in the log / Use the index to find the record |
| Docker the app / Git the change / Kubectl the pod / Terraform the VPC | Tool name used as verb | Use Docker / Save with Git / Use `kubectl` / Use Terraform |
| Secure the endpoint / Empty the buffer / Silent the log | Adjective used as verb | Make the endpoint secure / Make the buffer empty / Make the log silent |
| Static the variable / Ready the worker / Live the connection | Adjective used as verb | Make the variable static / Make the worker ready / Make the connection live |
| Utilize the cache / Leverage the library / Employ the service | Unapproved verb | Use the cache / Use the library / Use the service |
| Commence the build / Initiate the transfer / Terminate the process | Unapproved verb | Start the build / Start the transfer / Stop the process |
| Orchestrate the services / Facilitate the sync | Unapproved verb | Control the services / Help the sync |

"Clear" is approved as both a verb and an adjective, so "Clear the flag" is
permitted. The make + adjective pattern applies to true adjectives such as
"secure" and "empty".

---

## Rule 1.3 — Use approved words only with their approved meanings

Each approved word has a specified meaning that is often narrower than its
standard English meaning. Do not use the word with any other meaning.

- The approved meaning of "follow" is "come after, go after".
- The approved meaning of "obey" is "to do that which the procedures or
  instructions tell you".

Check procedure (run every content word through it):

1. Identify the part of speech as you wrote it.
2. Look up the approved meaning for that part of speech in the dictionary.
3. Ask whether your sentence uses exactly that meaning. If not, the word fails
   even though it is approved and the sentence reads well.
4. Replace the word, or rewrite the sentence so the word carries its approved
   meaning.

Worked check:

> **Sentence:** The background worker runs every night.
> **Step 1:** "runs" is a verb.
> **Step 2:** Approved meaning of the verb "run" = "execute a program or command".
> **Step 3:** The writer means "operates on a schedule". No match.
> **Step 4:** "The background worker operates every night."

---

## Rule 1.4 — Use only the approved forms of verbs and adjectives

The controlled terminology gives each approved verb with its approved forms,
and each approved adjective in base form with its comparative and superlative
forms where applicable.

| Infinitive/Imperative | Simple present | Simple past | Past participle (as adjective) |
|-----------------------|----------------|-------------|--------------------------------|
| (To) Compile / Compile | Compile(s) | Compiled | Compiled |

Adjective: FAST (adj) (FASTER, FASTEST). Base "fast", comparative "faster",
superlative "fastest". Adjectives that form comparatives with "more" and "most"
have no listed forms, because "more" and "most" are approved words.

Do not invent forms.

> **Non-STE:** The compiler is compilating the source files every time you save the document, and it compilates them even when no change occurs in the code.
>
> **STE:** The compiler compiles the source files each time you save the document, and it compiles them even when no change occurs in the code.

---

## Rule 1.5 — Code-domain technical noun categories

You can use a word that is not in the controlled terminology when you can put
it in one or more of these nineteen categories. Register each such noun in the
project glossary with its category, its approved meaning in the project, and an
example sentence.

| # | Category | Examples |
|---|----------|----------|
| 1 | Code components, modules, and libraries | class, controller, helper, hook, middleware, mixin, module, package, plugin, provider, repository, service, utility |
| 2 | Computing devices and their components | CPU, disk, GPU, keyboard, laptop, memory, monitor, mouse, printer, screen, server, smartphone, tablet, terminal |
| 3 | Development tools, environments, and support equipment | CLI, compiler, debugger, Docker, editor, IDE, Git, Jest, linter, loader, Prettier, terminal, test runner, TypeScript, webpack |
| 4 | Data structures, types, and formats | array, boolean, buffer, CSV, enum, hash map, integer, JSON, linked list, object, queue, stack, string, struct, tree, tuple, XML, YAML |
| 5 | Infrastructure, deployment, and platforms | AWS, CI/CD, container, deployment, Heroku, Kubernetes, load balancer, Node.js, pipeline, pod, production, staging, Vercel |
| 6 | Systems, subsystems, and architectural components | API gateway, authentication layer, caching layer, client, database layer, message broker, microservice, proxy, rate limiter, REST API, routing layer, server, WebSocket |
| 7 | Mathematical, algorithmic, and scientific terms | Big O notation, binary search, coefficient, complexity, exponent, hash function, iteration, logarithm, matrix, recursion, regex, sorting algorithm, time complexity, traversal |
| 8 | Interface elements and navigation | button, checkbox, dialog, dropdown, footer, header, menu, modal, navigation bar, radio button, scrollbar, sidebar, tab, text field, toggle, tooltip |
| 9 | Numbers, units of measurement, and time | byte, gigabyte (GB), hertz (Hz), hour (h), kilobyte (KB), megabyte (MB), millisecond (ms), minute, nanosecond (ns), second (s), terabyte (TB) |
| 10 | Quoted text | `Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused` |
| 11 | Professional roles, teams, and organizations | administrator, backend developer, contributor, DevOps engineer, frontend developer, Google, maintainer, Microsoft, product owner, QA engineer, reviewer, scrum master, user |
| 12 | Official documents, API references, and standards | API reference, changelog, code of conduct, contributing guide, diagram, figure, Getting Started guide, HTTP specification, note, paragraph, README, release notes, RFC, section, table, warning |
| 13 | Runtime environments and operational conditions | development, environment variable, garbage collection, heap, hot reload, live reload, memory leak, production, sandbox, stack trace, staging, test, thread, timeout, virtual machine |
| 14 | Colors | black, blue, cyan, gray, green, magenta, orange, red, white, yellow |
| 15 | Defects, errors, and fault terminology | assertion failure, bug, crash, deadlock, defect, exception, hang, infinite loop, memory leak, null pointer, race condition, regression, stack overflow, timeout, type error |
| 16 | Computer science, information, and communication technology | AI, algorithm, authentication, authorization, blockchain, containerization, cryptography, database, encoding, encryption, firewall, hashing, internet, machine learning, metadata, neural network, protocol, query, sandbox, schema, token, virtualization |
| 17 | Legal and licensing terms | Apache 2.0, BSD license, compliance, copyright, GPL, license, MIT license, open source, proprietary, terms of service, third-party, trademark, warranty |
| 18 | Database and storage terminology | connection pool, cursor, foreign key, index, migration, NoSQL, ORM, PostgreSQL, primary key, query, Redis, relation, row, schema, seed, SQL, SQLite, stored procedure, table, transaction, view |
| 19 | Network and protocol terminology | DNS, endpoint, HTTP, HTTPS, IP address, localhost, middleware, packet, port, request, response, route, socket, SSH, TCP, TLS, UDP, URL, VPN, WebSocket |

Colors are adjectives, but STE-Code identifies them as code-domain technical
nouns. Comparative and superlative forms of colors (blacker, the reddest) are
not permitted. The listed nouns are examples only, not a full list.

### Grammar notes for technical nouns

- **Articles.** Use "the" for a specific instance, "a" or "an" for an
  indefinite instance, and no article for a plural general reference:
  "Kubernetes pods run in a namespace."
- **Modifiers.** A technical noun can modify another technical noun. Both parts
  must belong to a recognized category: "The Redis cache server stores the
  session data."
- **Possessive form.** Permitted only for category 11 (roles, teams,
  organizations). Write "The user's session data" but "The configuration of the
  Docker container", not "The Docker container's configuration".
- **Plurals.** Standard English rules. Acronyms add a lowercase "s" without an
  apostrophe: "two APIs and three SQL queries", not "two API's".
- **Capitalization.** Proper nouns keep their original capitalization
  (TypeScript, PostgreSQL). Common technical nouns are lowercase unless they
  start a sentence (controller, endpoint, middleware).

### Edge cases

- **Framework names that are common words** (React, Vue, Swift, Go, Rust, Elm,
  Next, Nest) are technical nouns in category 3 or 5. Capitalize them or use
  the full term ("the Swift language", "the Go compiler") to remove ambiguity.
- **Code keywords** (`if`, `else`, `for`, `return`, `class`, `async`) are
  quoted text (category 10) in documentation. Write "The `if` statement checks
  the condition." Return `500 Internal Server Error`, not a bare 500.
- **Abbreviations and acronyms** (API, JSON, SQL, HTTP, TLS) are permitted in
  categories 16, 18, or 19. Define each one at first use unless the audience
  universally understands it.
- **Generated code and generated documentation** are exempt, because a machine
  produced them. Human-written comments inside generated files are not exempt.
- **Project-specific internal names** (`PhoenixCache`) are technical nouns only
  after glossary registration. Without registration they are non-approved words
  and violate Rule 1.6.
- **Numbers as technical nouns.** Version numbers, status codes, and port
  numbers are category 9 nouns or quoted text and must appear verbatim: "runs
  on port 5432 and returns `404 Not Found`".

---

## Rule 1.6 — Non-approved words only as technical nouns

A word that the controlled terminology does not approve is permitted only when
it is a code-domain technical noun or part of one.

> **Non-STE:** The handler processes each incoming event.
>
> **STE:** The function processes each incoming event.
>
> **STE:** The event handler processes each incoming event.

"Event handler" is a code-domain technical noun (category 1), so "handler" is
permitted inside it.

> **Non-STE:** The main configuration has the latest values.
>
> **STE:** The primary configuration has the latest values.
>
> **STE:** Merge the feature branch into the main branch.

"Main branch" is the approved Git technical noun (category 5). Do not replace
"main" with "primary" there, because "primary branch" is not the approved term.

---

## Rule 1.7 — Do not use technical nouns as verbs

Use a code-domain technical noun only as a noun, or as a modifier inside
another technical noun. Restructure the sentence so the word keeps its noun
role.

> **Non-STE:** Database the user records before the migration.
>
> **STE:** Store the user records in the database before the migration.

> **Non-STE:** Cache the API responses to improve performance.
>
> **STE:** Store the API responses in the cache to improve performance.

---

## Rule 1.8 — Use technical nouns approved in your project or field

If your project, company, industry, or subject field has an approved name for a
class, module, function, method, variable, component, or process, use that
name. Do not invent a new name for an item that already has one. The source of
truth is the codebase.

> **STE:** The dashboard page has a `UserTable` component and a `FilterPanel` component.

> **Non-STE:** The account controller manages login and user profile operations.
>
> **STE:** The `AccountController` manages authentication and user profile operations.

---

## Rule 1.9 — Select short technical nouns

When your project has no approved technical noun, select one that is short (not
more than three words) and easy to understand. Do not use a long descriptive
phrase when the context — a code snippet, a line number, a diagram, or an API
reference — already identifies the item. Add one or two adjectives only when
clarification is necessary.

> **Non-STE:** Call the asynchronous JavaScript XML HTTP request wrapper utility function (line 42) to get the serialized JSON payload from the remote application programming interface endpoint.
>
> **STE:** Call the `fetchUtility` function (line 42) to get the JSON data from the API endpoint.

---

## Rule 1.10 — No regional, slang, or jargon words

Some technical words are used only inside a confined community or a single
language ecosystem. Readers from other backgrounds, junior developers, and
non-native English speakers cannot understand them. Select well-known words.

> **Non-STE:** `"""Remove all the cruft from the legacy module."""`
>
> **STE:** `"""Remove all the unnecessary code from the legacy module."""`

Other examples: "snag the repo" → "clone the repository"; "fire up the dev
server" → "start the development server"; "K8s spins up pods" → "Kubernetes
starts pods"; "a funky TS bug" → "a known TypeScript defect".

---

## Rule 1.11 — One technical noun per item

Do not use different technical nouns for the same item in different parts of a
document. A changed name forces the reader to decide whether you refer to one
item or to several.

> **Non-STE:**
> 1. Initialize the UserService class to start the session manager.
> 2. Call the authenticate method on the AccountManager to verify a user.
> 3. The UserHandler returns a session token that you send in later requests.
>
> **STE:** Use `UserService` in all three sentences, because the repository
> defines one class with that name.

---

## Rule 1.12 — Code-domain technical verb categories

A code-domain technical verb names an operation or process in software
development. You can use a verb that is not in the controlled terminology when
you can put it in one of these four categories.

| # | Category | Examples |
|---|----------|----------|
| 1a | Development processes — write and modify code | compile, concatenate, import, inject, instantiate, lint, minify, marshal, optimize, polyfill, refactor, resolve, shim, stub, substitute, tokenize, transpile, trace, vectorize |
| 1b | Development processes — test and verify code | assert, benchmark, debug, fuzz, instrument, mock, profile, snapshot, spy, stub, unit-test |
| 1c | Development processes — build and package | bundle, deploy, package, publish, release, tag, version |
| 1d | Development processes — manage dependencies | hoist, install, link, lock, pin, update, upgrade |
| 2a | Computer processes — input and output | click, copy, cut, digitize, enter, paste, press, print, scan, swipe, tap, type |
| 2b | Computer processes — user interface and application operations | clear, close, delete, deselect, disable, drag, drag and drop, enable, encrypt, erase, filter, hide, highlight, invalidate, maximize, minimize, navigate, open, save, scroll, select, show, sort, store, submit, toggle, validate, zoom in, zoom out |
| 2c | Computer processes — system operations | abort, authenticate, authorize, boot, cache, communicate, configure, debug, deserialize, download, format, hydrate, initialize, install, load, log, manage, mount, process, reboot, render, retry, serialize, spawn, synchronize, throttle, update, upgrade, upload |
| 3a | Subject fields — algorithmic, mathematical, and data | aggregate, bisect, compute, concatenate, convert, count, decode, encode, escape, filter, hash, index, map, merge, normalize, parse, pipeline, precompute, recalculate, reduce, tokenize, transform, validate, verify |
| 3b | Subject fields — database and storage | backup, compact, flush, index, migrate, persist, query, replicate, restore, roll back, seed, shard, upsert, vacuum, write-ahead |
| 3c | Subject fields — network and communication | broadcast, connect, disconnect, establish, forward, handshake, intercept, listen, poll, proxy, reject, resolve, route, send, stream, timeout, tunnel, unsubscribe, webhook |
| 3d | Subject fields — security and authentication | authenticate, authorize, decrypt, decode, encode, encrypt, hash, revoke, salt, sanitize, sign, validate, verify |
| 4 | Legal and licensing texts | acknowledge, assign, comply with, conform to, disclose, enforce, explain, grant, inform, license, modify, notify, permit, regulate, sign, supersede, waive |

Code-domain technical verbs obey the same rules as approved verbs. The lists
are examples only.

Priority: if an approved verb gives the instruction or the information
accurately, use the approved verb. Use a technical verb only when no approved
verb is sufficient, and only when the technical verb is exact in your context.
Where possible, write the sentence with an approved verb plus a code-domain
technical noun.

> **Non-STE:** If you detect broken wires, repair them.
>
> **STE:** If you find broken wires, repair them.

---

## Rule 1.13 — Do not use technical verbs as nouns

Use a code-domain technical verb only as a verb. When you need a noun, use an
approved noun or a code-domain technical noun with the same meaning. A word can
belong to both systems when it fits a verb category (Rule 1.12) and a noun
category (Rule 1.5).

| Do not write | Write |
|--------------|-------|
| Do a build of the project | Build the project |
| The function does a parse of the input string | The function parses the input string |
| Does a compile of the source files | Compiles the source files |
| `// A retry of the connection` | `// Retry the connection` |
| Addition of login endpoint | Add login endpoint |
| Compile of module 'auth' failed | Failed to compile module 'auth' |
| Start of deploy for release v2.1.0 | Deploy started for release v2.1.0 |

When an API returns a named artifact (a `Build` object, a `Deployment`
resource), the noun form is a technical noun under Rule 1.5, not a misused
verb.

---

## Rule 1.14 — Use American English spelling

Use the spelling given in the STE-Code controlled terminology, which is
American English. Use a different spelling only when a project specification,
style guide, contract, or other official directive says so.

Do not change the spelling of quoted text — an error message, a code comment,
or a user interface label — even when it uses British English. See Rule 8.6.

> **Non-STE:** The log file shows the colour of each output line.
>
> **STE:** The log file shows the color of each output line.

> **Non-STE:** Initialise the variable before you use it in the loop.
>
> **STE:** Initialize the variable before you use it in the loop.



## 02-synonyms.md

# Level 2 — Technical Noun Categories: Grammar Rules (Rule 1.5)

This is the Rule 1.5 slice of STE-Code Level 2: the **grammar rules for
using code-domain technical nouns**. Level 1 gave you the nineteen categories
and the three-word gate (Rules 1.1 / 1.5 / 1.6). Level 2 adds the
section-specific grammar that governs how a technical noun is written once you
have decided it is allowed.

All content below is faithful to the authoritative Rule 1.5 adaptation
(`final/rules/a-sec1-rule1.5.md`). Every example stays inside the code domain.
The rule numbers and categories are not invented.

## Rule 1.5 — recap (before the grammar)

**Rule 1.5** You can use words that you can include in a code-domain technical
noun category.

A code-domain technical noun is a noun term that refers to a specified concept
in software development and is applicable to a subject field. The controlled
terminology does not include all code-domain technical nouns because there are
too many, and each project or subject field uses different technical nouns.
You can find many of these in your project glossary or terminology database.

The nineteen categories (Level 1) are the gate: a non-approved word is
permitted only when it names a precise concept in one of them **and** is
registered in your glossary. Level 2 now covers how to write that noun
correctly — articles, compounds, possessive, plural, and capitalization.

## Grammar rule 1 — Articles with technical nouns

Technical nouns follow the same article rules as approved nouns:

- Use **"the"** for a specific instance.
- Use **"a" / "an"** for an indefinite instance.
- Use **no article** for plural general references.

Acceptable:
- The `UserController` handles a request. The controller returns a response.
- Kubernetes pods run in a namespace.

(`UserController` is a specific code component; `request` and `response` are
network terms; `pods` is a plural general reference.)

## Grammar rule 2 — Technical nouns as modifiers (compound phrases)

A technical noun can modify another noun to form a compound technical noun
phrase. When two technical nouns form a compound, the first functions as a
modifier and the second as the head noun. **Both must belong to a recognized
category.**

Acceptable:
- The Redis cache server stores the session data.
  (`Redis` (database) modifies `cache server` (systems); `session data` is a
  compound where `session` (runtime) modifies `data` (data structure).)
- The PostgreSQL connection pool uses a round-robin scheduler.
  (`PostgreSQL` (database) modifies `connection pool` (database);
  `round-robin` (algorithmic) modifies `scheduler` (systems).)

Not acceptable:
- The thing layer processes the stuff queue.
  (Neither "thing" nor "stuff" is a recognized technical noun.)

## Grammar rule 3 — The possessive form

The possessive (`'s`) is permitted **only** for category 11 — professional
roles, individuals, groups, organizations, and teams. Do **not** use the
possessive with any other category of technical noun. Use "of" constructions or
noun-as-modifier constructions instead.

Acceptable:
- The user's session data is encrypted. (Category 11 permits possessive.)
- The configuration of the Docker container is stored in a YAML file.
  (Category 5 — use "of".)

Not acceptable:
- The Docker container's configuration is stored in a YAML file.
  (Category 5 does not permit possessive — use "of".)

## Grammar rule 4 — Pluralization

Technical nouns follow standard English pluralization. Acronyms and
initialisms form plurals by adding a lowercase **"s" without an apostrophe**.

Acceptable:
- The system uses two APIs and three SQL queries.
  (`APIs` is the plural of `API` (network); `queries` is the plural of
  `query` (database).)

Not acceptable:
- The system uses two API's and three SQL's.
  (The apostrophe incorrectly suggests possession. Use `APIs` and
  `SQL queries`.)

## Grammar rule 5 — Capitalization

Code-domain technical nouns that are **proper nouns** (programming language
names, company names, product names) keep their original capitalization.
**Common** technical nouns (for example `controller`, `endpoint`,
`middleware`) use lowercase unless they are the first word of a sentence.

Acceptable:
- The TypeScript compiler checks the types. The controller handles the request.
  (`TypeScript` is a proper noun (development tool); `controller` is a common
  technical noun (code component).)

Not acceptable:
- The typescript compiler checks the Types. The Controller handles the request.
  (`typescript` should be `TypeScript`; `Types` and `Controller` should be
  lowercase — not first word, not proper nouns.)

## Grammar-sensitive edge cases

These cases change how the grammar rules above apply.

### Framework names that are also common words

Some frameworks use common English words as names (`React`, `Vue`, `Swift`,
`Go`, `Rust`, `Elm`, `Next`, `Nest`). The framework name is a code-domain
technical noun (category 3 or 5) and does not follow the approved meaning of
the common word.

Acceptable:
- Use the React framework to build the user interface. (`React` is a
  development tool, not the verb "react".)
- The Go compiler builds the binary. (`Go` is a development tool, not the
  verb "go".)

When a sentence is ambiguous without capitalization (for example "use swift to
process the data"), always capitalize the framework name or use the full term
("the Swift language", "the Rust compiler") to distinguish it from an approved
word.

### Code keywords inside documentation

Code keywords (`if`, `else`, `for`, `while`, `return`, `class`, `def`, `fn`,
`let`, `const`, `var`, `async`, `await`) are **quoted text (category 10)** when
they appear in documentation. They do not need to be technical nouns. When you
use them as English words in a sentence, they must follow approved meanings.

Acceptable:
- The `if` statement checks the condition. (`if` is quoted text; the
  surrounding sentence uses approved words.)

Not acceptable:
- If the request fails, return a 500. (`500` is an HTTP status code — quoted
  text or a category 9 noun. Write `404 Not Found` or `500`.)

Acceptable:
- If the request fails, return `500 Internal Server Error`. (Status code is
  quoted text, category 10.)

### Abbreviations and acronyms

Code-domain technical nouns often appear as abbreviations or acronyms (`API`,
`JSON`, `SQL`, `HTML`, `CSS`, `HTTP`, `TCP`, `TLS`, `DNS`, `URL`). These are
permissible under Rule 1.5 (categories 16, 18, or 19). However, you must define
each abbreviation at its first use in a document, unless it is universally
understood by the target audience.

Acceptable (first use):
- The application programming interface (API) uses Hypertext Transfer Protocol
  Secure (HTTPS).

Acceptable (subsequent use):
- The API returns a JSON response over HTTPS.

Not acceptable:
- The API leverages HTTPS to transmit the payload. (Non-approved "leverage" →
  use "use"; non-approved "transmit" → use "send"; non-approved "payload" →
  use "data" or define as a technical noun.)

### Numbers as technical nouns

Quantitative values that name a configuration, version, status, or port are
code-domain technical nouns in category 9 when the value is a fixed, named
token rather than a measured quantity. Version numbers (`Node.js 18`), HTTP
status codes (`404`), and port numbers (`port 5432`) are quoted text or
category 9 nouns and must appear verbatim.

Acceptable:
- The service runs on port 5432 and returns `404 Not Found` when the row is
  absent. (`port 5432` is a category 9 noun; `404 Not Found` is quoted text.)

Not acceptable:
- The service runs on the default db port and gives a not found error.
  (Imprecise — use "port 5432" and "`404 Not Found`".)

## Cross-references

- **Rule 1.1 (Approved Words):** the dictionary for all common vocabulary;
  Rule 1.5 is the exception for domain-specific nouns.
- **Rule 1.2 (Part of Speech):** a technical noun is used only as a noun or
  noun modifier — never as a verb.
- **Rule 1.3 (Approved Meanings):** a technical noun carries the meaning
  registered in your glossary; do not reuse it with another meaning.
- **Rule 1.6 (Non-Approved Words):** forbids every non-approved word that is
  not a code-domain technical noun. Read Rules 1.5 and 1.6 together.
- **Rule 1.7 (Technical Nouns as Verbs):** a code-domain technical noun cannot
  be used as a verb (for example "host" is a noun; use "make available" or
  "run" as the verb).
- **Rule 1.8 (Standard Technical Nouns):** use well-known terms; do not invent
  a new term when a standard one exists.
- **Rule 1.9 (Short Technical Nouns):** prefer short, clear technical nouns
  over long, obscure ones.
- **Rule 1.11 (One Term per Concept):** each technical noun refers to exactly
  one concept in your project.
- **Rule 1.12 (Technical Verbs):** technical verbs (`build`, `deploy`, `test`,
  `lint`, `compile`, `debug`) are permitted but are a separate category from
  technical nouns.

## Summary

Level 2 adds the grammar layer on top of Level 1's nineteen categories. A
code-domain technical noun is written with correct articles, may modify other
nouns to form compound phrases, takes the possessive only when it is a
category-11 role/org term, pluralizes without an apostrophe, and keeps
proper-noun capitalization. Framework names that double as common words,
quoted code keywords, abbreviations, and fixed numeric tokens each have their
own handling. Together with Rules 1.1 and 1.6, these rules leave documentation
with only two kinds of words: approved STE-Code words for common vocabulary,
and code-domain technical nouns for domain-specific concepts — and the grammar
rules above govern how the second kind is written.



## 03-dictionary.md

# Level 2 — Adapted Dictionary (A–Z excerpt)

A code-domain adaptation of the ASD-STE100 Issue 9 dictionary (Part 2, pp. 149–434),
reshaped for use by an LLM that generates or reviews code documentation.

This slice teaches the STE approval model for words: which words are approved,
which are not, and how to rewrite unapproved words into approved ones. It uses
code-domain examples only (API docs, commit messages, README sections, code comments).

Use this slice when you:
- Write or review API documentation and reference pages
- Draft commit messages and pull-request descriptions
- Author README sections and module/package overviews
- Write inline code comments and docstrings

Scope note: this Level 2 slice shows the entry format with a few canonical examples
(letter **A**). The complete approved (~875) and unapproved (~1274) word lists are
bundled at higher STE-Code tiers (3/4/5). Do not invent words beyond what the
dictionary lists; for unknown words, prefer an approved verb or a technical noun.

---

## How to read an entry

- **UPPERCASE words** are approved in STE-Code — you may use them.
- **lowercase words** are unapproved — replace them with the listed alternative.
  Unapproved status is also marked with the tag **UNNAPROVED** on the entry.
- Each entry carries a part-of-speech tag:
  `(v)` verb · `(n)` noun · `(adj)` adjective · `(adv)` adverb ·
  `(prep)` preposition · `(conj)` conjunction · `(pron)` pronoun · `(art)` article
- Code-domain technical tags:
  `(TN)` = code-domain Technical Noun (e.g. *config*, *endpoint*, *pipeline*)
  `(TV)` = code-domain Technical Verb (e.g. *deploy*, *build*, *parse*)
- Every entry shows three things:
  1. the original ASD-STE100 rule text,
  2. the same idea rewritten for code documentation,
  3. one or more STE / non-STE code-example pairs demonstrating the approved form.

### LLM guidance

When generating or reviewing code documentation, prefer UPPERCASE-approved words
and the verbs listed as alternatives for unapproved words (e.g. use `STOP`/`TERMINATE`
instead of `abandon`, `CAN` instead of `ability to`). Keep the approved form as
the short, direct sentence; the non-STE form is the longer, indirect phrasing to avoid.

---

# A

## A (art) — APPROVED
Function word: indefinite article. Use before a singular countable noun.
- **Original:** A FUEL PUMP IS INSTALLED IN ZONE 10.
- **Code-domain:** A CONFIG FILE IS INCLUDED IN THE ROOT DIRECTORY.
- **STE:** A config file is included in the root directory.
- **Non-STE:** Config files included in root directory.

## ABANDON (v) — UNNAPROVED
Not approved. Replace with `STOP` (v) or `TERMINATE` (v).
- **Original:** GO (v), STOP (v). IF THERE IS A FIRE, IMMEDIATELY GO TO A SAFE AREA. / IF THE VALUES ARE INCORRECT, STOP THE TEST PROCEDURE.
- **Code-domain:** TERMINATE (v), STOP (v). IF THE BUILD FAILS, STOP THE DEPLOYMENT PIPELINE. / IF THE VALUES ARE INCORRECT, TERMINATE THE TEST RUN.
- **STE:** If the build fails, stop the deployment pipeline.
- **Non-STE:** If the build fails, abandon the deployment pipeline.
- **STE:** If the values are incorrect, terminate the test run.
- **Non-STE:** If the values are incorrect, abandon the test procedure.

## ABILITY (n) — UNNAPROVED
Not approved. Replace with `CAN` (v).
- **Original:** CAN (v). ONE GENERATOR CAN SUPPLY POWER FOR ALL THE SYSTEMS.
- **Code-domain:** CAN (v). ONE CONFIGURATION CAN HANDLE REQUESTS FOR ALL THE ENDPOINTS.
- **STE:** One configuration can handle requests for all the endpoints.
- **Non-STE:** One configuration has the ability to handle requests for all the endpoints.

---

## Quick substitutions (from this excerpt)

| Unapproved (avoid) | Approved replacement | Example (STE) |
| --- | --- | --- |
| abandon (v) | STOP (v), TERMINATE (v) | If the build fails, stop the deployment pipeline. |
| ability (n) (as "has the ability to") | CAN (v) | One configuration can handle all the endpoints. |

When you see an unapproved word in source text, swap it for the approved verb and
keep the sentence short and direct. Approved articles such as **A** stay as-is.

---

## Scope of this slice

This excerpt covers the A entries only. The patterns it demonstrates — approved
articles, unapproved verbs replaced by approved verbs (ABANDON → STOP/TERMINATE),
and unapproved nouns replaced by modal verbs (ABILITY → CAN) — repeat across the
full A–Z dictionary bundled in higher STE-Code tiers (3/4/5).

The Level 2 dictionary couples with `01-principles.md`, `02-synonyms.md`,
`04-templates.md`, and `05-grammar.md`. A word is permitted in Level 2 only when
it is an approved word, a code-domain technical noun `(TN)`, or a code-domain
technical verb `(TV)`.



## 04-templates.md

# Level 2 — Document Templates (Code Review / PR Feedback)

These templates apply STE-Code Level 2 to the two document types where controlled
words matter most in day-to-day engineering work: code review comments and pull
request feedback.

Level 1 gave the word-level gate (Rules 1.1–1.14) and the template shapes. Level 2
adds the **section-specific grammar rules** that govern how a review or PR sentence
is built once you have decided the words are allowed:

- the imperative (command) form for every action line (Rule 5.3),
- the descriptive-statement-before-command structure for findings and conditions
  (Rule 5.4),
- the technical-noun grammar for identifiers and code terms that appear in review
  text (Rule 1.5): backticks, one name per item, articles, possessive, plural,
  capitalization.

Each template below is a fill-in shape. Every word you add must pass one of the
three Level 1 gates:

1. It is approved in the controlled terminology (the STE-Code dictionary).
2. It is a code-domain technical noun (Rule 1.5, 19 categories).
3. It is a code-domain technical verb (Rule 1.12).

Identifiers, file paths, commands, and type names are technical nouns. Write them
in backticks and do not inflect them.

## Template selection

| Situation | Template |
|-----------|----------|
| One line or one hunk in a diff | T1 — Inline review comment |
| A defect the author must fix before merge | T2 — Blocking review finding |
| An optional improvement | T3 — Non-blocking suggestion |
| The summary you leave on the whole pull request | T4 — PR review summary |
| The description the author writes on the pull request | T5 — PR description |
| A reply to review feedback | T6 — Author response |

## Shared word rules for all templates

| Do not write | Write |
|--------------|-------|
| This looks a bit weird / smells off | This function returns `null` when the input list is empty. |
| Can we maybe just not do this? | Remove the call to `resetCache`. |
| It'd be great if you could refactor | Move the retry logic into `RetryPolicy`. |
| The code is broken | The `parseDate` function throws `TypeError` for an empty string. |
| We should probably handle errors | Catch `IOError` in `readConfig` and return a default value. |

Rules applied above: 1.1 (approved words only), 1.9 (short technical nouns),
1.10 (no slang or jargon), 1.11 (one noun per item).

The action line in every template uses the imperative form (Rule 5.3): start the
sentence with a base verb, no "must", no modal verb, no passive voice. The finding
and condition lines may be descriptive statements, but they still use approved words
and one technical noun per item (Rule 1.11).

## T1 — Inline review comment

Shape (three parts, in this order):

```
<observation>: one sentence, one subject, present tense.
<effect>: one sentence that gives the result of the observation.
<action>: one imperative sentence.
```

Example:

> The `getUser` function returns `undefined` when `id` is `0`.
> The caller in `UserController` then reads a property of `undefined`.
> Return `null` for an unknown `id`, and check the result in `UserController`.

Constraints:

- Use the imperative form for the action (Rule 5.3): start with a base verb,
  no "must", no modal ("can", "should", "may"), no passive voice.
- Name the item with the same technical noun each time (Rule 1.11). Do not write
  `getUser`, then "the getter", then "that helper".
- Do not use a technical noun as a verb (Rule 1.7). Write "Send a request to the
  `/users` endpoint", not "Endpoint the request".
- Use backticks for every identifier, path, and type name (Rule 1.5 grammar):
  `UserController`, `id`, `null` stay uninflected.

## T2 — Blocking review finding

```
**Finding:** <one sentence: what is wrong>
**Location:** `<path>:<line>` in `<symbol>`
**Cause:** <one sentence>
**Result:** <one sentence: what fails, and when>
**Required change:** <one imperative sentence>
```

Example:

> **Finding:** The `saveOrder` method does not validate the `quantity` field.
> **Location:** `src/orders/service.ts:142` in `OrderService.saveOrder`
> **Cause:** The method writes the request body to the database with no check.
> **Result:** A negative `quantity` value is written to the `orders` table.
> **Required change:** Reject a request when `quantity` is less than `1`.

Use "required change" for a defect. Write the change as a single imperative
sentence (Rule 5.3). Do not use "must" as an intensifier in the prose — the field
label already gives the obligation. The `Location` line names the item with one
technical noun each time (Rule 1.11); `src/orders/service.ts` and
`OrderService.saveOrder` stay in backticks and are not inflected.

## T3 — Non-blocking suggestion

```
**Suggestion (optional):** <one imperative sentence>
**Reason:** <one sentence>
```

Example:

> **Suggestion (optional):** Move the three retry constants into `RetryPolicy`.
> **Reason:** The same three values occur in `HttpClient` and in `QueueWorker`.

Mark the comment as optional in the first word. Write the suggestion as one
imperative sentence (Rule 5.3). Do not use hedge words such as "maybe", "perhaps",
or "just" to signal that a comment is optional (Rule 1.10).

## T4 — PR review summary

```
**Decision:** Approve | Request changes | Comment
**Scope:** <one sentence: what the pull request changes>
**Blocking findings:** <count>
1. <one sentence each, with `path:line`>
**Optional suggestions:** <count>
1. <one sentence each>
**Verification:** <one sentence: what you ran or read>
```

Example:

> **Decision:** Request changes
> **Scope:** The pull request adds a rate limiter to the `/api/v1/login` route.
> **Blocking findings:** 1
> 1. `src/middleware/rateLimit.ts:58` — The limiter counts a failed request and
>    a successful request in the same bucket.
> **Optional suggestions:** 1
> 1. Give the `WINDOW_MS` constant a unit in its name.
> **Verification:** I ran `npm test` and read the diff in `src/middleware`.

Write the decision as one of the three approved values. Do not invent a fourth
value, and do not write the decision as a sentence. Each finding line is one
sentence that names its item with one technical noun (Rule 1.11); each `path:line`
stays in backticks. The `Verification` line uses the first person only for the
actor ("I ran"), not to soften the obligation.

## T5 — PR description (author)

```
## What
<one to three sentences. One subject in each sentence.>

## Why
<one to three sentences. Give the cause, then the result.>

## How
1. <imperative sentence>
2. <imperative sentence>

## Test
- <one sentence per check, with the command in backticks>

## Risk
<one sentence. Write "None." when there is no risk.>
```

Example:

> ## What
> This pull request adds a retry to the `PaymentClient.charge` method.
>
> ## Why
> The payment gateway returns `503` during a deployment. The current client
> fails the order on the first `503` response.
>
> ## How
> 1. Add a `RetryPolicy` class with three attempts and an exponential delay.
> 2. Call `RetryPolicy.execute` from `PaymentClient.charge`.
>
> ## Test
> - Run `npm test -- payment` to check the new unit tests.
> - Send a request to the sandbox gateway to check the delay values.
>
> ## Risk
> A retry can create a duplicate charge if the gateway accepted the first
> request. The client sends an idempotency key to prevent this result.

The `How` steps are all imperative (Rule 5.3). The `What` and `Why` sections are
descriptive statements, but each sentence still uses one technical noun per item
(Rule 1.11) and approved words only (Rule 1.1).

## T6 — Author response to feedback

```
**Comment:** <link or `path:line`>
**Response:** Done | Changed | Not changed
**Detail:** <one sentence>
```

Example:

> **Comment:** `src/middleware/rateLimit.ts:58`
> **Response:** Changed
> **Detail:** The limiter now counts only a failed request in the login bucket.

Use one of the three approved response values. Do not use "LGTM", "nit", "wontfix",
or other jargon labels (Rule 1.10). The `Comment` line gives the item in backticks
with one name each time (Rule 1.11).

## Approved verbs for review and PR text

Use these code-domain technical verbs in the action line of any template. Use
the base form for an instruction (Rule 5.3), and the third-person form for a
statement of fact.

| Verb | Use it for |
|------|-----------|
| add | New code, a new field, a new file |
| remove | Deleted code or a deleted field |
| replace | One item exchanged for another |
| move | Code relocated with no change in behavior |
| rename | A new name for the same item |
| return | The value a function gives back |
| throw / raise | An error the code emits |
| catch / handle | An error the code accepts |
| validate | A check on input |
| reject | A refused input or request |
| call | Invocation of a function or method |
| read / write | Access to a file, field, or record |
| log | A record written to the audit trail or log |
| test | A check that runs in the test suite |

Do not use a verb from this table as a noun (Rule 1.13). Write "The function
returns a value", not "The return of the function".

## Forbidden words in review and PR text

| Forbidden | Reason | Use instead |
|-----------|--------|-------------|
| nit, LGTM, WIP, PTAL, IMO | jargon (Rule 1.10) | the full template label |
| smelly, hacky, ugly, clean | subjective, not approved (Rule 1.1) | the concrete defect |
| stuff, thing, some code | not a technical noun (Rule 1.5) | the identifier in backticks |
| leverage, utilize | not approved (Rule 1.3) | use |
| behaviour, initialise, colour | British spelling (Rule 1.14) | behavior, initialize, color |
| we should maybe possibly | hedging (Rule 1.1) | one imperative sentence |

## Section-specific grammar rules for review and PR text

Level 2 adds the grammar that governs how a review or PR sentence is built. The
two rules below come from the STE-Code procedural-grammar set (Rules 5.3 and 5.4),
reshaped for review and PR text.

### Grammar rule G1 — Imperative form in the action line (Rule 5.3)

Every action line (T1 `action`, T2 `Required change`, T3 `Suggestion`, T5 `How`)
starts with a base verb and gives a direct instruction. Drop the subject "you"
(the reader is implied), and do not use passive voice, gerunds, or modal verbs.

- Do not add "must" before the imperative in a standard instruction. Reserve
  "must" for a security or data-loss warning (for example a finding where a
  leaked key can cause permanent loss).
- Do not soften the instruction with "can", "could", "should", "may", or
  "might". "Set the timeout to 30 seconds" leaves no room for "optional".

> **Non-STE:** The test suite can be executed with `npm test`.
> **STE:** Run the unit tests with `npm test`.

> **Non-STE:** Before you delete the branch, you must push all local commits.
> **STE:** Before you delete the branch, push all local commits to the remote.

### Grammar rule G2 — Descriptive statement before the command (Rule 5.4)

When a finding or condition must be known first, write it as a descriptive
statement, then a comma, then the imperative. The comma is required: it shows
where the condition ends and the command begins. Moving the comma changes which
verb an adverb modifies.

> **STE:** If the connection pool is full, reject the request.
> (The comma after "full" shows "automatically" would modify "reject".)
> **STE:** If the connection pool is full automatically, reject the request.
> (The comma after "automatically" changes the meaning — the pool fills on its
> own; reject it.)

Apply G2 inside T2 (`Result` then `Required change`) and T4 (`Scope` sets the
condition, findings follow). Keep conditions short — one condition per sentence.

### Grammar rule G3 — Technical-noun grammar inside review text (Rule 1.5)

Identifiers, paths, type names, and commands in review text are code-domain
technical nouns. Apply the following grammar:

- **Backticks, no inflection.** Write `getUser`, `null`, `OrderService`. Do not
  write "the `getUser`s" or "two `null`s". Use a lowercase "s" for acronym plurals
  without an apostrophe: `APIs`, not `API's`.
- **One name per item (Rule 1.11).** Name the same symbol the same way every time
  in one comment thread: `getUser`, not "the getter", then "that helper".
- **Articles.** Use "the" for a specific instance, "a"/"an" for an indefinite one,
  no article for a plural general reference: "The `UserController` handles a
  request. Kubernetes pods run in a namespace."
- **Possessive only for roles/orgs (category 11).** Write "the user's session
  data" but "the configuration of the `Docker` container", not "the `Docker`
  container's configuration".
- **Capitalization.** Proper nouns keep their capitalization (`TypeScript`,
  `PostgreSQL`); common technical nouns are lowercase unless first word
  (`controller`, `endpoint`, `middleware`).
- **Quoted keywords and status codes.** Code keywords (`if`, `return`, `class`)
  and status codes (`404 Not Found`, `500`) are quoted text (category 10). Write
  "Return `500 Internal Server Error`", not a bare "500".

## Checklist before you post

1. Each sentence has one subject.
2. Each item has one name, used every time (Rule 1.11).
3. Each identifier is in backticks and is not inflected.
4. Each action is one imperative sentence (Rule 5.3).
5. Each condition comes before its command, separated by a comma (Rule 5.4).
6. No word from the forbidden table is present.
7. Spelling is American English (Rule 1.14).




## 05-grammar.md

# Level 2 — Section-Specific Grammar Rules

Grammar rules of STE-Code, grouped by the section of the standard that owns
them. Each rule is stated as a directive, then shown with a minimal
code-domain pair. Use this file as the grammar layer on top of the Level 2
dictionary and approved-word tables.

Scope: code documentation only — README files, API reference, docstrings,
inline comments, commit messages, error messages, changelogs, configuration
comments. Source code inside code blocks is never subject to these rules.

Reading key:
- **Non-STE** — text that breaks the rule.
- **STE** — the compliant rewrite.
- Word counts, where given, follow the counting rules in Section 8.

Rule map:

| Section | Topic | Rules |
|---|---|---|
| 2 | Technical noun structure | 2.1–2.3 |
| 3 | Verbs, tense, and voice | 3.1–3.7 |
| 4 | Sentence structure | 4.1–4.5 |
| 5 | Procedural writing | 5.1–5.5 |
| 6 | Descriptive writing | 6.1–6.6 |
| 7 | Safety instructions | 7.1–7.3 |
| 8 | Punctuation and word count | 8.1–8.7 |
| 9 | Word choice and consistency | 9.1–9.4 |

## Section 2 — Technical noun structure

### Rule 2.1 — Keep technical nouns short
Use a maximum of three words in a technical noun. Use prepositions ("of," "on,"
"in," "for," "to") to split longer noun phrases and show which part owns which.

> **Non-STE:** the authentication token expiration refresh interval setting
>
> **STE:** the refresh interval for the expiration of the authentication token

Keep approved adjectives attached to the short noun that they modify:
`idempotent`, `immutable`, `thread-safe`, `atomic`, `nullable`, `deprecated`,
`stateless`, `backward-compatible`, `asynchronous`, `concurrent`,
`deterministic`.

### Rule 2.2 — Write long technical nouns in full
When a technical noun has more than three words, write it in full the first time
that it occurs. Then make it clear with one of these methods:

- Give a shorter form and use that shorter form in the remaining text.
- Use hyphens between the words that operate as one unit (Rule 2.3).
- Use prepositions to split the noun into short parts (Rule 2.1).

> **STE:** Before you start this procedure, initialize the user session cache
> invalidation lock handler (in this procedure, the "invalidation lock handler").

Do not divide a technical noun that your framework, schema, or API
specification defines. Write it in its approved form.

### Rule 2.3 — Use hyphens between words used as one unit
Use a hyphen to show that related words operate as one unit. A hyphenated group
counts as one word (Rule 8.7), so it fills only one of the three slots that
Rule 2.1 allows.

> **Non-STE:** Move the main-feature-flag-rollback-handler trigger.
>
> **STE:** Move the main-feature-flag rollback-handler trigger.

- Do not hyphenate words that are not related. The hyphen changes the meaning.
- Do not make hyphen groups of more than three words. Split longer chains with
  `of`, `on`, or `in`.
- Do not change an approved hyphenated term, for example `input-output stream`,
  `thread-safe queue`, or `backward-compatible API`.

## Section 3 — Verbs, tense, and voice

### Rule 3.1 — Use only the verb forms in the dictionary
Each approved verb appears with its allowed forms: base, third-person singular,
simple past, and past participle. Use only those forms.

```
VALIDATE (v)   VALIDATES   VALIDATED,   VALIDATED
WRITE (v)      WRITES      WROTE,       WRITTEN
```

Do not use gerunds as verbs, participles with auxiliaries, or inflected forms
that the dictionary does not list.

### Rule 3.2 — Use only the approved forms and tenses
Approved forms and tenses:

- The infinitive form
- The imperative (command) form
- The simple present tense
- The simple past tense
- The simple future tense
- The past participle form, as an adjective only.

| Form | Regular verb (parse) | Irregular verb (write) |
|---|---|---|
| Infinitive | (to) parse | (to) write |
| Imperative | Parse the payload. | Write the log entry. |
| Simple present | It parses | It writes |
| Simple past | It parsed | It wrote |
| Simple future | It will parse | It will write |
| Past participle (adj) | the parsed file | the written log |

### Rule 3.3 — Use the past participle as an adjective
The past participle shows the condition of something. This is not passive voice.
Use it before a noun, or after "to be," "to become," or "to stay."

> **STE:** The parsed file stays in the cache. The endpoint becomes deprecated.

Tests that the word is an adjective and not passive voice:

1. The word gives a condition, not an action that an actor does.
2. You can put it directly before the noun: "the closed connection".
3. You can put it after "is", "becomes", or "stays": "the cache is initialized".
4. If the sentence names an actor and an action ("the file was parsed by the
   loader"), it is passive voice. Write the active voice instead (Rule 3.6).

Do not use a past participle that the dictionary does not approve.

### Rule 3.4 — Do not use auxiliary verbs for complex constructions
Do not put "have," "be," "will be," "can be," "must be," "should be," or
"is to be" with a past participle to make compound tenses or passive voice.

- Use the simple past instead of the present perfect or past perfect.
- Use the active voice with a named agent instead of "be + past participle."
- Use the imperative form instead of "is to be + past participle."
- Use "you can + base verb" instead of "can be + past participle."

> **Non-STE:** The loader has parsed the manifest.
>
> **STE:** The loader parsed the manifest.

If a compound construction seems necessary, split the sentence into two short
sentences with approved forms.

### Rule 3.5 — Use the "-ing" form only as a noun or a modifier
Use a word that has an "-ing" form only as a technical noun (for example, in a
heading) or as a modifier inside a technical noun. Do not use it as a verb.

Approved "-ing" words in STE-Code:

- Nouns: logging, monitoring, routing, servicing
- Adjectives: matching, missing, remaining
- A pronoun: something
- A preposition: during.

> **Non-STE:** The service is starting and then it is logging the request.
>
> **STE:** The service starts. Then it logs the request.

The present progressive is not an approved tense (Rule 3.2), and the "-ing"
form hides the auxiliary constructions that Rule 3.4 forbids.

### Rule 3.6 — Use the active voice
Use the active voice in all code documentation. In descriptive writing, the
passive voice is permitted only when the agent is unknown.

Test: ask "by whom or by what?" If the sentence answers that question, it is
passive. Move the agent into the subject position.

> **Non-STE:** The API response is parsed by the middleware.
>
> **STE:** The middleware parses the API response.

### Rule 3.7 — Use an approved verb for an action, not a noun
If an approved verb describes the action, use the verb. A noun names a thing; a
verb names the work.

> **Non-STE:** The endpoint performs validation of the token.
>
> **STE:** The endpoint validates the token.

The four Technical Code Verb categories:

| Category | Verbs |
|---|---|
| Development operations | build, compile, test, lint, format, commit, push, deploy, rollback |
| Data operations | read, write, serialize, deserialize, parse, encode, decode, query, insert, migrate |
| Application operations | handle, route, authenticate, authorize, validate, schedule, dispatch, resolve |
| Communication actions | send, receive, publish, subscribe, stream, poll, broadcast, connect |

Prefer the plain approved verb — `use`, `start`, `stop`, `show`, `make`, `get`,
`set`, `check`, `do`, `send`, `remove`, `keep` — over *utilize*, *leverage*,
*employ*, *commence*, *terminate*, or *initiate*.

## Section 4 — Sentence structure

### Rule 4.1 — One topic per sentence, no abstract text
In descriptive text (a class, module, or type description), give each sentence
one topic and do not use the imperative form. In procedural text (a function or
method description), give one instruction per sentence in the imperative form.
Do not write abstract text.

> **Non-STE:** The `HttpClient` class has two internal buffers connected
> together and linked with callbacks between the request handler and the
> response dispatcher.
>
> **STE:** The `HttpClient` class has two internal buffers. Callbacks connect
> the internal buffers. These callbacks link the request handler to the
> response dispatcher.

### Rule 4.2 — Do not omit words or use contractions
Each sentence must have all its parts.

- Do not omit the noun. The reader will not know which code element you mean.
- Do not omit the verb. The reader will not know the action.
- Do not omit the subject. The reader will not know which function, class, or
  module does the action.
- Do not omit articles ("the," "a," "an").
- Do not use contractions. Write "do not," "is not," and "are not."

> **Non-STE:** Can't be longer than 64 bytes.
>
> **STE:** The key can have a maximum length of 64 bytes.

### Rule 4.3 — Use a vertical list for complex text
When a sentence must include many items (parameters, return fields, error
codes, configuration options, environment variables, dependencies, or test
cases) or many actions, use a vertical list.

When you make a vertical list:

- Put a colon (:) at the end of the introductory sentence.
- Identify each item with a number, letter, dash, or bullet.
- Start each item with an uppercase letter.
- Where applicable, use an article before the noun that is the subject of the
  item.
- Put a period at the end of an item that is a full sentence.
- Do not put a period at the end of an item that is not a full sentence.

### Rule 4.4 — Use connecting words and connecting phrases
Connecting words and phrases link the topic of one sentence to the idea in the
sentence that follows.

- Approved connecting words: "and," "but," "then," "thus."
- Approved connecting phrases: "as a result," "at the same time."
- Demonstrative adjectives ("this," "these") also connect related sentences.

> **STE:** The middleware validates the token. Thus the controller receives
> only authenticated requests.

### Rule 4.5 — Use an article or a demonstrative adjective before a noun
Articles and demonstrative adjectives show the position of nouns in the
sentence. Do not remove them to make the text shorter.

- Do not use an article in a general statement or before an abstract concept
  ("performance," "scalability," "error handling," "concurrency," "backward
  compatibility").
- In short sentences, use an article before each noun.
- In a long series of items, use the article only before the first noun. If an
  adjective applies to the first item only, repeat the article.
- Do not use a definite article before a code identifier. A function name, a
  class name, a variable name, a file name, an environment variable, an error
  code, and a version tag are proper nouns.
- Always keep the noun after "this" or "these". Do not write "this" alone.

> **Non-STE:** Call the `parseConfig`. This returns a map.
>
> **STE:** Call `parseConfig`. This function returns a map.

## Section 5 — Procedural writing

### Rule 5.1 — Maximum of 20 words in a procedural sentence
Procedures include installation instructions, setup steps, deployment
checklists, debugging workflows, and API usage guides. Use a maximum of 20
words in each procedural sentence. Warnings and cautions obey the same limit.
A note has a maximum of 25 words in each sentence.

> **Non-STE:** Run the database migration script from the project root
> directory and then restart the application server to apply all pending schema
> changes to the production environment. (27 words)
>
> **STE:** Run the database migration script from the project root directory.
> Then restart the application server. (15 words)

Code snippets, command examples, and terminal output inside code blocks are not
subject to the word count.

### Rule 5.2 — One instruction per sentence
Write only one instruction in each sentence. Use numbered or bulleted lists to
show the sequence. A procedure can have any number of work steps.

You can write two instructions in one sentence with "and" only when both actions
occur at the same time. You can write more than one sentence in a work step
when:

- Two or more actions occur at the same time and you cannot separate them
- A result or measurement occurs immediately after the action.

### Rule 5.3 — Use the imperative (command) form for instructions
Start each procedural instruction with an imperative verb: "run," "set," "open,"
"save," "install," "configure," "restart," "copy," "delete," "create," "add,"
"enter," "select," "check."

> **Non-STE:** The configuration file should be edited before deployment.
>
> **STE:** Edit the configuration file before you deploy.

Do not use passive voice, gerunds, or modal verbs ("can," "could," "should,"
"may," "might") for instructions. Use "must" only for security warnings, data
loss cautions, and critical conditions.

In a README file, the imperative form applies to the procedural sections only
(installation, configuration, build, quick start). Descriptive sections can use
declarative sentences.

### Rule 5.4 — Put the descriptive statement before the command
When the reader must know a condition first, write the condition as a
descriptive statement, then a comma, then the instruction.

> **Non-STE:** Stop the service if the health check reports a failure.
>
> **STE:** If the health check reports a failure, stop the service.

The comma is the marker that makes the reader evaluate the condition before the
action. Do not bury the condition after the command.

### Rule 5.5 — Notes give information only
A note gives supplementary information. A note must not give an instruction, a
command, a requirement, a limit, or an expected result. Put that information in
the work step. A note must not contain an imperative verb.

> **STE:** NOTE: The API rate limiter permits a maximum of 1000 requests each
> minute for each client IP address on the free tier.

If the information prevents data loss, a security issue, or system damage, write
it as a WARNING or CAUTION instead (Section 7). To test a procedure, read it
without the notes. If the reader cannot complete it, move the missing
information into the work steps.

## Section 6 — Descriptive writing

### Rule 6.1 — Give information gradually
Give the reader one piece of information at a time. Each sentence has one
subject. Do not combine multiple actions, conditions, or subjects.

> **Non-STE:** The authentication middleware validates bearer tokens from the
> authorization header by calling the `validateToken` function which decodes
> the JWT payload and checks the `exp` claim before attaching the claims to the
> request and logging any failure to the audit trail.
>
> **STE:** The authentication middleware validates each incoming request. The
> middleware reads the bearer token from the `Authorization` header. It sends
> the token to the `validateToken` function. The function decodes the JWT
> payload. Then it compares the `exp` claim with the current server time.

### Rule 6.2 — Use key words and key phrases for logical structure
Key words are terms that occur again in a documentation block to link concepts.
Key phrases have the same function. Do not change a key word after you select
it (see also Rule 9.4).

Connecting words and phrases approved in STE-Code: `and`, `but`, `then`, `thus`,
`also`, `however`, `therefore`, `for example`, `as a result`, `at the same
time`. Put them at the start of the sentence.

Do not use `moreover`, `furthermore`, `nevertheless`, or `subsequently`.

### Rule 6.3 — Maximum of 25 words in a descriptive sentence
Descriptive text is more complex than procedural text, so the limit is 25 words.

> **STE:** The authentication middleware validates each incoming request before
> the controller processes it. (11 words)

### Rule 6.4 — Use paragraphs to show related information
A paragraph keeps related information together. Start each paragraph with a
topic sentence that tells the reader the topic. The sentences that follow
explain that topic or add information about it. A new paragraph tells the reader
that a new topic starts.

> **STE:** The data pipeline uses a sequence of stages to process events.
> Validation checks the event schema and rejects malformed events. Enrichment
> adds metadata to the event. Transformation converts the event into a target
> format. Persistence writes the event to the data store.

### Rule 6.5 — One topic in each paragraph
Each paragraph has one topic. The topic sentence is the first and most important
sentence. It gives new information and makes a logical connection to previous
information, usually with a key word or a connecting word.

If the reader collects the topic sentences of a document, those sentences make a
good outline of its content.

### Rule 6.6 — No more than six sentences in a paragraph
If a paragraph has more than six sentences, divide it into two paragraphs. Do
not put different topics in the same paragraph.

## Section 7 — Safety instructions

### Rule 7.1 — Use a signal word to show the level of risk

| Signal word | Use it when there is a risk of |
|---|---|
| WARNING | Security vulnerabilities, data loss, or system corruption |
| CAUTION | Unexpected behavior, performance degradation, or incorrect results |
| NOTE | No risk — supplementary information only (Rule 5.5) |

If the two levels of risk occur together, use a WARNING.

Severity mapping for release notes and changelogs: WARNING to BREAKING,
CAUTION to DEPRECATED, NOTE to NOTE.

A safety instruction must be specific. It must name the risk, not make a general
claim.

### Rule 7.2 — Start a safety instruction with a command or a condition
Start with a clear and accurate command. If the reader must know a condition
before they use a function, method, or API, give the condition first.

> **Non-STE:** WARNING: STORING API KEYS IN THE SOURCE CODE IS NOT RECOMMENDED.
>
> **STE:** WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. ALWAYS USE
> ENVIRONMENT VARIABLES OR A SECRETS MANAGER TO STORE API KEYS.

### Rule 7.3 — Give an explanation of the risk or possible result
Tell the reader what can occur if they do not obey the safety instruction. A
risk explanation has three parts:

1. The failure to obey the instruction
2. The immediate consequence
3. The final harm.

Write the chain in cause-first order: "If you do X, Y can occur."

> **Non-STE:** WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE.
>
> **STE:** WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. API KEYS IN
> SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.

## Section 8 — Punctuation and word count

### Rule 8.1 — Use all standard punctuation marks but not the semicolon
The semicolon (;) is not permitted. It permits very long sentences and it is not
easy to use correctly. Write two sentences instead.

> **Non-STE:** Call the function to parse the response data; handle any errors
> that occur.
>
> **STE:** Call the function to parse the response data. Handle any errors that
> occur.

This rule applies to documentation text only. It does not apply to source code,
where the semicolon is part of the language syntax, or to text inside code
blocks.

### Rule 8.2 — Use hyphens to connect words that are directly related
Five categories of hyphenation apply to code documentation:

| Category | Examples |
|---|---|
| Two or more words that are an adjective before a noun | high-priority task, read-only file, thread-safe method, event-driven architecture, run-time error, end-to-end test, server-side rendering, just-in-time compilation |
| Two-word fractions or numbers | seventy-two, twenty-eight, three-fourths |
| An uppercase letter or a number plus a noun | L-shaped bracket, 64-bit register, 8-byte alignment, 128-bit value |
| Verbs that have a noun as the first part | dry-run, hot-reload, cold-start, hard-code, soft-delete, short-circuit |
| A prefix that ends with a vowel before a root that starts with a vowel | re-enter, re-establish, co-occurrence |

### Rule 8.3 — Use of parentheses
You can use parentheses:

- To make references to code modules, diagrams, or text
- To include letters or numbers that identify items
- To identify the work steps in a procedure
- To include abbreviations
- To give the singular and plural forms of a noun at the same time
- To explain words or a part of a sentence
- To include an alternative.

> **STE:** Call the request handler (Figure 3, Module A).

### Rule 8.4 — A colon in a vertical list ends a sentence
In a vertical list, the colon (:) has the same effect on the word count as a
period.

- Procedural sentences: a maximum of 20 words before the colon.
- Descriptive sentences: a maximum of 25 words before the colon.

Each item after the colon counts as a new sentence, with the same limits: 20
words for procedural items, 25 words for descriptive items.

> **STE:** To handle possible error conditions, the error handler catches these
> exception types:
> - The connection timeout of the database
> - The authentication failure of an expired token
> - The validation error of a malformed payload.

### Rule 8.5 — Text in parentheses counts as one word
Text in parentheses counts as one word in the sentence that contains it. The
words inside the parentheses also make a new sentence, so count them again in
that sentence.

> **STE:** Make sure that the DEBUG environment variable is set to false (the
> DEBUG flag is off). (12 words; the sentence in parentheses has 5 words.)

An identifier or an abbreviation in parentheses also counts as one word.

### Rule 8.6 — Elements that count as one word
Count each of these as one word:

- Numbers
- Numbers together with units of measurement
- Abbreviations
- Alphanumeric identifiers
- Quoted text
- Titles, headings, and text on user interface elements and labels
- Proper nouns of individuals, groups, organizations, and geopolitical entities.

> **STE:** Do steps 13 thru 16 a minimum of three times. (10 words)

### Rule 8.7 — Hyphenated words count as one word
A hyphenated group is one unit for the reader, thus it is one word for the
sentence-length limits.

> **Non-STE:** The open function returns a read only file descriptor.
>
> **STE:** The open function returns a read-only file descriptor.
> ("read-only" is one word.)

## Section 9 — Word choice and consistency

### Rule 9.1 — Use a different sentence construction when replacement fails
The dictionary gives approved alternatives for words that are not approved. If
the alternative has the same part of speech and keeps the meaning, replace the
word. If it does not, write a new sentence with a different structure.

Write a new construction when:

1. The grammatical structure must change to use the alternative.
2. The word-for-word replacement gives an unclear result.
3. The alternative changes the meaning.
4. The word is not in the controlled terminology.

> **Non-STE:** A timeout value of 5000 ms is acceptable for this endpoint.
>
> **STE:** A timeout value of 5000 ms is permitted for this endpoint.

### Rule 9.2 — Use each approved word correctly
Some approved words have a restricted meaning. Read the approved meaning in the
dictionary before you use the word. Use each word only as its approved part of
speech. A small number of words are approved as more than one part of speech.

> **Non-STE:** Execute the initialization script before you start the server.
>
> **STE:** Run the initialization script before you start the server.

### Rule 9.3 — Do not make phrasal verbs
Do not put an approved verb and a preposition together to make a new phrase. Use
one approved verb that has the same meaning. Only a small number of phrasal
verbs are approved, and they all have a restricted meaning.

| Non-STE phrasal verb | STE verb |
|---|---|
| put out (a warning) | emit |
| carry out (a test) | do |
| give off (an event) | release |
| set up (the service) | configure |
| shut down (the process) | stop |

> **Non-STE:** The compiler puts out a warning when the type annotation is
> missing.
>
> **STE:** The compiler emits a warning when the type annotation is missing.

### Rule 9.4 — Use a consistent style
Use the same terminology and the same wording each time the same action or item
occurs.

- Use one name for one item. Do not alternate between "configuration file,"
  "settings file," and "config."
- Use one verb for one action. Do not alternate between "compile," "build," and
  "make."
- Use the same sentence structure for the same type of instruction.

> **Non-STE:** Edit the settings file. Then compile the project. Then build the
> config again to check it.
>
> **STE:** Edit the configuration file. Then build the project. Then build the
> project again to check the configuration file.

## Quick checklist

- Technical nouns: three words maximum; prepositions or hyphens for the rest.
- Verbs: infinitive, imperative, simple present, simple past, simple future,
  past participle as an adjective. No auxiliaries, no progressive.
- Voice: active, unless the agent is unknown in descriptive text.
- Sentences: 20 words in procedures, 25 words in descriptions.
- Instructions: one per sentence, imperative form, condition first.
- Paragraphs: one topic, six sentences maximum, topic sentence first.
- Safety: WARNING or CAUTION, command first, risk explained.
- Punctuation: no semicolon; hyphens for related words; colon ends a sentence.
- Words: one approved meaning, one part of speech, no phrasal verbs, one
  consistent term for one concept.


# === tier level3 ===


# STE-Code Level 3 — distilled index

> + complete dictionary excerpt + all rules

## Sub-documents

- 01-principles.md
- 02-synonyms.md
- 03-dictionary.md
- 04-templates.md
- 05-grammar.md
- rules-sec1-part1.md
- rules-sec1-part2.md
- rules-sec2.md
- rules-sec3.md
- rules-sec4.md
- rules-sec5.md
- rules-sec6.md
- rules-sec7.md
- rules-sec8.md
- rules-sec9.md



## 01-principles.md

# Level 3 — Core Principles (Words: Rules 1.1–1.14)

Section 1 of STE-Code governs **words**: which words you may use, in which part
of speech, with which meaning, and in which form. Every other section of the
standard assumes these fourteen rules already hold.

Three gates decide whether a word is allowed in code documentation:

1. The word is **approved in the controlled terminology** (STE-Code part 2), or
2. The word is a **code-domain technical noun** (Rule 1.5 categories), or
3. The word is a **code-domain technical verb** (Rule 1.12 categories).

A word that passes no gate must be replaced, or the sentence must be
restructured so that approved words can carry the meaning.

Definitions used throughout:

- **Controlled terminology** — the STE-Code approved word list. Each entry gives
  one part of speech and one approved meaning, plus the approved verb and
  adjective forms.
- **Code-domain technical noun** — a noun term for a specified concept in
  software development, applicable to a subject field (Rule 1.5, 19 categories).
- **Code-domain technical verb** — a verb term for a specified operation or
  process in software development (Rule 1.12, 4 categories).

Rule index:

| Rule | Statement |
|------|-----------|
| 1.1 | Use words that are approved in the controlled terminology, code-domain technical nouns, or code-domain technical verbs. |
| 1.2 | Use approved words only as the specified part of speech. |
| 1.3 | Use approved words only with their approved meanings. |
| 1.4 | Use only the approved forms of verbs and adjectives. |
| 1.5 | You can use words that you can include in a code-domain technical noun category. |
| 1.6 | Use a word that is not approved only when it is a code-domain technical noun or part of one. |
| 1.7 | Do not use words that are code-domain technical nouns as verbs. |
| 1.8 | Use code-domain technical nouns that are approved in your project, company, industry, or subject field. |
| 1.9 | When you must select a code-domain technical noun, use one which is short and easy to understand. |
| 1.10 | Do not use regional, slang, or jargon words as code-domain technical nouns. |
| 1.11 | Do not use different code-domain technical nouns for the same item. |
| 1.12 | You can use verbs that you can include in a code-domain technical verb category. |
| 1.13 | Do not use code-domain technical verbs as nouns. |
| 1.14 | Use American English spelling unless other official directives tell you differently. |

---

## Rule 1.1 — Use approved words, code-domain technical nouns, or code-domain technical verbs

In code documentation, use words that are:

- approved in the project controlled terminology,
- code-domain technical nouns, or
- code-domain technical verbs.

The controlled terminology gives the words most frequently used in code
documentation. It also lists words that are **not** approved, with approved
alternatives. Your project glossary or terminology database holds the technical
nouns and technical verbs of your subject field; always check it first.

Worked vocabulary swaps:

| Do not write | Write | Why |
|---|---|---|
| execute the script | run the script | "run" is the approved verb for executing programs |
| generate the artifact | make the artifact | "make" is approved; "generate" is not |
| utilize / leverage the cache | use the cache | inflated verb |
| bootstrap / initiate the service | start the service | "start" is approved |
| configure the runtime | set the runtime behavior | "set" is approved |
| retrieve / fetch the record | get the record | "get" is approved |
| transmit the payload | send the data | "send" is approved |
| validate / verify the input | check the input | "check" is approved |
| unable to connect | cannot connect | "cannot" is approved |
| invalid / malformed data | incorrect data, data that is not correct | "correct" is the approved adjective |

Technical terms stay: `UserAuthenticator` is a code-domain technical noun,
`serialize` is a code-domain technical verb, and both are permitted although
neither is in the controlled terminology.

Examples by documentation type:

> **Non-STE (README):** To begin utilizing the build toolchain, you must first
> generate the distributable artifact, then execute the compiled binary to
> bootstrap the local development service.
>
> **STE:** Use the build tool to make the binary. Run the binary to start the
> local service.

> **Non-STE (JSDoc):** Fetches a user record. The duration in milliseconds the
> client shall await a response prior to terminating the connection attempt.
>
> **STE:** Gets a user record. The time in milliseconds that the client waits
> for a response before it stops the connection.

> **Non-STE (docstring):** Performs validation on the input data to ensure it
> conforms to the expected schema.
>
> **STE:** Checks the input data against the schema. Gives `True` when the data
> is correct and `False` when the data is not correct.

> **Non-STE (commit):** feat: implement JWT authentication middleware
>
> **STE:** feat: add JWT authentication middleware

> **Non-STE (CLI error):** Unable to establish connection to the database.
> Please verify your credentials and retry.
>
> **STE:** Cannot connect to the database. Check your credentials and try again.

Paradigm notes:

- **Object-oriented** — prose uses approved verbs (make, get, set, call, send,
  keep). Class, method, and pattern names stay as technical nouns.
- **Functional** — `map`, `fold`, `reduce`, `filter`, `compose`, and `curry` are
  code-domain technical verbs, permitted under Rule 1.12. "Pure function" is a
  compound code-domain technical noun.
- **Procedural** — each step starts with an approved imperative verb.
  "Allocate" is not approved: write "make a buffer". "Free" and "dereference"
  are code-domain technical verbs.
- **Declarative** — SQL keywords and resource kind names are technical terms.
  "Provision" is not approved (use "make" or "set up"); "orchestrate" is not
  approved (use "control" or "manage").
- **Systems** — "own", "borrow", and "move" are Rust technical verbs.
  "Dangling pointer" and "undefined behavior" are compound technical nouns
  (category 15).

---

## Rule 1.2 — Use approved words only as the specified part of speech

Each entry in the controlled terminology carries one label: verb (v), noun (n),
adjective (adj), adverb (adv), preposition (prep), conjunction (conj), pronoun
(pron), or article (art). Use the word only in that grammatical role.

- "Query" is an approved **noun**, not a verb. Write "Send a query to the
  database", not "Query the database".
- "Static" is an approved **adjective**, not a verb. Write "Make the variable
  static", not "Static the variable".
- Some words carry more than one label. "Call" is an approved verb and an
  approved noun; the position in the sentence shows the function.

If the word you want is not in the controlled terminology:

1. Find the word in a standard English dictionary.
2. Find the best synonym that is approved in the STE-Code controlled terminology.
3. Use that approved word, or write a different sentence construction.

When you replace a word, make sure that the meaning does not change. If it
changes, select a different word or restructure the sentence.

| Violating form (do not use) | Part-of-speech error | Approved replacement |
|---|---|---|
| Query the database / Cache the result / Queue the job / Log the error / Index the record | technical noun used as verb | Send a query / Keep the result in the cache / Put the job in the queue / Write the error in the log / Use the index to find the record |
| Docker the app / Git the change / Kubectl the pod / Terraform the VPC | tool name used as verb | Use Docker / Save with Git / Use `kubectl` / Use Terraform |
| Secure the endpoint / Empty the buffer / Silent the log | adjective used as verb | Make the endpoint secure / Make the buffer empty / Make the log silent |
| Static the variable / Ready the worker / Live the connection | adjective used as verb | Make the variable static / Make the worker ready / Make the connection live |
| Utilize / Leverage / Employ the service | inflated verb | Use the service |
| Commence the build / Initiate the transfer / Terminate the process | inflated verb | Start the build / Start the transfer / Stop the process |
| Orchestrate the services / Facilitate the sync | unapproved verb | Control the services / Help the sync |

Examples:

> **Non-STE:** Docker the app and deploy to production. If it fails, rollback.
>
> **STE:** Use Docker to make a container for the application. Deploy the
> container to production. If the deployment fails, roll back to the previous
> version.

> **Non-STE:** Creates a user. Caches the profile. Errors on duplicate email.
>
> **STE:** Makes a new user record. Keeps the profile in the cache. Gives an
> error on a duplicate email address.

> **Non-STE:** # init the pool, then cache the results, finally error if null
>
> **STE:** # Start the connection pool. Keep the results in the cache. Give an
> error when the value is null.

> **Non-STE:** Error: Connection timeout. The server timed out after 30s.
>
> **STE:** Error: Connection did not complete. The server did not answer within
> the 30-second timeout.

Paradigm notes: "Factory the object" and "Singleton the instance" are OOP
violations (use "Make the object with a factory", "Get the singleton
instance"). "Malloc a buffer" and "Goroutine the task" are procedural
violations (use "Make a buffer with `malloc`", "Run the task in a goroutine").
"Terraform the VPC" is a declarative violation (use "Use Terraform to make the
VPC"). In Rust, mark keywords with backticks: "The function uses `unsafe` for
the pointer access."

---

## Rule 1.3 — Use approved words only with their approved meanings

Each approved word has one specified meaning, which is often narrower than the
standard English meaning. Do not use an approved word with any other meaning.

- The approved meaning of the verb **follow** is "come after, go after". Use it
  only for sequence: "Do the steps that follow."
- The approved meaning of the verb **obey** is "to do that which the procedures
  or instructions tell you". Use it for compliance: "Obey the instructions."

Four-step check for every approved word you write:

1. **Identify the part of speech** as you used it in the sentence.
2. **Look up the approved meaning** for that part of speech in the controlled
   terminology.
3. **Ask: does my sentence use exactly that meaning?** If not, the word fails —
   even when the word is approved and the sentence reads well.
4. **Replace or restructure** so the approved word carries its approved meaning.

Worked check:

> **Sentence:** The background worker runs every night.
> **Step 1:** "runs" is a verb.
> **Step 2:** Approved meaning of "run" = "execute a program or command".
> **Step 3:** The writer means "operates on a schedule". The meaning does not match.
> **Step 4:** Rewrite: "The background worker operates every night."

Examples:

> **Non-STE:** Follow the configuration steps to set up the server. After you
> follow the steps, the service starts and listens on port 8080.
>
> **STE:** Obey the configuration instructions to set up the server. After you
> do the steps that follow, the service starts and listens on port 8080.

---

## Rule 1.4 — Use only the approved forms of verbs and adjectives

The controlled terminology gives each approved verb with its approved forms, and
each approved adjective in the base form with the comparative and superlative
forms where applicable.

Verb entry:

COMPILE (v), COMPILES, COMPILED, COMPILED

| Infinitive / imperative | Simple present | Simple past | Past participle (as adjective) |
|---|---|---|---|
| (To) Compile / Compile | Compile(s) | Compiled | Compiled |

Forms that are not listed are not permitted: "compilating" and "compilates" are
both incorrect.

Adjective entry:

FAST (adj) (FASTER, FASTEST) — base form *fast*, comparative *faster*,
superlative *fastest*. Adjectives that make their comparative and superlative
with "more" and "most" have no extra forms in the terminology, because "more"
and "most" are approved words.

Do not use the "-ing" form as a main verb in procedural writing unless the
controlled terminology lists it.

Examples:

> **Non-STE:** The compiler is compilating the source files every time you save
> the document.
>
> **STE:** The compiler compiles the source files each time you save the
> document.

> **Non-STE:** This algorithm is more fast than the previous one.
>
> **STE:** This algorithm is faster than the previous one.

> **Non-STE:** After installing the dependencies, you can start compiling the
> project by running the build script.
>
> **STE:** After you install the dependencies, compile the project with the
> build script.

---

## Rule 1.5 — Code-domain technical noun categories

A code-domain technical noun is a noun term for a specified concept in software
development, applicable to a subject field. The controlled terminology cannot
list them all, because each project uses different ones; keep yours in the
project glossary or terminology database.

You may use a code-domain technical noun in procedural and descriptive writing
when you can put it in one or more of these **nineteen** categories. The words
shown are examples only, not a complete list.

| # | Category | Example terms |
|---|---|---|
| 1 | Code components, modules, and libraries | class, controller, helper, hook, middleware, mixin, module, package, plugin, provider, repository, service, utility |
| 2 | Computing devices and their components | CPU, disk, GPU, keyboard, laptop, memory, monitor, mouse, printer, screen, server, smartphone, tablet, terminal |
| 3 | Development tools, environments, and support equipment | CLI, compiler, debugger, Docker, editor, IDE, Git, Jest, linter, loader, Prettier, terminal, test runner, TypeScript, webpack |
| 4 | Data structures, types, and formats | array, boolean, buffer, CSV, enum, hash map, integer, JSON, linked list, object, queue, stack, string, struct, tree, tuple, XML, YAML |
| 5 | Infrastructure, deployment, and platforms | AWS, CI/CD, container, deployment, Heroku, Kubernetes, load balancer, Node.js, pipeline, pod, production, staging, Vercel |
| 6 | Systems, subsystems, and architectural components | API gateway, authentication layer, caching layer, client, database layer, message broker, microservice, proxy, rate limiter, REST API, routing layer, server, WebSocket |
| 7 | Mathematical, algorithmic, and scientific terms | Big O notation, binary search, coefficient, complexity, exponent, hash function, iteration, logarithm, matrix, recursion, regex, sorting algorithm, time complexity, traversal |
| 8 | Interface elements and navigation | button, checkbox, dialog, dropdown, footer, header, menu, modal, navigation bar, radio button, scrollbar, sidebar, tab, text field, toggle, tooltip |
| 9 | Numbers, units of measurement, and time | byte, gigabyte (GB), hertz (Hz), hour (h), kilobyte (KB), megabyte (MB), millisecond (ms), minute, nanosecond (ns), second (s), terabyte (TB) |
| 10 | Quoted text (text you cannot change: error messages, code snippets, UI labels, log output) | `Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused` |
| 11 | Professional roles, teams, and organizations | administrator, backend developer, contributor, DevOps engineer, frontend developer, Google, maintainer, Microsoft, product owner, QA engineer, reviewer, scrum master, user |
| 12 | Official documents, API references, and standards | API reference, changelog, code of conduct, contributing guide, diagram, figure, Getting Started guide, HTTP specification, note, paragraph, README, release notes, RFC, section, table, warning |
| 13 | Runtime environments and operational conditions | development, environment variable, garbage collection, heap, hot reload, live reload, memory leak, production, sandbox, stack trace, staging, test, thread, timeout, virtual machine |
| 14 | Colors | black, blue, cyan, gray, green, magenta, orange, red, white, yellow |
| 15 | Defects, errors, and fault terminology | assertion failure, bug, crash, deadlock, defect, exception, hang, infinite loop, memory leak, null pointer, race condition, regression, stack overflow, timeout, type error |
| 16 | Computer science, information, and communication technology | AI, algorithm, authentication, authorization, blockchain, containerization, cryptography, database, encoding, encryption, firewall, hashing, internet, machine learning, metadata, neural network, protocol, query, sandbox, schema, token, virtualization |
| 17 | Legal and licensing terms | Apache 2.0, BSD license, compliance, copyright, GPL, license, MIT license, open source, proprietary, terms of service, third-party, trademark, warranty |
| 18 | Database and storage terminology | connection pool, cursor, foreign key, index, migration, NoSQL, ORM, PostgreSQL, primary key, query, Redis, relation, row, schema, seed, SQL, SQLite, stored procedure, table, transaction, view |
| 19 | Network and protocol terminology | DNS, endpoint, HTTP, HTTPS, IP address, localhost, middleware, packet, port, request, response, route, socket, SSH, TCP, TLS, UDP, URL, VPN, WebSocket |

Note on category 14: colors are adjectives, but STE-Code identifies them as
code-domain technical nouns. Comparative and superlative forms of colors (for
example "blacker", "the reddest") are not permitted.

---

## Rule 1.6 — Unapproved words are permitted only inside technical nouns

A word that the controlled terminology marks as not approved fails when you use
it as a general noun or adjective, and passes when it is part of a recognized
code-domain technical noun.

**"Handler"** — not approved; the alternative is "function (n)".

> **Non-STE:** The handler processes each incoming event.
>
> **STE:** The function processes each incoming event.
>
> **STE:** The event handler processes each incoming event.
> ("Event handler" is a code-domain technical noun, category 1.)

**"Main"** — not approved as a general adjective; the alternative is
"primary (adj)".

> **Non-STE:** The main configuration has the latest values.
>
> **STE:** The primary configuration has the latest values.
>
> **STE:** Merge the feature branch into the main branch.
> ("Main branch" is a code-domain technical noun, category 5. Do not write
> "primary branch" — that is not the approved technical noun.)

**"Base"** — not approved for a surface location; the alternative is
"bottom (n)". "Base" stays inside the technical nouns "base case" (category 7)
and "base class" (category 1).

> **Non-STE:** Copy the files to the base of the build folder.
>
> **STE:** Copy the files to the bottom of the build folder.

---

## Rule 1.7 — Do not use code-domain technical nouns as verbs

Use a code-domain technical noun only as a noun, or as an adjective inside a
different technical noun. Restructure the sentence with an approved verb.

> **Non-STE:** Database the user records before the migration.
>
> **STE:** Store the user records in the database before the migration.

> **Non-STE:** Cache the API responses to improve performance.
>
> **STE:** Store the API responses in the cache to improve performance.

A word can be a technical noun **and** a technical verb when it fits a category
in Rule 1.5 and a category in Rule 1.12. Your project glossary decides:

> **STE (noun):** Write a log entry for each failed request.
>
> **STE (verb):** Log each failed request.

If your glossary lists the word only as a technical noun, obey Rule 1.7 and use
a different sentence construction.

> **See also:** Rule 1.5, Rule 1.12, Rule 1.13.

---

## Rule 1.8 — Use the technical nouns approved in your project or field

If your project, company, industry, or subject field already has an approved
name for a class, module, function, method, variable, component, or process,
use that name. These names live in your project glossary, API documentation,
coding standards, or company documentation.

Do not invent your own names for items that already have established names.
The source of truth is the repository.

> **STE:** The dashboard page has a `UserTable` component and a `FilterPanel`
> component.

> **Non-STE:** The account controller manages login and user profile operations.
>
> **STE:** The `AccountController` manages authentication and user profile
> operations.

---

## Rule 1.9 — Select short, easy technical nouns

When no approved technical noun exists in your project, company, industry, or
subject field, select one that is short (not more than three words) and easy to
understand. Do not write a long descriptive phrase when a shorter term is
enough. When the context identifies the item — a code snippet, a line number, a
diagram, an API reference — use the shortest unambiguous term. Add one or two
adjectives only when clarification is necessary.

```javascript
// client.js — line 42
async function fetchUtility(url) {
  const response = await fetch(url);
  return response.json();
}
```

> **Non-STE:** Call the asynchronous JavaScript XML HTTP request wrapper utility
> function (line 42) to get the serialized JSON payload from the remote
> application programming interface endpoint.
>
> **STE:** Call the `fetchUtility` function (line 42) to get the JSON data from
> the API endpoint.

---

## Rule 1.10 — No regional, slang, or jargon words as technical nouns

Some technical words are used only inside confined communities or single
technology ecosystems. They are not easy to understand for readers from a
different background or stack. Code documentation is read by junior developers,
developers from other language communities, and non-native English speakers: a
word that one subculture finds clear can be opaque to every other reader.
Always select well-known words.

| Do not write | Write |
|---|---|
| Remove all the cruft from the legacy module. | Remove all the unnecessary code from the legacy module. |
| The function monkeys with the input data before validation. | The function changes the input data before validation. |
| Bikeshedding delayed the API design by two weeks. | Unnecessary discussion about small details delayed the API design by two weeks. |
| I spent the morning yak shaving before I could write the test. | I spent the morning completing unrelated prerequisite tasks before I could write the test. |
| Replace the foo and bar placeholders with real values. | Replace the example and placeholder values with real values. |

---

## Rule 1.11 — One technical noun per item

Do not use a different code-domain technical noun in another part of your
documentation for the same item. Changing the name of one item between sections
forces the reader to decide whether you mean the same item or a different one.
The source of truth for the name is the code: the class, function, module,
table, resource, environment variable, or configuration key as it is defined in
the repository.

> **Non-STE:**
> 1. Initialize the UserService class to start the session manager.
> 2. Call the authenticate method on the AccountManager to verify a user.
> 3. The UserHandler returns a session token that you send in later requests.
>
> **STE:**
> 1. Initialize the UserService class to start the session manager.
> 2. Call the authenticate method on the UserService to verify a user.
> 3. The UserService returns a session token that you send in later requests.

> **Non-STE:** "/api/login path", "authentication route", "login endpoint" —
> three names for one endpoint.
>
> **STE:** Use "/api/login endpoint" in every sentence, because the OpenAPI file
> defines the path as `/api/login`.



## 02-synonyms.md

# Level 3 — Synonyms and Approved Words

This slice defines how to choose words in STE-Code when the approved-words
dictionary does not contain the term you need. It covers the **technical-noun
category system** (Rule 1.5) and the rules that govern unapproved-word use and
synonym selection (Rules 1.6–1.11).

Core idea: the dictionary lists approved everyday words. When you need a
word not in the dictionary, you may still use it if it qualifies as a
**technical noun** — a noun term for a specified software concept that fits one
of 19 categories. This lets project-specific terminology (class names, protocol
names, metrics, error strings) appear in documentation without breaking
controlled-language rules.

## Rule 1.5 — Technical noun categories (framework)

You can use a term in code documentation if you can include it in a technical
noun category.

- A **technical noun** is a noun term that refers to a specified software
  concept and is applicable to a given codebase, library, or system.
- The approved-words dictionary does not list project-specific technical nouns
  because each codebase, framework, and ecosystem uses different terminology.
- Find these terms in your project glossary, API reference, or architecture
  decision records (ADRs).
- Use technical nouns in procedural and descriptive documentation — API
  references, commit messages, READMEs, code comments, technical specs — when
  they fit one or more of the 19 categories below.

Non-STE vs STE:

| Non-STE | STE |
|---------|-----|
| Use the thing to call the function that gets data from the database. | Use the `fetchUser` method of the `UserRepository` to retrieve a `User` record from the `PostgreSQL` database. |
| ("thing", "gets data" — no technical nouns; ambiguous) | (`fetchUser`, `UserRepository`, `User`, `PostgreSQL` — all classified technical nouns) |

## The 19 technical noun categories

Each category below lists **code-domain** terms that count as technical nouns.
A term fits if it refers to a specified software concept of that kind. The lists
are examples, not a closed vocabulary — add project-specific terms via your
glossary.

### 1. API and library components
Terms for API and library components: endpoint, method, parameter, query
parameter, path parameter, request body, response body, header, status code,
module, class, interface, type alias, enum, constant, decorator, middleware,
route handler, serializer, DTO, model, schema, callback, hook, plugin.
- STE: Call the `POST /api/v1/users` endpoint with a `CreateUserRequest` body
  to create a `User` resource.

### 2. Applications, services, and subsystems
Web application, mobile app, desktop client, CLI tool, microservice, monolith,
API gateway, load balancer, database server, message broker, cache layer,
container, pod, cluster, frontend, backend, admin panel, user dashboard,
authentication service, payment service, notification service, search engine,
CDN, reverse proxy, serverless function, cron job, worker process.
- STE: The `nginx` reverse proxy on the `web-01` frontend server stopped
  responding.

### 3. Development tools and SDKs
IDE, code editor, terminal emulator, compiler, interpreter, transpiler, bundler,
linter, formatter, debugger, profiler, package manager, version control system,
CI runner, test framework, assertion library, mocking library, static analyzer,
API client, database client, container runtime, orchestration tool, IaC tool,
monitoring dashboard, log aggregator, feature flag service, secrets manager.
- STE: Run `ESLint` with the `@company/eslint-config` preset to find lint
  violations.

### 4. Dependencies, packages, technical debt
Dependency, transitive dependency, package, library, framework, runtime,
polyfill, shim, vendor bundle, dead code, deprecated API, legacy module,
orphaned code, code smell, TODO comment, FIXME comment, zombie import, circular
dependency, peer dependency, dev dependency, optional dependency, pinned
version, lockfile, SBOM, supply chain artifact, third-party script, ad-hoc
patch, monkey-patch, workaround code.
- STE: Remove the deprecated `UserService.legacyCreate()` method — dead code
  with zero callers as of v3.2.

### 5. Hosting, CI/CD, deployment infrastructure
Cloud provider, region, availability zone, data center, Kubernetes cluster,
namespace, Docker registry, artifact repository, build pipeline, deployment
pipeline, staging environment, production environment, sandbox environment,
on-premise server, virtual machine, bare-metal host, edge location, CDN
endpoint, storage bucket, message queue, event bus, API gateway endpoint, load
balancer target group, auto-scaling group, service mesh, ingress controller.
- STE: Deploy the `orders-service` container image to the `us-east-1`
  `production` Kubernetes cluster in namespace `orders`.

### 6. Software system design and architecture
Architecture, design pattern, layered architecture, hexagonal architecture,
microservice, event-driven architecture, CQRS, event sourcing, pub/sub, message
queue, event bus, database shard, read replica, write-ahead log, connection
pool, circuit breaker, retry policy, rate limiter, cache layer, CDN edge,
feature flag, A/B test variant, canary deployment, blue-green deployment,
rolling update, service registry, configuration provider, secret store, reverse
proxy, API gateway route, middleware chain, plugin system, dependency injection
container, ORM, migration runner.
- STE: The `PaymentGateway` client uses a `CircuitBreaker` pattern — after 5
  consecutive failures it opens and returns cached fallback responses for 30 s.

### 7. Algorithms, data structures, computational concepts
Algorithm, data structure, Big-O notation, time complexity, space complexity,
hash table, binary tree, linked list, graph, trie, bloom filter, LRU cache,
consistent hashing, recursion, memoization, dynamic programming, greedy
algorithm, backtracking, binary search, quicksort, mergesort, topological sort,
Dijkstra, BFS, DFS, A*, Paxos, Raft, two-phase commit, saga pattern, idempotency
key, eventual consistency, CAP theorem, ACID, BASE, vector clock, Lamport
timestamp, Merkle tree, shard key, partition key, compound index, covering
index, query plan, cardinality, selectivity, normalization, denormalization,
OLTP, OLAP, ETL, stream processing, batch processing, map-reduce, actor model,
CSP, semaphore, mutex, atomic operation, CAS.
- STE: `computeShippingCost(addressHash)` is memoized with an `LRU Cache`
  (capacity 1024, `O(1)` eviction) to avoid redundant API calls.

### 8. Codebase navigation and project structure
Directory, subdirectory, file path, import path, package root, module root,
workspace root, monorepo root, source directory, test directory, build output,
entry point, barrel export, index file, re-export, absolute import, relative
import, path alias, symlink, Git root, branch, tag, commit, HEAD, upstream,
origin, fork, submodule, subtree, vendor directory, node_modules, virtual
environment, GOPATH, classpath, namespace, package scope, module scope, public
API surface, internal package, private module, exported symbol.
- STE: The `formatCurrency` helper is in `src/shared/utils/formatting.ts`,
  re-exported from the barrel file at `src/shared/utils/index.ts`.

### 9. Metrics, timing, quantitative measurements
Latency, throughput, response time, p50, p95, p99, p999, ops/sec, req/sec, RPM,
RPS, QPS, TPS, bytes, KB, MB, GB, TB, KiB, MiB, ms, µs, ns, s, min, hr, CPU
core, thread count, memory usage, heap size, stack size, GC pause, cold start
time, warm start time, bootstrap time, build time, deploy time, MTTR, MTBF,
uptime, downtime, error rate, success rate, availability (99.9%, 99.99%), RPO,
RTO, SLO, SLI, SLA, concurrency, connection count, pool size, batch size, page
size, offset, limit, TTL, timeout, interval, poll interval, retry delay, backoff
multiplier, rate limit (tokens/sec), quota, sample rate, cardinality.
- STE: The `GET /search` endpoint has a p95 latency of 120 ms and a p99 latency
  of 350 ms at 5000 RPM.

### 10. Quoted text (cannot change)
Quoted error messages, log output, API responses, UI string literals, CLI
output: error message, stack trace, log line, HTTP response body, JSON payload,
XML response, environment variable value, CLI flag, command option, shell
command output, status code text, exception message, assertion message,
deprecation warning, compiler diagnostic, linter rule ID, test failure message,
benchmark output, profiler report, API route pattern, SQL query string, GraphQL
query, regex pattern, glob pattern, cron expression, semantic version string,
git commit hash, UUID string, JWT token (example), `"Connection refused"`,
`"404 Not Found"`, `"TypeError: Cannot read properties of undefined"`,
`"--config=./prod.yaml"`, `"npm ERR! code ERESOLVE"`.
- STE: If the application logs `"FATAL: sorry, too many clients already"` from
  `PostgreSQL`, restart the `pgbouncer` connection pooler.

### 11. Project roles, teams, organizations, entities
Maintainer, author, contributor, reviewer, approver, code owner, release
manager, on-call engineer, SRE, DevOps engineer, security champion, triage team,
core team, steering committee, technical lead, staff engineer, principal
engineer, intern, vendor, client, stakeholder, end user, GitHub organization,
npm organization, Docker Hub organization, CNCF, Apache Software Foundation,
Linux Foundation, Mozilla, Google, Microsoft, OpenAPI Initiative, ECMA, ISO,
W3C, IETF, OWASP, `CODEOWNERS` file, `@backend-team`, `@security-reviewers`.
- STE: Request a review from `@frontend-core` (code owners for `src/components/`
  per `.github/CODEOWNERS`).

### 12. UI elements, interaction points, accessibility
Button, text input, checkbox, radio button, dropdown, select menu, toggle,
slider, modal, dialog, tooltip, popover, toast, snackbar, banner, tab, accordion,
breadcrumb, pagination, carousel, card, table, data grid, form, form field,
label, placeholder, icon, avatar, badge, spinner, progress bar, skeleton loader,
navbar, sidebar, footer, header, search bar, filter panel, drawer, split pane,
context menu, keyboard shortcut, hotkey, focus trap, skip link, screen reader
label, ARIA role, ARIA attribute, landmark region, heading hierarchy.
- STE: Click the `hamburger` icon in the `Navbar` to open the `Sidebar` drawer
  (ARIA role `navigation`, label "Main menu").

### 13. User data, preferences, session state
User profile, display name, avatar URL, email address, phone number, billing
address, shipping address, payment method, credit card, subscription plan, usage
quota, rate limit bucket, API key, access token, refresh token, ID token,
session cookie, CSRF token, user preference, theme setting, language locale,
timezone, notification setting, opt-in flag, consent record, bookmark,
watchlist, shopping cart, wishlist, search history, recently viewed, draft
content, clipboard data, localStorage key, IndexedDB store, browser fingerprint,
device ID, push notification token.
- STE: Persist the user's `uiPreferences` (theme `"dark"`, locale `"en-GB"`,
  timezone `"Europe/London"`) to `localStorage` under key `user_prefs_v2`.

### 14. System health, diagnostics, observability, failure modes
Health check, liveness probe, readiness probe, startup probe, heartbeat, ping,
metric, trace, span, log level, structured log, correlation ID, trace ID, span
ID, alert, incident, SLO, SLI, error budget, burn rate, on-call rotation,
escalation policy, runbook, playbook, postmortem, root cause analysis (RCA),
mean time to recovery (MTTR), mean time to detection (MTTD), anomaly detection,
threshold breach, saturation, latency tail, error spike, traffic drop, resource
exhaustion, memory pressure, disk pressure, CPU throttling, GC thrashing,
connection storm, thundering herd, cascading failure, split-brain, partition,
degraded state, brownout, blackout.
- STE: The `payments-service` `readinessProbe` is failing — `/healthz` returns
  HTTP 503; the service is `degraded` and removed from the load balancer target
  group.

### 15. Documents, standards, specifications, their parts
README, CHANGELOG, CONTRIBUTING, LICENSE, CODE_OF_CONDUCT, SECURITY, GOVERNANCE,
ARCHITECTURE, ADR (Architecture Decision Record), RFC (Request for Comments),
API reference, OpenAPI spec, GraphQL schema, AsyncAPI spec, style guide, coding
standard, linting rules, PR template, issue template, discussion template,
release notes, migration guide, upgrade guide, getting started guide, quickstart,
tutorial, how-to guide, explanation, reference, concept document, FAQ, glossary,
onboarding guide, runbook, playbook, incident report, postmortem, design doc,
technical spec, product requirements document (PRD), test plan, test case,
acceptance criteria, Definition of Done, Definition of Ready, service level
agreement (SLA), terms of service (TOS), privacy policy, cookie policy, data
processing agreement (DPA), semantic versioning (SemVer), conventional commits,
Git commit message format, doc comment, TSDoc, JSDoc, godoc, docstring,
annotation, attribute, decorator doc, heading, subheading, section, subsection,
paragraph, code block, table, list, admonition (note, warning, tip, danger,
caution, important), hyperlink, cross-reference, footnote, bibliography, index,
glossary entry, TOC (table of contents).
- STE: Record the decision in an ADR
  (`docs/adr/0014-use-event-sourcing-for-orders.md`) with Context, Decision,
  Consequences, Alternatives Considered sections.

### 16. Runtime environments, execution contexts, operating parameters
Production, staging, development, testing, CI, localhost, operating system, OS
version, kernel version, distribution, CPU architecture (x86_64, arm64), Node.js
version, Python version, Java version, Go version, browser, browser version,
rendering engine, screen resolution, viewport size, device type, network
condition (offline, slow 3G, 4G, WiFi), Docker image, container runtime,
Kubernetes version, cloud region, availability zone, environment variable, build
flag, feature flag state, A/B test bucket, configuration profile, Spring
profile, Rails environment, NODE_ENV, DEBUG mode, verbose logging, trace level,
read-only mode, maintenance mode, degraded mode, dark mode, high contrast mode,
reduced motion, forced colors, RTL locale, daylight saving time transition, leap
second, timezone offset.
- STE: The `TextRenderer` crash only reproduces on `macOS 14.5` (arm64) with
  `Node.js 20.11.0` — the `canvas` native addon fails to load the prebuilt
  binary.

### 17. Colors and theme tokens
Primary, secondary, accent, success, warning, error, info, neutral, background,
surface, text, border, divider, shadow, overlay, red, green, blue, yellow,
orange, purple, pink, teal, cyan, gray, black, white, transparent, hex code
(`#FF5733`, `#1A1A2E`), RGB (`rgb(255, 87, 51)`), RGBA (`rgba(26, 26, 46, 0.8)`),
HSL (`hsl(12, 100%, 60%)`), CSS custom property (`--color-primary-500`,
`--color-text-on-primary`), design token, color ramp, color scale (50-900), light
mode, dark mode, high contrast mode, color blindness safe palette, WCAG contrast
ratio, semantic color, Brand Color.
- Colors in design systems are technical nouns. Do NOT use comparative forms
  ("darker", "lightest") — reference the specific design token or ramp step.
- STE: Set the page background to `--color-surface-page` (resolves to `#FFFFFF`
  in light mode, `#121212` in dark mode), WCAG AA contrast ≥ 4.5:1.

### 18. Bugs, errors, exceptions, failure modes
Crash, segfault, null pointer exception, undefined is not a function, type error,
reference error, syntax error, range error, stack overflow, buffer overflow,
memory leak, resource leak, dangling pointer, use-after-free, double free, race
condition, deadlock, livelock, starvation, priority inversion, ABA problem, torn
read, torn write, dirty read, non-repeatable read, phantom read, lost update,
write skew, serialization anomaly, split-brain, network partition, timeout,
connection reset, DNS failure, TLS handshake failure, certificate expiry,
HTTP 500, HTTP 502, HTTP 503, HTTP 504, rate limit exceeded, quota exceeded, out
of memory (OOM), disk full, inode exhaustion, file descriptor exhaustion, thread
pool exhaustion, connection pool exhaustion, GC thrashing, cache stampede, cache
penetration, cache avalanche, hot partition, data corruption, bit rot, checksum
failure, hash collision, infinite loop, infinite recursion, integer overflow,
integer underflow, floating point precision error, off-by-one error, SQL
injection, XSS, CSRF, prototype pollution, deserialization vulnerability,
dependency confusion, supply chain attack, CVE, CWE, zero-day.
- STE: `OrderProcessor` has a race condition: threads A and B both check
  `inventory[sku].quantity > 0` before either decrements — oversell. Fix:
  `SELECT ... FOR UPDATE` row lock.

### 19. Computer science and ICT
API, REST, GraphQL, gRPC, WebSocket, SSE, HTTP/2, HTTP/3, TCP, UDP, TLS, mTLS,
OAuth 2.0, OIDC, SAML, JWT, API key, CORS, CSP, HSTS, DNS, CDN, IP, IPv4, IPv6,
CIDR, VPN, VPC, subnet, firewall rule, WAF, DDoS, load balancing, reverse proxy,
forward proxy, caching, compression, serialization (JSON, Protobuf, MessagePack,
Avro), encoding (Base64, URL encoding), hashing (SHA-256, bcrypt, Argon2),
encryption (AES-256-GCM, RSA, ECDSA), encoding (UTF-8, ASCII), Unicode, emoji,
regex, glob pattern, SQL, NoSQL, ORM, migration, seed data, transaction, ACID,
BASE, sharding, replication, partitioning, indexing, normalization,
denormalization, message queue, pub/sub, event sourcing, CQRS, saga, distributed
transaction, consensus, leader election, service discovery, circuit breaker,
bulkhead, retry, backoff, idempotency, rate limiting, throttling, API versioning,
semantic versioning, feature flag, canary release, blue-green deployment, rolling
update, immutable infrastructure, infrastructure as code, configuration as code,
GitOps, observability, telemetry, tracing, metrics, logging, profiling, APM, RUM,
continuous integration, continuous delivery, continuous deployment, DevOps,
DevSecOps, Git, Docker, Kubernetes, Helm, Terraform, Ansible.
- STE: `Orders API` uses OAuth 2.0 Authorization Code flow (PKCE); clients get a
  JWT from `POST /oauth/token` and pass it in the `Authorization: Bearer <token>` header.

### 20. DevOps, release management, lifecycle support
Deployment, release, rollout, rollback, hotfix, patch, minor release, major
release, breaking change, deprecation, end-of-life (EOL), sunset, migration,
upgrade path, backward compatibility, forward compatibility, downtime,
maintenance window, zero-downtime deployment, graceful shutdown, drain, scale up,
scale down, scale out, scale in, autoscaling, horizontal scaling, vertical
scaling, incident, outage, service disruption, failover, disaster recovery,
backup, restore, point-in-time recovery, snapshot, retention policy, runbook
execution, playbook, on-call handoff, escalation, war room, status page, SLA
breach, SLO violation, error budget policy, change freeze, code freeze, release
train, sprint, iteration, milestone, roadmap, epic, user story, bug ticket,
triage, priority (P0, P1, P2, P3), severity (SEV0, SEV1, SEV2, SEV3), SL1-SL4,
service level objective, operational level agreement (OLA), underpinning
contract (UC), vendor management, procurement, onboarding, offboarding, access
revocation, audit log, compliance check, penetration test, vulnerability scan,
security patch, responsible disclosure, coordinated vulnerability disclosure
(CVD).
- STE: Initiate a hotfix: cherry-pick `fix/payment-null-pointer` onto
  `release/v3.2`, trigger `deploy-hotfix`, canary at 10% for 30 min before full
  rollout.

### 21. Licenses, compliance, regulatory and legal texts
License, open-source license, proprietary license, MIT License, Apache 2.0
License, GPLv3, LGPL, BSD, AGPL, MPL, Unlicense, Creative Commons, EULA, terms of
service (TOS), privacy policy, cookie policy, data processing agreement (DPA),
service level agreement (SLA), contributor license agreement (CLA), Developer
Certificate of Origin (DCO), copyright, trademark, patent, intellectual property,
attribution, copyleft, permissive license, compliance, regulatory compliance,
GDPR, CCPA, HIPAA, SOC 2, ISO 27001, PCI DSS, FedRAMP, FISMA, export control, EAR,
ITAR, sanctions list, embargo, data residency, data sovereignty, data retention
policy, right to erasure, right to access, data subject request (DSR), personal
data, PII, PHI, sensitive data, data classification, data handling policy,
acceptable use policy, code of conduct, vendor risk assessment, security
questionnaire (CAIQ, SIG), audit report, attestation, SOC report, penetration
test report, vulnerability disclosure policy, bug bounty program terms,
responsible disclosure policy, indemnification, limitation of liability, warranty
disclaimer, governing law, jurisdiction, severability, force majeure, assignment,
termination, survival clause, third-party notice, open-source attribution,
NOTICE file, SBOM.
- STE: The `request@2.88.2` package has a missing license field — replace with
  `node-fetch@3.3.2` (MIT). Validate with `npx license-checker --onlyAllow
  "MIT;Apache-2.0;ISC;BSD-2-Clause;BSD-3-Clause"`.

### 22. Test fixtures, mock data, sample datasets, placeholders
Test fixture, mock object, stub, spy, fake, dummy, test double, seed data, sample
data, example record, placeholder, synthetic data, faker data, lorem ipsum,
"John Doe", "Jane Smith", "Acme Corp", "example.com", "test@example.com",
"user_12345", "order_abc", "00000000-0000-0000-0000-000000000000", "foo", "bar",
"baz", "qux", "quux", "spam", "eggs", "ham", "hello world", "TODO", "FIXME",
"HACK", "XXX", "WIP", "tmp", "scratch", "sandbox", "playground", "hello-world-app",
"my-first-repo", "boilerplate", "starter-kit", "todo-mvc", "hello-kubernetes",
"nginx-hello", "FakeUser", "MockOrderRepository", "StubPaymentGateway",
"InMemoryDatabase", "NullLogger", "noop", `TestUserFactory.create()`,
`Fixtures.defaultUser()`, `faker.internet.email()`.
- STE: The `OrderService` test uses `Fixtures.defaultOrder()` and a
  `MockPaymentGateway` stub that returns `PaymentResult.SUCCESS` without real
  HTTP calls.

## Related rules — unapproved words, synonyms, technical-noun use

### Rule 1.6 — Use an unapproved word only as a technical noun
Use a word that is not approved in the standard documentation vocabulary only
when it is a technical noun (classified in one of the 19 categories) or part of a
technical noun.

| Non-STE | STE |
|---------|-----|
| The `base` class holds shared logic for all the page objects. | The `BasePage` class (technical noun, Category 1: API and library components) holds shared logic for all `PageObject` subclasses. |
| ("base" is ambiguous — common word or class name?) | (`BasePage` is a classified technical noun — intentional, project-specific identifier.) |

### Rule 1.7 — Do not verb technical nouns
Do not use words that are technical nouns as verbs in code documentation.

| Non-STE | STE |
|---------|-----|
| `docker` the container and `curl` the endpoint to verify it. | Build the `Docker` image (Category 5: Hosting, CI/CD) and send a request to the endpoint using `curl` (Category 3: Development tools). |

### Rule 1.8 — Use approved technical nouns
Use technical nouns that are approved in your project glossary, organization
style guide, or ecosystem conventions.

| Non-STE | STE |
|---------|-----|
| The `data fetcher thing` in the `store layer` gets records from the `DB`. | The `Repository` pattern implementation (`UserRepository`) in the `data` layer fetches `User` entities from `PostgreSQL` via `TypeORM`. |

### Rule 1.9 — Keep technical nouns short
When you must select a technical noun for code documentation, use one which is
short (not more than three words) and easy to understand.

| Non-STE | STE |
|---------|-----|
| Call the `asynchronous JavaScript Object Notation web token-based user authentication and authorization pre-validation middleware handler`. | Call the `JWT auth middleware`. |

### Rule 1.10 — No slang, regional, or jargon technical nouns
Do not use team-internal slang, regional programming jargon, or company-specific
nicknames as technical nouns in public-facing documentation.

| Non-STE | STE |
|---------|-----|
| The `magic button` on the `admin doodad page` sends a `zap` to the `thingamajig service`. | The `"Sync All"` button on the `Admin Dashboard` sends a `POST` request to the `DataSyncService`. |

### Rule 1.11 — One technical noun per entity
Do not use different technical nouns for the same software entity across your
documentation.

| Non-STE | STE |
|---------|-----|
| Step 1: Call the `UserFetcher` service. Step 2: Configure the `AccountRetriever` module. Step 3: Restart the `ProfileLoader` microservice. | Step 1: Call the `UserService`. Step 2: Configure the `UserService`. Step 3: Restart the `UserService` microservice. |

## Closing notes

- The terms listed in each category are **examples only**. Rule 1.5 does not
  give a full list of all possible technical nouns for code documentation.
- Listed terms use backtick formatting (`LikeThis`) only when the term is a
  literal identifier, API name, or exact string value from code — for example,
  class names, function names, environment variable names, and error message
  strings.
- Add project-specific technical nouns to your project glossary or terminology
  database; they then qualify as approved technical nouns under these categories.

## Quick reference for LLM code-doc generation

1. If the word is in the approved-words dictionary, use it as written.
2. If the word is not in the dictionary, check whether it fits a technical-noun
   category (1–22). If yes, you may use it — preferably verbatim as an
   identifier (`ClassName`) when it is a literal code name.
3. Never verb a technical noun (Rule 1.7); never use slang nicknames for
   public docs (Rule 1.10); never invent multiple names for one entity
   (Rule 1.11).
4. Keep added technical nouns short (≤ 3 words) and consistent with the project
   glossary (Rules 1.9, 1.8, 1.11).






## 03-dictionary.md

## Dictionary excerpt (approved / unapproved)

# STE-Code Adapted Dictionary A-Z

> **Source:** Adapted from ASD-STE100 Issue 9, Part 2 - Dictionary, Pages 149-434
> **Source file:** ste-code/merged/master.md (lines 5591-10976)
> **Generated:** 2026-07-30
> **Domain adaptation:** aerospace → code documentation (API docs, commit messages, README sections, code comments)
> **Preserved:** word alphabetization, STE/non-STE pair format, approved/unapproved status, parts of speech
> **Replaced:** aerospace examples with code examples
> **Approved words:** ~875 (UPPERCASE) | **Unapproved words:** ~1274 (lowercase + UNNAPROVED)

---

## How to Read This Dictionary

- **UPPERCASE words** are approved in STE-Code.
- **lowercase words** are not approved; use the listed alternatives instead.
- **(v)** = verb, **(n)** = noun, **(adj)** = adjective, **(adv)** = adverb, **(prep)** = preposition, **(conj)** = conjunction, **(pron)** = pronoun, **(art)** = article
- **(TN)** = code-domain Technical Noun, **(TV)** = code-domain Technical Verb
- Each entry shows: original rule text → code-domain rewrite → STE/non-STE code example pairs

---

# A

## A (art)
- **Original:** Function word: indefinite article. A FUEL PUMP IS INSTALLED IN ZONE 10.
- **Code-domain:** Function word: indefinite article. A CONFIG FILE IS INCLUDED IN THE ROOT DIRECTORY.
> **STE:** A config file is included in the root directory.
> **Non-STE:** Config files included in root directory.

*Ref: master.md - Dictionary entry A (art), Page 149*

---

## ABANDON (v) - UNNAPROVED
- **Original:** GO (v), STOP (v). IF THERE IS A FIRE, IMMEDIATELY GO TO A SAFE AREA. / IF THE VALUES ARE INCORRECT, STOP THE TEST PROCEDURE.
- **Code-domain:** TERMINATE (v), STOP (v). IF THE BUILD FAILS, STOP THE DEPLOYMENT PIPELINE. / IF THE VALUES ARE INCORRECT, TERMINATE THE TEST RUN.
> **STE:** If the build fails, stop the deployment pipeline.
> **Non-STE:** If the build fails, abandon the deployment pipeline.

> **STE:** If the values are incorrect, terminate the test run.
> **Non-STE:** If the values are incorrect, abandon the test procedure.

*Ref: master.md - Dictionary entry abandon (v), Page 149*

---

## ABILITY (n) - UNNAPROVED
- **Original:** CAN (v). ONE GENERATOR CAN SUPPLY POWER FOR ALL THE SYSTEMS.
- **Code-domain:** CAN (v). ONE CONFIGURATION CAN HANDLE REQUESTS FOR ALL THE ENDPOINTS.
> **STE:** One configuration can handle requests for all the endpoints.
> **Non-STE:** One configuration has the ability to handle requests for all the endpoints.

*Ref: master.md



## 04-templates.md

# Level 3 — Document Templates (All Code-Documentation Types)

This slice gives ready-to-fill templates for the document types where STE-Code
matters most in daily engineering work, and the rules that govern how a sentence
in any of them is built. It pairs with `01-principles.md` (words) and
`03-dictionary.md` (terminology).

Level 1 gave the word-level gate (Rules 1.1–1.14). Level 2 applied it to review
and pull-request text. Level 3 widens the lens to **every** code-documentation
type and states the governing sentence-level rules directly so an LLM can apply
them without cross-referencing the full standard.

Every template below follows the same three constraints:

1. **Word gate** — each word you add passes one of: approved in the controlled
   terminology (the STE-Code dictionary), a code-domain technical noun (Rule 1.5,
   19 categories), or a code-domain technical verb (Rule 1.12).
2. **Imperative action** — every instruction line starts with a base verb, no
   "must", no modal verb, no passive voice (Rule 5.3).
3. **One technical noun per item** — name the same symbol the same way every
   time, in backticks, uninflected (Rules 1.5, 1.11).

---

## Governing rules

These four sentence-level rules apply to every template in this slice. Read them
once; apply them everywhere.

### Rule 5.3 — Imperative (command) form for instructions

Write every instruction in the imperative (command) form: start with a base verb,
omit the subject "you" (implied), and give a direct instruction.

- Do **not** use passive voice ("The tests are run by CI"), gerunds
  ("Running the tests…"), or modal verbs ("can", "could", "should", "may",
  "might", "would").
- Do **not** put "must" before the imperative in a standard instruction. Reserve
  "must" for WARNING / CAUTION blocks (security, data loss, safety). Example:
  "WARNING: IF YOU MUST DELETE THE DATABASE, FIRST MAKE A BACKUP."
- Use the base verb for the action: "Set the port to 8080", not "The port should
  be set to 8080".

Document-type boundaries:

- **README** — use the imperative only for procedural sections (install,
  configure, build, quick-start). Descriptive sections (project goals, feature
  lists, architecture summary) may use declarative sentences.
- **API docs** — endpoint descriptions are descriptive ("Returns a list of
  users"); the imperative applies to setup, auth walkthroughs, and "getting
  started" steps. Example request blocks are inherently imperative.
- **Docstrings / inline comments** — describe behavior, don't command the
  reader ("This function returns the profile for the user ID", not "Return the
  profile"). Exception: shell-script headers and Makefile target comments, which
  the reader executes.
- **Commit messages** — the subject line is imperative and completes "If
  applied, this commit will…": "Fix the race condition", not "Fixed the race
  condition". The body may use descriptive sentences.
- **Error messages** — describe what failed, then give a recovery instruction,
  separated by a period or newline: "The port 8080 is already in use. Set a
  different port with the `--port` option."

> **Non-STE:** The test suite can be executed with `npm test`.
> **STE:** Run the unit tests with `npm test`.

> **Non-STE:** Before you delete the branch, you must push all local commits.
> **STE:** Before you delete the branch, push all local commits to the remote.

### Rule 5.4 — Descriptive statement before the command

When the reader must know a condition before they act, write it as a descriptive
statement, then a **comma**, then the imperative command. The comma is required:
its position determines which verb an adverb modifies.

> **STE:** If the connection pool is full, reject the request.
> (comma after "full" → "reject" is the command)
> **STE:** If the connection pool is full automatically, reject the request.
> (comma after "automatically" → the pool fills on its own)

- Keep one condition per sentence. For multi-step procedures, write each
  condition–command pair as a separate step.
- Apply inside every template that has a "condition then action" shape (T2
  `Result` → `Required change`, T4 `Scope` sets the condition, T5 `How` steps).

> **Non-STE:** Run the database migration after you set `DATABASE_URL` and
> confirmed the server accepts connections.
> **STE:** After you set the `DATABASE_URL` variable, run the database migration.

### Rule 3.6 — Active voice

Use the active voice in all code documentation. The subject does the action.
Passive voice is permitted in descriptive writing **only** when the agent (the
person, service, or component that does the action) is unknown.

Test: ask "by whom or by what?" If the sentence answers that question, it is
passive — convert by making the agent the subject.

- **Passive:** The circuits are connected by a switching relay.
- **Active:** A switching relay connects the circuits.
- **Passive (agent unknown, allowed):** During transmission, the data was
  corrupted.

### Rule 9.4 — Consistent style

When you select terminology or wording, use the same style every time the same
type of step occurs. Three dimensions, each audited independently:

- **Lexical** — one term per concept ("config file", never "settings file" /
  "config" / "config file" alternating).
- **Syntactic** — same grammatical template for the same action type ("Install
  the package to add the CLI tool"; don't switch some steps to passive or
  conditional).
- **Semantic** — a term keeps the same meaning across every file, module, and
  doc type ("build" means the same thing in the README as in the CI docs).

Apply per doc type:

- **README** — one word for the project artifact ("library", not "package" in
  paragraph 3).
- **API docs** — an endpoint/parameter has exactly one name across all
  references; map prose to the schema by name.
- **Docstrings** — use the same term as the function signature (parameter
  `max_retries`, not "maximum attempts").
- **Commit messages** — same imperative verb for the same category of change
  across the project ("Add", never "Introduce"/"Insert"/"Create" mixed in).
- **Error messages** — one error code produces the same text every time;
  operators search logs by message.
- **CLI / help text** — a flag's description matches in `--help`, man pages,
  docs, and error messages.

```markdown
## Non-STE (inconsistent)
1. Open the configuration file in a text editor.
2. Change the port number in the settings file.
3. Save the config and close it.
4. Compile the project with the build command.
5. Make the binary for the target platform.

## STE (consistent)
1. Open the configuration file in a text editor.
2. Change the port number in the configuration file.
3. Save the configuration file and close it.
4. Build the project with the build command.
5. Build the binary for the target platform.
```

### Rule 1.5 grammar — technical nouns in running text

Identifiers, file paths, type names, commands, and status codes are code-domain
technical nouns. Apply this grammar whenever one appears in template prose:

- **Backticks, no inflection.** Write `getUser`, `null`, `OrderService`. Not
  "the `getUser`s" or "two `null`s". Acronym plurals: `APIs`, not `API's`.
- **One name per item (Rule 1.11).** Name a symbol the same way in one thread:
  `getUser`, not "the getter", then "that helper".
- **Articles.** "the" for a specific instance, "a"/"an" for an indefinite one,
  no article for a plural general reference: "The `UserController` handles a
  request. Pods run in a namespace."
- **Possessive only for roles/orgs (category 11).** "the user's session data"
  but "the configuration of the `Docker` container", not "the `Docker`
  container's configuration".
- **Capitalization.** Proper nouns keep theirs (`TypeScript`, `PostgreSQL`);
  common technical nouns are lowercase unless first word (`controller`,
  `endpoint`, `middleware`).
- **Quoted keywords and status codes (category 10).** `if`, `return`, `class`
  and codes like `404 Not Found`, `500` are quoted text: "Return `500 Internal
  Server Error`", not a bare "500".

---

## Template selection

| Situation | Template |
|-----------|----------|
| One line or one hunk in a diff | T1 — Inline review comment |
| A defect the author must fix before merge | T2 — Blocking review finding |
| An optional improvement | T3 — Non-blocking suggestion |
| Summary on the whole pull request | T4 — PR review summary |
| PR description the author writes | T5 — PR description |
| Reply to review feedback | T6 — Author response |
| Setup / install / build steps | T7 — README procedure |
| API endpoint reference entry | T8 — API doc entry |
| Function / method docstring | T9 — Docstring |
| A completed change | T10 — Commit message |
| A runtime failure the user sees | T11 — Error message |

---

## T1 — Inline review comment

```text
<observation>: one sentence, one subject, present tense.
<effect>: one sentence that gives the result of the observation.
<action>: one imperative sentence.
```

> The `getUser` function returns `undefined` when `id` is `0`.
> The caller in `UserController` then reads a property of `undefined`.
> Return `null` for an unknown `id`, and check the result in `UserController`.

Constraints: imperative action (Rule 5.3); one technical noun per item (Rule
1.11); no technical noun as a verb (Rule 1.7): "Send a request to the `/users`
endpoint", not "Endpoint the request"; identifiers in backticks, uninflected.

## T2 — Blocking review finding

```text
**Finding:** <one sentence: what is wrong>
**Location:** `<path>:<line>` in `<symbol>`
**Cause:** <one sentence>
**Result:** <one sentence: what fails, and when>
**Required change:** <one imperative sentence>
```

> **Finding:** The `saveOrder` method does not validate the `quantity` field.
> **Location:** `src/orders/service.ts:142` in `OrderService.saveOrder`
> **Cause:** The method writes the request body to the database with no check.
> **Result:** A negative `quantity` value is written to the `orders` table.
> **Required change:** Reject a request when `quantity` is less than `1`.

Write the change as one imperative sentence. Do not use "must" as an intensifier
— the field label gives the obligation. `Location` names each item with one
technical noun (Rule 1.11).

## T3 — Non-blocking suggestion

```text
**Suggestion (optional):** <one imperative sentence>
**Reason:** <one sentence>
```

> **Suggestion (optional):** Move the three retry constants into `RetryPolicy`.
> **Reason:** The same three values occur in `HttpClient` and in `QueueWorker`.

Mark optional in the first word. One imperative sentence. No hedge words
("maybe", "perhaps", "just") — Rule 1.10.

## T4 — PR review summary

```text
**Decision:** Approve | Request changes | Comment
**Scope:** <one sentence: what the pull request changes>
**Blocking findings:** <count>
1. <one sentence each, with `path:line`>
**Optional suggestions:** <count>
1. <one sentence each>
**Verification:** <one sentence: what you ran or read>
```

> **Decision:** Request changes
> **Scope:** The pull request adds a rate limiter to the `/api/v1/login` route.
> **Blocking findings:** 1
> 1. `src/middleware/rateLimit.ts:58` — The limiter counts a failed request and a successful request in the same bucket.
> **Optional suggestions:** 1
> 1. Give the `WINDOW_MS` constant a unit in its name.
> **Verification:** I ran `npm test` and read the diff in `src/middleware`.

Decision is one of the three approved values — no fourth, no sentence. Each
finding line is one sentence naming its item with one technical noun (Rule 1.11).

## T5 — PR description (author)

```text
## What
<one to three sentences. One subject in each sentence.>

## Why
<one to three sentences. Give the cause, then the result.>

## How
1. <imperative sentence>
2. <imperative sentence>

## Test
- <one sentence per check, with the command in backticks>

## Risk
<one sentence. Write "None." when there is no risk.>
```

> ## What
> This pull request adds a retry to the `PaymentClient.charge` method.
> ## Why
> The payment gateway returns `503` during a deployment. The current client fails
> the order on the first `503` response.
> ## How
> 1. Add a `RetryPolicy` class with three attempts and an exponential delay.
> 2. Call `RetryPolicy.execute` from `PaymentClient.charge`.
> ## Test
> - Run `npm test -- payment` to check the new unit tests.
> - Send a request to the sandbox gateway to check the delay values.
> ## Risk
> A retry can create a duplicate charge if the gateway accepted the first
> request. The client sends an idempotency key to prevent this result.

`How` steps are all imperative (Rule 5.3). `What` and `Why` are descriptive but
still use one technical noun per item (Rule 1.11) and approved words only.

## T6 — Author response to feedback

```text
**Comment:** <link or `path:line`>
**Response:** Done | Changed | Not changed
**Detail:** <one sentence>
```

> **Comment:** `src/middleware/rateLimit.ts:58`
> **Response:** Changed
> **Detail:** The limiter now counts only a failed request in the login bucket.

One of the three approved values. No "LGTM", "nit", "wontfix", or other jargon
(Rule 1.10). `Comment` gives the item in backticks with one name each time.

## T7 — README procedure (install / configure / build)

Use the imperative only for the procedural steps. Keep one condition–command pair
per step (Rule 5.4). Name the same file, command, and variable identically across
all steps (Rule 9.4).

```text
## Setup

Clone the repository.
Install the dependencies with `npm install`.
Set the `DATABASE_URL` environment variable in `.env`.
After the dependencies install without errors, run the development server with `npm run dev`.
```

> **Non-STE:** First you need to have Node.js version 18 or higher installed then
> run `npm install` and after all dependencies finish downloading if there are no
> errors you can run `npm run build`…
> **STE:** Make sure that Node.js version 18 or higher is installed. Run `npm
> install`. After the dependencies install without errors, run `npm run build`.

Descriptive README sections (About, Features, Architecture) use declarative
sentences — they do not instruct the reader to act.

## T8 — API doc entry (endpoint reference)

Endpoint behavior is descriptive ("Returns a list of users"). The imperative
applies to setup, auth walkthroughs, and "getting started" steps. State the
condition that triggers an error before you describe the response (Rule 5.4).

```text
### GET /users

Gets the list of users.

Request:
GET /users HTTP/1.1
Authorization: Bearer <token>

Response:
200 OK — a JSON array of user records.

Errors:
If the client sends more than 100 requests per minute, the API returns a
`429 Too Many Requests` status code. The response includes a `Retry-After`
header that shows the wait time.
```

> **Non-STE:** You can authenticate by sending a POST request to `/auth/login`
> with your credentials, and you should include the returned token in the
> Authorization header.
> **STE:** Send a POST request to `/auth/login` with your credentials. Include
> the returned token in the `Authorization` header.

## T9 — Docstring (function / method)

Describe what the code does, in the active voice (Rule 3.6), not what the reader
must do. State preconditions before behavior (Rule 5.4). Use the same term as the
function signature (Rule 9.4).

```python
def get_profile(user_id: int) -> Profile:
    """Return the profile data for the given user ID.

    Query the database for the row that matches `user_id` and return
    a Profile object. If the user does not exist, raise ValueError.
    """
    return db.query(Profile).filter_by(id=user_id).one()
```

> **Non-STE:** Gets a user record. The duration in milliseconds the client shall
> await a response prior to terminating the connection attempt.
> **STE:** Gets a user record. The time in milliseconds that the client waits for
> a response before it stops the connection.

## T10 — Commit message

Subject line is imperative and completes "If applied, this commit will…"
(Rule 5.3). The body may use descriptive sentences for rationale. Use one
imperative verb for the same category of change across the project (Rule 9.4).

```text
Fix the race condition in the connection pool

The pool returned the same connection to two threads under load.
Add a lock around the checkout path so each thread gets a unique
connection. The retry test in tests/test_pool.py now passes.
```

> **Non-STE:** Fixed the race condition in the connection pool.
> **STE:** Fix the race condition in the connection pool.

> **Non-STE:** When the connection pool reaches max connections, add a mutex lock
> around pool access to prevent a race condition.
> **STE:** When the connection pool reaches its maximum capacity, add a mutex
> lock around pool access to prevent a race condition. (condition before command,
> comma after the clause — Rule 5.4)

## T11 — Error message

Describe what failed, then give a recovery instruction, separated by a period or
newline. Do not use the imperative unless you also tell the user how to recover
(Rule 5.3). One error code produces the same text every time (Rule 9.4).

```python
raise RuntimeError(
    "The port 8080 is already in use. "
    "Set a different port with the --port option."
)
```

> **Non-STE:** Port is already in use.
> **STE:** The port 8080 is already in use. Set a different port with the
> `--port` option.

> **Non-STE:** Invalid configuration file. Check the schema.
> **STE:** The configuration file failed schema validation. Check the
> `config.schema.json` file for required fields.

---

## Approved verbs for action lines

Use these code-domain technical verbs in the imperative line of any template. Use
the base form for an instruction (Rule 5.3) and the third-person form for a
statement of fact.

| Verb | Use it for |
|------|-----------|
| add | New code, a new field, a new file |
| remove | Deleted code or a deleted field |
| replace | One item exchanged for another |
| move | Code relocated with no change in behavior |
| rename | A new name for the same item |
| return | The value a function gives back |
| throw / raise | An error the code emits |
| catch / handle | An error the code accepts |
| validate | A check on input |
| reject | A refused input or request |
| call | Invocation of a function or method |
| read / write | Access to a file, field, or record |
| log | A record written to the audit trail or log |
| test | A check that runs in the test suite |

Do not use a verb from this table as a noun (Rule 1.13): "The function returns a
value", not "The return of the function".

## Forbidden words in template prose

| Forbidden | Reason | Use instead |
|-----------|--------|-------------|
| nit, LGTM, WIP, PTAL, IMO | jargon (Rule 1.10) | the full template label |
| smelly, hacky, ugly, clean | subjective, not approved (Rule 1.1) | the concrete defect |
| stuff, thing, some code | not a technical noun (Rule 1.5) | the identifier in backticks |
| leverage, utilize | not approved (Rule 1.3) | use |
| behaviour, initialise, colour | British spelling (Rule 1.14) | behavior, initialize, color |
| we should maybe possibly | hedging (Rule 1.1) | one imperative sentence |
| delete (verb) | not approved (Rule 1.1) | remove |
| execute (verb) | not approved (Rule 1.1) | run |
| compile (verb) | not approved (Rule 1.1) | build |

## Checklist before you publish

1. Each sentence has one subject.
2. Each item has one name, used every time (Rule 1.11).
3. Each identifier is in backticks and is not inflected.
4. Each action is one imperative sentence (Rule 5.3).
5. Each condition comes before its command, separated by a comma (Rule 5.4).
6. Voice is active; passive appears only when the agent is unknown (Rule 3.6).
7. Terminology is consistent across the document and the project (Rule 9.4).
8. No word from the forbidden table is present.
9. Spelling is American English (Rule 1.14).

---

## Dictionary excerpt — instruction and template words

A focused slice of the STE-Code controlled terminology (full list in
`03-dictionary.md`). UPPERCASE = approved; lowercase = not approved, use the
listed alternative. Parts of speech: (v) verb, (n) noun, (adj) adjective,
(conj) conjunction, (TN/TV) code-domain technical noun/verb.

| Word | PoS | Approved? | STE example | Non-STE to replace |
|------|-----|-----------|-------------|--------------------|
| ADD | (v) | ✓ | Add 5 lines of configuration to the file. | Append 5 lines of configuration to the file. |
| AFTER | (conj) | ✓ | After you deploy the update, do a smoke test. | Following deployment of the update, do a smoke test. |
| BEFORE | (conj) | ✓ | Before you run the migration, read the release notes. | Prior to running the migration, read the release notes. |
| CHECK | (n) | ✓ | Do a check of the input values. | Validate the input values. |
| CHECK | (v) | ✗ | Do a check of the values. / Verify the data integrity. | Check the values. |
| CLICK | (v) (TV) | ✓ | Click the "Submit" button. | Press the "Submit" button. |
| CREATE | (v) | ✓ | Create a new instance of the class. | Instantiate a new object of the class. |
| DELETE | (v) | ✗ | Remove the file from the directory. | Delete the file from the directory. |
| IF | (conj) | ✓ | If the status code is 500, retry the request. | In the event of a 500 status code, retry the request. |
| INSTALL | (v) | ✓ | Install the package with npm. | Set up the package with npm. |
| MAKE | (v) | ✓ | Make a copy of the file. | Create a copy of the file. |
| OPEN | (v) | ✓ | Open the file for reading. | Read the file. |
| REMOVE | (v) | ✓ | Remove the deprecated function. | Delete the deprecated function. |
| REPLACE | (v) | ✓ | Replace the old library with the new one. | Swap the old library for the new one. |
| RUN | (v) | ✓ | Run the script from the terminal. | Execute the script from the terminal. |
| SAVE | (v) | ✓ | Save the file to disk. | Write the file to disk. |
| SELECT | (v) | ✓ | Select the database from the list. | Choose the database from the list. |
| SET | (v) | ✓ | Set the variable to 10. | Assign 10 to the variable. |
| TYPE | (n) (TN) | ✓ | The type of the variable is string. | The variable is a string. |
| USE | (v) | ✓ | Use the API to fetch data. | Utilize the API to fetch data. |
| WHEN | (conj) | ✓ | When the build finishes, deploy the artifact. | After the build finishes, deploy the artifact. |

Key mapping notes for template authors:

- **execute → run**, **compile → build**, **delete → remove**, **create → make**,
  **instantiate → create**, **assign → set**, **utilize/leverage → use**,
  **press (UI) → click**, **choose → select**, **swap → replace**, **validate
  (verb) → do a check / verify**, **write (file) → save**.
- Prepositions **IF / WHEN / AFTER / BEFORE** are approved for condition and
  sequence clauses (Rule 5.4). Keep the comma between the clause and the command.
- **CHECK** is approved as a noun with "do a check of"; do not use it as a verb.
- **TYPE** is a technical noun for a data type; do not use it as a verb
  ("type the command" → "enter the command").



## 05-grammar.md

# Level 3 — Grammar

Grammar layer of STE-Code: the parts of the standard that constrain **form** —
word class, verb form, sentence shape, punctuation, and word count.
Vocabulary (which words you may use) is in `03-dictionary.md`; this file is
about how approved words are combined.

Scope: all code documentation — README files, API reference, docstrings, inline
comments, commit messages, error and log messages, changelogs, configuration
comments, specifications. Source code itself and the contents of fenced code
blocks are **out of scope**.

## Quick contract for a generator

| Constraint | Value |
|---|---|
| Approved verb forms | infinitive, imperative, simple present, simple past, simple future, past participle **as adjective only** |
| Forbidden verb forms | perfect, progressive, perfect-progressive, gerund-as-verb, auxiliary + past participle |
| Voice | active; passive only in descriptive text when the agent is unknown |
| Procedural sentence | max 20 words |
| Descriptive sentence / note | max 25 words |
| Instructions per sentence | 1 |
| Topics per sentence | 1 |
| Sentences per paragraph | max 6, one topic per paragraph |
| Technical noun length | max 3 words |
| Semicolon | forbidden — split into two sentences |
| Contractions | forbidden — write words in full |
| Phrasal verbs | forbidden unless explicitly approved |
| Articles | required before nouns; omitted before identifiers and abstract concepts |

## 1 — Words and parts of speech

**1.1 Use approved words only.** A word is usable if it is approved in the
controlled terminology, or is a code-domain technical noun, or is a code-domain
technical verb. Nothing else.

**1.2 Use an approved word only as its approved part of speech.** The
dictionary fixes the class. `TEST (n)` is not a licence to write "test the
build" unless `TEST (v)` is also approved.

**1.3 Use an approved word only with its approved meaning.** Approved words
normally carry exactly one meaning. Other standard-English senses are excluded.

**1.4 Use only the approved forms of verbs and adjectives.** See section 3.

**1.5 Technical nouns may be added by category.** A code-domain technical noun
names a specified software concept in a subject field (codebase, framework,
ecosystem). The controlled terminology cannot list them all; add them to the
project glossary, API reference, or ADRs, and only inside an approved category.

**1.6 An unapproved word is permitted only when it is (or is part of) a
code-domain technical noun.** Never as ordinary prose.

**1.7 Do not use technical nouns as verbs.**

> Do not write: The service *databases* the record.
>
> Write: The service writes the record to the database.

**1.8 Prefer technical nouns already approved in your project, company,
industry, or subject field** over invented ones.

**1.9 When you must coin a technical noun, make it short and clear** — not more
than three words. Add one or two adjectives only when the context does not
disambiguate.

> Do not write: Delete the four deprecated middleware registration statement entries that bind the request route to the legacy cover module.
>
> Write: Delete the four handler entries (lines 10–14) that bind the route to the cover module.

**1.10 Do not use regional words, slang, or jargon as technical nouns.**

**1.11 Do not use different technical nouns for the same item.** One item, one
name. Do not alternate `configuration file`, `settings file`, and `config`.

**1.12 Technical verbs may be added by category.** A code-domain technical verb
names a specified operation or process in software development.

**1.13 Do not use technical verbs as nouns.**

> Do not write: Run a *deploy* of the service.
>
> Write: Deploy the service.

**1.14 Use American English spelling** unless a project specification, style
guide, or contract directs otherwise. Do not change the spelling of quoted
text — error strings and UI labels stay verbatim.

### Approved technical verb categories

| Category | Verbs |
|---|---|
| Development operations | build, compile, test, lint, format, commit, push, deploy, rollback |
| Data operations | read, write, serialize, deserialize, parse, encode, decode, query, insert, migrate |
| Application operations | handle, route, authenticate, authorize, validate, schedule, dispatch, resolve |
| Communication actions | send, receive, publish, subscribe, stream, poll, broadcast, connect |

Prefer the plain approved verb — use, start, stop, show, make, get, set, check,
do, send, remove, keep — over *utilize*, *leverage*, *employ*, *commence*,
*terminate*, *initiate* when the simple verb already carries the meaning.

## 2 — Noun phrases

**2.1 Keep technical nouns short** — maximum three words. Split longer strings
with prepositions (of, on, in, for, to).

> Do not write: Request handler timeout retry policy value.
>
> Write: The retry policy for the timeout of the request handler.

**2.2 Write a long technical noun in full**, then make it usable by one of:

- Give a shorter form after the first full occurrence.
- Hyphenate the words that act as one unit.
- Split the noun with prepositions.

A term that comes from an official source (an API specification, a schema, an
OpenAPI file, an architecture diagram) is written in full at first occurrence,
explained, and then abbreviated for the rest of the document. Terms fixed by
your framework or subject field stay as they are.

**2.3 Use hyphens between words used as one unit.** See Rule 8.2 for the five
hyphenation categories and Rule 8.7 for their word count.

## 3 — Verbs

**3.1 Use only the verb forms that the dictionary gives.** Every approved verb
lists four forms in this order: base, third-person singular, simple past, past
participle.

```
VALIDATE (v)
VALIDATES
VALIDATED,
VALIDATED

BUILD (v)
BUILDS
BUILT,
BUILT
```

**3.2 Use only these forms and tenses.**

| Verb | Imperative | Simple present | Simple past | Simple future | Past participle (adjective) |
|---|---|---|---|---|---|
| (to) parse | Parse the file | It parses | It parsed | It will parse | the parsed file |
| (to) write | Write the log | It writes | It wrote | It will write | the written log |
| (to) build | Build the image | It builds | It built | It will build | the built artifact |
| (to) send | Send the request | It sends | It sent | It will send | the sent request |
| (to) validate | Validate the token | It validates | It validated | It will validate | the validated token |

Not approved: present perfect (has parsed), past perfect (had parsed),
progressive (is/was parsing), future progressive (will be parsing), perfect
progressive (has been parsing), gerund used as a verb (keeps parsing), and all
other complex constructions.

Selection:

1. Infinitive after a modal or to state a purpose — "Use this flag to parse the file."
2. Imperative for each procedure step — "Parse the file. Write the log."
3. Simple present for a fact or system behavior — "The parser reads the file."
4. Simple past for a completed action — "The build failed."
5. Simple future with `will` + base form — "The job will start at 02:00."
6. Past participle only as an adjective before a noun — "the deprecated method."

Repairs:

| Unapproved | Approved |
|---|---|
| has parsed | parsed |
| had parsed | simple past, split into two sentences with "Then" |
| is parsing / was parsing | simple present or simple past |
| will be parsing | will parse |
| is being parsed | name the actor: "the worker parses the file" |

**3.3 Use the past participle as an adjective**, not as part of a verb.

**3.4 Do not use auxiliary verbs to build complex verb constructions.** Do not
combine have, be, will, can, must, should, or "is to be" with a past participle
to make compound tenses or the passive voice.

> Do not write: The build has compiled the module before the test runs.
>
> Write: The build compiled the module. Then the test runs.
> Do not write: The migration is to be run before you deploy the service.
>
> Write: Before you deploy the service, run the migration.
> Do not write: The cache can be cleared.
>
> Write: You can clear the cache.

**3.5 Use an "-ing" form only as a technical noun or as a modifier inside a
technical noun** — never as a verb. Approved "-ing" words include the nouns
logging, monitoring, routing, servicing; the adjectives matching, missing,
remaining; the pronoun something; and the preposition during. The progressive
tense is excluded because it is not in the Rule 3.2 list.

**3.6 Use the active voice.** In descriptive text the passive is permitted only
when the agent is unknown. Test a sentence by asking "by whom or by what?" — if
the sentence answers it, it is passive.

> Do not write: The API response is parsed by the middleware.
>
> Write: The middleware parses the API response.

**3.7 Describe an action with an approved verb, not a noun.**

> Do not write: Validation of the token happens in the handler.
>
> Write: The handler validates the token.

## 4 — Sentences

**4.1 One topic per sentence. No abstract text.** Do not combine multiple
actions, conditions, or subjects.

**4.2 Do not omit words and do not use contractions.** Keep the subject, the
verb, the nouns, and the articles. Write "do not", "is not", "are not" — never
"don't", "isn't", "aren't". A shorter sentence is not automatically clearer.

> Do not write: Can be a maximum of five inches long.
>
> Write: A cache key can have a maximum length of 64 characters.

**4.3 Use a vertical list for complex text.** Use a list when a sentence must
carry many items — parameters, return fields, error codes, configuration
options, environment variables, dependencies, test cases.

- Put a colon at the end of the introductory sentence.
- Mark each item with a number, letter, dash, or bullet.
- Start each item with an uppercase letter.
- Use an article before the subject noun of an item where applicable.
- End a full-sentence item with a period; an imperative step is a full sentence.
- Do not end a fragment item with a period, a comma, or a semicolon.
- Put a period at the end of the last item.

Do not mix imperative instructions and descriptive statements in one list. In
safety instructions, write the negative command (DO NOT) inside each item that
needs it.

**4.4 Use connecting words and connecting phrases.** Approved connectors:
`and`, `but`, `then`, `thus`, `also`, `however`, `therefore`, `for example`,
`as a result`, `at the same time`. Place the connector at the start of the
sentence so the reader sees the signal before the content. Do not use
*moreover*, *furthermore*, *nevertheless*, or *subsequently*. Demonstrative
adjectives (this, these) may also connect a sentence to the one before it.

**4.5 Use an article or a demonstrative adjective before a noun.**

- Use an article before each noun in a short sentence.
- In a series, use the article before the first noun only — unless an adjective
  applies to one item only, in which case repeat the article.
- Do not use an article before an abstract concept: performance, scalability,
  error handling, concurrency, backward compatibility.
- Do not use a definite article before a code identifier. A function, class,
  variable, file name, environment variable, error code, and version tag are
  proper nouns.
- Always keep the noun after `this` or `these`. Never write `this` alone.

## 5 — Procedures

**5.1 Maximum 20 words in a procedural sentence.** This covers installation
steps, setup guides, deployment checklists, debugging workflows, and API usage
guides. Warnings and cautions obey the same limit. Notes may reach 25 words.
Code blocks, command examples, terminal output, string literals, and identifier
names inside examples are excluded from the count.

> Do not write: Run the database migration script from the project root directory and then restart the application server to apply all pending schema changes to the production environment. (27 words)
>
> Write: Run the database migration script from the project root directory. Then restart the application server. (9 + 7 words)

**5.2 One instruction per sentence.** If a step contains two actions, write two
sentences or two numbered steps.

**5.3 Use the imperative form for instructions.** "Set the timeout value." Not
"The timeout value should be set."

**5.4 Put the descriptive statement before the command.** Give the condition
first, then the action, so the reader knows when the step applies.

**5.5 Notes give information only.** A note must not contain an instruction, a
command to run, a step, or an imperative verb. It must not give requirements,
limits, tolerances, or expected results of a step — that information belongs in
the step itself. Move anything critical for data loss, security, or system
damage into a WARNING or CAUTION. Each note sentence has a maximum of 25 words.

Verification: read the procedure without the notes. If the reader cannot
complete it, the missing information belongs in a step.

> NOTE: The API rate limiter allows a maximum of 1000 requests per minute per client IP address on the free tier.

## 6 — Text structure

**6.1 Give information gradually.** One subject per sentence. Do not pack a
request lifecycle, an error path, and a logging side effect into one sentence.

**6.2 Use key words and key phrases to give the text a logical structure.** Key
words repeat across a documentation block and link its concepts. Do not vary
them. Connecting words act as traffic signs: they tell the reader whether the
information is new, contrasting, or a result.

**6.3 Write short sentences — maximum 25 words in descriptive text.**
(Procedural text keeps the 20-word limit of Rule 5.1.)

**6.4 Use paragraphs to show related information.**

**6.5 One topic per paragraph.**

**6.6 Maximum six sentences per paragraph.**

## 7 — Safety instructions

**7.1 Use a signal word to show the level of risk.**

| Signal word | Use when | Release-note / changelog mapping |
|---|---|---|
| WARNING | Risk of security vulnerability, data loss, or system corruption | BREAKING |
| CAUTION | Risk of unexpected behavior, performance degradation, or incorrect results | DEPRECATED |
| NOTE | Supplementary information only | NOTE |

If both risk levels apply together, use WARNING.

**7.2 Start a safety instruction with a clear and accurate command or
condition.** If the reader must know a condition before using a function,
method, or API, give the condition first.

> Do not write: WARNING: STORING API KEYS IN THE SOURCE CODE IS NOT RECOMMENDED.
>
> Write: WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. USE ENVIRONMENT VARIABLES OR A SECRETS MANAGER.

**7.3 Explain the risk or the possible result.** A risk explanation has three
parts: the failure to obey the instruction, the immediate consequence, and the
final harm. Write it cause-first: "If you do X, Y can happen." An instruction
without a risk explanation is a prohibition the reader can dismiss.

> WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.

## 8 — Punctuation and word count

**8.1 Use all standard English punctuation except the semicolon.** The
semicolon lets you build long sentences that are hard to read in comments and
docs, and it is easy to misuse. Write two sentences instead. The rule does not
apply to source code or to text inside code blocks, where the semicolon is
language syntax.

> Do not write: Call the function to parse the response data; handle any errors that occur.
>
> Write: Call the function to parse the response data. Handle any errors that occur.

**8.2 Use hyphens to connect words that are directly related.** Five categories:

| Category | Code-domain examples |
|---|---|
| 1. Multi-word adjective before a noun | high-priority task, read-only file, thread-safe method, event-driven architecture, run-time error, end-to-end test, server-side rendering, just-in-time compilation |
| 2. Two-word fractions and numbers | seventy-two, one hundred and twenty-eight, three-fourths |
| 3. Uppercase letter or number plus a noun (shape or configuration) | L-shaped bracket, T-shaped connector, 64-bit register, 8-byte alignment, 128-bit value |
| 4. Verb whose first part is a noun or other part of speech | dry-run, hot-reload, cold-start, hard-code, soft-delete, short-circuit |
| 5. Prefix ending in a vowel before a root starting with a vowel | pre-initialized, re-entrant, de-allocated, anti-aliasing, re-indexed |

A hyphen joins words into one concept. A dash separates ideas or shows a range
("lines 12–48"). Keep them distinct.

**8.3 Use parentheses** to:

- Make references to code modules, diagrams, or text
- Include letters or numbers that identify items
- Identify the work steps in a procedure
- Include abbreviations
- Give the singular and plural forms of a noun at the same time
- Explain a word or part of a sentence
- Include an alternative.

**8.4 A colon in a vertical list counts as a period.** It marks the end of a
sentence. So the introductory part before the colon takes a maximum of 20 words
in procedural text and 25 words in descriptive text, and each item after the
colon counts as a new sentence with the same limits.

**8.5 Text in parentheses counts as one word** in the sentence that contains
it. The words inside the parentheses also form their own sentence, so count
them there. An identifier or an abbreviation in parentheses counts as one word.

> Write: Make sure that the DEBUG environment variable is set to false (the DEBUG flag is off). (12 words)

**8.6 Count each of these as one word:**

- Numbers
- Numbers together with units of measurement
- Abbreviations
- Alphanumeric identifiers
- Quoted text
- Titles, headings, and text on user interface elements and labels
- Proper nouns of individuals, groups, organizations, and geopolitical entities.

**8.7 A hyphenated word counts as one word.** A group of words hyphenated to act
as an adjective before a noun is one unit for the word-count limits.

> Do not write: The open function returns a read only file descriptor.
>
> Write: The open function returns a read-only file descriptor. ("read-only" = one word)

## 9 — Applying the standard

**9.1 Use a different sentence construction when a word-for-word replacement is
not sufficient.** When a word is unapproved, the dictionary gives alternatives.
Replace word-for-word only when the part of speech matches and the meaning does
not change. Rewrite the sentence when:

1. The grammatical structure must change to use the alternative.
2. The replacement gives a meaningless or unclear result.
3. The alternative changes the meaning.
4. The word to replace is not in the controlled terminology.

Then think about the purpose of the sentence: select different words, change
the verb form, write shorter sentences, remove unnecessary information, or ask
a developer for more information.

**9.2 Use each approved word correctly.** Read the approved meaning before you
use a word. Approved words normally have one approved meaning and one approved
part of speech. A small number are approved as more than one part of speech.

**9.3 Do not make phrasal verbs.** Two individually approved words can combine
into a phrasal verb whose meaning is different from its parts. Replace it with
a single approved verb. Only a few phrasal verbs are approved, and they have a
restricted meaning.

| Phrasal verb | Approved verb |
|---|---|
| put out (a warning) | emit |
| give off | release |
| carry out (a test) | do |
| shut down | stop |
| set up | configure |

> Do not write: The compiler puts out a warning when the type annotation is missing.
>
> Write: The compiler emits a warning when the type annotation is missing.

**9.4 Use a consistent style for terminology and wording.** The same type of
step gets the same wording every time. Use one name for one item (not
"configuration file", "settings file", and "config"). Use one verb for one
action (not "compile", "build", and "make"). Use the same sentence structure
for the same type of instruction.

> Do not write: Apply the patch to the main module. Wipe the module clean. Inspect the module assembly for errors.
>
> Write: Apply the patch to the module. Clean the module. Check the module for errors.




## rules-sec1-part1.md

# Level 3 — STE-Code Section 1 Rules, Part 1 (Words)

LLM-optimized distillation of the STE-Code controlled standard, Section 1 (Words).
This document covers the vocabulary-control rules for code documentation:
which words you may use, how to use them, and how to spell them.

Scope of this slice:
- Rule 1.1 — Approved words, technical nouns, technical verbs (the three-gate model)
- Rule 1.2 — Approved words only as their specified part of speech
- Rule 1.3 — Approved words only with their approved meanings
- Rule 1.4 — Only approved verb and adjective forms
- Rule 1.10 — No slang, jargon, or regional terms
- Rule 1.11 — One term per concept (consistency)
- Rule 1.12 — Technical verbs are allowed (category list)
- Rule 1.13 — Do not use technical verbs as nouns
- Rule 1.14 — American English spelling

It is self-contained: every rule below is stated plainly with code-domain examples.
For the full controlled terminology (dictionary) and the 19 technical-noun categories,
see `a-dictionary.md` and `a-categories.md` in the same artifact set.

## Principle legend (recurs in the examples)

These codes label the fix applied in each before/after pair:
- P1 — use an approved word from the controlled terminology
- P2 — use the approved part of speech
- P3 — use the approved meaning of the word
- P4 — use only approved verb/adjective forms (no "-ing" main verbs, correct tense/mood)
- P6 — quoted text (code, keywords, third-party output) is exempt and kept as-is
- P7 — do not use a technical noun as a verb
- P8 — use standard, well-known technical nouns
- P9 — prefer short, clear technical nouns
- P10 — no slang / jargon / metaphor
- P11 — one term per concept
- P12 — technical verbs allowed only when no approved verb fits
- P13 — do not use a technical verb as a noun
- P14 — American English spelling

---

## Rule 1.1 — Use Words That Are Approved in the Dictionary, Technical Nouns, or Technical Verbs

Every word in code documentation must pass one of three gates:

1. **Approved word** — listed in the STE-Code controlled terminology (Part 2), used with its
   specified part of speech (Rule 1.2) and approved meaning (Rule 1.3).
2. **Code-domain technical noun** — not in the terminology (or listed UNAPPROVED) but fits one
   of the 19 technical-noun categories (Rule 1.5). Names a specific concept, component, tool, or
   entity in software (e.g. `UserAuthenticator`, `Promise`, `kubectl`). A word that passes here
   must not be used as a verb (Rule 1.7).
3. **Code-domain technical verb** — not in the terminology but names a specific software operation
   (Rule 1.12), e.g. `serialize`, `refactor`, `lint`. A word that passes here must not be used as a
   noun (Rule 1.13).

A word that passes none of the three gates must be replaced with an approved alternative or the
sentence restructured.

Applies to all documentation types (README, API docs, docstrings, commit messages, error messages).
In each type, imperative verbs must come from the approved list.

Short substitutions to internalize:
- "execute" → `run` · "generate" → `make` · "configure" → `set` · "utilize/leverage" → `use`
- "retrieve/fetch" → `get` · "transmit" → `send` · "delete/purge" → `remove` · "verify" → `check`
- "unable to" → `cannot` · "invalid" → `not correct` · "commence/initiate" → `start` · "terminate" → `stop`
- "implement" → `make`/`add` (not approved as a verb) · "optimize" → `make faster`/`make smaller`

Example (README setup):
> Non-STE: To begin utilizing the build toolchain, you must first generate the distributable
> artifact via `npm run build`. Then, execute the compiled binary to bootstrap the local
> development service.
> STE: Use the build tool to make the binary. Run the binary to start the local service.

Example (API docstring):
> Non-STE: Fetches a user record from the remote API.
> STE: Gets a user record from the remote API.

See also: Rules 1.2–1.14, and `a-dictionary.md` / `a-categories.md`.

---

## Rule 1.2 — Use Approved Words Only as the Specified Part of Speech

Each approved word in the controlled terminology carries a part-of-speech label
(verb, noun, adjective, adverb, preposition, conjunction, pronoun, article). Use it only in that role.

Most common violations:
- **Noun-as-verb** — a tool/library/data-structure name used as a verb.
  `Docker the app` → `Use Docker to make a container` · `Git the change` → `Save the change with Git`
  `Cache the result` → `Keep the result in the cache` · `Query the database` → `Send a query to the database`
- **Adjective-as-verb** — `Secure the endpoint` → `Make the endpoint secure` ·
  `Empty the buffer` → `Make the buffer empty` (note: `clear` IS approved as both, so `Clear the flag` is fine)

Preferred approved verbs to replace inflated or misused forms:
- "utilize/leverage/employ" → `use` · "commence/initiate" → `start` · "terminate" → `stop`
- "orchestrate" → `control` · "facilitate" → `help`

The fix patterns:
1. Prepositional phrase: `Git the changes` → `Save the changes with Git`
2. Infinitive: `Queue the jobs` → `Use the queue to hold the jobs`
3. Make + adjective: `Secure the endpoint` → `Make the endpoint secure`

A word approved as more than one part of speech (e.g. `call`, `set`, `clean`) is valid in each role,
but the sentence structure must make the role clear. If a word appears twice with different roles,
restructure (e.g. use "change history" instead of "commit history" to avoid double "commit").

Exceptions:
- Code-domain technical verbs under Rule 1.12 override this rule for that specific word/context
  (e.g. `serialize` is permitted as a verb even though not in the general approved list).
- Quoted code/CLI commands in code blocks are exempt (Rule 1.5, category 10).

Examples:
> Non-STE: Query the database for user records.
> STE: Send a query to the database for user records.
>
> Non-STE: Static the variable to prevent modification.
> STE: Make the variable static to prevent modification.
>
> Non-STE: refactor: interface the user repository and factory the database connection
> STE: refactor: add an interface to the user repository and use a factory for the database connection

Command/keyword edge case: `return` is an approved verb ("send a value back from a function") —
`Return the result` is fine. `import`/`export` are NOT approved verbs — use
`Use \`import\` to add the module` / `Use \`export\` to make the function available`.

See also: Rules 1.1, 1.3, 1.4, 1.5, 1.7, 1.10, 1.12, 1.13.

---

## Rule 1.3 — Use Approved Words Only with Their Approved Meanings

Each approved word has exactly ONE approved meaning in the controlled terminology. Using the right
word with the wrong meaning is a violation even when the sentence is grammatical.

Decision procedure before publishing:
1. Identify the part of speech you used (Rule 1.2 selects the meaning).
2. Look up the approved meaning for that part of speech in `a-dictionary.md`.
3. Does your sentence use it with exactly that meaning? If no, it fails.
4. Replace with an approved word whose meaning fits, or restructure.

Most-misused approved words (use only the approved meaning):

| Word | Approved meaning | Wrong meaning to avoid → use instead |
|------|------------------|--------------------------------------|
| run | execute a program or command | operate/manage/continue → `operate`/`continue` |
| return | send a value back from a function to its caller | go back to a state/location → `go back` |
| call | invoke a function/method | name something → `name` |
| get | fetch or retrieve data from a source | become/understand → `become`/`understand` |
| set | put a value into a variable/config | become solid/prepare → `become solid`/`prepare` |
| make | bring into existence by building | force/earn → `cause`/`earn` |
| send | transmit data to a destination | cause a person to go → `cause to go` |
| raise | cause an exception to occur | increase/lift → `increase`/`lift` |
| catch | handle or intercept an exception | capture a moving object → `capture` |
| pass | give data as an argument to a function | go past/succeed → `go past`/`succeed` |
| check | examine for correctness or state | stop/restrain → `stop`/`leave` |
| break | exit a loop/switch immediately | divide into parts/damage → `split`/`damage` |
| continue | skip to next loop iteration | keep doing without interruption → `keep` |
| fail | an operation did not complete | not pass a test → `not pass` |
| move (Rust) | transfer ownership of a value | change physical position → `go`/`change position` |
| borrow (Rust) | take a reference without ownership | take temporarily → `take temporarily` |

Paradigm-specific meanings matter: e.g. in OOP `extend` = "create a subclass", `override` = "replace an
inherited method"; in functional `map` = "transform each element", `reduce` = "combine into one value",
`pure` = "no side effects"; in declarative SQL `select` = "retrieve rows" (not "choose"), `drop` =
"remove a table permanently"; in systems `own`/`borrow`/`move`/`drop` carry Rust ownership meanings.

Examples:
> Non-STE: This tool runs on Node.js and runs in the browser.
> STE: This tool operates on Node.js and operates in the browser. (first two "runs" = operates)
>
> Non-STE: Raises the value by 10% and passes it through the pipeline.
> STE: Increases the value by 10% and sends it through the pipeline.
>
> Non-STE: refactor: break the UserService into smaller classes
> STE: refactor: split the UserService into smaller classes  ("break" = exit a loop, not divide)

Edge case — multiple approved meanings: `set`, `run`, `file`, `test` have >1 approved meaning tied to
part of speech; `call` means "invoke" (verb) vs "invocation" (noun). Use "name", not "call", for
"we call this pattern X". Edge case — framework name shares spelling with an approved word
(`Express` the framework vs `express` the verb): capitalize the framework, do not use it as a verb.

See also: Rules 1.1, 1.2, 1.4, 1.7, 1.11, 1.13.

---

## Rule 1.4 — Use Only the Approved Forms of Verbs and Adjectives

The controlled terminology lists the approved inflected forms of each approved verb and adjective.
Use only those forms.

Verbs: use the imperative/base form for procedures, simple present (3rd-person `-s`) for descriptions,
simple past for completed actions. **Do not use the "-ing" form as the main verb of a procedural or
descriptive sentence** — this is the most common Rule 1.4 violation. Concentrate tenses: simple
present, simple past, simple future; not present/past perfect continuous.

Example approved verb table:

| Verb | Imperative | 3rd-person | Past | Past participle (adj) | Non-approved |
|------|-----------|------------|------|------------------------|--------------|
| make | Make | Makes | Made | Made | Making, Maked |
| get | Get | Gets | Got | Got (past only) | Getting, Getted |
| set | Set | Sets | Set | Set | Setting, Setted |
| call | Call | Calls | Called | Called | Calling |
| check | Check | Checks | Checked | Checked | Checking |
| give | Give | Gives | Gave | Given | Giving, Gived |
| run | Run | Runs | Ran | Run | Runned, Running (as main verb) |

Adjectives: use the dictionary-listed comparative/superlative forms (`fast`→`faster`/`fastest`,
`slow`→`slower`/`slowest`). Do not use "more fast" / "more slow". Adjectives that form comparatives
with `more`/`most` use those approved words instead. Do not invent forms like "compilating",
"membered", "performant".

Examples:
> Non-STE: The compiler is compilating the source files every time you save.
> STE: The compiler compiles the source files each time you save.
>
> Non-STE: This algorithm is more fast than the previous one.
> STE: This algorithm is faster than the previous one.
>
> Non-STE: Fixed memory leak and adding timeout configuration
> STE: Fix memory leak and add timeout configuration  (commit subjects: imperative, base form)
>
> Non-STE: Connection failed: the database is not running. Please verify and retrying the migration.
> STE: Connection failed: the database does not run. Check and try the migration again.

Code-domain technical verbs (Rule 1.12) follow standard English morphology and are exempt from the
closed approved-verb list, but still obey the tense/mood constraints (no "-ing" main verbs, correct
tense). `run` is irregular (run/runs/ran/run); `give` (give/gives/gave/given).

See also: Rules 1.1, 1.2, 1.3.

---

## Rule 1.10 — Do Not Use Regional, Slang, or Jargon Words as Technical Nouns

Use well-known words. Avoid regional terms (ecosystem-specific vocabulary), slang (metaphorical or
casual verbs), and jargon (community-dependent fuzzy terms) — even when they name a "concept".

Replace jargon with plain approved words:
- `cruft` → `unnecessary code` · `monkeys with` → `changes` · `grok` → `understand`
- `yak shaving` → `completing unrelated prerequisite tasks`
- `bikeshedding` → `unnecessary discussion about small details`
- `foo`/`bar` → `example`/`placeholder` · `pear-shaped` → `failed`
- `yeet` → `remove` · `dumpster fire`/`nuke` → state problem + action plainly
- `nerfed` → `decreased performance` · `shiny new hotness` → `current interface`
- `twiddle`/`tweak` → `change`/`set` · `pwn` → `control`

Community abbreviations that transcended jargon stay as technical nouns: `API`, `JSON`, `SQL`, `HTML`.
Less-universal ones remain jargon: `AFAICT`, `IIRC`, `IMHO` — spell out or omit. Initialisms that encode
principles (`DRY`, `KISS`, `YAGNI`) are jargon abbreviations; state the principle directly.

Temporal jargon has no fixed meaning: `modern`, `legacy`, `cutting-edge`, `state-of-the-art` → describe
the specific characteristic (`uses async/await`) or date (`written in 2018`).

Examples:
> Non-STE: Remove all the cruft from the legacy module.
> STE: Remove all the unnecessary code from the legacy module.
>
> Non-STE: I spent the morning yak shaving before I could write the test.
> STE: I spent the morning completing unrelated prerequisite tasks before I could write the test.
>
> Non-STE: This library lets you pwn the DOM.
> STE: This library lets you control the DOM.
>
> Non-STE: Replace the foo and bar placeholders with real values.
> STE: Replace the example and placeholder values with real values.
>
> Non-STE: The upload went pear-shaped halfway through.
> STE: The upload failed at 50 percent. Check your network connection and try again.

Paradigm slang to avoid: OO `POJO-ify`/`bean-ize` → `convert to a plain object`; FP `eta-reduce` →
`simplify the function`; procedural `massage the buffer` → `adjust the buffer`; declarative
`cattle not pets` → `disposable resources`; systems `UB`/`UAF` → `undefined behavior`/`use-after-free`
(spell out on first use).

Review checklist: (1) would a developer from another country understand every word? (2) replace
metaphors/idioms with literal descriptions; (3) expand abbreviations on first use; (4) replace
community nicknames with standard terms; (5) replace temporal words with dates/characteristics;
(6) verify every noun/verb is approved or a justified technical noun; (7) no slang verbs
(`hit`, `nuke`, `yeet`, `tweak`, `twiddle`).

See also: Rules 1.1, 1.5, 1.6, 1.11, 1.12, 1.13, 1.14.

---

## Rule 1.11 — Do Not Use Different Technical Nouns for the Same Item

Pick one code-domain technical noun for each component, service, module, endpoint, class, function,
table, resource, environment variable, or configuration key — and use it consistently everywhere.
The source of truth is the code itself (the class/function/module/table/resource name as defined in
the repo). Do not drift to colloquial synonyms.

Examples:
> Non-STE: Initialize the UserService class ... Call the authenticate method on the AccountManager ...
>          The UserHandler returns a session token.
> STE: Initialize the UserService class ... Call the authenticate method on the UserService ...
>       The UserService returns a session token.
>
> Non-STE: Send a request to the /api/login path ... The authentication route returns a JSON Web Token ...
> STE: Send a request to the /api/login endpoint ... The /api/login endpoint returns a JSON Web Token ...
>
> Non-STE: Set the database_connection_timeout ... The DB timeout parameter ... Increase the connection deadline ...
> STE: Set the database_connection_timeout ... The database_connection_timeout parameter ...
>       Increase the database_connection_timeout value ...

Per paradigm: the canonical noun is the class name (OO), the module/function name or type alias
(functional), the function/struct/file path (procedural), the resource/table name (declarative), the
language-spec or glossary term (systems, abstract concepts). Parallel lists must use one naming
convention. When a project genuinely has multiple components, introduce each explicitly rather than
drifting names.

Grammar consequence: consistent nouns keep English article and pronoun reference chains intact
(`the UserService ... it returns` — not `the AccountManager`, which breaks anaphora).

Edge cases: framework/library names that are also approved words (`Make`, `Act`, `Before`) — use the
framework name as a technical noun, capitalize to disambiguate (`Use the Make build tool to make the
project`). Generated code symbols — use the generated name as-is, define a declared alias if long.
Renaming during refactor — after commit, update all docs to the new name; keep `DEPRECATED` marker only
if the old name persists in a public API.

See also: Rules 1.1, 1.3, 1.5, 1.6, 1.8, 1.9, 1.10, 3.1, 3.6.

---

## Rule 1.12 — You Can Use Verbs That You Can Include in a Technical Verb Category

Code-domain technical verbs are permitted even when not in the approved word list, IF they name a
specific software operation and no approved verb gives the same meaning. They obey the same tense/
mood/voice rules as approved verbs (Rule 1.4, Section 3).

**Prefer an approved verb when one fits** (e.g. `find` over `detect` when not a security context;
`run` + noun over `migrate`; `run` over `execute`; `check` over `verify`). Use the technical verb only
when precision needs it and an approved verb would be vague.

The four categories (examples — not an exhaustive list):

**1. Development processes**
- a) Write/modify code: `compile, concatenate, import, inject, instantiate, lint, minify, marshal,
  optimize, polyfill, refactor, resolve, shim, stub, substitute, tokenize, transpile, trace, vectorize`
- b) Test/verify: `assert, benchmark, debug, fuzz, instrument, mock, profile, snapshot, spy, stub, unit-test`
- c) Build/package: `bundle, deploy, package, publish, release, tag, version`
- d) Manage deps: `hoist, install, link, lock, pin, update, upgrade`

**2. Computer processes and applications**
- a) I/O: `click, copy, cut, digitize, enter, paste, press, print, scan, swipe, tap, type`
- b) UI/app ops: `clear, close, delete, deselect, disable, drag, drag and drop, enable, encrypt,
  erase, filter, hide, highlight, invalidate, maximize, minimize, navigate, open, save, scroll,
  select, show, sort, store, submit, toggle, validate, zoom in, zoom out`
- c) System ops: `abort, authenticate, authorize, boot, cache, communicate, configure, debug,
  deserialize, download, format, hydrate, initialize, install, load, log, manage, mount, process,
  reboot, render, retry, serialize, spawn, synchronize, throttle, update, upgrade, upload`

**3. Instructions for subject fields**
- a) Algorithmic/math/data: `aggregate, bisect, compute, concatenate, convert, count, decode, encode,
  escape, filter, hash, index, map, merge, normalize, parse, pipeline, precompute, recalculate,
  reduce, tokenize, transform, validate, verify`
- b) Database/storage: `backup, compact, flush, index, migrate, persist, query, replicate, restore,
  roll back, seed, shard, upsert, vacuum, write-ahead`
- c) Network/communication: `broadcast, connect, disconnect, establish, forward, handshake, intercept,
  listen, poll, proxy, reject, resolve, route, send, stream, timeout, tunnel, unsubscribe, webhook`
- d) Security/auth: `authenticate, authorize, decrypt, decode, encode, encrypt, hash, revoke, salt,
  sanitize, sign, validate, verify`

**4. Legal and licensing terms** (only for legal/regulatory text):
`acknowledge, assign, comply with, conform to, disclose, enforce, explain, grant, inform, license,
modify, notify, permit, regulate, sign, supersede, waive`

Paradigm-specific verb sets:
- OO: `instantiate, inherit, override, extend, implement, encapsulate, delegate, inject`
- Functional: `compose, curry, map, reduce, fold, recurse, memoize, lift`
- Procedural: `allocate, deallocate, dereference, flush, signal`
- Declarative: `provision, converge, reconcile, apply, destroy`
- Systems (Rust): `borrow, own, drop, move, pin, acquire, release`

Examples:
> Non-STE: If you detect broken wires, repair them.  →  STE: If you find broken wires, repair them.
> (general context: "detect" not approved → use approved `find`)
>
> Non-STE: The intrusion detection system detects unauthorized access ...  (security context)
> STE: The intrusion detection system detects unauthorized access ...  ("detect" is a technical verb here)
>
> Non-STE: migrate the database schema ... verify the row counts
> STE: run the migration of the database schema ... check the row counts  (approved verb + noun preferred)

Light-verb anti-pattern (see Rule 1.13): do not wrap a technical verb in `do/make/perform/execute`
as a noun. Multi-word technical verbs (`roll back`, `drag and drop`, `zoom in`, `write-ahead`) stay as
one unit — do not split them with an object.

See also: Rules 1.1, 1.2, 1.5, 1.7, 1.11, 1.13, Section 3.

---

## Rule 1.13 — Do Not Use Technical Verbs as Nouns

Code-domain technical verbs (Rule 1.12) must be used only as verbs, never as nouns. If you need a noun,
use an approved noun or a code-domain technical noun. The most common violation is the **light-verb
construction**: a weak verb (`do/make/perform/execute/run`) + a nominalized technical verb.

Fix: use the technical verb as the main verb.
- `Make a commit` → `Commit` · `Do a compile` → `Compile` · `Execute a deploy` → `Deploy`
- `Run a build` → `Build` (when "build" names an artifact/process, it is a dual-category noun — see below)
- `The /api/login endpoint` (noun) ✓ vs `Do a login` → `Log in`
- `merge` as noun → `merge operation` · `import` as noun → `import operation`

Dual-category words (permitted as both verb and noun because they name a concrete artifact/event):
`build` (category 3 dev tools), `deploy` (cat 5 infra), `test` (cat 3), `commit` (cat 4 data structures),
`merge` (cat 4), `release` (cat 5), `patch` (cat 4), `log` (cat 13 runtime), `import` (cat 4).
Test: if you can put `a/an/the` before it and the sentence stays grammatical AND the word names a
concrete artifact/event in a technical-noun category, it is correct (`the build failed` ✓). If not
(`the compile failed`), it is a violation.

Article test: `the lint found errors` → VIOLATION (`lint` not dual-category) → `the linter found errors`.
`the serialize failed` → VIOLATION → `the serialization failed` or `the function serializes`.

Per paradigm: OOP — `do an instantiate` → `instantiate`; functional — `do a map over the list` →
`map over the list`; procedural — `do an allocate of memory` → `allocate memory`; declarative —
`do an apply of the manifest` → `apply the manifest`; systems — `the borrow of the reference` →
`the reference borrow` (or `borrow` as noun is fine for the Rust borrow concept, but `do a borrow` is wrong).

Examples:
> Non-STE: The `build` job does a compile of the source files, then starts the unit tests.
> STE: The `build` job compiles the source files, then starts the unit tests.
>
> Non-STE: Make a commit of your changes before you switch branches.
> STE: Commit your changes before you switch branches.
>
> Non-STE: If the error rate stays above five percent, execute a rollback of the migration.
> STE: If the error rate stays above five percent, roll back the migration.

Gerunds ("compiling takes ten seconds") are permitted in descriptive text but avoid as main verbs in
procedural sentences. Generated tool output (compiler messages) is quoted text — preserve as-is.

See also: Rules 1.12, 1.5, 1.7, 1.4, 1.10.

---

## Rule 1.14 — Use American English Spelling

Default to American English spelling in all prose. Exceptions: quoted text (third-party error
messages, terminal output, UI labels, code keywords) and proper names/technical nouns keep their
original spelling. An official project style guide mandating British English overrides this rule
(document it in CONTRIBUTING.md), but then the project is outside STE-Code for spelling.

Three spelling classes:
1. **Prose words** — American English only, no exceptions.
2. **Quoted text** — preserved as-is (Rule 1.5, category 10).
3. **Code-domain technical nouns** — use official spelling; surrounding prose stays American.

Suffix rules:
- **-ize / -ise**: use `-ize` (initialize, serialize, optimize, organize, recognize, synchronize,
  standardize, parameterize, customize, authorize, analyze, paralyze). Never `-ise` in prose.
- **-or / -our**: use `-or` (color, behavior, flavor, humor, labor, neighbor, rumor, harbor, honor,
  vapor, rigor). Not `-our`.
- **-er / -re**: use `-er` (center, theater, liter, meter [measuring device], fiber, caliber). Not `-re`.
  Note: "meter" (device) ≠ "metre" (length) — code docs always use "meter".
- **-l / -ll**: single `-l` in American (canceled, traveler, modeled, labeled, signaled). Not `-ll`.
  Exception: stress-final-syllable words double in both dialects (compelled, rebelled).

Common swaps:

| British | American | | British | American |
|---------|----------|---|---------|----------|
| colour | color | | licence (n) | license |
| behaviour | behavior | | defence | defense |
| centre | center | | programme | program |
| analyse | analyze | | practise (v) | practice |
| optimise | optimize | | catalogue | catalog |
| parametrise | parameterize | | analogue | analog |
| customise | customize | | judgement | judgment |

Same spelling both dialects (do NOT "fix"): address, all, committee, disappoint, necessary,
occurrence, parallel, recommend.

Examples:
> Non-STE: The log file shows the colour of each output line.
> STE: The log file shows the color of each output line.
>
> Non-STE: Initialise the variable before you use it.
> STE: Initialize the variable before you use it.
>
> Non-STE: The terminal shows the message `Colour profile not recognised`.
> STE: The terminal shows the message `Colour profile not recognised`. (quoted text preserved)
>
> Non-STE: The ColourPicker component uses the colour library for colour space conversions.
> STE: The `ColourPicker` component uses the `colour` library for color space conversions.
> (framework names preserved; prose uses American)

Enforcement: configure spell checker to en-US; pre-commit hook; CI step rejecting British spellings;
maintain a project dictionary of British-spelled technical nouns so the checker does not flag them.

See also: Rules 1.1, 1.5, 1.11, 8.6.



## rules-sec1-part2.md

# Level 3 — Words, Part 2: Code-Domain Technical Nouns (Rules 1.5–1.9)

Scope: the technical-noun block of STE-Code Section 1. Five rules decide which
words outside the approved dictionary may appear in code documentation, how they
must be spelled, shaped, and used, and which part of speech they may take.

Reading order: 1.5 defines what a code-domain technical noun is → 1.6 is the gate
that admits unapproved words → 1.7 forbids using those nouns as verbs → 1.8 picks
the standard name among competing candidates → 1.9 keeps the chosen name short.

Vocabulary model in one line: every word in STE-Code documentation is either an
approved dictionary word (Rule 1.1) or a code-domain technical noun (Rule 1.5) or
a technical verb (Rule 1.12). There is no fourth category.

---

## Rule 1.5 — You can use words that you can include in a code-domain technical noun category

**Rule.** You can use words that you can include in a code-domain technical noun
category.

A code-domain technical noun names a specified concept in software development
and is applicable to a subject field. The controlled terminology does not list
them all — there are too many, and each project uses different ones. Record the
ones your project uses in the project glossary or terminology database.

Technical nouns are permitted in procedural and descriptive writing when they fit
one or more of the nineteen categories below.

### The nineteen categories

| # | Category | Examples |
|---|---|---|
| 1 | Code components, modules, and libraries | class, controller, helper, hook, middleware, mixin, module, package, plugin, provider, repository, service, utility |
| 2 | Computing devices and their components | CPU, disk, GPU, keyboard, laptop, memory, monitor, mouse, printer, screen, server, smartphone, tablet, terminal |
| 3 | Development tools, environments, and support equipment | CLI, compiler, debugger, Docker, editor, IDE, Git, Jest, linter, loader, Prettier, terminal, test runner, TypeScript, webpack |
| 4 | Data structures, types, and formats | array, boolean, buffer, CSV, enum, hash map, integer, JSON, linked list, object, queue, stack, string, struct, tree, tuple, XML, YAML |
| 5 | Infrastructure, deployment, and platforms | AWS, CI/CD, container, deployment, Heroku, Kubernetes, load balancer, Node.js, pipeline, pod, production, staging, Vercel |
| 6 | Systems, subsystems, and architectural components | API gateway, authentication layer, caching layer, client, database layer, message broker, microservice, proxy, rate limiter, REST API, routing layer, server, WebSocket |
| 7 | Mathematical, algorithmic, and scientific terms | Big O notation, binary search, coefficient, complexity, exponent, hash function, iteration, logarithm, matrix, recursion, regex, sorting algorithm, time complexity, traversal |
| 8 | Interface elements and navigation | button, checkbox, dialog, dropdown, footer, header, menu, modal, navigation bar, radio button, scrollbar, sidebar, tab, text field, toggle, tooltip |
| 9 | Numbers, units of measurement, and time | byte, gigabyte (GB), hertz (Hz), hour (h), kilobyte (KB), megabyte (MB), millisecond (ms), minute, nanosecond (ns), second (s), terabyte (TB) |
| 10 | Quoted text (unchangeable text) | `Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused` |
| 11 | Professional roles, teams, and organizations | administrator, backend developer, contributor, DevOps engineer, frontend developer, Google, maintainer, Microsoft, product owner, QA engineer, reviewer, scrum master, user |
| 12 | Official documents, API references, and standards | API reference, changelog, code of conduct, contributing guide, diagram, figure, Getting Started guide, HTTP specification, note, paragraph, README, release notes, RFC, section, table, warning |
| 13 | Runtime environments and operational conditions | development, environment variable, garbage collection, heap, hot reload, live reload, memory leak, production, sandbox, stack trace, staging, test, thread, timeout, virtual machine |
| 14 | Colors | black, blue, cyan, gray, green, magenta, orange, red, white, yellow |
| 15 | Defects, errors, and fault terminology | assertion failure, bug, crash, deadlock, defect, exception, hang, infinite loop, memory leak, null pointer, race condition, regression, stack overflow, timeout, type error |
| 16 | Computer science, information, and communication technology | AI, algorithm, authentication, authorization, blockchain, containerization, cryptography, database, encoding, encryption, firewall, hashing, internet, machine learning, metadata, neural network, protocol, query, sandbox, schema, token, virtualization |
| 17 | Legal and licensing terms | Apache 2.0, BSD license, compliance, copyright, GPL, license, MIT license, open source, proprietary, terms of service, third-party, trademark, warranty |
| 18 | Database and storage terminology | connection pool, cursor, foreign key, index, migration, NoSQL, ORM, PostgreSQL, primary key, query, Redis, relation, row, schema, seed, SQL, SQLite, stored procedure, table, transaction, view |
| 19 | Network and protocol terminology | DNS, endpoint, HTTP, HTTPS, IP address, localhost, middleware, packet, port, request, response, route, socket, SSH, TCP, TLS, UDP, URL, VPN, WebSocket |

Colors (category 14) are adjectives, but STE-Code classifies them as code-domain
technical nouns. Comparative and superlative color forms (blacker, the reddest)
are not permitted.

The listed terms are examples only. Rule 1.5 does not give a complete list.

### Category selection by documentation type

| Documentation type | Typical categories | Example |
|---|---|---|
| README | 1, 3, 5, 17 | "This package provides a middleware for Express." |
| API documentation | 4, 6, 18, 19 | "The `GET /users/:id` route returns a JSON object with a user struct." |
| Docstrings and comments | 4, 7, 15 | "Traverse the binary search tree in-order and return a sorted array." |
| Commit messages | 1, 15, 18 | "Fix race condition in the connection pool that caused a deadlock on PostgreSQL." |
| Error messages | 9, 13, 15, 19 | "Connection refused: the TCP socket on port 5432 timed out after 30 seconds." |
| Test specifications | 1, 4, 15 | "The test calls `parseConfig` with a null pointer and checks for an assertion failure." |

### Relation to the neighbouring rules

- Rule 1.1 requires approved words for common vocabulary. Rule 1.5 is the
  complement: it permits words outside the dictionary when they name a technical
  concept. Use an approved word whenever one exists.
- Rule 1.6 forbids every unapproved word that Rule 1.5 does not admit. Read the
  two rules as one gate.

### Glossary registration is mandatory

Before you use a code-domain technical noun, add it to the project glossary. Each
entry states: the noun term; its STE-Code category or categories; the approved
meaning in the project context; one correct example sentence. A project without a
glossary drifts into ambiguity and breaks Rule 1.11 (one term per concept).

### Paradigm notes

| Paradigm | Lean on categories | Correct | Incorrect |
|---|---|---|---|
| Object-oriented (Java, C++, C#, Python) | 1, 4, 6, 16 | "The `UserRepository` class extends the `BaseRepository` abstract class and implements the `IAuditable` interface." | "The repo leverages the base to retrieve user data." (use "use"; use "repository") |
| Functional (Haskell, Elixir, Clojure, Rust) | 4, 7, 16 | "The function returns an `Option` monad. Use pattern matching to extract the value." | "The combinator stuff chains stuff together." (name the terms: parser combinator, function, pipeline) |
| Procedural (C, Go, Bash) | 4, 13, 19 | "The Go goroutine reads from the channel. The mutex prevents a race condition." | "The script fires off a subprocess to crunch the numbers." (use "starts", "process") |
| Declarative (SQL, Terraform, Kubernetes) | 5, 10, 12, 18 | "The `SELECT` statement uses an `INNER JOIN` on the `users` and `orders` tables." | "K8s spins up a bunch of pods inside the thing." (use "Kubernetes", "starts", "namespace") |
| Systems (Rust ownership, C memory) | 4, 13, 15, 16 | "The borrow checker prevents dangling pointers at compile time." | "Rust's thingy stops you from shooting yourself in the foot." (idiom forbidden by P10) |

```java
/**
 * The UserRepository class extends the BaseRepository abstract class
 * and implements the IAuditable interface.
 * Use the findById method to get a user struct from the database layer.
 */
public class UserRepository extends BaseRepository implements IAuditable {
    public User findById(Long id) { /* ... */ }
}
```

```rust
// The Rust compiler enforces the ownership rules.
// The borrow checker prevents dangling pointers at compile time.
fn parse_input(buffer: Vec<u8>) -> Result<String, Utf8Error> {
    let text = String::from_utf8(buffer)?;  // heap allocation (category 13)
    Ok(text)
}
```

### Edge cases

1. **Framework names that are also common words** (React, Vue, Swift, Go, Rust,
   Elm, Next, Nest). The framework name is a technical noun (category 3 or 5) and
   does not follow the dictionary meaning. Capitalize it, or use the full term
   ("the Swift language", "the Rust compiler"), so it cannot be read as the
   approved verb.
2. **Code keywords in documentation** (`if`, `for`, `return`, `class`, `async`).
   Inside backticks they are quoted text (category 10) and exempt. In prose they
   must follow the approved meaning. Write "If the request fails, return
   `500 Internal Server Error`." — not a bare `500`.
3. **Abbreviations and acronyms** (API, JSON, SQL, HTML, HTTP, TCP, DNS, URL) are
   technical nouns in categories 16, 18, or 19. Expand each at first use unless
   the audience universally knows it: "the application programming interface
   (API) uses Hypertext Transfer Protocol Secure (HTTPS)".
4. **Generated code and generated documentation** (OpenAPI specs, protobuf stubs,
   migration files, JSDoc or Sphinx output) are exempt, because a machine
   produces them. Every human-written comment or annotation inside them is not.
5. **Project-specific internal names** (`PhoenixCache`, "Hammerhead subsystem")
   are technical nouns under category 1 or 6 **only when registered in the
   project glossary**. Without registration they are unapproved words and break
   Rule 1.6.
6. **Numbers as technical nouns.** Fixed named values — version numbers
   (`Node.js 18`), status codes (`404`), port numbers (`port 5432`) — are
   category 9 nouns or quoted text and must appear verbatim. Do not write "the
   default db port" or "a not found error".

### Grammar of technical nouns

- **Articles.** Same as approved nouns: "the" for a specific instance, "a"/"an"
  for an indefinite one, no article for plural general reference — "Kubernetes
  pods run in a namespace."
- **As modifiers.** A technical noun may modify another to form a compound; both
  parts must belong to a recognized category. "The Redis cache server stores the
  session data." Not: "The thing layer processes the stuff queue."
- **Possessive.** Permitted only for category 11 (roles, organizations):
  "the user's session data". Use an "of" construction elsewhere: "the
  configuration of the Docker container" — not "the Docker container's
  configuration".
- **Plurals.** Standard English rules; acronyms add a lowercase "s" with no
  apostrophe. "two APIs and three SQL queries" — not "two API's".
- **Capitalization.** Proper-noun technical nouns keep published casing
  (`TypeScript`); common ones stay lowercase unless sentence-initial
  (controller, endpoint, middleware).

### Worked pair

> **Non-STE:** The developer used the thing to get data from the storage layer and put it on the screen.
>
> **STE:** The frontend developer used the API client to get data from the database and show it on the UI.

frontend developer (11), API client (16), database (18), UI (8). "Thing" names
nothing; "screen" is category 2 hardware, not the interface element.

> **Non-STE:** The endpoint leverages the middleware to authenticate the request and then kicks off a background job to crunch the data.
>
> **STE:** The endpoint uses the authentication middleware to check the request. The endpoint then starts a background job to process the data.

> **Non-STE:** First, snag the repo and then cd into it. After that, fire up the dev server.
>
> **STE:** First, clone the repository. Then, change to the repository directory. After that, start the development server.

> **Non-STE:** Bumped deps and fixed the wonky timeout thing that was breaking prod.
>
> **STE:** Update dependencies. Fix a timeout defect in the connection pool that caused a crash in production.

### Rule 1.5 cross-references

Rule 1.1 (approved words) · Rule 1.2 (part of speech) · Rule 1.3 (approved
meanings) · Rule 1.4 (verb and adjective forms) · Rule 1.6 (unapproved words) ·
Rule 1.7 (nouns not as verbs) · Rule 1.8 (standard names) · Rule 1.9 (short
names) · Rule 1.11 (one term per concept) · Rule 1.12 (technical verbs).

---

## Rule 1.6 — Use an unapproved word only when it is a code-domain technical noun, or part of one

**Rule.** Use a word that is not approved in the controlled terminology only when
it is a code-domain technical noun or part of a code-domain technical noun.

Some words are listed as unapproved. If such a word fits an applicable technical
noun category, it may be used in that noun sense — and only in that sense.

### The three-test gate

An unapproved word may stay only if it clears all three tests.

| Test | Question | Fails | Passes |
|---|---|---|---|
| 1 | Is the word unapproved? | "function" (approved — Rule 1.1 handles it) | "handler" enters the gate |
| 2 | Is it a technical noun, or inside a compound technical noun (Rule 1.5)? | "handler" alone; "main" alone | "event handler" (cat. 1); "main branch" (cat. 5) |
| 3 | Is it used as a noun in the sentence? | "This class handlers the request." | "The event handler processes the request." |

Failing any test means: replace with the approved alternative, or restructure.

### Compound checklist

A compound counts as a code-domain technical noun only when all three hold:

1. The words together name one concept that the domain recognizes.
2. The compound fits one of the nineteen categories.
3. Swapping the unapproved word for its approved alternative changes the
   recognized name and causes confusion.

Swap test: if the approved alternative still names the same concept, it is not a
technical noun — make the replacement. If the swap produces a name nobody in the
domain would recognize, the compound is a technical noun and the unapproved word
stays inside it.

Authority for "recognized": the project glossary, the framework or language
documentation, or an industry standard (RFC, W3C, POSIX).

### Core pairs

> **Non-STE:** The handler processes each incoming event.
>
> **STE:** The function processes each incoming event.
>
> **STE:** The event handler processes each incoming event. *("Event handler" is category 1.)*

> **Non-STE:** The main configuration has the latest values.
>
> **STE:** The primary configuration has the latest values.
>
> **STE:** Merge the feature branch into the main branch. *("Main branch" is the Git term, category 5; "primary branch" is not.)*

> **Non-STE:** Make sure that the two connectors at the base of the chassis engage.
>
> **STE:** Make sure that the two connectors at the bottom of the chassis engage.
>
> "Base" stays inside "base case" (cat. 7), "base class" (cat. 1), "base URL" (cat. 8).

### Descriptive adjective or technical noun?

| Permitted (technical noun) | Replace (descriptive) |
|---|---|
| "Check out the main branch before you merge." | "The main configuration has the latest values." → primary |
| "The base case returns the single-element array." | "The base configuration is loaded first." → primary |
| "The event handler processes each request." | "The handler processes each request." → function |

Criterion: does the compound appear in the official documentation of the
framework, language, or standard? If yes, technical noun. If no, prose — replace.

### Category overlap

The same unapproved word can pass in different categories when its meaning
changes: "base" in "base case" (7), "base class" (1), "base URL" (8); "cache" in
"cache layer" (6), "cache invalidation" (16), "query cache" (18). Each names a
specific concept — not a general adjective or verb.

### Worked trace

> **Non-STE:** The main config loader backups the data through the handler pipeline.
>
> **STE:** The primary config loader makes an auxiliary copy of the data through the processing pipeline.

| Word / phrase | Unapproved? | Technical noun? | Used as noun? | Result |
|---|---|---|---|---|
| main config loader | yes | "main" is a general adjective here | — | "main" → "primary" |
| backups | yes | verb sense is not a technical noun | no, verb | → "makes an auxiliary copy" |
| handler pipeline | yes | not a recognized compound | yes, but fails Test 2 | → "processing pipeline" |

### Applied by documentation type

**README.**

> **Non-STE:** The base setup leverages Express for the main API and MongoDB for the database backend. The handler backs up the data every night.
>
> **STE:** The primary setup uses Express for the main API and MongoDB for the database backend. The function makes an auxiliary copy of the data each night.

Package names (`Express`, `MongoDB`, `react-router`) are technical nouns
(cat. 3, 18). Keep a package-name compound whole — never split the unapproved
word out of `react-router`.

**API documentation.** Paths and field names stay; verbs must be approved.

```yaml
/api/v1/backup:
  summary: Makes an auxiliary copy of the database. Returns a backup ID.
  responses:
    '200':
      description: The auxiliary copy was made. The event handler processed the request.
```

**Docstrings and comments.**

```python
def serve(req):
    """Processes the request and returns a response."""
    # base case: the event handler returns null when req is empty
    if not req:
        return None
    return build(req)
```

"Handles" → "processes"; "base case" stays (cat. 7); "handler" → "event handler".
In Go: "the base URL is null and the event handler runs longer than the timeout"
— not "times out".

**Commit messages.** Conventional prefixes are technical nouns; the description
obeys the gate.

```
feat: add an event handler for the auxiliary-copy endpoint and the primary config loader
fix: run the backup script before the primary migration
chore: update the main config loader settings   # glossary names the file "main config"
```

**Error messages.**

```
Error: primary config file not found. The event handler for auxiliary copies will stop.
Build failed: the primary config loader ran longer than the timeout. The auxiliary-copy handler did not start.
```

### Paradigm notes

- **Object-oriented.** Class and pattern names stay: `BaseService`, `MainFactory`.
  Verbs must be approved: "handlers" → "processes", "backups" → "makes auxiliary
  copies", "factories" → "makes". A pattern name is never a verb: "This class
  uses the Singleton pattern for the connection used by all callers."
- **Functional.** Type and monad names stay (`ReaderT`). Use "base monad" only if
  the library's own docs use it; otherwise "underlying monad". "Base case" is a
  permitted compound (cat. 7).
- **Procedural.** `main` as the entry-point function name and the Go `main`
  package are technical nouns and stay; "main goroutine" as a general adjective
  becomes "primary goroutine". Make a bare "handler" explicit: "file handler".
- **Declarative.** Table names (`backup_logs`) and resource kinds (`ConfigMap`,
  `Deployment`) stay; "backups" → "keeps auxiliary copies"; "base settings" →
  "primary settings".
- **Systems.** `unsafe` block, `raw pointer`, `dangling pointer` are technical
  nouns. As a descriptive adjective, "unsafe" is not approved: write "This
  approach is not safe because the buffer is shared." "Base allocation" →
  "primary allocation"; bare "handler" → "drop handler".

### Rule 1.6 edge cases

1. **Framework name that is also an unapproved word.** `pandas`, `Express`,
   `webpack` are technical nouns when they name the tool, with published
   capitalization. As general verbs they are unapproved: "use pandas to load the
   CSV into a data frame, then use Express to send the results as JSON".
2. **Code keyword that is also a general word.** Inside backticks it is quoted
   text (cat. 10). In prose its role decides: "The category of objects that
   `return` a value must not block the primary thread." ("class" as a general
   noun → "category"; "main" → "primary".)
3. **A compound that looks technical but is not recognized.** "The handler
   pipeline integrates with the backup orchestrator via the main dispatcher"
   contains three invented compounds → "The processing pipeline integrates with
   the auxiliary-copy service through the primary dispatcher."
4. **Auto-generated documentation.** Apply the gate to the source docstring or
   annotation, not the generated output: `/// <summary>Processes the
   auxiliary-copy operation for the primary controller.</summary>`
5. **Project and brand names.** `Homebrew` stays (cat. 3 or 11); the descriptive
   prose around it is still reviewed: "Use Homebrew to install the primary
   packages. Then use `webpack` to make the primary bundle."

### Terminology referenced by Rule 1.6

| Term | Status | Approved alternative | Permitted inside |
|---|---|---|---|
| BASE (n) | unapproved | BOTTOM (n) for a surface or stack position; ROOT (n) for a filesystem root | base case (7), base class (1), base URL (8) |
| MAIN (adj) | unapproved | PRIMARY (adj) | main branch (5), main function / `main()` (1) |
| HANDLER (n) | unapproved | FUNCTION (n) | event handler, request handler, file handler (1) |
| BACKUP (n, v) | unapproved | AUXILIARY (adj); "makes an auxiliary copy" for the verb | backup file, `backup_logs` (18), `/api/v1/backup` (19) |
| BOTTOM (n, adj) | approved | — | — |
| FUNCTION (n) | approved | — | — |
| PRIMARY (adj) | approved | — | — |
| AUXILIARY (adj) | approved | — | — |
| ROOT (n) | technical noun | top-level directory (5 or 13) | — |

Categories most used by this rule: 1 (event handler, base class, main function),
3 (Express, pandas, webpack), 5 (main branch, ConfigMap), 7 (base case), 8 (base
URL, Git root), 18 (backup file, config file), 19 (backup as a resource name).

### Rule 1.6 cross-references

Rule 1.1 · Rule 1.2 · Rule 1.5 · Rule 1.7 · Rule 1.8 · Rule 1.9 · Rule 1.11 ·
Rule 1.12.

---



## rules-sec2.md

# Level 3 — Section 2: Technical Noun Rules (2.1–2.3)

Distilled reference for LLMs that generate code documentation. These three
rules govern how to write multi-word technical nouns so they stay short, clear,
and parseable. All examples are code-domain. Adapted from ASD-STE100 Issue 9.

Scope of this slice:
- Rule 2.1 — Keep Technical Nouns Short
- Rule 2.2 — Write Long Technical Nouns in Full
- Rule 2.3 — Use Hyphens Between Words Used as One Unit

Core idea shared by all three: a technical noun phrase (a class name, config
key, endpoint path, error type, test fixture, or commit subject) should stay
short — ideally three words or fewer. When it must be longer, write it in full
once, then use a short form or abbreviation. Use prepositions (`of`, `on`,
`in`, `for`, `to`) to break ownership chains, and hyphens only to glue related
words into one unit.

## Rule 2.1 — Keep Technical Nouns Short

**Source:** ASD-STE100 Issue 9, Rule 2.1 (adapted for code documentation).

### Rule
To keep multi-word technical nouns short, use prepositions (`of`, `on`, `in`,
`for`) and explain the noun instead of stacking modifiers. A code component that
is a technical noun — a module name, class name, config key, endpoint path,
error type, or test fixture — must stay short so the reader parses it without
effort.

Split a noun chain at its ownership/containment points and connect the parts
with prepositions. Do not write one long noun that stacks modifiers.

### Why it matters
- A reader scans docs fast. A stacked noun such as
  `authentication_token_expiration_refresh_interval_setting` hides which part
  owns which. Prepositions reveal the tree.
- Short technical nouns match how code is already structured: a config key,
  class, or JSON field is one short concept; prepositions show how concepts
  relate.
- Use short plain words (Microsoft/Google style): `use` not `utilize`/`leverage`
  /`employ`; `start`/`stop` not `commence`/`initiate`/`terminate`.
- Approved code-domain adjectives stay attached to the short noun they modify:
  `idempotent`, `immutable`, `thread-safe`, `atomic`, `nullable`, `deprecated`,
  `stateless`, `backward-compatible`, `asynchronous`, `concurrent`,
  `deterministic`. Write `the idempotent retry policy`, not `idempotentretrypolicy`.

### How to apply
1. Find a noun that stacks two or more modifiers (a "noun chain").
2. Split the chain at ownership/containment points.
3. Connect parts with `of`, `on`, `in`, or `for`.
4. Name each code component by its short technical noun (class, key, file),
   not a merged word.
5. In instruction text use approved verbs: `set`, `get`, `make`, `show`,
   `check`, `remove`, `send`, `start`, `stop`, `use`, `update`. Do not use
   `configure` for `set`, `retrieve` for `get`, `delete`/`purge` for `remove`,
   or `display` for `show`.

### Examples in STE-Code

**1. Configuration key — auth token refresh**
- Non-STE: Authentication token expiration refresh interval setting
- STE: Setting of the refresh interval of the expiration of the authentication token

```yaml
# STE-Code: short keys, one concept per level
auth:
  token:
    expiration:
      refresh_interval_seconds: 300   # setting of the refresh interval of the expiration of the authentication token

# Non-STE: one long key hides the relationship (do not write this)
authentication_token_expiration_refresh_interval_setting: 300
```

```python
def get_refresh_interval(token):
    """Return the setting of the refresh interval of the expiration of the authentication token."""
    return token.expiration.refresh_interval_seconds
```

**2. Deployment labels — middleware config**
- Non-STE: Install the forward service request validator middleware config tags.
- STE: Install the config tags on the validator middleware of the request of the forward service.

```bash
# the tag goes on the validator middleware of the request of the forward service
kubectl label pods -l app=forward-service middleware=validator config=enabled
```

```yaml
# Non-STE (do not write this)
install_forward_service_request_validator_middleware_config_tags: true
```

**3. Cleanup task — migration lock files**
- Non-STE: Remove the database migration script output directory lock files.
- STE: Remove the lock files that lock the output directory of the migration script of the database.

```python
def remove_migration_lock_files(db_name: str) -> int:
    """Remove the lock files that lock the output directory of the migration script of the database."""
    output_dir = Path("migrations") / db_name / "output"
    removed = 0
    for lock in output_dir.glob("*.lock"):
        lock.unlink()
        removed += 1
    return removed
```

```python
def test_remove_migration_lock_files(tmp_path):
    out = tmp_path / "app" / "output"
    out.mkdir(parents=True)
    (out / "write.lock").write_text("")
    count = remove_migration_lock_files("app")
    assert count == 1
    assert not any(out.glob("*.lock"))
```

**4. Test setup — cache hook alignment**
- Non-STE: Adjust to obtain cache invalidation hook alignment with the event emitter.
- STE: Adjust the cache invalidation hook until it aligns with the event emitter.

```python
def align_cache_hook(hook, emitter, timeout: float = 5.0) -> bool:
    """Adjust the cache invalidation hook until it aligns with the event emitter."""
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        if hook.target is emitter:
            return True
        hook.nudge()
    return False
```

**5. API documentation — retry policy**
- Non-STE: Payment gateway timeout retry exhaustion notification handler.
- STE: Handler of the notification of the exhaustion of the retry of the timeout of the payment gateway.

```python
class PaymentGatewayTimeoutRetryExhaustionNotificationHandler:
    """Handler of the notification of the exhaustion of the retry of the timeout of the payment gateway."""

    def handle(self, notice) -> None:
        log.error("retry of the timeout of the payment gateway is exhausted")
```

**6. Commit message — schema change**
- Non-STE: User account profile avatar image storage bucket policy update.
- STE: Update of the policy of the storage bucket of the image of the avatar of the profile of the user account.

```text
# STE-Code commit title
Update the policy of the storage bucket of the image of the avatar of the profile of the user account

# Non-STE commit title (do not write this)
useraccountprofileavatarimagestoragebucketpolicyupdate
```

**7. README section — rate limit**
- Non-STE: The inbound request rate limit window reset schedule controls the burst.
- STE: The schedule of the reset of the window of the rate limit of the inbound request controls the burst.

```markdown
The schedule of the reset of the window of the rate limit of the inbound
request controls the burst. Set the window to 60 seconds.
```

**8. Code comment — background job**
- Non-STE: The background worker queue overflow alert suppression rule runs on the staging cluster.
- STE: The alert suppression rule on the overflow of the background worker queue runs on the staging cluster.

```python
def install_alert_rule(cluster: str) -> None:
    rule = AlertSuppressionRule(on=OverflowOf(WorkerQueue(background=True)))
    deploy(rule, cluster="staging")
```

### See also
- Rule 1.5 — Technical Noun Categories (what counts as a technical noun).
- Rule 1.3 — Use Approved Words Only (keep verbs/nouns plain).
- Rule 2.2 — Write Long Technical Nouns in Full.
- Rule 2.3 — Use Hyphens Between Words Used as One Unit.

## Rule 2.2 — Write Long Technical Nouns in Full

**Source:** ASD-STE100 Issue 9, Rule 2.2 (adapted for code documentation).

### Rule
When a technical code noun has more than three words, write it in full the
first time it occurs. Then use one of these methods to make it clear:
- Give a shorter form of the technical code noun.
- Use hyphens (`-`) between words used as one unit (see Rule 2.3).
- Use prepositions (`of`, `on`, `in`, `for`, `to`) to split a long noun into
  short, separate parts (see Rule 2.1).

A long multi-word code noun can be one long technical noun, or a combination of
shorter ones. When the noun is an official term your company, framework, or
subject field uses, you must write it in its approved form — even if you cannot
split it.

### Method 1 — Shorter form / abbreviation
If a long technical code noun comes from an official code document (API spec,
schema, OpenAPI file, architecture diagram), write it in full the first time it
occurs. Then, if possible, give a shorter form or approved abbreviation in
parentheses, and reuse that form in the rest of the document.

- Write "user session cache invalidation lock handler" in full, then refer to
  it as the "invalidation lock handler" (3 words, obeys Rule 2.1).
- Approved abbreviations from official code docs are allowed, but a text full
  of abbreviations is hard to read. If an approved noun is three words or less,
  do not abbreviate.

```python
def initialize_session_lock(user_id: str) -> None:
    """Initialize the user session cache invalidation lock handler.

    The invalidation lock handler locks the cache of the user session so that
    a background job cannot read stale data while a write is in flight.
    """
    handler = UserSessionCacheInvalidationLockHandler(user_id)
    handler.engage()   # from here, refer to it as the "invalidation lock handler"
```

Abbreviation defined on first use, then reused:

```typescript
// The Main Form Validation Module (MFVM) is a TypeScript module that
// includes a Main Export Controller Unit (MECU) and a Data Bridge (DB).
interface FormPayload { fields: Record<string, unknown>; }

class MainFormValidationModule {       // MFVM
  constructor(
    private readonly exportController: MainExportControllerUnit,  // MECU
    private readonly bridge: DataBridge,                          // DB
    private readonly config: DynamicConfigUnit,                   // DECU
  ) {}

  submit(payload: FormPayload): void {
    this.config.onEvent("submit", () => this.exportController.run(payload));
  }
}
```

Parts list — name each part in full; do not pack parts into letter codes:

```yaml
controller:
  data_transformer_assembly:   # (8)  part of the view body
  pipeline_validator_assembly: # (15) sits on its seat
  buffer_assembly:             # (17) part of the view body

# Non-STE (do not write this):
#   parts: [DTA_8, PVA_15, BA_17, VB_20]
```

```python
def disassemble_controller(view_body, validator_seat):
    view_body.remove(data_transformer_assembly)        # (8)
    validator_seat.remove(pipeline_validator_assembly) # (15)
    view_body.remove(buffer_assembly)                  # (17)
```

### Method 2 — Prepositions to break a long noun
When a long noun is a chain of short nouns (e.g. "user authentication token
refresh failure retry policy"), make the main noun the head of the sentence and
attach the rest with prepositions. Put the key noun first, then add modifiers
with `of`, `on`, `in`, `for`, `to`.

- Non-STE: Configure the user authentication token refresh failure retry policy before you deploy the service to production.
- STE: Configure the retry policy for the failure of the refresh of the user authentication token before you deploy the service to production.

- Non-STE: Install the background worker queue overflow alert suppression rule on the staging cluster.
- STE: Install the alert suppression rule on the overflow of the background worker queue on the staging cluster.

- Non-STE: Remove the database connection pool exhaustion recovery timeout configuration parameter from the settings file.
- STE: Remove the configuration parameter that sets the recovery timeout for the exhaustion of the database connection pool from the settings file.

```python
def set_recovery_timeout(pool, seconds: float) -> None:
    """Set the configuration parameter that sets the recovery timeout
    for the exhaustion of the database connection pool."""
    pool.config["recovery_timeout_seconds"] = seconds
```

- Non-STE: Update the build script to obtain output directory naming consistency with the package convention.
- STE: Update the build script until the output directory naming is consistent with the package convention.

### Method 3 — Hyphenate words used as one unit
When two or more words act as a single modifier before a noun, use a hyphen to
show they are one unit. Hyphenate compound modifiers such as `request-response`,
`read-write`, `build-time`, `out-of-band`, `end-to-end`, `run-time`. Do NOT
hyphenate when the first word is an `-ly` adverb (e.g. "a publicly documented
API" stays open).

- Non-STE: Set the request response mapping handler to the new schema before the migration.
- STE: Set the request-response mapping handler to the new schema before the migration.

- Non-STE: Run the build time configuration check after you compile the module.
- STE: Run the build-time configuration check after you compile the module.

- Non-STE: Add an end to end test for the payment flow before you merge the change.
- STE: Add an end-to-end test for the payment flow before you merge the change.

- Non-STE: Use the out of band signal to stop the long running job.
- STE: Use the out-of-band signal to stop the long-running job.

```python
def handle_request_response(handler: "RequestResponseMappingHandler") -> None:
    """Set the request-response mapping handler to the new schema."""
    handler.apply(schema=SCHEMA_V2)

def run_build_time_check() -> None:
    """Run the build-time configuration check after you compile the module."""
    ...
```

Note: hyphenation groups words into one unit but does not make a long technical
noun short. If the hyphenated unit still has more than three words (e.g.
"request-response mapping handler"), write it in full the first time, then use
the shorter form ("mapping handler") afterward.

### Expanded code-domain example pairs
Each Non-STE line breaks the rule; each STE line writes the long noun in full,
then uses the shorter form or abbreviation.

- Non-STE: The USCIlh must run before the shutdown hook releases the cache. If the USCIlh fails, the stale session remains.
- STE: Initialize the user session cache invalidation lock handler (the handler that locks the cache of the user session; in this procedure, we call it the "invalidation lock handler"). Run the invalidation lock handler before the shutdown hook releases the cache. If the invalidation lock handler fails, the stale session remains.

```python
class UserSessionCacheInvalidationLockHandler:
    def engage(self) -> None: ...
    def release(self) -> None: ...

def shutdown_hook(session_id: str) -> None:
    handler = UserSessionCacheInvalidationLockHandler(session_id)
    handler.engage()          # invalidation lock handler
    if not handler.release():
        raise StaleSessionError(session_id)  # stale session remains
```

- Non-STE: The MFVM uses the MECU and the DB. The DECU sends events to the MFVM so that the MFVM can get data from the MFP.
- STE: The Main Form Validation Module (MFVM) is a TypeScript module that includes a Main Export Controller Unit (MECU) and a Data Bridge (DB). The Dynamic Config Unit (DECU) sends events to operate the MFVM, and the MFVM gets form data from the Main Form Provider (MFP).

```typescript
const mfvm = new MainFormValidationModule(     // MFVM
  mecu,  // Main Export Controller Unit
  db,    // Data Bridge
  decu,  // Dynamic Config Unit
);
decu.onEvent("submit", () => mfvm.submit(mfp.getData()));  // MFP = Main Form Provider
```

- Non-STE: Call the DTA to configure the MFVM before you run the build, then check the MFVM output for errors.
- STE: Use the data transformer adapter to configure the main form validation module before you run the build. Then check the output of the main form validation module for errors.

```bash
make configure MODULE=data-transformer-adapter   # data transformer adapter
make build MODULE=main-form-validation-module    # main form validation module
make test   MODULE=main-form-validation-module && echo "output checked for errors"
```

- Non-STE: Update the cross service request tracing correlation identifier generator after the schema change.
- STE: Update the correlation identifier generator for the tracing of the request across services after the schema change. (On first use, write "cross-service request tracing correlation identifier generator" in full, then refer to it as the "correlation identifier generator.")

```python
def update_correlation_generator(schema: dict) -> None:
    """Update the cross-service request tracing correlation identifier generator.

    After the first use, this component is the correlation identifier generator.
    """
    CorrelationIdentifierGenerator.for_request_tracing().apply(schema)
```

- Non-STE: The CI pipeline docker image layer cache warming step now runs in parallel.
- STE: The cache warming step for the layer of the Docker image of the CI pipeline now runs in parallel. (On first use, write "CI pipeline Docker image layer cache warming step" in full, then refer to it as the "cache warming step.")

```yaml
jobs:
  warm_cache:   # cache warming step for the layer of the Docker image of the CI pipeline
    runs-on: ubuntu-latest
    strategy:
      matrix:
        layer: [base, deps, build]
    steps:
      - run: ./scripts/warm-cache.sh "${{ matrix.layer }}"
```

- Non-STE: Document the legacy database migration rollback failure notification webhook endpoint in the runbook.
- STE: Document the webhook endpoint for the notification of the failure of the rollback of the legacy database migration in the runbook. (On first use, write "legacy database migration rollback failure notification webhook endpoint" in full, then refer to it as the "notification webhook endpoint.")

```text
Document the webhook endpoint for the notification of the failure of the
rollback of the legacy database migration. After the first use, refer to it
as the "notification webhook endpoint" and add it to the on-call alert route.
```

### How to apply in code documentation
1. Find the long technical code noun (more than three words) in your sentence.
2. Write it in full the first time it occurs. If it comes from an official
   source (API spec, schema, architecture diagram), keep the exact approved form.
3. Give a shorter form or approved abbreviation right after the full form, in parentheses.
4. In the rest of the document, use only the shorter form or the abbreviation.
5. If the noun is a chain of short nouns, split it with prepositions (Rule 2.1).
6. If two or more words act as one modifier, hyphenate them (Rule 2.3).
7. Do not fill a procedure with abbreviations. A short, clear noun beats a
   string of letters.

> Microsoft/Google style note: use short plain words — `use` not
> `utilize`/`leverage`/`employ`; `start`/`stop` not `commence`/`initiate`/`terminate`.

### See also
- Rule 2.1 — Keep Technical Nouns Short.
- Rule 1.5 — Technical Noun Categories and Your Company Glossary.
- Rule 1.3 — Use Approved Words (use, set, get, make, show, check, remove, send, start, stop).

## Rule 2.3 — Use Hyphens Between Words Used as One Unit

**Source:** ASD-STE100 Issue 9, Rule 2.3 (adapted for code documentation).

### Rule
A hyphen connects words or parts of words. Use hyphens between words to show
how related words operate as one unit. This keeps multi-word code nouns within
the three-word limit of Rule 2.1. A hyphenated word counts as one word, so it
fills only one of the three slots a noun phrase may use.

- Do NOT connect unrelated words with a hyphen — it changes the meaning of the
  multi-word noun. If unsure, explain the noun plainly, then use a shorter form
  or an approved abbreviation.
- If an approved technical code noun already includes hyphens — e.g.
  `input-output stream`, `thread-safe queue`, `backward-compatible API` — keep
  the hyphen. Do not change official terms.
- Do NOT use hyphens to make groups of more than three words. Keep the hyphen
  group to at most three words; split longer chains with prepositions
  (`of`, `on`, `in`).

### Examples in STE-Code

| Example | Note |
|---|---|
| Make sure that the fail-safe shutdown-handler connection is safe. | (3 words: make / sure / connection) |
| Inspection of the request rate-limit device. | (3 words: inspection / of / device) |
| The thread-safe queue keeps the order of the write operations. | (3 words: queue / keeps / order) |
| Remove the backward-compatible API client before you make the change. | (3 words) |

When a hyphen joins two related words, the pair is one unit. Apply this in
procedural and descriptive code docs so the reader parses the noun without
re-reading.

**Full example — hyphenate related words, keep to three words**
- Non-STE: Move the `main-feature-flag-rollback-handler` trigger to start the test run. (2 words, but not correct — four words joined as one unit)
- STE: Move the `main-feature-flag` rollback-handler trigger to start the test run. (3 words: move / trigger / run)

```bash
# the hyphen joins the related pair only
make test trigger=rollback-handler flag=main-feature-flag
```

```python
def move_trigger(main_feature_flag: str, rollback_handler: str) -> None:
    """Move the main-feature-flag rollback-handler trigger to start the test run."""
    trigger = f"{main_feature_flag}:{rollback_handler}"
    start_test_run(trigger)
```

**Full example — do not hyphenate a three-word approved technical noun**
When the official name is three words or less, leave the spaces. Hyphenating it
changes the count and confuses the reader.
- Non-STE: A. Remove the `data-adapter` assembly (8) from the view body (20). B. Remove the `pipeline-validator` assembly (15) from its seat.
- STE: A. Remove the `data adapter` assembly (8) from the view body (20). B. Remove the `pipeline validator` assembly (15) from its seat.

```python
def remove_assembly(name: str, part_id: int) -> None:
    """Remove the data adapter assembly (part_id) from the view body."""
    detach(name, part_id)
    log(f"removed {name} assembly {part_id}")

remove_assembly("data adapter", 8)
remove_assembly("pipeline validator", 15)
```

**Full example — keep a hyphen the official name already has**
If official code docs or an approved standard already hyphenates a term, keep
the hyphen. Removing it changes the term.
- Non-STE: The `input output stream` is part of the logging system.
- STE: The `input-output stream` is part of the logging system.

```python
class LoggingSystem:
    def __init__(self, stream: "InputOutputStream") -> None:
        # The input-output stream is part of the logging system.
        self.stream = stream

    def write(self, message: str) -> None:
        self.stream.push(message)
```

```yaml
logging:
  # The input-output stream is part of the logging system.
  input-output-stream:
    buffer-size: 4096
    flush-on-error: true
```

### See also
- Rule 2.1 — Keep Technical Nouns Short (the three-word limit hyphenated units help you meet).
- Rule 1.5 — Use Technical Nouns from the Approved Categories (where hyphenated code terms such as `thread-safe queue` and `backward-compatible API` are defined).
- Rule 2.2 — Write Long Technical Nouns in Full (pair hyphenated nouns with short approved verbs such as `make`, `get`, `set`, `start`, `remove`).

<!-- END-SEC2-4 -->






## rules-sec3.md

# Level 3 — Section 3: Verbs

Scope: STE-Code Section 3, Rules 3.1 through 3.7. These rules control which verb
forms you can use, which tenses are approved, how to use the past participle,
how to avoid auxiliary constructions and "-ing" verbs, when to use the active
voice, and when to use a verb instead of a noun.

Audience: an LLM that writes or edits code documentation (README files, API
reference, docstrings, code comments, commit messages, error messages, CLI help,
configuration comments).

## Section 3 at a glance

| Rule | Statement | Primary test |
|---|---|---|
| 3.1 | Use only the verb forms that the dictionary gives. | Is the form one of the four listed lines of the entry? |
| 3.2 | Use only the approved verb forms and tenses. | Is the tense infinitive, imperative, simple present, simple past, simple future, or past participle as an adjective? |
| 3.3 | Use the past participle form as an adjective. | Does the word give a condition, before a noun or after be/become/stay? |
| 3.4 | Do not use auxiliary verbs to make complex verb constructions. | Does the sentence stack have/be/will/can/must + past participle? |
| 3.5 | Use the "-ing" form only as a technical noun or as a modifier in a technical noun. | Is the "-ing" word acting as a verb? Then it is not approved. |
| 3.6 | Use the active voice. | Ask "by whom or by what?" If the sentence answers it, the sentence is passive. |
| 3.7 | Use an approved verb to describe an action, not a noun. | Is the action hidden in a noun phrase such as "gives an indication of"? |

## Quick decision procedure

1. Find the verb in the STE-Code dictionary. If the verb is not there, replace it
   with the approved verb (Rule 3.1, Rule 3.7).
2. Choose one of the six approved forms (Rule 3.2).
3. Name the actor and put the actor in the subject position (Rule 3.6).
4. Remove every auxiliary chain (Rule 3.4).
5. Remove every "-ing" verb. Keep "-ing" only inside a technical noun (Rule 3.5).
6. Keep the past participle only as an adjective (Rule 3.3).
7. If a sentence becomes long, split it into two short sentences and join the
   sequence with "Then".

---

## Rule 3.1 — Use only the verb forms that the dictionary gives

The STE-Code dictionary gives the allowed forms of each approved verb. Use only
those forms. Do not use gerunds, participles with auxiliaries, or inflected forms
that the entry does not list.

Each entry shows four forms in this order: base form, third-person singular,
simple past, past participle.

```
VALIDATE (v)
VALIDATES
VALIDATED,
VALIDATED

WRITE (v)
WRITES
WROTE,
WRITTEN
```

### How to read a dictionary entry

| Line | Form | Example with WRITE | Where you use it |
|---|---|---|---|
| 1 | Base form (infinitive and imperative) | WRITE | "Write the log." / "to write the log" |
| 2 | Third-person singular, simple present | WRITES | "The logger writes the record." |
| 3 | Simple past | WROTE | "The job wrote the record." |
| 4 | Past participle (as an adjective) | WRITTEN | "the written log" |

If a form is not on one of those four lines, the form is not approved. The simple
future is not a separate line: you make it with "will" and the base form
("will write").

### The four approved verb categories

| Category | Verbs |
|---|---|
| Development operations | build, compile, test, lint, format, commit, push, deploy, rollback |
| Data operations | read, write, serialize, deserialize, parse, encode, decode, query, insert, migrate |
| Application operations | handle, route, authenticate, authorize, validate, schedule, dispatch, resolve |
| Communication operations | send, receive, publish, subscribe, stream, poll, broadcast, connect |

### How to apply the rule

1. Find the verb in the STE-Code dictionary.
2. If the verb is not in the dictionary, use the approved verb instead.
3. If the verb is in the dictionary, use one of the four listed forms only.
4. Do not make a new form from an approved verb. "Parsing", "parseable", and
   "parser" are not verb forms of PARSE. A noun such as "parser" is approved only
   when the dictionary or a technical noun category gives it.
5. Use the past participle only as an adjective ("the parsed manifest", "the
   deprecated method"). Do not use it with "have", "has", "had", or "get".

### Frequent replacements

| Do not use | Use |
|---|---|
| generate | make |
| retrieve | get |
| verify | check |
| utilize, leverage | use |
| initiate | start |
| terminate | stop |
| delete | remove |
| render | show |
| execute | do |
| maintain | keep |

### Examples

| Non-STE | STE | Why |
|---|---|---|
| The linter validates the file and is reporting the errors to the terminal. | The linter validates the file. It reports the errors to the terminal. | "is reporting" is not a listed form of REPORT. |
| The script has written the output to the log before the test starts. | The script wrote the output to the log. Then the test starts. | The present perfect "has written" is not a listed form. |
| The service utilizes a token cache and leverages the parser for each request. | The service uses a token cache. The service parses each request. | "utilize" and "leverage" are not in the dictionary. |
| The parsing of the manifest is done by the loader, and the validating of the schema comes after. | The loader parses the manifest. Then the loader validates the schema. | Gerunds are not listed forms. Name the actor. |
| The migration had deleted the deprecated column and was terminating the open connections. | The migration removed the deprecated column. Then the migration stopped the open connections. | Use REMOVE and STOP. The past perfect and the progressive are not listed. |
| The client will be receiving the streamed records after the broker has been publishing them for one minute. | The broker publishes the records. The client will receive the streamed records after one minute. | Make the simple future with "will" and the base form. "streamed" is a participle used as an adjective. |
| The given options get validated by the gateway, and the removed entries are gotten from the cache. | The gateway validates the given options. The gateway gets the removed entries from the cache. | "get validated" and "are gotten" are not listed forms. |

Code context:

```python
# STE: the loader parses the manifest. Then the loader validates the schema.
manifest = loader.parse(path)      # parse -> parses / parsed / parsed
loader.validate(manifest, schema)  # validate -> validates / validated / validated
```

```javascript
// STE: the service uses a token cache. The service parses each request.
const cache = new TokenCache();          // use -> uses / used / used
app.post("/orders", (req, res) => {
  const order = parseOrder(req.body);    // parse -> parses / parsed / parsed
  res.json(order);
});
```

```go
// STE: the broker publishes the records.
// The client will receive the streamed records after one minute.
func (b *Broker) Publish(rec []byte) error { // publish -> publishes / published / published
    return b.topic.Send(rec)                 // send -> sends / sent / sent
}
```

See also: Rule 3.2, Rule 3.3, Rule 3.4, Rule 1.1, Rule 1.5, and the STE-Code
dictionary (the full list of approved verbs and their allowed forms).

---

## Rule 3.2 — Use only these verb forms and tenses of verbs

Approved forms and tenses:

- The infinitive form
- The imperative form (command form)
- The simple present tense
- The simple past tense
- The simple future tense
- The past participle form (as an adjective)

| Infinitive | Imperative | Simple present | Simple past | Simple future | Past participle (adj) |
|---|---|---|---|---|---|
| (To) parse (regular) | Parse + object | you/we/they parse; it parses | you/we/they parsed; it parsed | will parse | the parsed file |
| (To) write (irregular) | Write + object | you/we/they write; it writes | you/we/they wrote; it wrote | will write | the written log |
| (To) build (irregular) | Build + object | you/we/they build; it builds | you/we/they built; it built | will build | the built artifact |
| (To) send (irregular) | Send + object | you/we/they send; it sends | you/we/they sent; it sent | will send | the sent request |
| (To) validate (regular) | Validate + object | you/we/they validate; it validates | you/we/they validated; it validated | will validate | the validated token |

Not approved:

- The present perfect (have/has parsed)
- The past perfect (had parsed)
- The present or past progressive (is/was parsing)
- The future progressive (will be parsing)
- The perfect progressive (has been parsing, had been parsing)
- The gerund used as a verb with an auxiliary (is parsing, keeps parsing)
- All other complex verb constructions

### How to select the correct form

1. Infinitive — after a modal verb or to state a purpose: "Use this flag to parse the file."
2. Imperative — for each step of a procedure: "Parse the file. Write the log."
3. Simple present — for a general fact, a repeated action, or system behavior: "The parser reads the file."
4. Simple past — for an action that is complete: "The build failed."
5. Simple future — "will" plus the base form: "The job will start at 02:00."
6. Past participle — only as an adjective before a noun: "the parsed file".

### How to correct an unapproved form

| Unapproved | Correction |
|---|---|
| has parsed (present perfect) | parsed (simple past) |
| had parsed (past perfect) | simple past in two sentences joined with "Then" |
| is parsing, was parsing (progressive) | simple present or simple past; add "at the same time" for concurrent actions |
| will be parsing (future progressive) | will parse (simple future) |
| is being parsed (passive progressive) | name the actor and use the active voice (Rule 3.6) |

### Examples

| Non-STE | STE |
|---|---|
| The linter has found three errors in the source file. | The linter found three errors in the source file. |
| The server was processing the request when the timeout occurred. | The server processed the request. Then the timeout occurred. |
| The framework had already initialized the connection pool before the query started. | The framework made the connection pool. Then the query started. |
| The scheduler is deploying the build to production while the tests are running. | The scheduler sends the build to production. The tests run at the same time. |
| The cache has been keeping the serialized records since the service started, and the client will be reading them after the restart. | The cache keeps the serialized records. The client will read the records after the restart. |
| To be parsing the configuration file, the loader must be having read access to the directory. | To parse the configuration file, the loader must have read access to the directory. |
| You should be setting the timeout value and then you will be restarting the service. | Set the timeout value. Then start the service again. |
| The payload is being validated by the gateway and the deprecated field gets removed by the migration. | The gateway validates the payload. The migration removes the deprecated field. |
| The written log and the parsed manifest are showing that the build had completed with the given options. | The written log and the parsed manifest show that the build completed with the given options. |
| We have been building the release artifact and the CI pipeline will have run the tests by the time you review the pull request. | We built the release artifact. The CI pipeline will run the tests. Then you can review the pull request. |
| If the connection drops, the client is retrying the request until the server responds. | If the connection drops, the client retries the request. Then the server responds. |

Code context:

```bash
# STE: one imperative step for each line
# Set the timeout value.
export REQUEST_TIMEOUT=30
# Then start the service again.
systemctl restart api.service
```

```python
# STE: the server processed the request. Then the timeout occurred.
try:
    response = server.process(request)   # process -> processes / processed / processed
except TimeoutError:
    log.write("request timeout after 30 s")
```

```yaml
# .github/workflows/ci.yml
# STE: we built the release artifact. The CI pipeline will run the tests.
jobs:
  build:
    steps:
      - run: make release
  test:
    needs: build
    steps:
      - run: make test
```

See also: Rule 3.1, Rule 3.3, Rule 3.4, Rule 3.5, Rule 3.6, Rule 1.1.

---

## Rule 3.3 — Use the past participle form as an adjective

When you use the past participle form as an adjective, it shows the condition of
something. This is not passive voice. Use the past participle of an approved verb
as an adjective:

- Before a noun
- After a form of "to be", "to become", or "to stay"

Do not use the past participle form if it is not in the STE-Code dictionary. Some
approved adjectives in the dictionary are past participles of verbs that are not
approved; their part of speech is "(adj)", so you can use them.

### How to know that the participle is an adjective and not passive voice

1. The word gives the condition of the thing, not an action that an actor does.
2. You can put the word directly before the noun: "the parsed file", "the deprecated method", "the closed connection".
3. You can put the word after "is", "becomes", or "stays": "the cache is initialized", "the endpoint becomes deprecated", "the record stays locked".
4. If the sentence names an actor and an action ("the file was parsed by the loader"), the sentence is passive voice. Write the active voice instead (Rule 3.6).

### Approved code-domain past participles used as adjectives

| Past participle (adj) | Example noun phrase | Condition that it shows |
|---|---|---|
| parsed | the parsed manifest | The parser read the file. |
| serialized | the serialized record | The record is in a transport format. |
| deserialized | the deserialized object | The object is in memory again. |
| initialized | the initialized cache | The cache is ready for use. |
| deprecated | the deprecated method | The method is old. Do not use it. |
| allowed | the allowed memory | The limit that the configuration gives. |
| corrupted | the corrupted index | The data is not correct. |
| locked | the locked row | Another transaction holds the row. |
| written | the written log | The log file is on disk. |
| given | the given options | The options that the caller sends. |
| built | the built artifact | The build made the artifact. |
| signed | the signed token | The token has a valid signature. |

### Cautions

- Do not make a new past participle from an unapproved verb. Write "the removed branch", not "the deleted branch", when "delete" is not in the dictionary.
- Do not use a past participle as a verb with "have", "has", or "had" (Rule 3.2).
- Do not put more than one past participle before the same noun. Split a difficult phrase into two short sentences.
- Prefer the plain word: "started" not "commenced"; "used" not "utilized" or "leveraged"; "stopped" not "terminated".

### Correct use (adjective)

| STE | Why it is correct |
|---|---|
| Inspect all fields of the deserialized object for corruption. | "deserialized" is an adjective before the noun "object". |
| When the cache is fully initialized, start the worker threads. | "initialized" comes after "to be" and gives a condition. |
| Do not exceed the allowed memory for the buffer. | "allowed" is an approved adjective. |
| Make sure that the input values are not corrupted. | "corrupted" is an approved adjective. |

### Correction pairs

| Non-STE | STE |
|---|---|
| The parsed file was processed by the loader. | The parsed file is ready for the loader. |
| The method has been deprecated by the API team in release 4.2. | The method is deprecated in release 4.2. Do not use the deprecated method in new code. |
| After the record gets locked, the transaction which was started earlier is being committed. | The transaction writes the locked record. Then the transaction ends. |
| The signed token which had been given to the client is validated by the gateway on each request. | The gateway validates the signed token on each request. |
| When the index becomes corrupted it will have to be being rebuilt by the maintenance job. | When the index becomes corrupted, the maintenance job makes the index again. |
| The build artifact stays uncompiled until the pipeline has compiled the modified sources. | The artifact stays unbuilt until the pipeline builds the modified sources. |
| The user is shown a warning if the uploaded configuration file was found to be malformed. | The CLI shows a warning if the uploaded configuration file is malformed. |
| All of the returned records had already been serialized before the response was sent. | The API sends the serialized records in the response. |
| Make sure that the written log and the given options are not being modified by the plugin. | Make sure that the plugin does not change the written log or the given options. |

Code context:

```go
// STE: "initialized" comes after "is" and gives the condition of the cache.
if cache.IsInitialized() {
    pool.Start(workerCount)
}
```

```sql
-- STE: the transaction writes the locked record. Then the transaction ends.
BEGIN;
SELECT * FROM orders WHERE id = 42 FOR UPDATE;  -- the locked row
UPDATE orders SET status = 'sent' WHERE id = 42;
COMMIT;
```

```javascript
// STE: the gateway validates the signed token on each request.
app.use((req, res, next) => {
  const signedToken = req.headers.authorization; // the signed token
  if (!gateway.validate(signedToken)) {
    return res.status(401).send("the signed token is not valid");
  }
  next();
});
```

See also: Rule 3.1, Rule 3.2, Rule 3.4, Rule 3.5, Rule 3.6, Rule 1.1.

---

## Rule 3.4 — Do not use auxiliary verbs to make complex verb constructions

Do not use the past participle form as a verb together with the auxiliary verb
"have". That construction makes a tense that is not approved.

Do not use auxiliary verbs ("have", "be", "will", "can", "must", "should",
"is to be") with a past participle to build compound tenses or the passive voice.
Write the action with a simple, approved verb form instead:

- Use the simple past instead of "have/has/had + past participle".
- Use the active voice with a clear agent instead of "be + past participle" (Rule 3.6).
- Use the imperative form for instructions instead of "is to be + past participle".
- Use "you can + base verb" instead of "can be + past participle" when the reader is the agent.
- Use "will + base verb" with a named agent instead of "will be + past participle + by + agent".

When a compound construction seems unavoidable, split it into separate simple
sentences. Rule 3.2 lists the only approved forms.

### Conversion table

| Construction | Non-STE | STE |
|---|---|---|
| Present perfect | The build has compiled the module before the test runs. | The build compiled the module. Then the test runs. |
| "is to be" | The migration is to be run before you deploy the service. | Before you deploy the service, run the migration. |
| "can be" | The cache can be cleared. | You can clear the cache. |
| "must be" | The timeout must be set before the job starts. | Set the timeout before the job starts. |
| "will be ... by" | The report will be generated by the scheduler. | The scheduler will generate the report. |
| Present perfect passive | The connection pool has been created before the first query is sent. | The connection pool was created. Then the first query is sent. |
| "must be" (procedure) | The configuration file must be validated before the server starts. | Validate the configuration file before the server starts. |
| "are to be" | The user credentials are to be encrypted at rest and the key is rotated monthly. | Encrypt the user credentials at rest. Rotate the key every month. |
| "can be ... by" | The log entries can be exported to a CSV file by the admin. | The admin can export the log entries to a CSV file. |
| "will be ... by" | An error message will be shown by the validator if the input is empty. | The validator will show an error message if the input is empty. |
| Past perfect passive | The temporary files had been deleted by the cleanup task before the backup started. | The cleanup task removed the temporary files. Then the backup started. |

See also: Rule 3.2, Rule 3.3, Rule 3.5, Rule 3.6.

---

## Rule 3.5 — Use the "-ing" form only as a technical noun or as a modifier in a technical noun

In code documentation, a word that has an "-ing" form can be part of a verb, an
adjective, a noun, or a long group of modifiers. These functions cause ambiguity
and long sentences. Therefore an "-ing" word is not permitted as a verb.

Use an "-ing" word only as a technical noun (for example, in a heading) or as a
modifier inside a technical noun.

### Approved "-ing" words in STE-Code

| Part of speech | Words |
|---|---|
| Nouns | logging, monitoring, routing, servicing |
| Adjectives | matching, missing, remaining |
| Pronoun | something |
| Preposition | during |

### Why the progressive verb form is not approved

Rule 3.2 lists the only permitted forms: infinitive, imperative, simple present,
simple past, simple future, and past participle as an adjective. The progressive
("is running", "are deploying", "was processing") is not on that list. Replace
the progressive with the simple present or the simple past, and break a long
continuous clause into short sentences.

The "-ing" form also hides auxiliary constructions that Rule 3.4 forbids. Do not
write "the service is starting and then it is logging the request". Write "The
service starts. Then it logs the request."

### Approved "-ing" technical nouns (headings and titles)

Logging · Monitoring · Testing and Fault Isolation · Handling · Packaging ·
Shipping · Troubleshooting · Building · Deployment

### Approved "-ing" modifiers (inside a technical noun)

logging service · monitoring agent · routing table · switching relay ·
caching layer · building pipeline · binding configuration · streaming endpoint ·
rendering engine

Do not pull the "-ing" word out of the technical noun and use it as a verb. "The
caching layer stores the result" is approved. "The layer is caching the result"
is not.

### Correction pairs

| Non-STE | STE |
|---|---|
| When you are running this script, obey all the safety checks. | When you run this script, obey all the safety checks. |
| While the deployment is starting, you must watch the logs and you must not stop the process because stopping it during startup can corrupt the state file. | The deployment starts. While it starts, watch the logs. Do not stop the deployment. If you stop the deployment during startup, the state file can become corrupt. |
| The background worker is processing the queue and it is writing the results to the cache while the main thread is waiting for the response, causing the request to time out and the user to see an error. | The background worker processes the queue. It writes the results to the cache. The main thread waits for the response. If the main thread waits too long, the request times out and the user sees an error. |
| Be careful while the process is starting. | Be careful while the process starts. |
| The function is returning the value while the cache is loading the entry, which makes the result incorrect during the first request. | The function returns the value. The cache loads the entry. During the first request, the result is incorrect. |
| The matching algorithm is comparing the remaining items during the iteration and it is removing the missing records from the list. | The matching algorithm compares the remaining items during the iteration. It removes the missing records from the list. |
| Something going wrong during the migration can make the database stay in a broken state. | If something goes wrong during the migration, the database can stay in a broken state. |

### Long "-ing" clauses become vertical lists

Non-STE:

> A script opening a socket without checking the firewall rules and sending data
> to an unknown host, using an unverified certificate without reading the
> security policy, is in danger of causing a breach and thus exposing private
> keys and credentials.

STE:

> Before you open a socket, obey these precautions: (1) Read the security policy.
> (2) Make sure that the firewall rules allow the connection. (3) Verify the host
> certificate. (4) Get the correct credentials to send data to the host. If you do
> not obey these precautions, a breach of private keys and credentials can occur.

Non-STE:

> Developers committing code without running the test suite and pushing directly
> to the main branch, ignoring the review policy, risk breaking the build and
> therefore blocking the release for all team members.

STE:

> Before you commit code, obey these precautions: (1) Run the test suite. (2) Make
> sure that the tests pass. (3) Open a review before you merge to the main branch.
> If you do not obey these precautions, you can break the build and block the
> release for all team members.

See also: Rule 3.2, Rule 3.4, Rule 1.5.

---

## Rule 3.6 — Use the active voice

Use the active voice in all code documentation. In descriptive writing, the
passive voice is permitted only when the agent (the person, service, or component
that does the action) is unknown.

In the active voice, the subject does the action. The reader immediately knows
who or what performs the operation.

- Active: The middleware parses the API response.
- Passive: The API response is parsed by the middleware.

### The "by" test

Ask "by whom or by what?" after the verb phrase. If the sentence answers the
question, the sentence is passive.

- *The data was encrypted…* → by the crypto module. (Passive.)
- *The file was saved.* → by the application. (Passive, agent omitted.)
- *The file is saved.* (Not passive — a condition, a past participle used as an adjective. See Rule 3.3.)

### Four conversion methods

| Method | Use it when | Non-STE | STE |
|---|---|---|---|
| 1 — Move the agent to the subject | A "by"-phrase names the agent | The API response is parsed by the middleware. | The middleware parses the API response. |
| 2 — Change an infinitive to an active verb | A purpose clause hides the actor | To calculate the memory usage from these values. | The profiler calculates the memory usage from these values. |
| 3 — Use the imperative | Procedural text; the reader is the agent | The dependencies can be installed with the following command. | Install the dependencies with this command: `npm install` |
| 4 — Insert "you" or "we" | No agent is given | The configuration file can be edited with a text editor. | You can edit the configuration file with a text editor. |

Use "you" when the agent is the reader. Use "we" when the agent is your project
or organization.

### Method 1 in context — request pipeline README

Non-STE:

```markdown
## How the request pipeline works

After the client sends a request, the raw HTTP body is read by the server.
The API response is parsed by the middleware. The parsed data is then
validated by the schema checker before the controller receives it.
```

STE:

```markdown
## How the request pipeline works

After the client sends a request, the server reads the raw HTTP body.
The middleware parses the API response. The schema checker then validates
the parsed data before the controller receives it.
```

### Method 2 in context — a profiling docstring

Non-STE:

```python
def report_memory(samples):
    """To calculate the memory usage from these values. The peak is
    returned as a percentage of the allocated heap."""
```

STE:

```python
def report_memory(samples):
    """Calculate the memory usage from these values. Return the peak
    as a percentage of the allocated heap."""
```

### Method 3 in context — a contributing guide

Non-STE:

```markdown
## Setup

The dependencies can be installed with the following command. The test
suite can then be run from the same directory.
```

STE:

```markdown
## Setup

Install the dependencies with this command:

    npm install

Then run the test suite from the same directory:

    npm test
```

### Method 4 in context — a getting-started page

Non-STE:

```markdown
## First run

The configuration file can be edited with a text editor. The server
can be started after you save your changes.
```

STE:

```markdown
## First run

You can edit the configuration file with a text editor. After you save
your changes, you can start the server.
```

### When the agent is unknown

- Passive (correct): During the network request, the data was corrupted. The agent is unknown.
- Active (correct): During the network request, something corrupted the data.
- Active (incorrect): The network request corrupted the data. "network request" is not the correct agent, so the sentence becomes technically wrong.

### Further correction pairs

| Non-STE | STE |
|---|---|
| The database connection is established by the connection pool at startup. | The connection pool establishes the database connection at startup. |
| The test results can be viewed in the terminal output. | You can see the test results in the terminal output. |
| The configuration is loaded by the bootstrap routine. | The bootstrap routine loads the configuration. |
| The linting errors are reported by the linter. | The linter reports the linting errors. |
| The coverage report is generated by the coverage tool. | The coverage tool makes the coverage report. |

## Rule 3.6 by document type

### README files

A README mixes procedural text (installation, build, usage) and descriptive text
(overview, features, architecture). Use the imperative in procedural sections and
a named agent in descriptive sections.

| Non-STE | STE |
|---|---|
| The package can be installed with pip install. | Install the package with this command: `pip install .` |
| Support for WebSocket connections is provided by this library. | This library supports WebSocket connections. |

```markdown
## Installation

Install the package with this command:

    pip install .

Create a virtual environment before you install the package.
```

### API reference and docstrings

| Non-STE | STE |
|---|---|
| The input string is validated and a boolean is returned by this method. | This method validates the input string and returns a boolean. |
| The URL is transformed by the callback before the request is sent. | The callback transforms the URL before the client sends the request. |
| A `Promise<User>` is returned by this function. | This function returns a `Promise<User>`. |
| """A hash of the input data is computed and then it is returned as a hex string.""" | """Compute a hash of the input data. Return the hash as a hex string.""" |

### Code comments

| Non-STE | STE |
|---|---|
| // The buffer is flushed before new data is written. | // The writer flushes the buffer before it writes new data. |
| // The connection is closed by the finally block. | // The finally block closes the connection. |

### Commit messages

| Non-STE | STE |
|---|---|
| The authentication bug was fixed. | Fix the token refresh in the authentication middleware. |
| Rate limiting was added to the API endpoints. | Add rate limiting to the API endpoints. |

### Error messages

| Non-STE | STE |
|---|---|
| An invalid configuration value was encountered while the file was being parsed. | The parser found an invalid configuration value at line 12. |
| The request was rejected by the rate limiter. | The rate limiter rejected the request. |

## Rule 3.6 by paradigm

### Object-oriented (Java, C++, C#, Python classes)

Classes, methods, and pattern components are the agents.

| Non-STE | STE |
|---|---|
| The dependency is resolved by the container at runtime. | The container resolves the dependency at runtime. |
| New instances are created by the factory method when they are requested by the client. | The factory method creates a new instance when the client requests one. |
| The `validate()` method is called before the data is processed by the handler. | The handler calls the `validate()` method before it processes the data. |

```java
/**
 * The handler calls the validate() method before it processes the data.
 * The handler throws a ValidationException when it rejects the record.
 */
interface RequestHandler { void handle(Request req); }
```

### Functional (Haskell, Elixir, Clojure, Rust)

Functions and combinators are the agents.

| Non-STE | STE |
|---|---|
| Each element in the list is transformed by the `map` function. | The `map` function transforms each element in the list. |
| The input is filtered, then mapped, and finally the result is reduced to a single value. | The `filter` function removes invalid items. The `map` function transforms each item. The `reduce` function combines the results into a single value. |
| Two functions are composed into a new function by the `compose` combinator. | The `compose` combinator combines two functions into a new function. |

```clojure
;; The filter function removes invalid items. The map function transforms
;; each item. The reduce function combines the results into a single map.
(->> items (filter valid?) (map enrich) (reduce merge {}))
```

### Procedural (C, Go, Bash)

The script, the tool, or the function is the agent. Use the imperative in
procedural text.

| Non-STE | STE |
|---|---|
| The file is opened, the contents are read, and the connection is closed. | The script opens the file. It reads the contents. Then it closes the connection. |
| Environment variables are checked before the build process is started. | The script checks the environment variables. Then it starts the build process. |
| The log file can be rotated with the --rotate flag. | Use the --rotate flag to rotate the log file. |

```makefile
# The script checks the environment variables. Then it starts the build.
# Use the --rotate flag to rotate the log file.
build:
	./configure && $(MAKE)
```

### Declarative (SQL, Terraform, Kubernetes YAML, Dockerfile)

The declaration does not act. The tool or engine that reads the declaration acts.

| Non-STE | STE |
|---|---|
| An AWS VPC with three subnets is provisioned by this Terraform module. | This Terraform module provisions an AWS VPC with three subnets. |
| All rows with a status of 'active' are selected by this query. | This query selects all rows with a status of 'active'. |
| Three replicas of the pod are maintained by the deployment controller. | The deployment controller maintains three replicas of the pod. |
| # The base image is set to Ubuntu 22.04. | # Use Ubuntu 22.04 as the base image. |

NOTE: YAML comments and Dockerfile comments are procedural. Use the imperative
form and the active voice, because they instruct the reader or the build engine.

```sql
-- This query selects all rows with a status of 'active'. The aggregate
-- then counts the matching accounts.
SELECT count(*) FROM accounts WHERE status = 'active';
```

### Systems programming (Rust ownership, C memory, concurrency)

The allocator allocates. The function takes ownership. The mutex locks. The
channel sends.

| Non-STE | STE |
|---|---|
| The memory block is allocated by the allocator and a pointer is returned. | The allocator allocates the memory block. It returns a pointer. |
| Ownership of the string is taken by the `process` function. | The `process` function takes ownership of the string. |
| Access to the shared state is controlled by the mutex. | The mutex controls access to the shared state. |

```rust
// The mutex controls access to the shared state. The channel sends the
// value to the worker.
let guard = state.lock().unwrap();
tx.send(guard.clone());
```

## Rule 3.6 — extended examples

### Example 1 — README feature description

Non-STE: Authentication via OAuth2 and JWT tokens is supported by this service.
Rate limiting is applied to all endpoints. Requests are logged to a centralized
logging system.

STE: This service supports authentication with OAuth2 and JWT tokens. It applies
rate limiting to all endpoints. It sends request logs to a centralized logging
system.

The original has three consecutive passive constructions. The STE version
establishes "this service" as the agent once, then uses active verbs.

### Example 2 — API method documentation

Non-STE: `createUser(payload)` — A new user is created with the provided payload.
The payload is validated before the user record is inserted into the database. A
`User` object is returned upon success.

STE: `createUser(payload)` — Create a new user with the provided payload. The
method validates the payload. Then it inserts the user record into the database.
It returns a `User` object on success.

The reader of the original cannot tell whether the method, the database, or the
caller validates the payload.

### Example 3 — class docstring

```python
class ConnectionPool:
    """Manage a pool of database connections. The class lends a connection
    when a request arrives. It returns the connection when the request is
    complete. The reaper thread closes idle connections."""
```

### Example 4 — commit message

Non-STE: The memory leak in the image processing pipeline was fixed. Redundant
allocations were removed and the buffer pool was refactored.

STE: Fix the memory leak in the image processing pipeline. Remove redundant
allocations. Refactor the buffer pool.

### Example 5 — error message

```json
{
  "level": "error",
  "msg": "The token validator found a malformed token. The server rejected the request."
}
```

### Example 6 — configuration comment

```toml
# This setting controls the maximum number of concurrent connections.
# The server queues requests beyond this limit.
max_connections = 100
```

## Rule 3.6 — edge cases

### Edge case 1 — unknown agent (the standard exception)

When the agent is genuinely unknown, the passive voice is correct. In code
documentation this applies to:

- Unexpected data corruption with no identifiable cause
- External network failures where the remote endpoint is unknown
- Hardware faults that appear as software errors
- Race conditions where the exact sequence of events is not reproducible

- Correct (passive): The data was corrupted before the checksum was computed.
- Incorrect (active): Something corrupted the data before the checksum was computed. ("something" adds no information.)

NOTE: Use "something" as the agent only when you can describe the type of agent
(for example, "some process", "some external service"). If you cannot describe
the type, keep the passive voice.

### Edge case 2 — topic-comment structure in descriptive text

When the object is the established topic of the paragraph and the agent is
irrelevant, the passive voice can be clearer.

- Active (awkward): The developer stores the configuration file in the `/etc/myapp` directory.
- Passive (acceptable): The configuration file is stored in the `/etc/myapp` directory.
- Active (correct for a responsibility section): You must store the configuration file in the `/etc/myapp` directory.

Decision rule: if the paragraph topic is the object and an active rewrite would
introduce a distracting agent, use the passive voice. If the paragraph topic is
the agent, use the active voice.

### Edge case 3 — quotations from RFCs and specifications

Keep the passive voice inside a quotation and add a NOTE that identifies the
non-STE source. Do not rewrite the quotation. The rule applies only to the text
that you write.

> NOTE: The following description quotes RFC 7230. The passive voice in the
> quotation is from the original RFC text.
>
> > "The request message is parsed by the server into its component parts."

### Edge case 4 — framework-generated documentation

If you control the generator template (a Sphinx theme, a JSDoc template),
configure it to use the active voice. If you do not control the output, add a
NOTE at the top of the generated document.

> NOTE: This document was generated by [tool name]. Some sentences use the
> passive voice. Refer to the source code comments for STE-Code compliant
> descriptions.

### Edge case 5 — passive voice in established error message standards

Do not rewrite error strings from external systems (POSIX strings, HTTP reason
phrases, database error codes). The rule applies only to the messages that you
write.

- Your message (STE): The server cannot connect to the database at host:port.
- System message (unchanged): Connection refused.

## Rule 3.6 — grammar notes

### Structures

```
Active:  Subject (Agent) + Verb + Object (Patient)
Passive: Subject (Patient) + be + Past Participle (+ by + Agent)
```

Active voice gives the agent and the action in the natural reading order. Passive
voice gives the action first and the agent last, or not at all.

### Common passive constructions and their active equivalents

| Passive construction | Active equivalent | Method |
|---|---|---|
| is returned by | returns | 1 — move agent to subject |
| can be used to | you can use … to | 4 — insert "you" |
| is configured by | configures | 1 |
| is called when | calls | 1 |
| was added in version | (we) added … in version | 4 — insert "we" |
| should be installed | install (imperative) | 3 |
| is designed to | (we) designed … to | 4 |
| has been deprecated | (we) deprecated | 4 |
| will be removed in | (we) will remove … in | 4 |

### Passive with a modal verb

Keep the modal verb and move the agent to the subject position.

| Passive with modal | Active with modal |
|---|---|
| The file can be opened with this command. | You can open the file with this command. |
| The setting must be configured before startup. | You must configure the setting before startup. |
| The output will be written to stdout. | The program will write the output to stdout. |

### Structural patterns

| Pattern | Input structure | Output structure | Example |
|---|---|---|---|
| A — agent in a "by"-phrase (Method 1) | Patient + be + past participle + by + Agent | Agent + active verb + Patient | The token is validated by the auth middleware. → The auth middleware validates the token. |
| B — no agent, procedural (Method 3) | Patient + modal + be + past participle | Imperative verb + Patient | The dependencies should be installed before the build. → Install the dependencies before the build. |
| C — no agent, descriptive (Method 4) | Patient + be + past participle | You/We + active verb + Patient | The configuration file is stored in the config directory. → You must store the configuration file in the config directory. |

### Work together with the Canonical Synonym Table

When you convert a passive sentence, also check the replacement verb against the
Canonical Synonym Table.

| Non-STE | STE | Fixes applied |
|---|---|---|
| The result is used by the downstream pipeline. | The downstream pipeline uses the result. | Passive → active (Rule 3.6). |
| The error is displayed on the console by the logger. | The logger shows the error on the console. | Passive → active; "display" → "show" (Rule 1.1). |
| The report is generated by the scheduler every night. | The scheduler makes the report every night. | Passive → active; "generate" → "make" (Rule 1.1). |

### Rule 3.6 cross-references

- Rule 1.1 — the new agent must be an approved word or a permitted technical noun.
- Rule 1.5 — technical nouns that name code entities (middleware, validator, container, allocator, mutex) are permitted as agents. The agent must be a real code entity, not a vague abstraction.
- Rule 1.12 — the active verb is often a technical verb (parse, compile, deploy, render, query, allocate). Use its approved simple form.
- Rule 3.1 and Rule 3.2 — active voice sentences use the simple tenses. Converting to active voice also simplifies the tense.
- Rule 3.4 — the passive voice uses the auxiliary "be" plus a past participle. Converting to active voice removes the auxiliary.
- Rule 3.5 — a passive progressive ("is being parsed") breaks both Rule 3.5 and Rule 3.6. Convert to active voice first, then check the remaining "-ing" forms.
- Rule 3.7 — sentences must not exceed 20 words in procedural text and 25 words in descriptive text. Converting to active voice usually shortens the sentence. If the sentence is still too long, split it.



## rules-sec4.md

# Level 3 — STE-Code Section 4: Sentence Structure (Rules 4.1–4.5)

This slice covers the five Section 4 rules that govern sentence-level structure in
code documentation: one topic per sentence, no omitted words or contractions,
vertical lists, connecting words, and articles / demonstrative adjectives.

Apply these rules to docstrings, API references, README sections, commit messages,
and code comments. This is the Level 3 (high-fidelity) form: every rule is complete
with code-domain examples, paradigm guidance, edge cases, grammar notes, and a
checklist. Use the checklist at the end of each rule as a quick pass before you
publish documentation.

Each rule below gives: the requirement, code-domain examples, paradigm-specific
guidance, edge cases, grammar notes, and a summary checklist.

---

## Rule 4.1 — One Topic Per Sentence, No Abstract Text

**Requirement**
- Descriptive text (a class, module, or type description): each sentence has one
  topic and does not use the imperative mood. Add detail in the sentences that follow.
- Procedural text (an API method or function description): one instruction per
  sentence in the imperative mood.
- Never write abstract sentences. Show how to use a function or how a module
  operates. State the action or the measured result — not a vague property.

**Code examples — descriptive (one topic per sentence)**
- Non-STE: `The HttpClient class has two internal buffers connected together and linked with callbacks between the request handler and the response dispatcher.`
- STE: `The HttpClient class has two internal buffers. The internal buffers are connected together with callbacks. These callbacks link the request handler to the response dispatcher.`

**Code example — descriptive docstring (Java)**
```java
/**
 * STE:
 * The ConnectionPool manages a set of reusable TCP connections.
 * The connections are created lazily when the pool starts.
 * Each connection is validated when the caller checks it out.
 * Each connection is reset before the caller returns it to the pool.
 * The caller always receives a clean socket from the pool.
 */
public class ConnectionPool { /* ... */ }
```

**Code examples — avoid abstract statements**
- Non-STE: `No null values are permitted.` → STE: `Make sure that the function does not return a null value.`
- Non-STE: `Different payload sizes will change the parse time.` → STE: `When the payload size increases, the parse time will increase.` / `The parse time is 2 milliseconds for a payload of 1 KB.`

**Code example — avoid abstract statements (Python docstring)**
```python
# Non-STE:
def read_config(path: str) -> dict:
    """Loads the configuration. Returns None on error."""
    ...

# STE:
def read_config(path: str) -> dict:
    """Load the configuration from the file at the given path.
    Return an empty dictionary if the file does not exist.
    Do not return null. Raise ConfigError if the file is not valid."""
    ...
```

**Code example — procedural (one instruction per sentence, imperative)**
```python
# STE:
# 1. Build the HttpClient with the default configuration.
# 2. Set the timeout to 30 seconds.
# 3. Call the send method with the request object.
# 4. Check the response status code.
# 5. Read the response body into a string.
def send_request(req: Request) -> str:
    ...
```

**Code example — procedural (Bash CLI)**
```bash
# STE:
# 1. Export the API token to the TOKEN variable.
# 2. Select the staging environment with the --env flag.
# 3. Run the deploy script.
# 4. Check the build log for the success message.
```

**Code example — declarative resource (Terraform)**
```hcl
# STE:
# The aws_s3_bucket resource creates a storage bucket for application logs.
# The bucket name is "app-logs".
# The bucket keeps a version of each object that you overwrite.
# The bucket encrypts each object with the AES256 algorithm.
resource "aws_s3_bucket" "logs" {
  bucket = "app-logs"
}
```

**Paradigm guidance**
- Object-Oriented (Java, C++, C#, Python): class docs are descriptive (one short sentence, one topic); method descriptions are numbered imperative steps.
- Functional (Haskell, Elixir, Clojure, Rust): type signatures descriptive (one property per sentence); effectful functions use procedural steps.
- Procedural (C, Go, Bash): function docs are a sequence of steps; each step is one imperative sentence with one instruction.
- Declarative (SQL, Terraform, Kubernetes YAML): resource docs descriptive; describe what the configuration does, one fact per sentence.
- Systems (Rust ownership, C memory): describe invariants and ownership rules in descriptive sentences; use imperative steps only for unsafe operations.

**Edge cases**
- Generated documentation (JSDoc, Sphinx, `go doc`): apply Rule 4.1 to the source docstrings and comments; fix the source text, not the generated output.
- Single-sentence module summary: the first line conveys the purpose; expand the body with one topic per sentence.
- Safety callouts (BREAKING, DEPRECATED, NOTE): keep the callout to one short sentence; put detail in the paragraph that follows.
- Error messages: one topic; state what failed and, when useful, tell the reader how to fix it in a second sentence. Do not write a vague abstract error such as "Invalid input occurred."
- Commit messages: subject line one topic; each related change its own bullet in the body.
- README sections: one idea per paragraph; one sentence per listed feature.

**Grammar notes**
- Sentence length: max 20 words for procedural, 25 words for descriptive. Code spans, inline code, and URLs do not count.
- Imperative mood: start each procedural step with an imperative verb (call, set, pass, check, start, send, remove, add, make, use, run, build, test, deploy). Avoid "you should" / "the user must."
- Clause nesting: do not nest clauses deeper than two levels; break nested clauses into separate sentences.
- Voice: prefer active for both descriptive and procedural sentences; the subject performs the action.
- Abstract text: replace "performance may vary" with a sentence giving the measured value and the condition.

**Checklist**
- [ ] Max 20 words (procedural) / 25 words (descriptive).
- [ ] One topic or one instruction per sentence.
- [ ] Procedural sentences use the imperative mood.
- [ ] Descriptive sentences do not use the imperative mood.
- [ ] Text is not abstract; shows how to use the code.
- [ ] Each descriptive sentence states one fact in the active voice.
- [ ] Each measurable claim gives the value and the condition.

---

## Rule 4.2 — Do Not Omit Words or Use Contractions

**Requirement**
- Every sentence must have all its parts. Do not omit words or use contractions to
  make a sentence shorter; a shorter sentence is not necessarily easier to read.
- Do not omit nouns (the reader will not know which code element the sentence refers to).
- Do not omit verbs (the reader will not understand the action performed).
- Do not omit the subject (the reader will not know which function, class, or module acts).
- Do not omit articles (the, a, an); omitted articles cause ambiguity.
- Do not use contractions. Write "do not" not "don't", "is not" not "isn't",
  "are not" not "aren't", "cannot" not "can't", "will not" not "won't".

**Code examples**
- Subject: Non-STE: `Can be a maximum length of 256 characters.` → STE: `The input string can have a maximum length of 256 characters.`
- Verb: Non-STE: `The return value a boolean that indicates success.` → STE: `The return value is a boolean that indicates success.`
- Noun: Non-STE: `The function returns the parsed.` → STE: `The function returns the parsed configuration object.`
- Article: Non-STE: `` `validate` function checks input parameter. `` → STE: `The \`validate\` function checks the input parameter.`
- Contraction: Non-STE: `The method doesn't throw an exception when the input is null.` → STE: `The method does not throw an exception when the input is null.`
- Noun the verb acts on (parallel): Non-STE: `Remove the bolt and stop.` → STE: `Remove the bolt and the stop.`
- Conditional verb: Non-STE: `If installed, remove the shims.` → STE: `If shims are installed, remove them.`
- Safety subject: Non-STE: `BREAKING: MAKE SURE THAT THE DATABASE IS BACKED UP. IF NOT, THIS CAN CAUSE DATA LOSS.` → STE: `BREAKING: MAKE SURE THAT THE DATABASE IS BACKED UP. A MISSING BACKUP CAN CAUSE DATA LOSS.`

**Code example — do not omit the subject (Python docstring)**
```python
def validate_username(name: str) -> bool:
    """Check whether the user name is valid.

    The user name can have a maximum length of 256 characters.
    The user name must contain only letters, digits, and underscores.
    """
    return len(name) <= 256 and name.isidentifier()
```

**Code example — do not use a contraction (C# XML doc)**
```csharp
/// <summary>
/// Reads the next record from the stream.
/// </summary>
/// <remarks>
/// The method does not throw an exception when the input is null.
/// The method returns null when the end of the stream is reached.
/// </remarks>
public Record? ReadNext(Stream? input) { ... }
```

**Code example — contraction in a warning (README)**
```markdown
> **WARNING**
> If your hands are wet, do not touch the USB power adapter.
> The adapter supplies current that can cause injury.
> Keep the adapter away from water while it is connected.
```

**Paradigm guidance**
- Object-Oriented: method return descriptions often omit the subject — write "The method returns…"; constructor docs often omit the verb — write "The constructor creates…"; getter/setter comments often omit the article — write "The getter returns the value of the field."
- Functional (Haskell, Elixir, Clojure, F#): pattern-match docs often omit verbs — write each arm as a full sentence with a verb; type-variable descriptions often omit subjects — add "The type variable represents…"; monad-law notes often omit articles — write "The first law states that…"
- Procedural (C, Go, Bash, Rust): function synopses in headers often omit articles and subjects — write "The function reads a configuration file."; makefile/shell comments often omit the verb — write "The script removes the build directory."
- Declarative (SQL, Terraform, Kubernetes YAML, Ansible): comments and resource descriptions often omit verbs and articles — write each as a full sentence with subject and verb. For a SQL view: "The view returns the active users." For a Terraform block: "The resource creates a storage bucket."
- Systems (Rust unsafe, C memory): safety docs with omitted subjects cause real bugs. Always write subject, verb, and articles in full — e.g. "The caller must ensure that the pointer is valid."

**Edge cases**
- Commit message summary line: the 72-char limit makes full sentences hard; the summary may use a relaxed form, but the body must follow the rule strictly.
- CLI help text: terminal width causes omitted articles/subjects; long-form docs must use full sentences. CLI help may relax to `rm FILE`; the manual page must write "The command removes the file."
- Code token that is also a contraction: a token such as `won't` (test name), `can't` (variable), `it's` (map key) is a technical noun — keep it in backticks, do not expand. Write "The test `won't` checks the failure path," not "The test `will not` checks the failure path."
- Error messages and log lines: short error strings may omit articles; the docs that explain the error must use full sentences ("The error means that the connection is closed.").
- Tables and lists: a cell may hold a short phrase; the surrounding prose and the column header must supply the subject and verb. Write the header "The function returns the status code," not "Returns status."

**Grammar notes**
- Write "do not," "is not," "are not," "cannot," "will not," "does not," "did not" in full. No apostrophe contractions.
- Every sentence needs a subject, a verb, and the required articles (the, a, an).
- When you connect two nouns with "and," repeat the article if the two items are different physical or logical things: "Remove the bolt and the stop," not "Remove the bolt and stop."
- Prefer plain dictionary verbs: "check" not "verify," "make" not "create," "get" not "retrieve," "set" not "configure," "remove" not "delete" when the simpler word fits.

**Checklist**
- [ ] Every sentence has a subject, a verb, and the required articles.
- [ ] No words are omitted to make the sentence shorter.
- [ ] No contractions are used (write "do not," "is not," "are not," "cannot," "will not" in full).
- [ ] The reader knows which element performs the action.
- [ ] Parallel nouns joined by "and" each keep their article.
- [ ] Code tokens that look like contractions stay in backticks and are not expanded.

---

## Rule 4.3 — Use a Vertical List for Complex Text

**Requirement**
- When a sentence is long and lists many items (parameters, return fields, error
  codes, configuration options, environment variables, dependencies, test cases) or
  actions, put them in a vertical list.
- Put a colon (`:`) at the end of the introductory sentence, before the first item.
- Identify each item with a number, letter, dash, or bullet.
- Start each item with an uppercase letter.
- Where applicable, use an article before the noun that is the subject of each item.
- Put a period at the end of an item if it is a full sentence (e.g. an imperative
  step like "Set the timeout value"). Do not put a period at the end of a non-sentence
  item (e.g. "The `timeout` parameter that controls the delay").
- Do not put a comma or semicolon at the end of an item.
- Put a period at the end of the last item.
- Use vertical lists in procedural and descriptive docs, but do not mix imperative
  instructions and descriptive statements in the same list.
- In safety instructions, include negative commands (DO NOT) where necessary for each item.
- Each item must connect clearly to the introductory text. Test by reading
  "Introductory text [item]" as one sentence.
- Do not nest a second vertical list inside the primary list. Use the same level for
  all items. If a sub-item needs its own list, start a new introductory sentence after
  the parent item, or use a table or a separate list under a new heading.
- An item can contain a verb and not be a full sentence; then it takes no period.

**Code examples**
- Non-STE: `The UserService constructor accepts the database URL, the cache backend, and the maximum retry count.`
- STE:
```
The `UserService` constructor accepts these parameters:
- The `database_url` for the PostgreSQL connection string.
- The `cache_backend` for session storage.
- The `max_retries` for transient failure handling.
```

**Code example — constructor parameters (Python docstring)**
```python
class UserService:
    """Manage application users and their sessions.

    The UserService constructor accepts these parameters:
    - The database_url for the PostgreSQL connection string.
    - The cache_backend for session storage.
    - The max_retries for transient failure handling.
    """

    def __init__(self, database_url, cache_backend, max_retries=3):
        self.database_url = database_url
        self.cache_backend = cache_backend
        self.max_retries = max_retries
```

**Code example — procedural steps (one type only)**
```
## Deploy the application

To deploy the application, do these steps:
- Set the `DATABASE_URL` environment variable.
- Run the `apply-migrations` command.
- Start the server on port 8080.

The server binds to port 8080 after startup.
```

**Code example — error codes (HTTP API)**
- Non-STE: `The API returns 400 for validation issues, 401 when the token is expired, 403 if permissions are not sufficient, and 404 when the resource is missing.`
- STE:
```
The API returns these error codes:
- `400 Bad Request` for a failed input validation.
- `401 Unauthorized` for an expired or missing token.
- `403 Forbidden` for insufficient permissions.
- `404 Not Found` for a missing resource.
```

**Code example — safety instruction (negative command per item)**
```
CAUTION: WHEN YOU ACCESS THE CONFIGURATION THROUGH THE ADMIN PANEL:
- DO NOT CHANGE THE SECRET KEY.
- DO NOT DISABLE THE AUDIT LOG.
```

**Code example — declarative config fields (YAML)**
```
# The config.yaml file has these top-level fields:
# - The server.port that sets the listen port.
# - The log.level that sets the log verbosity.
# - The database.pool_size that sets the maximum open connections.
# - The features that lists the enabled feature flags.
server:
  port: 8080
log:
  level: info
database:
  pool_size: 20
features:
  - new_checkout
  - dark_mode
```

**Code example — function return codes (Go)**
```go
// The openFile function returns these codes:
// - 0 for a successful open.
// - -1 for a missing path.
// - -2 for insufficient permission.
func openFile(path string) (int, error) {
    if _, err := os.Stat(path); errors.Is(err, os.ErrNotExist) {
        return -1, fmt.Errorf("the path %q is missing", path)
    }
    f, err := os.Open(path)
    if err != nil {
        return -2, fmt.Errorf("the user lacks permission for %q", path)
    }
    defer f.Close()
    return 0, nil
}
```

**Other list types covered by this rule**
- Data-transfer-object fields (object has these fields: `email`, `display_name`, `role`)
- Test cases (the function passes these test cases: accept `"10s"` and return 10 seconds; …)
- Dependencies in a package manifest (`express` for HTTP routing; `pg` for PostgreSQL; `redis` for cache)
- Environment variables (the worker reads these: `LOG_LEVEL`, `QUEUE_URL`, `MAX_WORKERS`)

**Paradigm guidance**
- Object-Oriented: use a vertical list for constructor parameters, public methods, DTO fields, and exceptions a method can send.
- Functional: use a vertical list to document each variant of a sum type or each pattern-match arm.
- Procedural (C, Go, Bash): use a vertical list for function return codes; one item per code and meaning.
- Declarative (SQL, Terraform, YAML): use a vertical list for top-level fields; a separate list for sub-fields of a complex field.
- Systems (Rust, C memory): use a vertical list for ownership or lifecycle rules; one item per constraint.

**Edge cases**
- Nested fields: do not put a second vertical list inside the primary list; describe sub-fields with a new introductory sentence after the parent item, or with a table.
- Generated documentation (JSDoc, Sphinx, rustdoc) may use tables — acceptable; apply Rule 4.3 to prose a human writes.
- Very short lists: a list of two or three items under ~5 words each may stay inline; use a vertical list when each item has more than five words or the inline sentence exceeds 25 words.
- Code blocks in items: put the code block after the item text, indented under the item; the item still starts with an uppercase letter.
- Mixed code and prose: keep the item sentence first (starting uppercase), then add the code block; do not start the item with a code fence.

**Grammar notes**
- Each item must complete the introductory sentence grammatically.
- Use "the" or "a/an" consistently across all items; put the article before the backticks when the item starts with a code identifier.
- A full sentence has a subject and a finite verb. An item with only a verb phrase (e.g. "Set the timeout value") is a full imperative sentence and gets a period. An item such as "The `timeout` parameter that controls the delay" is a relative clause and gets no period until the last item.

**Checklist**
- [ ] The introductory sentence ends with a colon.
- [ ] Each item starts with an uppercase letter.
- [ ] Each item connects to the introductory text.
- [ ] No period on non-sentence items; period on the last item.
- [ ] No mixed procedural and descriptive items in one list.
- [ ] No nested vertical lists.
- [ ] Each code sample (if any) comes after its item sentence.

---

## Rule 4.4 — Use Connecting Words and Connecting Phrases

**Requirement**
- Connecting words and phrases connect a topic in one sentence with an idea in the
  sentence that follows.
- In code documentation they give the writing a logical structure and make technical
  information easy to understand.
- Approved connecting words: "and," "but," "then," "thus."
- Approved connecting phrases: "as a result," "at the same time."
- Demonstrative adjectives (this, these) also connect ideas in related sentences; they
  refer back to a topic named in the previous sentence.
- In procedural docs, use connecting words when an explanation is necessary after a work
  step. In safety instructions, use them to connect related sentences and make the text clear.
- Starting a sentence with "and" or "but" is permitted and encouraged — it creates short,
  independent sentences with an explicit logical link.

**Code examples**
- "and" (two related descriptions):
  - Non-STE: `` `parseInput` validates the request payload and `formatOutput` serializes the response, and they're both called in the handler. ``
  - STE: `The \`parseInput\` function validates the request payload. And the \`formatOutput\` function serializes the response data.`
- "but" (exception or alternative):
  - Non-STE: `These error-handling rules are the minimum necessary for the API layer, although the local project conventions may specify additional ones.`
  - STE: `These error-handling rules are the minimum necessary for the API layer. But the local project conventions can give other necessary error-handling rules.`
- "thus" (logical consequence):
  - Non-STE: `If the validation step fails, the middleware sets an error code on the response object, so the downstream handler gets it and skips processing.`
  - STE: `If the validation step fails, the middleware sets an error code on the response object. Thus, the downstream handler receives the error code and skips the processing step.`
- "as a result" (cause and effect):
  - Non-STE: `When the cache eviction policy runs, expired entries are removed, which frees up capacity for new entries.`
  - STE: `When the cache eviction policy runs, expired entries are removed from the cache. As a result, the cache has free capacity for new entries.`
- "then" (time sequence in a procedure):
  - Non-STE: `Open the database connection, after that run the migration script, and finally start the API server.`
  - STE: `Open the database connection. Then run the migration script. And then start the API server.`
- Demonstrative adjective "this" in procedures:
  - Non-STE: `Tag the deprecated methods with the @deprecated annotation; it helps developers migrate to the new API.`
  - STE: `Tag the deprecated methods with the @deprecated annotation. This annotation will help developers during the migration to the new API.`
- Safety instruction:
  - Non-STE: `Always validate user input in this module because it prevents injection attacks.`
  - STE: `BREAKING: ALWAYS VALIDATE USER INPUT IN THIS MODULE. THIS PRECAUTION WILL PREVENT INJECTION ATTACKS.`
- Missing connection (STE makes the link explicit):
  - Non-STE: `POST /users creates a new user account and returns a 201 status. The response body contains the created user object with an auto-generated ID. The ID can be used in later requests to reference this user.`
  - STE: `A POST request to /users makes a new user account. As a result, the API returns a 201 status code. And the response body contains the created user object with an auto-generated ID. You can use this ID in later requests to refer to the user.`
- "at the same time" (concurrency):
  - Non-STE: `The worker fetches the page and parses it concurrently using asyncio tasks.`
  - STE: `The worker fetches the page from the remote server. At the same time, the parser reads the response stream. And both tasks finish before the timeout.`
- "but" in an error-message description:
  - Non-STE: `The read_file function returns the contents; however, it raises PermissionError when the path is not readable.`
  - STE: `The read_file function returns the contents of the file. But it raises a PermissionError when the path is not readable.`

**Paradigm guidance**
- Object-Oriented: describe class invariants in one sentence; use "thus" to connect them to public-API behavioral guarantees; use "this" to refer to a private field; use "and" to group related methods.
- Functional: describe the input type in one sentence; use "and" to connect happy path to error path; use "thus" to connect a transformation step to the output shape.
- Procedural (C, Go, Bash): describe the allocation step in one sentence; use "then" to introduce initialization; use "as a result" to connect processing to the final state.
- Declarative (SQL, Terraform, YAML): describe the resource spec in one sentence; use "thus" to connect the spec to the reconciliation outcome; use "this" to refer to a named resource.
- Systems (Rust, C memory): describe the ownership rule in one sentence; use "thus" to connect the rule to the compiler guarantee; use "but" to introduce an unsafe escape hatch.

**Edge cases**
- Connecting word that is also a framework name: e.g. the `Then` assertion library, the Rust `and_then` combinator. When the word is a code token in backticks, treat it as a technical noun; the sentence-initial connecting word is not in backticks.
- "Then" ambiguity: use "after" for time or "thus" for logic when ambiguous (do A, then do B = time; if A, then B = logic).
- Generated code comments: this rule applies to documentation you write, not auto-generated comments. Do not edit generated comments to add connecting words.
- Connecting across three or more sentences: limit connecting-word chains to two or three sentences; if more are needed, restructure into a list or a table.
- Connecting word at the start of a section: do not use a connecting word at the very start of a new section to link it to the previous section; the heading provides the connection. Restate the topic so the section stands alone.

**Grammar notes**
- Start a sentence with "and" or "but" to create short, independent sentences with an explicit logical link.
- "Thus" and "as a result" sit at the start of the second sentence; do not use a semicolon before "thus."
- "This" and "these" are demonstrative adjectives when they modify a noun ("this function," "these parameters"); prefer the adjective form with an explicit noun to remove ambiguity.
- When you connect two sentences with "and," keep the two sentences parallel in structure.

**Checklist**
- [ ] Each connecting word links a sentence to the one that follows.
- [ ] Only approved connecting words and phrases are used.
- [ ] Demonstrative adjectives refer back to a clearly introduced topic.
- [ ] No mixed procedural and descriptive modes inside one connected pair.
- [ ] Connecting-word chains do not exceed three sentences.

---

## Rule 4.5 — Use an Article or a Demonstrative Adjective Before a Noun

**Requirement**
- Articles ("the," "a," "an") and demonstrative adjectives ("this," "these") show the
  position of nouns in the sentence. Use them correctly; do not remove them to shorten text.
- Do not use an article in a general statement or before an abstract concept
  ("performance," "scalability," "error handling," "concurrency," "backward compatibility").
- In short sentences, use an article before each noun.
- In a long series of items, use the article only before the first noun in the series.
- When an adjective applies to only one item in a series, repeat the article before each
  item to avoid ambiguity.
- Do not use a definite article before a noun when a code identifier follows it — the
  identifier makes the noun phrase a proper noun (function, class, variable, file,
  environment variable, error code, version tag).
- Use a demonstrative adjective ("this," "these") to connect a noun to the topic of the
  previous sentence; always keep the noun after it — do not write "this" or "these" alone.

**Code examples**
- Article in a short instruction:
  - Non-STE: `Call callback function. Pass response object to handler and set retry flag.`
  - STE: `Call the callback function. Pass the response object to the handler. Then set the retry flag.`
- API reference sentence:
  - Non-STE: `Method reads configuration file and returns settings object.`
  - STE: `The \`load\` method reads the configuration file and returns the settings object.`
- No article in a general statement:
  - Non-STE: `The error handling is important for the production applications. A function throws the error when the input is not valid.`
  - STE: `Error handling is important for production applications. The function throws an error when the input is not valid.`
- Article only before the first noun in a long series:
  - Non-STE: `Delete temporary files, log files, cache entries, and lock files before you start the build.`
  - STE: `Delete the temporary files, log files, cache entries, and lock files before you start the build.`
- Article before each noun when an adjective applies to only one item:
  - Non-STE: `Register the new event listeners, timers, subscriptions, and cleanup callbacks.`
  - STE: `Register the new event listeners, the timers, the subscriptions, and the cleanup callbacks.` (Only the event listeners are new.)
- No article before a noun with a code identifier:
  - Non-STE: `Call the function \`validateInput\` before you send the request.` → STE: `Call function \`validateInput\` before you send the request.` (or `Call the \`validateInput\` function …`)
  - Non-STE: `Set the variable \`LOG_LEVEL\` to \`debug\`.` → STE: `Set variable \`LOG_LEVEL\` to \`debug\`.`
  - Non-STE: `Install the version 3.2.1 of the package.` → STE: `Install version 3.2.1 of the package.`
- Demonstrative adjective for sentence linking:
  - Non-STE: `The function returns a configuration object. Configuration object has three fields: host, port, and timeout.`
  - STE: `The function returns a configuration object. This object has three fields: \`host\`, \`port\`, and \`timeout\`.`
- Article in a commit message / release note:
  - Non-STE: `Fix race condition in scheduler; worker pool now waits for queue drain.`
  - STE: `Fix the race condition in the scheduler. The worker pool now waits for the queue to become empty.`
- Article in an error message / test description:
  - Non-STE: `Input not valid: field must be string.` → STE: `The input is not valid. The \`name\` field must be a string.`
  - Non-STE: `Test verifies handler returns 404 when record missing.` → STE: `The test checks that the handler returns the status code 404 when the record is not in the database.`

**Paradigm guidance**
- Object-Oriented (Java, C#, Python, TypeScript): use an article to separate a class (the type) from an instance (the value): "The `ConnectionPool` class manages a pool of database connections. Each instance keeps a list of open connections." No article directly before a bare identifier: "Call `connect`."
- Functional (Haskell, Elixir, F#, Scala): use an article to separate a type constructor from a value: "The `Ok(value)` pattern shows a successful result. A `Result` value is either `Ok` or `Err`." Write concepts ("immutability," "referential transparency") with no article.
- Procedural (C, Go, Bash): use an article to separate a pointer from the value at the address: "The function receives a pointer to a buffer. The buffer must hold at least 512 bytes."
- Declarative (SQL, Terraform, YAML, Kubernetes): use an article to separate a resource type from a resource instance: "A `Deployment` resource manages a set of pods. The `web` deployment runs three replicas." No article before a named resource: "Apply manifest `web-deployment.yaml`."
- Systems (Rust, C memory, embedded): use an article to make ownership and lifetime relationships clear: "The pointer must point to an initialized region of memory. A borrow of the value must not outlive the owner."

**Edge cases**
- Identifier as a proper noun compared with a concept: `ConnectionPool` alone is a proper noun (no article); "The `ConnectionPool` class" takes "the" because "class" is the noun. "Call `initialize`" takes no article; "The `initialize` function" takes "the" because "function" is the noun.
- "a" compared with "an": use "an" before a vowel sound (an SQL query, an HTML element, an XML parser, an ID, an API key); use "a" before a consonant sound (a URL, a Unix system, a UUID, a JSON payload, a `User` record). Match the usual pronunciation.
- Headings, titles, and table cells: may omit the article; the first sentence below the heading must obey the full rule.
- Product / framework names that start with "The" (e.g. `TheMovieDB`): treat as a proper noun; the leading "The" is part of the identifier, not an article.
- Plural types used as a general statement: "Iterators are lazy in this library" is general (no article); "The iterator stops at the end of the sequence" refers to one identifiable item (uses "the").
- Code samples and command lines: do not add an article inside a code block, command, or log line; this rule applies to prose only.
- Acronyms that expand to a different sound: choose the article for the spoken form (write "an API", not "a API").
- Uncountable technical nouns: "memory," "throughput," "latency," "state" take no indefinite article ("The function allocates memory", not "The function allocates a memory").

**Grammar notes**
- "A" refers to any instance of a type; "the" refers to one specific, identifiable item; no article refers to the type or concept as a whole.
- First mention uses "a" ("The method throws a `ValidationError`"); later mentions use "the" ("The `ValidationError` contains a message field").
- Proper-noun exception: a code identifier is a proper noun — do not put a definite article directly before it ("Call `connect`" correct; "Call the `connect`" not correct).
- Demonstrative adjectives keep their noun: write "this object" or "these headers"; do not write "this" or "these" alone as a pronoun.
- Multi-word nouns: put the article before the full multi-word noun ("the retry policy object", not "retry the policy object").
- Possessive forms replace the article ("its return value" and "the return value of the method" are both correct; do not write "the its return value").

**Checklist**
- [ ] Articles and demonstrative adjectives are used correctly and not removed to shorten text.
- [ ] No article appears before a general statement or an abstract concept.
- [ ] Short sentences use an article before each noun.
- [ ] A long series uses the article only before the first noun, unless an adjective applies to one item only.
- [ ] No definite article appears directly before a code identifier used as a proper noun.
- [ ] "a" and "an" match the spoken sound of the term that follows.
- [ ] Each demonstrative adjective is followed by a noun and refers to one clear topic.



## rules-sec5.md

# Level 3 — Section 5: Procedural Writing Rules (5.1–5.5)

Scope: how to write procedures in code documentation — README steps, quickstarts,
runbooks, API walkthroughs, docstrings, commit messages, error messages, and CLI help.

Section 5 has five rules:

| Rule | Requirement | One-line test |
| --- | --- | --- |
| 5.1 | Maximum 20 words in a procedural sentence (25 in a note) | Count the words. |
| 5.2 | One instruction per sentence | Count the imperative verbs. |
| 5.3 | Write instructions in the imperative (command) form | Does the sentence start with a base-form verb? |
| 5.4 | Put the condition first, then a comma, then the command | Is the condition before the comma? |
| 5.5 | Notes give information only, never instructions | Can the reader finish the task with the notes removed? |

Counting conventions used throughout Section 5:

- Code blocks, terminal output, and string literals are excluded from word counts.
- A code token inside backticks counts as one word, whatever its length
  (`Result<T, E>` = 1 word; `async fn` = 2 words).
- Hyphenated compounds count as one word (`command-line` = 1 word).
- Numbers, symbols, and parenthetical references count as one word each
  (`(2)` = 1 word; `HTTP/2` = 1 word).
- Procedural sentence: 20-word limit. Descriptive sentence and note: 25-word limit.

---

## Rule 5.1 — Short Sentences (Maximum 20 Words)

> Source: ASD-STE100 Issue 9, Rule 5.1

### Rule

Write short sentences. Use a maximum of 20 words in each procedural sentence.
Warnings and cautions obey the same 20-word limit. Notes (Rule 5.5) may use up
to 25 words per sentence, because notes give information only.

In code documentation, procedures include installation instructions, setup steps,
deployment checklists, debugging workflows, and API usage guides. The reader
executes commands while reading. Long sentences cause skipped actions.

### Apply

- Break a long procedural sentence into shorter sentences. Each sentence covers
  one part of the task.
- Split at the coordinating conjunction. Start the next sentence with
  `Then,`, `Next,`, or `After that,`.
- Move a condition into its own sentence (see Rule 5.4).
- Separate the action from its purpose: instruction first, reason second.
- Convert an enumeration into a bulleted or numbered list. List items are not
  sentences and are not subject to the 20-word limit, but keep them short.

### Examples

> **Non-STE:** Run the database migration script from the project root directory and then restart the application server to apply all pending schema changes to the production environment. (27 words)
>
> **STE:** Run the database migration script from the project root directory. (9 words) Then, restart the application server to apply all pending schema changes. (13 words)

```bash
cd /srv/payments-service
alembic upgrade head
systemctl restart payments.service
```

> **Non-STE:** Set the environment variable HTTP_TIMEOUT to the value 30000 which represents the maximum number of milliseconds that the client will wait for a response from the upstream server. (30 words)
>
> **STE:** Set the environment variable HTTP_TIMEOUT to 30000. (8 words) This value is the maximum wait time in milliseconds for a response from the upstream server. (17 words)

```bash
export HTTP_TIMEOUT=30000
```

> **CAUTION:** IF YOU DELETE THE CONFIGURATION DIRECTORY WITHOUT A BACKUP, YOU CANNOT RESTORE THE APPLICATION SETTINGS TO THEIR PREVIOUS STATE. (18 words)

```bash
cp -r ./config ./config.bak   # back up first
rm -rf ./config               # then delete
```

> **Non-STE:** For more detailed information about the supported authentication methods and their respective configuration parameters in this release, please refer to the official authentication module documentation page. (27 words)
>
> **STE (note, 25-word limit):** For more information about the supported authentication methods, refer to the authentication module documentation. (15 words)

### By document type

**README files.** Installation and quick-start steps. One instruction per step,
each step a command the reader can copy.

> **Non-STE:** Clone the repository to your local machine using the command shown below and then navigate into the newly created project directory before running the setup script. (28 words)
>
> **STE:** Clone the repository to your local machine. (6 words) Then, navigate into the new project directory. (7 words) Run the setup script. (4 words)

```bash
git clone https://github.com/example/payments-service.git
cd payments-service
./setup.sh
```

**API documentation.** Parameter descriptions in tables are descriptive: 25 words.
Setup, authentication, and request-sequencing sentences are procedural: 20 words.

> **Non-STE:** The `page` query parameter accepts a positive integer value that specifies which page of results the server should return in the paginated response to this endpoint. (28 words)
>
> **STE:** The `page` query parameter accepts a positive integer. (8 words) It specifies which page of results to return. (9 words) This is for paginated responses. (6 words)

```http
GET /v1/orders?page=2&page_size=50 HTTP/1.1
Host: api.example.com
Authorization: Bearer ***
```

**Docstrings and inline comments.** Procedural sentences for callers: 20 words.
Return-value and side-effect descriptions: 25 words.

> **Non-STE:** Call this method to initialize the connection pool with the provided configuration and establish the minimum number of idle connections specified in the pool settings before returning control to the caller. (32 words)
>
> **STE:** Call this method to initialize the connection pool. (8 words) Use the provided configuration. (4 words) The method establishes the minimum number of idle connections. (10 words) Then, it returns control to the caller. (8 words)

```python
def init_pool(config: PoolConfig) -> ConnectionPool:
    """Initialize the connection pool.

    Use the provided configuration. The method establishes the minimum
    number of idle connections. Then, it returns control to the caller.
    """
    ...
```

**Commit messages.** Keep the subject line to 72 characters or fewer; this is a
separate constraint from the word count. Body: 20 words for procedural sentences,
25 for descriptive ones.

> **Non-STE:** Refactored the authentication middleware to extract the token validation logic into a separate utility function so that it can be reused by the WebSocket upgrade handler and the GraphQL subscription resolver as well. (35 words)

```text
Refactor authentication middleware

Extracted the token validation logic into a separate utility function.
The WebSocket upgrade handler and the GraphQL subscription resolver now
reuse this function.
```

**Error messages.** Read under stress. Actionable messages: 20 words. Messages that
only report a condition: 25 words. Separate the diagnosis from the remedy.

> **Non-STE:** The configuration file could not be parsed because it contains a syntax error on line 42 that is most likely caused by a missing closing bracket or an unquoted string value containing special characters. (35 words)
>
> **STE:** The configuration file has a syntax error on line 42. (11 words) Check for a missing closing bracket or an unquoted string value. (13 words)

```text
Config error on line 42: missing closing bracket or unquoted string.
```

### By paradigm

**Object-oriented (Java, C++, C#, Python classes).** Do not describe all
constructor parameters in one sentence. Give each parameter its own sentence.

> **Non-STE:** The constructor accepts a database connection string, a logger instance that must implement the ILogger interface, and an optional configuration object for setting the retry policy and the connection timeout duration. (33 words)
>
> **STE:** The constructor accepts three parameters. Parameter one is a database connection string. Parameter two is a logger instance. It must implement the ILogger interface. Parameter three is an optional configuration object. Use this object to set the retry policy and the connection timeout.

```csharp
public DatabaseClient(
    string connectionString,
    ILogger logger,
    ClientConfig? config = null
) { ... }
```

**Functional (Haskell, Elixir, Clojure, Rust).** Give each stage of a composition
pipeline its own sentence, so the reader traces one transformation at a time.

> **Non-STE:** The `process` function first maps the transformation over each element in the list and then filters out any results that are `None` before finally folding the remaining values into a single accumulator using the provided binary operator. (35 words)
>
> **STE:** The `process` function maps a transformation over each element in the list. Then, it filters out any `None` results. Finally, it folds the remaining values into a single accumulator. The provided binary operator controls the fold.

```haskell
process :: (a -> b) -> (b -> Bool) -> (b -> b -> b) -> [a] -> b
process f p op = foldl1 op . filter p . map f
```

**Procedural (C, Go, Bash).** Do not combine an error check with the operation
being checked. Do not describe conditional branching in prose.

> **Non-STE:** Run the configure script to detect your system's available libraries and compiler features and then run make with the -j flag set to the number of CPU cores on your machine to compile the program from source. (37 words)
>
> **STE:** Run the configure script. This script detects your system libraries and compiler features. Then, run make to compile the program from source. Use the -j flag. Set it to the number of CPU cores on your machine.

```bash
./configure
make -j"$(nproc)"
```

**Declarative (SQL, Terraform, Kubernetes YAML).** Do not describe a resource and
all its attributes in one sentence. Check prerequisites before the action.

> **Non-STE:** Execute the migration script against the production database after taking a full backup and verifying that the replication lag on all read replicas is less than five seconds to prevent any data inconsistency during the schema change. (38 words)
>
> **STE:** Take a full backup of the production database. Verify that the replication lag on all read replicas is less than five seconds. Then, execute the migration script against the production database.

```bash
pg_dump "$PROD_DSN" > backup_$(date +%F).sql
REPLICA_LAG=$(psql "$PROD_DSN" -t -c "SELECT EXTRACT(SECONDS FROM now() - pg_last_xact_replay_timestamp());")
[ "$(echo "$REPLICA_LAG < 5" | bc)" -eq 1 ] && alembic upgrade head
```

**Systems (Rust ownership, C memory management).** Never bury a hazard in a
subordinate clause. Prohibition, reason, and consequence each get a sentence.

> **Non-STE:** After calling this function the caller must not use the original buffer pointer because ownership of the memory has been transferred to the callee and any subsequent access through the old pointer will result in undefined behavior. (37 words)
>
> **STE:** After you call this function, do not use the original buffer pointer. Ownership of the memory is transferred to the callee. Access through the old pointer causes undefined behavior.

```rust
fn take_buffer(buf: Vec<u8>) -> Parser {
    // buf is moved into Parser; the caller's buf is no longer valid.
    Parser::new(buf)
}
```

### Edge cases

1. **Long framework or service names.** Use the shortest accepted form on first
   use, define an abbreviation, then use the abbreviation. The abbreviation counts
   as one word. (`Amazon Web Services Elastic Kubernetes Service` → `Amazon EKS`.)
2. **Code keywords that form long phrases.** A backticked token is one word. Do
   not expand generics or type parameters into prose words.
3. **Generated documentation.** Apply the rule to the source docstrings the
   generator reads; the output inherits compliance. Do not edit generated output —
   fix the source. If the source is third-party, apply the 25-word descriptive
   limit and record the exception in the project style guide.
4. **Legal and compliance text.** Not procedural; the 20-word limit does not apply.
   Keep it in a separate "Legal" section or a `NOTE (legal requirement):` block.
5. **Multi-line code examples in prose.** The code block is not counted. The
   introducing sentence and the following sentence each obey the limit
   independently.

### Grammar notes

- A sentence ends with `.`, `?`, or `!`. A comma does not end a sentence.
- Do not join independent clauses with a comma (no comma splices).
- Do not use semicolons to join independent clauses. Use periods.
- Coordinating conjunctions (and, but, or, nor, for, so, yet) may join two short
  clauses only when the total stays at or below 20 words.
  Allowed: `Run the tests and check the output.` (8 words)
- Limit subordinate clause depth to two levels. Flatten deeper structures into
  separate sentences.

> **Non-STE:** The server returns an error when the client sends a request that contains a payload that exceeds the limit that the administrator configured in the settings file. (27 words, 4 levels)
>
> **STE:** The server returns an error when the request payload exceeds the configured limit. The administrator sets this limit in the settings file.

```python
MAX_PAYLOAD = settings["max_payload_bytes"]  # set by the administrator

def handle(req):
    if len(req.body) > MAX_PAYLOAD:
        raise PayloadTooLarge(settings["max_payload_bytes"])
```

### Checklist — Rule 5.1

- [ ] Every procedural sentence has 20 words or fewer.
- [ ] Every note sentence has 25 words or fewer.
- [ ] Warnings and cautions obey the 20-word limit.
- [ ] No comma splices; no semicolons joining independent clauses.
- [ ] Long sentences are split at conjunctions or condition boundaries.
- [ ] Code blocks, terminal output, and string literals are excluded from counts.
- [ ] Backticked code tokens count as one word each.
- [ ] Long technical names are abbreviated after first definition.
- [ ] Generated documentation is fixed at the source level.
- [ ] Subordinate clauses stay within two levels of depth.

> **See also:** Rule 5.2, Rule 5.3, Rule 5.5, Rule 1.1, Rule 1.9, Rule 1.12, Section 8 (word count).

---

## Rule 5.2 — One Instruction Per Sentence

> Source: ASD-STE100 Issue 9, Rule 5.2

### Rule

Write only one instruction in each sentence, unless two or more actions occur at
the same time. Show the sequence of the work steps clearly, usually with numbers
or letters. A procedure may have as many work steps as it needs.

When a sentence carries several instructions, the reader can skip an action. In
code documentation, a skipped action causes a broken configuration, a failed
deployment, or a debugging session that starts from a wrong state.

### Apply

- One instruction for the reader to perform per sentence.
- Use a numbered list to show sequence.
- Join two instructions with "and" only when both actions occur at the same
  moment and cannot be separated.
- You may write more than one sentence in a single work step when:
  - two or more actions occur at the same time and are inseparable, or
  - a result, limit, or measurement follows the action immediately.

Actions that occur at the same time (one sentence is correct):

- Hold the Shift key and click the Reload button.
- Press and release the reset button on the device.
- Copy and replace the existing configuration file.
- Download and extract the archive to the target directory.

### Examples

> **Non-STE:** Open the configuration file in a text editor and locate the database section and change the connection string to point to the staging server and then save the file and close the editor. (37 words, 5 instructions)
>
> **STE:** (1) Open the configuration file in a text editor. (2) Locate the database section. (3) Change the connection string to point to the staging server. (4) Save the file. (5) Close the editor.

```markdown
## Point the app at the staging database

1. Open `config/database.toml` in a text editor.
2. Find the `[database]` section.
3. Set `connection_string = "postgres://staging-db:5432/app"`.
4. Save the file.
5. Close the editor.
```

> **Non-STE:** Run the test suite with the coverage flag enabled and verify that the total line coverage is above 80 percent across all modules in the project. (27 words)
>
> **STE:** Run the test suite with the coverage flag enabled. (9 words) The total line coverage must be more than 80 percent across all project modules. (14 words)
>
> (The second sentence states the result limit. The work step is one action and is not divided.)

```markdown
## Run the tests

Run the suite with coverage:

    pytest --cov=src --cov-report=term-missing

The total line coverage must be more than 80 percent across all project modules.
```

> **Non-STE:** Make sure the environment variable DATABASE_URL is set correctly and then execute the initialization script to create the required database tables and populate them with the seed data. (31 words)
>
> **STE:** Make sure that the environment variable DATABASE_URL is set correctly. Then, execute the initialization script. The script creates the required database tables and populates them with the seed data.
>
> (The check and the execution form one continuous work step. The third sentence describes what the script does.)

```markdown
## Set up the local database

Make sure that the `DATABASE_URL` environment variable is set correctly:

    export DATABASE_URL="postgres://localhost:5432/app"

Then, run the initialization script:

    python scripts/init_db.py

The script creates the required tables and loads the seed data.
```

> **Non-STE:** Set the logging level to debug mode and then restart the application server and after that monitor the log output in the terminal for any error messages that appear during the startup sequence. (35 words)
>
> **STE:** (1) Set the logging level to debug. (2) Restart the application server. (3) Monitor the terminal log output for error messages during the startup sequence.

```markdown
## Debug a slow startup

1. Set the logging level to debug in `config/logging.yaml`.
2. Restart the application server: `systemctl restart app-server`.
3. Watch the log output: `journalctl -u app-server -f`.
```

### By document type

- **README files.** Quick-start sections are the most common violation site.
  Turn each verb into its own numbered step, so the reader can copy one command
  at a time.
- **API documentation.** Split authentication, request construction, and response
  handling into separate steps. Do not fold "get a token" into "call the endpoint".
- **Docstrings.** A usage section is a procedure. One call per sentence. Describe
  the return value in its own sentence.
- **Commit messages.** The body may list several changes, but each sentence
  describes one change. Use a bulleted list when the change has several parts.
- **Error messages.** When a failure has several remedies, give each remedy its
  own sentence, not one chained sentence.

### By paradigm

**Object-oriented.** Instantiation guides, dependency injection setup, and mock
configuration all chain method calls. Give each call its own step.

**Functional.** Do not chain "map, then filter, then fold" as one instruction to
the reader. Document each stage separately.

**Procedural (C, Go, Bash).** Comments in build scripts often compress three
actions into one line.

```bash
# Non-STE
# Download the latest release binary, verify its checksum, and move it to
# /usr/local/bin.

# STE
# Download the latest release binary.
curl -LO https://example.com/tool.tar.gz
# Verify the checksum of the downloaded binary.
sha256sum -c tool.tar.gz.sha256
# Move the binary to /usr/local/bin.
sudo mv tool /usr/local/bin/
```

**Declarative (SQL, Terraform, Kubernetes YAML).** A resource comment that lists
every attribute in one sentence violates the rule.

```hcl
# Non-STE
# Creates an S3 bucket with versioning enabled, a lifecycle policy to
# delete old objects after 30 days, and a private ACL.

# STE
# This resource creates an S3 bucket.
# It enables versioning on the bucket.
# It configures a lifecycle policy to delete objects after 30 days.
# It sets the bucket ACL to private.
```

**Systems (Rust ownership, C memory model).** Allocation, use, and release are
three instructions. Never combine them, because a missed step causes a leak or
undefined behavior.

### Edge cases

1. **A framework CLI command that looks like several instructions.** One command
   the reader runs is one instruction, even when the tool performs many actions
   internally. `npx create-next-app --typescript --eslint` is one step.
2. **Error messages with several root causes.** Give one sentence per cause and
   one sentence per remedy. Do not chain them with "or".
3. **Generated or auto-formatted documentation.** Fix the source comment. The
   generator inherits compliance from its input.
4. **Multi-step test assertions.** A test that asserts several conditions is one
   work step for the reader ("Run the test"), but the documented assertions are
   listed one per line.
5. **Console log messages during a multi-step operation.** Each log line reports
   one completed action. Do not report two actions in one line.

### Grammar notes

**Single predicate rule.** Each imperative sentence has exactly one main verb in
the imperative mood.

- Correct: `Install the package.`
- Incorrect: `Install the package and configure the settings.`

**Simultaneous action exception.** Two predicates may share a sentence when the
actions occur at the same moment. Test: if you can insert a pause between the
actions, they are sequential and must be split.

- Simultaneous (allowed): `Hold the Shift key and click the Reload button.`
- Sequential (split): `Install the package and run the tests.`

**Result clause separation.** Move a result clause introduced by "until", "so
that", "to", or "such that" into its own sentence.

- Before: `Run the migration until the output shows "Migration complete".`
- After: `Run the migration. Continue until the output shows "Migration complete".`
- Before: `Set the timeout to 30 seconds so that the connection does not hang.`
- After: `Set the timeout to 30 seconds. This prevents the connection from hanging.`

**Compound objects are not compound instructions.** One verb with several objects
is one instruction.

- Allowed: `Remove the log files, cache files, and temporary directories.`
- Not allowed: `Remove the log files and restart the server.`

**The "-ing" form prohibition.** Gerund phrases hide implied instructions.

- Before: `After installing the package, configuring the environment, and setting up the database, run the application.`
- After:

```text
(1) Install the package.
(2) Configure the environment.
(3) Set up the database.
(4) Run the application.
```

**Subordinate clauses and instruction count.** If a subordinate clause contains an
action the reader must perform, that action is an instruction and needs its own step.

- Before: `Before you run the tests, set the TEST_MODE environment variable to true.`
- After: `(1) Set the TEST_MODE environment variable to true. (2) Run the tests.`
- Before: `After the build completes, deploy the artifact to the staging server.`
- After: `(1) Wait for the build to complete. (2) Deploy the artifact to the staging server.`

### Checklist — Rule 5.2

- [ ] Each procedural sentence has exactly one imperative verb.
- [ ] Sequences use numbered or lettered steps.
- [ ] "and" joins two verbs only for simultaneous, inseparable actions.
- [ ] Result and limit clauses are separate sentences inside the same step.
- [ ] No gerund phrase hides an instruction.
- [ ] No subordinate clause hides a precondition action.

> **See also:** Rule 5.1, Rule 5.3, Rule 5.5, Rule 1.1, Rule 1.12, Rule 1.13.

---

## Rule 5.3 — Imperative (Command) Form for Instructions

> Source: ASD-STE100 Issue 9, Rule 5.3

### Rule

Write instructions in the imperative (command) form. Start each procedural
instruction with a base-form verb.

Other sentence forms cause ambiguity. The reader cannot tell whether a work step
is required, whether somebody else already did it, or whether the system does it
automatically.

Common imperative verbs in code documentation: run, set, open, save, install,
configure, restart, execute, copy, delete, create, add, enter, select, click,
type, check, build, push, test.

Do not use:

- passive voice (`The file is saved.`)
- gerunds as main verbs (`Saving the configuration before deployment.`)
- modal verbs for instructions (can, could, should, may, might, would)
- indirect phrasing (`It is recommended that you...`, `You are to...`)
- `must` before an imperative in a standard instruction

Reserve `must` for security warnings, data-loss cautions, and safety-critical
conditions.

| Do not write: | Before you remove the cache directory, you must stop the service. |
| --- | --- |
| WRITE: | Before you remove the cache directory, stop the service. |
| STE (safety): | WARNING: IF YOU MUST STORE USER PASSWORDS, ALWAYS HASH THEM WITH BCRYPT. DO NOT STORE PASSWORDS IN PLAIN TEXT. |

### Core examples

> **Non-STE:** The test can be continued.
>
> **STE:** Continue the test.

> **Non-STE:** The old log files are to be removed before the new deployment.
>
> **STE:** Remove the old log files. Then, start the deployment.

> **Non-STE:** The configuration file should be validated against the schema before the application is started.
>
> **STE:** Validate the configuration file against the schema. Then, start the application.

> **Non-STE:** The SSL certificate must be renewed and then the web server must be restarted to apply the changes.
>
> **STE:** Renew the SSL certificate. Then, restart the web server to apply the changes.

> **Non-STE:** It is recommended that you create a backup of the database before running the migration script.
>
> **STE:** Before you run the migration script, create a backup of the database.

### By document type

**README files.** A setup section is instructional; an about section is descriptive.
Do not mix the two moods inside a numbered list.

```markdown
## Setup

1. Install the dependencies with `npm install`.
2. Copy `.env.example` to `.env`.
3. Start the development server with `npm run dev`.
```

**API documentation.** Quickstarts use the imperative. Endpoint behavior is
descriptive: `The endpoint returns a 201 status code.`

**Docstrings and inline comments.** A comment that tells the reader (or the next
maintainer) to act uses the imperative.

```dockerfile
# Build the production Docker image.
docker build -t myapp:prod .
```

**Commit messages.** Write the subject line in the imperative, as an instruction
to the codebase.

```text
# Non-STE commit log
Fixed the login bug
Adding retry logic

# STE commit log (git log --oneline)
Fix the login redirect loop
Add retry logic to the payment client
```

**Error messages.** Describe the failure in the descriptive mood, then give the
recovery step in the imperative.

```text
# Non-STE: a bare, unrecoverable string
ERROR: bad config

# STE: failure, then instruction
Config error on line 42: missing closing bracket. Fix the syntax, then restart the service.
```

### Grammar notes

**Subject omission.** The imperative omits "you". The implied subject is always
the reader, so there is no ambiguity about who acts. Passive constructions hide
the agent. Gerunds function as nouns and describe an action as a concept, not as
a directive.

**Modal verb elimination.** Modals express possibility, permission, or
recommendation. In instructions they create doubt. `You can set the timeout to 30
seconds` reads as optional; `Set the timeout to 30 seconds` does not. `Must` is
redundant before an imperative, because the imperative already conveys necessity.

**Tense consistency.** The imperative uses the base verb form. It does not inflect
for tense, number, or person. This helps translation, machine processing, and
non-native readers.

**Coordination with Rule 5.4.** A descriptive statement may set the context before
the imperative command. Each sentence then has a distinct grammatical role.

```bash
# Descriptive: states a required condition.
# The Docker daemon must be running.
# Imperative: gives the action.
docker build -t myapp:dev .
```

### By paradigm

**Object-oriented.** Setup and configuration use the imperative. Class invariants,
inheritance hierarchies, and design rationale stay descriptive.

> **Non-STE:** An instance of the DatabaseConnection class can be created by calling the static factory method `create`, and you should pass a valid connection string.
>
> **STE:** Create an instance of the `DatabaseConnection` class with the static factory method `create`. Pass a valid connection string.

**Functional.** Project setup, build tool usage, and REPL walkthroughs use the
imperative. Function descriptions stay declarative, because they describe
transformations rather than commands to the reader.

> **Non-STE:** You should apply `map` to transform the list and then you can pipe the result into `filter`.
>
> **STE:** Apply `map` to transform the list. Then, pipe the result into `filter`.

NOTE: When you document a function that the reader must call, the imperative form
is correct. When you document what a function does internally, the descriptive
form is correct.

**Procedural (C, Go, Bash).** Build steps, compile flags, and linking instructions
are all reader actions, so the imperative dominates.

> **Non-STE:** The binary can be compiled with `gcc -O2 -Wall main.c -o tool` and then you are to place it in `/usr/local/bin`.
>
> **STE:** Compile the binary with `gcc -O2 -Wall main.c -o tool`. Then, move the binary to `/usr/local/bin`.

**Declarative (SQL, Terraform, Kubernetes YAML).** The manifest itself is
descriptive: it states desired state. The operator workflow that applies the
manifest is imperative.

```bash
kubectl apply -f deployment.yaml
kubectl rollout status deployment/web
```

**Systems (Rust ownership, C memory management).** Safety instructions use the
imperative and, when the consequence is severe, the `must` form inside a WARNING.

```text
WARNING: DO NOT USE THE BUFFER POINTER AFTER YOU MOVE THE BUFFER.
ACCESS AFTER A MOVE CAUSES UNDEFINED BEHAVIOR.
```

### Extended examples

**Gerund as instruction (Docker docs).**

```text
# Non-STE (reads like a status, not an action)
# Building the image with --no-cache to ensure a clean build.

# STE (direct command the reader runs)
# Build the image with --no-cache to make sure that the build is clean.
docker build --no-cache -t myapp .
```

**Passive voice in a pipeline step (CI/CD docs).** Describe what the pipeline does
in the descriptive mood; give the local runbook in the imperative.

```text
# Descriptive: system behavior
# The CI pipeline runs the test suite after each push to the main branch.

# STE (local runbook for the reader)
# To run the tests locally, run npm test.
```

**"Must" misuse in a standard procedure (database migration).**

```text
# STE (deploy checklist)
Before you deploy to production:
  back up the database
  run the migration script
  notify the on-call engineer
```

**Indirect phrasing in a README (open-source project).**

```markdown
## Contributing

1. Fork the repository.
2. Create a feature branch from `main`.
3. Add tests for your change.
4. Open a pull request.
```

**Conditional imperative in a security-critical context.**

```text
# Non-STE
# When handling user passwords, you should hash them with bcrypt
# and you must never store them in plain text.

# STE
# WARNING: IF YOU MUST STORE USER PASSWORDS, ALWAYS HASH THEM WITH BCRYPT.
# DO NOT STORE PASSWORDS IN PLAIN TEXT. PLAIN-TEXT PASSWORDS CAN CAUSE DATA BREACHES.
```

### Edge cases

1. **A framework name that is also a verb.** `React`, `Express`, `Spring`, `Build`,
   `Watch` are technical code nouns (Rule 1.5) when they name a product. They do
   not turn a descriptive sentence into an instruction.
2. **Generated code and tool output.** Write `--help` text in the imperative at
   the source. Do not post-edit the generated output.
3. **Code keywords that conflict with the rule.** A keyword such as `return`,
   `import`, or `yield` inside backticks is a code token, not the sentence verb.
4. **Release notes and changelogs.** These describe completed work, so they use
   the past or descriptive form, not the imperative. Migration instructions inside
   a release note do use the imperative.
5. **Interactive tutorials and walkthroughs.** Exploratory prompts are acceptable
   in a tutorial. Reference documentation, README files, and API specifications
   follow the rule strictly.

### Checklist — Rule 5.3

- [ ] Every instruction starts with a base-form imperative verb.
- [ ] No passive voice in a procedural sentence.
- [ ] No gerund used as a main verb in an instruction.
- [ ] No modal verb (can, should, may, might) used to give an instruction.
- [ ] `must` appears only in WARNING or CAUTION content, or in a critical condition.
- [ ] Descriptive statements about system behavior stay in the descriptive mood.

> **See also:** Rule 5.1, Rule 5.2, Rule 5.4, Rule 5.5, Rule 1.5, Rule 7.1.



## rules-sec6.md

# Level 3 — Section 6: Sentence and Paragraph Structure

This slice covers STE-Code Rules 6.1 through 6.6. It is the structural layer of
the standard: how to shape sentences and paragraphs in code documentation so that
a developer can read and understand it on the first pass.

These rules apply to every form of code documentation: README files, API reference
docs, docstrings, inline comments, commit messages, error messages, log entries,
changelogs, and configuration files.

## How to use this slice

- Apply the rules in order 6.1 → 6.2 → 6.3 → 6.4 → 6.5 → 6.6. Each refines the
  output of the previous one.
- 6.1 splits compound thoughts into one subject per sentence.
- 6.2 threads key words through the resulting sentences so they stay connected.
- 6.3 keeps every sentence at 25 words or fewer.
- 6.4 groups related sentences into paragraphs that open with a topic sentence.
- 6.5 keeps each paragraph to a single topic.
- 6.6 keeps each paragraph to six sentences or fewer.

## Rules at a glance

| Rule | One-line requirement | Hard limit |
|------|----------------------|------------|
| 6.1 Give Information Gradually | One subject per sentence; introduce one fact at a time. | No compound multi-subject sentences. |
| 6.2 Use Key Words and Key Phrases | Repeat the key term across sentences; use approved connectors. | Connectors from the approved set only. |
| 6.3 Write Short Sentences | Keep each sentence short and single-idea. | 25 words maximum per sentence. |
| 6.4 Use Paragraphs for Related Info | Group related sentences; open with a topic sentence. | One topic sentence per paragraph. |
| 6.5 One Topic per Paragraph | A paragraph covers exactly one topic. | No topic drift within a paragraph. |
| 6.6 Six Sentences Max per Paragraph | Cap paragraph length to preserve the thread. | 6 sentences maximum per paragraph. |

---

## Rule 6.1 — Give Information Gradually

In code documentation, give information gradually and make sure that each sentence
contains only one subject. If you give too much information too quickly, your
documentation will not be easy to understand, and the reader must read it again.

Give the reader one piece of information at a time. Do not combine multiple
actions, multiple conditions, or multiple subjects in one sentence.

### Core requirement

- One subject per sentence. The subject is the noun phrase that performs the
  action of the main verb.
- One action per sentence where the verbs share that subject. "The function
  validates input and returns a result" is acceptable (one subject, two verbs).
- Two subjects require two sentences: "The function validates input. The
  middleware logs the result." — not "...and the middleware logs..."

### Code-domain example

Non-STE (one dense sentence, multiple subjects and actions):

> The authentication middleware validates bearer tokens from the authorization
> header by calling the `validateToken` function in the security module which
> decodes the JWT payload using the `HS256` algorithm from the `jwt-signer`
> library and checks the `exp` claim against the current server time before
> extracting the `sub` and `role` claims and attaching them as properties on the
> `request.auth` object, and if the token is expired or malformed the middleware
> returns a `401 Unauthorized` response with a JSON error body containing a
> `message` field and an `errorCode` field set to `TOKEN_EXPIRED` or
> `TOKEN_MALFORMED` respectively, while also logging the failure to the audit
> trail via the `AuditLogger.log` static method which writes to the
> `audit_events` table.

STE (one subject, one action per sentence):

> The authentication middleware validates each incoming request. The middleware
> reads the bearer token from the `Authorization` header. It sends the token to
> the `validateToken` function in the `security` module. The `validateToken`
> function decodes the JWT payload. It uses the `HS256` algorithm from the
> `jwt-signer` library. Then it compares the `exp` claim with the current server
> time. If the token is not expired and not malformed, the function gets the
> `sub` and `role` claims. It attaches these claims as properties on the
> `request.auth` object. If the token is expired, the middleware returns a `401
> Unauthorized` response. The response body is a JSON object:
> - The `message` field contains a description of the error.
> - The `errorCode` field is set to `TOKEN_EXPIRED`.
> If the token is malformed, the middleware returns a `401 Unauthorized`
> response. The `errorCode` field in the response is set to `TOKEN_MALFORMED`.
> The middleware also logs each failure to the audit trail. It calls the
> `AuditLogger.log` static method. This method writes a record to the
> `audit_events` table in the primary database. The write uses an asynchronous
> pattern that does not block the response pipeline.

### How it applies by documentation type

- **README.** Introduce one concept per section. Three separate sections for
  purpose, install, and usage — not one paragraph mixing all three.
- **API docs.** Describe the method and path in one sentence; one sentence per
  parameter; one sentence per response field or status code.
- **Docstrings / inline comments.** One behavior per sentence. Each parameter and
  each return condition gets its own sentence.
- **Commit messages.** One logical change per commit. Split a compound change
  into a summary line plus bullet points.
- **Error messages / logs.** One problem per message with a distinct error code.
  One event per log line.
- **Changelogs.** One change per entry; separate feature, fix, and deprecation.

### Paradigm-specific guidance

- **Object-oriented.** Describe one method or one class behavior per sentence.
  For override chains: base class first, then the override, then the side effect.
- **Functional.** Describe one transformation per sentence. A `>>=` or pipe chain
  becomes one sentence per step.
- **Procedural (C, Go, Bash).** One step or one branch per sentence. Do not
  combine an if-else chain, a loop body, and cleanup into one sentence.
- **Declarative (SQL, Terraform, K8s YAML).** One resource, constraint, or column
  per sentence. Do not describe the resource and all its relationships in one
  sentence.
- **Systems (Rust ownership, C memory).** One ownership rule, lifetime, or memory
  operation per sentence. Separate allocation, transfer, annotation, and
  deallocation into distinct sentences.

### Edge cases

- **Framework names with multiple concepts** (e.g. `UserAuthenticationService`):
  treat the whole identifier as one technical noun. Do not split it; apply the
  rule to the surrounding prose.
- **Generated documentation** (OpenAPI, JSDoc, Sphinx): if you cannot change the
  output, add a plain-language summary above it that follows Rule 6.1.
- **Control-flow keywords** (`if`, `else`, `while`, `try/catch`): one sentence
  per branch. Describe the try block and the catch block in separate sentences.
- **Brevity contexts** (CLI `--help`, error codes): use the minimum number of
  sentences, but each must still have one subject. Use fragments only when the
  display format enforces them.
- **Rewriting existing docs:** if a compound sentence hides a dependency, describe
  the dependency first, then the dependent step.

### Connects to

Rule 6.2 (thread the split sentences with key words) · Rule 6.3 (then check the
25-word limit) · Rule 6.4 (group the short sentences into paragraphs) · Rule 6.5
(one topic per resulting paragraph) · Rule 1.1 (use approved words) · Rule 1.11
(one term per concept).

---

## Rule 6.2 — Use Key Words and Key Phrases to Give Your Text a Logical Structure

In code documentation, use key words and key phrases to connect related ideas
across sentences. Key words are terms that occur multiple times to link concepts.
Key phrases are multi-word expressions that serve the same connecting function.

These key words and phrases show how information is related and give the
documentation a logical structure. Do not change them in your text — the same
terminology keeps the documentation clear and correct.

### Approved connecting words and phrases

Use these at the start of a sentence so the reader sees the signal before the
content:

- **Connecting words:** `and`, `but`, `then`, `thus`, `also`, `however`,
  `therefore`.
- **Connecting phrases:** `for example`, `as a result`, `at the same time`.

Do **not** use `moreover`, `furthermore`, `nevertheless`, `subsequently`, or the
verbs `utilize` / `leverage` as connectors — they are not in the approved set.

### Core technique: repeat the key word

Pick the subject of the block (a class name, function name, parameter name,
resource name, or concept such as "middleware") and use it as the key word.

- Repeat it in the subject position of consecutive sentences.
- A pronoun (`it`, `they`) may refer back once, but after two sentences repeat the
  full key word to avoid ambiguity.
- Keep multi-word key phrases intact: "connection pool", "rate limiter",
  "retry policy". Do not shorten them to "pool" mid-documentation.

**Example chain:**

> The authentication middleware validates each incoming request.
> The middleware reads the bearer token from the `Authorization` header.
> It sends the token to the `validateToken` function in the `security` module.
> The `validateToken` function decodes the JWT payload.
> It uses the `HS256` algorithm from the `jwt-signer` library.

"middleware" and "validateToken" recur, so the reader follows the flow.

### How it applies by documentation type

- **README.** Repeat the project name, library name, and core concept across
  sections. Do not switch to "the library" or "this tool" later.
- **API docs.** Use function names, parameter names, and return-type names as key
  words. Consistent key words prevent the reader losing track of which parameter a
  sentence describes.
- **Docstrings.** Introduce the function or class name as the key word in the
  first sentence. Do not switch to synonyms like "transmit", "data", or "queue".
- **Commit messages.** Use the component name and action verb as key phrases. Do
  not switch to "conn pool" or "connection manager" within the same message.
- **Error messages.** Use the operation name and resource name as key words. A
  follow-up message must reuse the resource name, not switch to "document" or
  "path".

**Cross-type consistency:** the same key word must carry the same meaning across
all documentation types in a project (Rule 1.11). If the README says
"authentication middleware", the API docs and docstrings must say the same.

### Paradigm-specific guidance

- **Object-oriented.** Use class names, method names, property names as key words.
  For a method chain, repeat the return type as the key word.
- **Functional.** Use type names, function names, data constructors. The value
  that flows through transformations is the key word.
- **Procedural (C, Go, Bash).** Use variable names, struct fields, error codes.
  Each step must refer to the same variable by the same name.
- **Declarative (SQL, Terraform, K8s YAML).** Use resource names, column names,
  attribute names so the reader maps sentences to exact identifiers.
- **Systems (Rust ownership, C memory).** Use ownership terms, lifetime names,
  pointer names. Precision here prevents bugs.

### Edge cases

- **Framework name conflicts with an unapproved word** (e.g. a library named
  `Leverage`): it is a technical code noun (Rule 1.5). Use it as-is; do not replace
  with an STE synonym.
- **Code keyword too short to be a key word** (Go `go`, Rust `mut`): use a longer
  descriptive key phrase that includes it (e.g. "the `go` keyword starts a
  goroutine" — key word is "goroutine").
- **Generated code** (protobuf, OpenAPI, ORM): use the generated type names as key
  words even if verbose; do not abbreviate.
- **Multi-language repos:** choose one key word for a shared concept (e.g. "map";
  Python `dict`, Java `HashMap`, Go `map`) and note the language-specific names
  once.
- **Multi-word key phrases:** keep the full phrase as the key unit.

### Grammar notes

Rule 6.2 applies *lexical cohesion* to code docs: repetition, pronoun reference,
and approved synonym ties bind sentences into a chain. Keep one stable topic (key
word) in the subject position of every sentence in a block. Connecting words are
grammatical signals placed at the sentence start:

- `and` — addition about the same key word.
- `but` — contrast.
- `then` — next step involving the key word.
- `thus` / `therefore` — consequence.

A **dangling key word** (introduced once, never repeated) breaks the structure.
Repeat the important terms.

### Connects to

Rule 6.1 (the sentences to thread) · Rule 6.3 (short sentences keep key words
visible) · Rule 6.4 (a paragraph is a group of sentences that share a key word) ·
Rule 6.5 (the one topic is the key word) · Rule 1.5 (technical code nouns allowed)
· Rule 1.8 (use standard technical nouns) · Rule 1.9 (prefer short clear nouns) ·
Rule 1.11 (one term per concept).

---

## Rule 6.3 — Write Short Sentences. Use a Maximum of 25 Words in Each Sentence.

Good code documentation uses short sentences for complex topics. Short sentences
give a clear structure and make information easier to understand. In descriptive
code documentation, the maximum sentence length is 25 words.

### Core requirement

- Keep every descriptive sentence at 25 words or fewer.
- A sentence under 25 words can still be too dense if it packs multiple subjects —
  apply Rule 6.1 first, then count words.
- The 25-word limit indirectly limits clause density: a long sentence with several
  clauses overloads working memory.

### Code-domain example

Non-STE (32 words, one sentence):

> The configuration loader reads the YAML manifest file from the filesystem and
> parses it into an in-memory representation that other modules can query at runtime
> to determine their operational parameters.

STE (four sentences, each under 25 words):

> The configuration loader reads the YAML manifest file from the filesystem. It
> parses the file into an in-memory representation. Other modules can query this
> representation at runtime. They use it to find their operational parameters.

### How it applies by documentation type

- **README.** One sentence for the project, one for prerequisites, one for the
  install command. A reader scans and finds each without parsing a dense paragraph.
- **API docs.** One short sentence per part: endpoint, each parameter, each
  response field, each status code.
- **Docstrings.** One sentence for purpose, one per parameter, one for the return
  value, one per exception. Each under 25 words.
- **Commit messages.** Subject line under 72 characters; one short sentence per
  logical change in the body. Makes `git log` and `git bisect` readable.
- **Error messages.** Two short sentences: the problem, then the action. Each
  under 25 words. Log lines stay easy to search.

### Paradigm-specific guidance

- **Object-oriented.** Break inheritance and behavior into separate sentences. A
  class with many methods gets one sentence per method, not one sentence for all.
- **Functional.** Split composition from error behavior: describe the pipeline,
  then the short-circuit, then the error accumulator — each its own sentence.
- **Procedural (C, Go, Bash).** Each step is naturally one sentence. For
  safety-critical detail, split allocation from copy, copy from return.
- **Declarative (SQL, Terraform, K8s YAML).** Document each resource block and
  each argument in its own sentence. Do not mix properties in one 28-word sentence.
- **Systems (Rust ownership, C memory).** Short sentences are essential for memory
  models and concurrency guarantees. Split borrowing, lifetime tracking, and
  compile-time checks into separate sentences.

### Edge cases

- **Long technical terms** (e.g. "single sign-on", "continuous integration and
  continuous deployment"): count the phrase as one word. If it pushes the sentence
  over 25, use the acronym after the first mention.
- **Verbose code keywords** (`synchronized`, `concurrent.futures`,
  `__attribute__((constructor))`): count the keyword as one word, but keep the rest
  short.
- **Compound type signatures** (TypeScript generics, Rust trait bounds): one
  sentence for the type shape, one for the constraints, one for the behavior.
- **Legal / license text** (MIT, Apache, GPL, copyright): exempt from the 25-word
  limit. Surrounding explanation still obeys it.
- **Generated documentation** (JSDoc, Sphinx, `go doc`): the generator may produce
  long sentences; fix the source docstrings, not the generated output.

### Grammar notes

- **Clause density:** most English clauses are 6–12 words. A 25-word sentence holds
  at most two clauses with connecting words — matching working-memory capacity.
- **Coordination vs. subordination:** prefer coordination across separate sentences
  over deep subordination. "The `parse` function throws a `SyntaxError`. This error
  occurs when the input string contains invalid JSON." beats a 27-word sentence with
  three levels of subordination.
- **Implicit connectives:** short sentences in documentation order (purpose → usage →
  edge cases) need no explicit glue; the reader infers the relationship.
- **Counting rules:** count hyphenated compounds as one word ("least-recently-used"
  = 1). Count acronyms as one word (JSON = 1). Count code tokens as one word
  (`Result<Vec<T>>` = 1). Do not count parenthetical word-count notes ("(12
  words)") in examples.

### Connects to

Rule 6.1 (short sentences enable gradual delivery) · Rule 6.2 (short sentences make
key words visible) · Rule 6.4 (short sentences form clear paragraphs) · Rule 6.5
(short sentences help each paragraph stay on topic) · Rule 1.1 (short sentences
reduce the need for complex vocabulary) · Rule 1.10 (short sentences expose jargon).

---

## Rule 6.4 — Use Paragraphs to Show Related Information

In descriptive code documentation, paragraphs keep related information together and
give a logical sequence to the text. A paragraph starts with a **topic sentence**
that tells the developer the topic. The sentences that follow explain or expand it.

When a new paragraph starts, the reader knows there will be a new topic or different
information.

### Core requirement

- Start each paragraph with a topic sentence in the simple present tense, naming the
  topic (a class, function, module, or concept) in subject position.
- Keep related sentences together; use paragraph breaks to separate different
  subjects or different phases of a process.
- Do not start a paragraph with a subordinate clause ("Because...", "When...",
  "If...", "Although..."). Start with the subject.

### Code-domain example

Non-STE (one dense paragraph, mixed topics):

> The data pipeline processes incoming events through a sequence of stages. Each
> stage transforms the event payload and passes it to the next stage. The first
> stage is validation, which checks the event schema and rejects malformed events.
> The second stage is enrichment, which adds metadata such as timestamps, source
> identifiers, and geolocation data from an external lookup service. The third
> stage is transformation, which converts the event into the target format required
> by downstream consumers such as the analytics warehouse and the real-time
> dashboard. The final stage is persistence, which writes the transformed event to
> the primary data store and to the event log for audit purposes. Error handling is
> implemented at each stage to catch exceptions without breaking the entire
> pipeline.

STE (each topic gets its own paragraph with a topic sentence):

> **1. Data Pipeline Overview**
> The data pipeline processes incoming events through a sequence of stages. Each
> stage transforms the event payload and passes it to the next stage. Error
> handling is implemented at each stage to catch exceptions without breaking the
> pipeline.
>
> **2. Validation Stage**
> The first stage is validation. This stage checks the event schema. It rejects
> events that are malformed.
>
> **3. Enrichment Stage**
> The second stage is enrichment. This stage adds metadata to the event:
> - Timestamps
> - Source identifiers
> - Geolocation data from an external lookup service.
>
> **4. Transformation Stage**
> The third stage is transformation. This stage converts the event into the target
> format. Downstream consumers use this format. These consumers include:
> - The analytics warehouse
> - The real-time dashboard.
>
> **5. Persistence Stage**
> The final stage is persistence. This stage writes the transformed event to two
> destinations. It writes the event to the primary data store. It also writes the
> event to the event log for audit purposes.

### How it applies by documentation type

- **README.** Each section starts with a clear topic sentence. Use section headings
  for major topics; paragraph breaks for sub-topics. Move install, configuration,
  and dependencies to separate paragraphs/sections.
- **API docs.** Each endpoint description starts with a topic sentence stating what
  it does. Give authentication, query parameters, response, and status codes
  separate paragraphs (or sub-sections).
- **Docstrings / inline comments.** A docstring starts with a one-line topic
  sentence, then a blank line, then more paragraphs. Each paragraph covers one
  sub-topic (parameters, returns, exceptions, side effects, examples). Inline
  comments are one-sentence paragraphs that state the topic of the following code.
- **Commit messages.** The first line is the topic sentence. The body uses
  paragraphs to group the problem, the changes, and the monitoring notes.
- **Error messages.** Multi-line error output uses paragraphs to separate the error
  description, the diagnostic items, and the stack trace.

### Paradigm-specific guidance

- **Object-oriented.** Separate class purpose, constructor details, public API, and
  internal design into paragraphs. Document each method as a paragraph group.
- **Functional.** Separate the type signature, the behavior, the purity note, and
  the internal composition into paragraphs. Document each pipeline stage separately.
- **Procedural (C, Go, Bash).** Separate initialization, the main loop, cleanup, and
  error handling into paragraphs (phases of execution).
- **Declarative (SQL, Terraform, K8s YAML).** Give each resource or constraint its
  own paragraph group. Separate resource identity, specification, and dependencies.
- **Systems (Rust ownership, C memory).** Separate each ownership relationship or
  memory lifecycle into its own paragraph.

### Edge cases

- **Auto-generated documentation** (JSDoc, Sphinx, `go doc`): insert a blank comment
  line between topics so the generator emits separate paragraphs.
- **Multi-author documents:** apply structural linting. Flag paragraphs over 5
  sentences or lacking a topic sentence. Break long paragraphs at topic boundaries.
- **Cross-cutting concerns** (security, performance): give them their own document or
  top-level section; in each module write a one-paragraph summary with a link.

### Grammar notes

- **Topic sentence as anchor:** the topic sentence carries the main clause; the
  following sentences carry subordinate information. It must be declarative,
  simple present, naming the topic in subject position.
- **Paragraph length:** most STE paragraphs have 2–4 sentences. A paragraph over 5
  sentences usually covers more than one topic — split it.
- **Paragraph breaks as signals:** place a break before a new concept, a code
  example, a warning, a list, or a change in abstraction level. Do not break between
  a topic sentence and its supporting sentences.
- In markdown, separate paragraphs with a blank line (not indentation alone).

### Connects to

Rule 6.1 (paragraphs implement the gradual sequence at section level) · Rule 6.2
(topic sentences use key words) · Rule 6.3 (short sentences make paragraphs
readable) · Rule 6.5 (one paragraph, one topic) · Rule 1.1 (topic sentences use
approved words) · Rule 1.5 (technical nouns allowed in topic sentences) · Rule 1.11
(one term per concept across paragraphs) · Rule 7.1 (use lists for three or more
items).

---

## Rule 6.5 — Make Sure That Each Paragraph Has Only One Topic

In descriptive code documentation, paragraphs describe topics, and each paragraph
must have only one topic. The topic sentence is the first and most important
sentence in a paragraph. The other sentences add more information on that topic.

If you write down the topic sentences of a text, you get a good outline of its
content. The reader finds applicable information quickly.

### Core requirement

- One paragraph = one topic. The topic sentence names that topic.
- A paragraph that covers two topics must be split, even if it is short.
- The topic sentence usually contains a key word (Rule 6.2) and/or a connecting word
  (Rule 6.2) to link to the previous paragraph.
- Use deductive structure: the topic sentence is first, never last (developers scan).

### Code-domain example

Non-STE (five topics in one sentence):

> The authentication middleware validates each request and the logging system records
> all validation failures to the audit trail while the response pipeline returns JSON
> error bodies with error codes and the database connection pool maintains idle
> connections for reuse and the configuration module reloads settings when the
> manifest file changes on disk.

STE (three single-topic paragraphs; reading only the topic sentences gives the
outline):

> The authentication middleware validates each incoming request. The middleware reads
> the bearer token from the `Authorization` header. It sends the token to the
> `validateToken` function in the `security` module. The `validateToken` function
> decodes the JWT payload using the `HS256` algorithm from the `jwt-signer` library.
> Then it compares the `exp` claim with the current server time. If the token is not
> expired and not malformed, the function gets the `sub` and `role` claims and
> attaches them to the `request.auth` object.
>
> If the token is expired, the middleware returns a `401 Unauthorized` response. The
> response body is a JSON object with a `message` field and an `errorCode` field set
> to `TOKEN_EXPIRED`. If the token is malformed, the middleware returns a `401
> Unauthorized` response with the `errorCode` field set to `TOKEN_MALFORMED`.
>
> The middleware also logs each failure to the audit trail. It calls the
> `AuditLogger.log` static method. This method writes a record to the `audit_events`
> table in the primary database. The write uses an asynchronous pattern that does not
> block the response pipeline.

Outline from topic sentences: (1) "The authentication middleware validates each
incoming request." (2) "If the token is expired, the middleware returns a `401
Unauthorized` response." (3) "The middleware also logs each failure to the audit
trail."

### How it applies by documentation type

- **README.** One topic per section: "Installation" explains install only, not API
  design; "Configuration" shows config only, not usage.
- **API docs.** One paragraph per aspect: endpoint purpose, request format, each
  response status group, authentication. Do not mix `200 OK` with `404 Not Found`.
- **Docstrings / inline comments.** The docstring topic is the function's contract:
  inputs, outputs, behavior. Do not explain why it exists or list its callers.
- **Commit messages.** One commit = one topic. Two unrelated changes belong in two
  commits. The subject line summarizes the single topic; the body expands only on it.
- **Error messages.** One topic: what went wrong (one sentence), why (one sentence),
  how to fix (one sentence). No stack traces or unrelated state in the message body.

### Paradigm-specific guidance

- **Object-oriented.** One paragraph per concern: class purpose, constructor,
  public interface, inheritance, thread safety. Method implementation details go in
  the method docstring.
- **Functional.** One paragraph per transformation: input shape, transformation
  logic, output shape, edge cases. Document each pipeline stage separately.
- **Procedural (C, Go, Bash).** One paragraph per phase: initialization, main loop,
  cleanup, error handling. Do not merge `setup` with `teardown`.
- **Declarative (SQL, Terraform, K8s YAML).** One paragraph per table/view,
  resource block, or object. A Deployment and its Service are separate topics even
  though they work together.
- **Systems (Rust ownership, C memory).** One paragraph per ownership relationship or
  memory lifecycle. Allocation and deallocation share a paragraph only when they are
  one lifecycle (e.g. RAII).

### Edge cases

- **Framework names that are unapproved words** (e.g. a library named `Execute`):
  technical code noun (Rule 1.5), allowed. But do not use it as a verb in the same
  paragraph — write "Use the `Execute` library to run jobs", not "Execute jobs with
  `Execute`".
- **Large multi-topic functions:** list responsibilities as bullet points in the
  docstring; give each its own paragraph in module-level docs. The docstring is a
  topic index.
- **Generated documentation:** each individual docstring must still be a self-contained
  topic even though the page combines many.
- **Cross-cutting concerns:** give them their own document/section; in each module
  write a one-paragraph summary with a link.
- **Error-code reference tables:** the table is the container; each descriptive cell
  is a mini-paragraph that covers one error condition.

### Grammar notes

- **Topic sentence position:** always first (deductive). A topic sentence at the end
  is invisible to a scanning reader.
- **Key word repetition:** the topic sentence introduces a key word; supporting
  sentences repeat it or use a clear synonym. A new key word without connection means
  the paragraph has drifted.
- **Connecting words in the topic sentence:** "Also," (more on same topic), "However,"
  (contrast), "For example," (instance), "Therefore," (result).
- **Paragraph length:** 3–7 sentences. A 10+ sentence paragraph almost always has more
  than one topic.
- **Visual separation:** in markdown, separate paragraphs with a blank line; screen
  readers and renderers do not treat indentation as a break.

### Connects to

Rule 6.1 (gradual information) · Rule 6.2 (key words in topic sentences) · Rule 6.3
(short sentences make topic drift visible) · Rule 6.4 (paragraphs group related
info) · Rule 1.11 (consistent terms prevent false topic starts) · Rule 3.6 (topic
sentence usually starts with a simple-present verb) · Rule 5.1 (imperative procedural
paragraphs) · Rule 6.6 (six-sentence cap).

---

## Rule 6.6 — Make Sure That No Paragraph Has More Than Six Sentences

In code documentation, make sure that no paragraph has more than six sentences.
Paragraphs divide a documentation block into logical units and keep the developer's
attention. If a paragraph is too long, it cannot do this. Do not put different
topics in the same paragraph (see Rule 6.5). If a paragraph has more than six
sentences, divide it into two smaller paragraphs.

### Core requirement

- Cap each paragraph at six sentences. This is a ceiling, not a target — most good
  paragraphs use two to four sentences.
- Rule 6.6 works with 6.4 (use paragraphs) and 6.5 (one topic): 6.4 says use
  paragraphs, 6.5 says one topic each, 6.6 says keep them short.
- Split a paragraph when: it has more than six sentences, OR it covers two or more
  topics (Rule 6.5), OR a sentence introduces a new key word not used earlier (Rule
  6.2).

### Code-domain example

Non-STE (four components in one five-sentence paragraph):

> The connection pool manager has these primary components: a set of pre-allocated
> socket connections that the manager reuses across requests to avoid repeated TCP
> handshakes and TLS negotiation, a background reaper thread that closes idle
> connections and runs a periodic health probe, a bounded queue that holds pending
> acquire requests and rejects with a timeout error, and a metrics collector that
> records active connections and wait-time distribution for observability.

STE (one outline paragraph plus four short paragraphs, each under six sentences):

> The connection pool manager has these primary parts:
> - A set of pre-allocated socket connections.
> - A background reaper thread.
> - A bounded queue for pending acquire requests.
> - A metrics collector.
>
> The socket connections let the application reuse one link for many requests. The
> reuse avoids repeated TCP handshakes and TLS negotiation.
>
> The reaper thread closes connections idle longer than the idle timeout. The reaper
> thread also runs a periodic health probe to find dropped links.
>
> The bounded queue holds pending acquire requests when all connections are in use.
> The queue rejects new requests with a timeout error after the acquire timeout
> expires.
>
> The metrics collector records the number of active connections. The collector also
> records the wait-time distribution and the count of rejected acquires. The
> observability stack reads these metrics.

### How it applies by documentation type

- **README.** One feature = one short paragraph. A feature paragraph listing install,
  configure, and usage in eight sentences forces three topics at once — split them.
- **API docs.** One short paragraph per aspect: purpose, request, response, errors.
- **Docstrings.** Keep the summary paragraph short. One short paragraph per concern;
  move a long parameter list to a bulleted list and keep the prose under six
  sentences.
- **Error messages / logs.** An error message is usually one sentence; keep a
  multi-line diagnostic block to six lines or fewer, or split into a cause paragraph
  and a recovery paragraph.

### Paradigm-specific guidance

- **Object-oriented.** One responsibility per paragraph. Each collaborator of a class
  gets its own short paragraph.
- **Functional.** One transformation stage per paragraph; a map/filter/fold pipeline
  should not live in one paragraph.
- **Procedural (C, Go, Bash).** One phase per paragraph: setup, execution, cleanup.
  Do not document `setup` and `teardown` together.
- **Declarative (SQL, Terraform, K8s YAML).** One resource or block per paragraph; a
  module declaring a database, a cache, and a queue documents each separately.
- **Systems (Rust ownership, C memory).** One ownership rule per paragraph; memory
  contracts are easy to bury in a long paragraph.

### Edge cases

- **A topic needs more than six sentences:** keep the first paragraph under six
  sentences and continue the same topic in a second paragraph. Start the second with a
  connecting phrase ("Also,", "In addition,") so the reader knows the topic continues.
- **A list counts as one paragraph:** a bulleted/numbered list is one paragraph
  regardless of item count. Rule 6.6 limits the prose around it, not the list items.
  Keep the introductory sentence short; do not add a long closing sentence.
- **Generated docs that emit long paragraphs:** set the generator to break at sentence
  boundaries if you can. If you cannot, add a short human-written summary above the
  generated block; the summary must follow Rule 6.6. The generated block is exempt only
  if you do not edit its source annotations.
- **A short paragraph that mixes two topics:** Rule 6.6 and 6.5 are independent. A
  three-sentence paragraph describing both the cache and the queue must split even
  though it is under the sentence limit.

### Grammar notes

- **Why six:** a reader holds a paragraph's topic in working memory; after about six
  sentences the topic fades and they must re-read. The limit guards against drift.
- **Sentence count, not word count:** six short sentences or six long sentences both
  pass. Prefer two to four short sentences; apply Rule 6.3 together with 6.6.
- **Lists and tables reset the count:** the surrounding prose (introductory + closing
  sentence) is what counts. Keep that prose under six sentences.
- **Splitting technique:** split where the key word changes (Rule 6.2) or the topic
  changes (Rule 6.5). Start the new paragraph with a topic sentence naming the new key
  word.
- **Procedures:** each step is its own paragraph by convention, so 6.6 rarely applies;
  it applies when a step has a long note — keep the note under six sentences.

### Connects to

Rule 6.4 (6.6 is the size limit 6.4 assumes) · Rule 6.5 (6.6 limits sentence count,
6.5 limits topic count) · Rule 6.1 (short paragraphs support gradual delivery) · Rule
6.2 (the new paragraph starts with the new key word) · Rule 6.3 (short sentences make
it easier to stay under six).

---

## Applying Section 6 end to end (the pipeline)

When writing or checking documentation, apply the rules in sequence:

1. **6.1** — Split compound sentences so each has one subject and one action.
2. **6.2** — Thread the split sentences with repeated key words and approved connectors.
3. **6.3** — Check every sentence is 25 words or fewer.
4. **6.4** — Group related sentences into paragraphs opened by a topic sentence.
5. **6.5** — Verify each paragraph covers exactly one topic; split if it drifts.
6. **6.6** — Verify each paragraph has six sentences or fewer; split if longer.

A paragraph that passes 6.4, 6.5, and 6.6 is short, single-topic, and scannable. This
is the structural backbone that the vocabulary rules (Section 1) and the writing rules
(Sections 3, 5, 7) build on.

### Related rules outside Section 6

- Rule 1.1 — Use approved words from the STE-Code dictionary.
- Rule 1.5 — Technical code nouns are allowed.
- Rule 1.8 / 1.9 — Use standard, short, clear technical nouns as key words.
- Rule 1.10 — No slang, jargon, or regional terms.
- Rule 1.11 — One term per concept (keeps key words and topics stable).
- Rule 3.6 — Use approved forms of verbs.
- Rule 5.1 — Write instructions in the imperative mood.
- Rule 7.1 — Use lists for three or more items.



## rules-sec7.md

# Level 3 — Section 7: Safety Instructions (Warnings and Cautions)

This slice covers STE-Code Rules 7.1, 7.2, and 7.3. It is the risk layer of the
standard: how to signal risk, how to open a safety instruction, and how to
explain what happens if the reader ignores it.

These rules apply to every form of code documentation: README files, API
reference docs, docstrings, inline comments, commit messages, error messages,
changelogs, release notes, and configuration files.

## How to use this slice

- Apply the rules in order 7.1 → 7.2 → 7.3. Each adds one required part of a
  complete safety instruction.
- 7.1 picks the signal word (WARNING or CAUTION) that matches the risk level.
- 7.2 opens the body with a clear command or a clear condition.
- 7.3 states the consequence, so the reader knows why the instruction matters.

A safety instruction is complete only when it has all three parts:

```
WARNING: [COMMAND OR CONDITION]. [CONSEQUENCE]. [RISK ESCALATION].
```

If the command is missing, the instruction is not actionable. If the consequence
is missing, the reader does not know why the command matters. Both are required.

## Rules at a glance

| Rule | One-line requirement | Hard limit |
|------|----------------------|------------|
| 7.1 Identify the level of risk | Use WARNING or CAUTION as the first word; match it to the real risk. | One signal word per instruction. |
| 7.2 Start with a command or condition | The first sentence after the colon is a command or a condition. | 20 words maximum for that sentence. |
| 7.3 Explain the risk | Name the concrete consequence in cause-first order. | No vague nouns ("problems," "issues"). |

## Risk level mapping

| Risk in the code domain | Signal word | Release-note severity |
|-------------------------|-------------|-----------------------|
| Security vulnerability, data loss, system corruption | WARNING | BREAKING |
| Unexpected behavior, performance degradation, incorrect results | CAUTION | DEPRECATED |
| Information only, no risk | NOTE | NOTE |

If two levels of risk apply together, use WARNING.

---

## Rule 7.1 — Use an Applicable Word to Identify the Level of Risk

> Adapted from ASD-STE100 Issue 9, Rule 7.1.

In code documentation, use a signal word (for example, WARNING or CAUTION) to
immediately show your reader the level of the related risk.

- If there is a risk of security vulnerabilities, data loss, or system
  corruption, use a WARNING.
- If there is a risk of unexpected behavior, performance degradation, or
  incorrect results, use a CAUTION.
- If the two levels of risk apply together, use a WARNING.

Do not let the signal word become routine noise. A document that marks every
note as a WARNING teaches the reader to ignore all of them.

### Escalation: choose the level from the real risk, not from the topic

An abstract caution must become a warning when the true risk is security or data
loss. This is the core move of the rule.

> **Non-STE:** CAUTION: ALWAYS VALIDATE INPUT DATA.
>
> **STE:** WARNING: BEFORE YOU PROCESS INPUT DATA, MAKE SURE THAT YOU SANITIZE AND VALIDATE THE DATA. UNSANITIZED INPUT CAN CAUSE SECURITY BREACHES AND DATA LOSS.

> **Non-STE:** CAUTION: THE CONFIGURATION FILE MAY CONTAIN OUTDATED SETTINGS.
>
> **STE:** CAUTION: BEFORE YOU DEPLOY THE APPLICATION, COMPARE THE CONFIGURATION FILE AGAINST THE REFERENCE CONFIGURATION. OUTDATED SETTINGS CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.

The first pair escalates to WARNING because the true risk is a security breach.
The second stays a CAUTION because the risk is incorrect results only.

### By documentation type

| Type | Use WARNING for | Use CAUTION for |
|------|-----------------|-----------------|
| README | Security-critical setup steps | Configuration that can cause incorrect behavior |
| API docs | Sensitive data, authentication, destructive endpoints | Side effects, rate limits |
| Docstrings and comments | Misuse that corrupts data or breaks security | Performance pitfalls, non-obvious side effects |
| Commit messages | Security fixes, data-loss prevention | Behavior changes downstream consumers must know |
| Error messages | Detected security compromise or data corruption | Detected condition that gives incorrect results |

**README — WARNING:**

> **Non-STE:** Note: you should be careful with the API key and not commit it to version control.
>
> **STE:** WARNING: DO NOT COMMIT THE API KEY TO VERSION CONTROL. AN EXPOSED API KEY CAN CAUSE UNAUTHORIZED ACCESS AND DATA LOSS.

**README — CAUTION:**

> **Non-STE:** Make sure the port number does not conflict with other services or the app won't start.
>
> **STE:** CAUTION: BEFORE YOU START THE APPLICATION, CHECK THAT THE PORT NUMBER DOES NOT CONFLICT WITH OTHER SERVICES. A PORT CONFLICT CAN CAUSE THE APPLICATION TO FAIL.

**API docs — WARNING for a destructive endpoint:**

> **Non-STE:** DELETE /users/:id removes the user and all associated data, this cannot be undone.
>
> **STE:** WARNING: `DELETE /users/:id` REMOVES THE USER AND ALL RELATED DATA PERMANENTLY. THIS OPERATION CANNOT BE UNDONE. VERIFY THE USER ID BEFORE YOU SEND THE REQUEST.

**API docs — CAUTION for a rate limit:**

> **Non-STE:** This endpoint allows 100 requests per minute, exceeding this will return 429 errors.
>
> **STE:** CAUTION: THE ENDPOINT ALLOWS A MAXIMUM OF 100 REQUESTS PER MINUTE. IF YOU EXCEED THE LIMIT, THE ENDPOINT RETURNS A 429 ERROR. MONITOR THE `X-RateLimit-Remaining` HEADER.

**Docstring — WARNING (Python):**

```python
def execute_sql(query: str, params: tuple = ()) -> list:
    """Run a raw SQL query.

    WARNING: THIS FUNCTION EXECUTES THE QUERY DIRECTLY. SANITIZE ALL
    USER INPUT BEFORE YOU PASS IT TO THIS FUNCTION. UNSANITIZED INPUT
    CAN CAUSE SQL INJECTION ATTACKS AND DATA LOSS.

    Parameters:
        query: The raw SQL query string.
        params: The query parameters. The default is an empty tuple.

    Returns:
        A list of result rows.
    """
```

**JSDoc — CAUTION (JavaScript):**

```javascript
/**
 * Caches the result of an expensive computation.
 *
 * CAUTION: THE CACHE USES MEMORY PROPORTIONAL TO THE NUMBER OF
 * UNIQUE ARGUMENTS. FOR UNBOUNDED INPUT SETS, USE A CACHE WITH
 * A SIZE LIMIT. AN UNLIMITED CACHE CAN CAUSE MEMORY EXHAUSTION.
 *
 * @param {Function} fn - The function to cache.
 * @returns {Function} A cached version of the function.
 */
function memoize(fn) {
  const cache = new Map();
  return function (...args) {
    const key = JSON.stringify(args);
    if (cache.has(key)) return cache.get(key);
    const result = fn.apply(this, args);
    cache.set(key, result);
    return result;
  };
}
```

**Commit messages.** Use `WARNING:` as the type prefix for commits that fix
security vulnerabilities or prevent data loss. Use `CAUTION:` for commits that
change behavior downstream consumers depend on. Changelog tools can then group
commits by severity.

> **Non-STE:** fix: patch SQL injection in login form
>
> **STE:** WARNING: Prevent SQL injection in the login form. The previous code did not sanitize the `username` parameter. This vulnerability could permit unauthorized database access.

> **Non-STE:** change: update default timeout from 30s to 10s
>
> **STE:** CAUTION: Change the default timeout from 30 seconds to 10 seconds. Update all callers that rely on the previous default. The shorter timeout can cause connection failures in high-latency environments.

**Error messages.** Error messages are read during incidents. They must be
actionable.

> **Non-STE:** Error: invalid signature
>
> **STE:** WARNING: THE REQUEST SIGNATURE IS NOT VALID. THE REQUEST MAY HAVE BEEN TAMPERED WITH. REJECT THE REQUEST. CHECK YOUR SIGNING KEY AND ALGORITHM.

> **Non-STE:** The configuration value for max_connections must be less than database pool size.
>
> **STE:** CAUTION: THE `max_connections` VALUE IS GREATER THAN THE `pool_size` VALUE. THIS CONFIGURATION CAN CAUSE CONNECTION FAILURES. SET `max_connections` TO A VALUE THAT IS NOT MORE THAN `pool_size`.

### Paradigm notes for 7.1

| Paradigm | WARNING when | CAUTION when |
|----------|--------------|--------------|
| Object-oriented (Java, C++, C#, Python classes) | A subclass override can break a security invariant | A method mutates shared state |
| Functional (Haskell, Elixir, Clojure, Rust) | An unsafe escape hatch breaks referential transparency | A lazy operation can cause a space leak |
| Procedural (C, Go, Bash) | Buffer overflow, use-after-free, undefined behavior | Platform-specific behavior, resource limits |
| Declarative (SQL, Terraform, Kubernetes YAML) | Data destruction, public exposure of a resource | Configuration values with subtle effects |
| Systems (Rust ownership, C memory) | Undefined behavior, data races, memory corruption | Performance characteristics of unsafe optimizations |

**Object-oriented — WARNING (Java):**

> **Non-STE:** Subclasses should be careful to call super.validate() before performing custom validation.
>
> **STE:** WARNING: OVERRIDE THE `validate` METHOD WITH CARE. CALL `super.validate()` BEFORE YOU ADD CUSTOM VALIDATION LOGIC. IF YOU SKIP THE BASE VALIDATION, UNTRUSTED DATA CAN BYPASS SECURITY CHECKS.

```java
abstract class RequestValidator {
    /** Base security checks that apply to all request types. */
    void validate(Request request) {
        if (request.getUser() == null) {
            throw new SecurityException("Missing user context");
        }
        if (!request.isAuthenticated()) {
            throw new SecurityException("Request is not authenticated");
        }
    }
}

class PaymentRequestValidator extends RequestValidator {
    @Override
    void validate(Request request) {
        // WARNING: CALL super.validate() BEFORE YOU ADD CUSTOM LOGIC.
        super.validate(request);
        PaymentRequest payment = (PaymentRequest) request;
        if (payment.getAmount() <= 0) {
            throw new IllegalArgumentException("Amount must be greater than zero");
        }
    }
}
```

**Object-oriented — CAUTION (C++ shared state):**

> **Non-STE:** Note that this method modifies the internal cache which may affect other threads.
>
> **STE:** CAUTION: THE `invalidateCache` METHOD MODIFIES THE INTERNAL CACHE. THIS CHANGE AFFECTS ALL THREADS THAT USE THE CACHE. USE A LOCK BEFORE YOU CALL THIS METHOD.

**Functional — WARNING and CAUTION (Haskell):**

> **Non-STE:** Use unsafePerformIO with caution as it breaks purity.
>
> **STE:** WARNING: `unsafePerformIO` BYPASSES THE IO TYPE SYSTEM. THIS FUNCTION HIDES SIDE EFFECTS IN PURE CODE. INCORRECT USE CAN CAUSE NONDETERMINISTIC BEHAVIOR AND DATA CORRUPTION. USE THIS FUNCTION ONLY WHEN NO SAFE ALTERNATIVE EXISTS.

> **Non-STE:** foldl is strict, but if you accumulate large thunks you might run out of memory.
>
> **STE:** CAUTION: `foldl` ACCUMULATES UNEVALUATED EXPRESSIONS (THUNKS). A LARGE ACCUMULATOR CAN CAUSE A SPACE LEAK AND MEMORY EXHAUSTION. USE `foldl'` FOR STRICT ACCUMULATION.

**Procedural — WARNING (C) and CAUTION (Go):**

> **Non-STE:** Make sure the destination buffer is at least as large as the source string when using strcpy.
>
> **STE:** WARNING: `strcpy` DOES NOT CHECK THE SIZE OF THE DESTINATION BUFFER. IF THE SOURCE STRING IS LARGER THAN THE DESTINATION BUFFER, THE FUNCTION WRITES PAST THE BUFFER BOUNDARY. THIS BUFFER OVERFLOW CAN CAUSE SECURITY VULNERABILITIES AND SYSTEM CRASHES. USE `strncpy` WITH A SIZE LIMIT.

> **Non-STE:** On Windows, filepath separator is backslash, be careful with cross-platform paths.
>
> **STE:** CAUTION: THE `filepath` PACKAGE USES THE OPERATING SYSTEM PATH SEPARATOR. USE `filepath.Join` OR `filepath.FromSlash` TO BUILD CROSS-PLATFORM PATHS. HARDCODED SEPARATORS CAUSE INCORRECT PATHS.

**Declarative — WARNING (SQL), CAUTION (Terraform), WARNING (Kubernetes):**

> **Non-STE:** Caution: this migration drops the users table.
>
> **STE:** WARNING: THIS MIGRATION DROPS THE `users` TABLE. ALL USER DATA IS DELETED PERMANENTLY. BACK UP THE DATABASE BEFORE YOU RUN THIS MIGRATION. VERIFY THAT YOU RUN THE MIGRATION AGAINST THE CORRECT DATABASE.

> **Non-STE:** Changing the subnet_id will cause the EC2 instance to be recreated, which may cause downtime.
>
> **STE:** CAUTION: IF YOU CHANGE THE `subnet_id` ARGUMENT, TERRAFORM DESTROYS THE EXISTING INSTANCE AND CREATES A NEW ONE. THIS RECREATION CAUSES DOWNTIME. THE INSTANCE PUBLIC IP ADDRESS CHANGES. PLAN THE CHANGE DURING A MAINTENANCE WINDOW.

> **Non-STE:** Be careful with LoadBalancer type services as they expose your app to the internet.
>
> **STE:** WARNING: A SERVICE OF TYPE `LoadBalancer` EXPOSES THE APPLICATION TO THE PUBLIC INTERNET. UNAUTHORIZED USERS CAN SEND REQUESTS TO THE APPLICATION. MAKE SURE THAT AUTHENTICATION AND NETWORK POLICIES ARE IN PLACE BEFORE YOU APPLY THIS CONFIGURATION.

**Systems — WARNING and CAUTION (Rust):**

> **Non-STE:** Dereferencing a raw pointer is unsafe and may cause undefined behavior if the pointer is invalid.
>
> **STE:** WARNING: DEREFERENCING A RAW POINTER CAN CAUSE UNDEFINED BEHAVIOR. UNDEFINED BEHAVIOR CAN CORRUPT MEMORY, CAUSE SECURITY VULNERABILITIES, AND CRASH THE PROGRAM. BEFORE YOU DEREFERENCE A RAW POINTER, CHECK THAT: (1) THE POINTER IS NOT NULL. (2) THE POINTER IS CORRECTLY ALIGNED. (3) THE POINTER POINTS TO VALID, INITIALIZED MEMORY.

> **Non-STE:** Using MaybeUninit can improve performance but be careful about initialization.
>
> **STE:** CAUTION: `MaybeUninit` SKIPS INITIALIZATION TO IMPROVE PERFORMANCE. IF YOU READ UNINITIALIZED MEMORY, THE PROGRAM BEHAVIOR IS UNDEFINED. MAKE SURE THAT YOU INITIALIZE THE VALUE BEFORE YOU READ IT. MEASURE THE PERFORMANCE GAIN BEFORE YOU USE THIS TYPE.

### Common signal-word failures

| Failure | Fix |
|---------|-----|
| CAUTION used for a security risk (exposed API key) | Escalate to WARNING; name unauthorized access, data theft, service abuse |
| WARNING with no consequence ("run this migration carefully") | Name the irrecoverable loss and give a pre-action check |
| Abstract caution ("be mindful of thread safety") | Name the class, the race, and the safe alternative |
| WARNING used for slowness | Downgrade to CAUTION; give the complexity, a threshold, and an alternative |
| No signal word at all | Add the signal word that matches the real risk |
| Two risks in one callout, marked CAUTION | If either risk is WARNING-level, use WARNING |

Worked corrections:

> **Non-STE:** CAUTION: Store the API key in an environment variable.
>
> **STE:** WARNING: STORE THE API KEY IN AN ENVIRONMENT VARIABLE. DO NOT HARDCODE THE API KEY IN THE SOURCE CODE. AN EXPOSED API KEY CAN CAUSE UNAUTHORIZED ACCESS, DATA THEFT, AND SERVICE ABUSE. ADD THE `.env` FILE TO `.gitignore`.

> **Non-STE:** WARNING: Run this migration carefully.
>
> **STE:** WARNING: BEFORE YOU RUN THIS MIGRATION, BACK UP THE `transactions` TABLE. THE MIGRATION REMOVES ALL RECORDS OLDER THAN 90 DAYS. THE DATA CANNOT BE RECOVERED AFTER THE MIGRATION COMPLETES. VERIFY THE DATE THRESHOLD AGAINST YOUR RETENTION POLICY.

> **Non-STE:** CAUTION: Be mindful of thread safety when using this library.
>
> **STE:** CAUTION: THE `Cache` CLASS IS NOT THREAD-SAFE. IF YOU SHARE A `Cache` INSTANCE ACROSS THREADS, RACE CONDITIONS CAN CAUSE INCORRECT CACHE ENTRIES AND APPLICATION CRASHES. USE `ConcurrentCache` FOR MULTI-THREADED APPLICATIONS. USE A MUTEX FOR MANUAL SYNCHRONIZATION.

> **Non-STE:** WARNING: This function is slow for large inputs.
>
> **STE:** CAUTION: THIS FUNCTION HAS O(N²) TIME COMPLEXITY. FOR INPUTS LARGER THAN 10,000 ITEMS, THE FUNCTION CAN TAKE SEVERAL MINUTES TO COMPLETE. USE `fastSort` FOR LARGE INPUTS. `fastSort` HAS O(N LOG N) TIME COMPLEXITY.

> **Non-STE:** The DEBUG_MODE environment variable controls verbose logging. Setting it to true in production will leak sensitive information.
>
> **STE:** WARNING: DO NOT SET `DEBUG_MODE=true` IN A PRODUCTION ENVIRONMENT. DEBUG MODE WRITES SENSITIVE DATA TO THE LOG OUTPUT. THIS DATA INCLUDES REQUEST BODIES, AUTHENTICATION TOKENS, AND DATABASE QUERIES. AN ATTACKER WITH LOG ACCESS CAN STEAL USER CREDENTIALS.

> **Non-STE:** CAUTION: The reset method clears the database and disables authentication, only use in development.
>
> **STE:** WARNING: THE `reset` METHOD CLEARS THE DATABASE AND DISABLES AUTHENTICATION. IF YOU CALL THIS METHOD IN A PRODUCTION ENVIRONMENT, ALL USER DATA IS DELETED AND ALL REQUESTS BYPASS AUTHENTICATION. THIS METHOD IS FOR DEVELOPMENT USE ONLY. CHECK THE `NODE_ENV` VARIABLE BEFORE YOU CALL THIS METHOD.

### Edge cases for 7.1

**The word "warning" is also a code identifier.** Some languages use it as a
name (`warnings` in Python, `#[allow(warnings)]` in Rust, `console.warn()` in
JavaScript). Put the identifier in backticks. Use plain uppercase for the signal
word.

> **Non-STE:** Warning: the warnings module suppresses warnings by default.
>
> **STE:** CAUTION: THE `warnings` MODULE SUPPRESSES WARNINGS BY DEFAULT. THE OUTPUT FROM `warn()` CALLS IS NOT SHOWN. CALL `warnings.simplefilter('always')` TO SHOW ALL WARNINGS.

**A third-party library uses a different convention.** Translate `DANGER`,
`CRITICAL`, or `IMPORTANT` into the STE-Code signal words. Do not replicate the
third-party convention.

> **Third-party:** DANGER: This operation is irreversible.
>
> **STE-Code:** WARNING: THIS OPERATION IS IRREVERSIBLE. THE DATA CANNOT BE RECOVERED AFTER THE OPERATION COMPLETES. BACK UP THE DATA BEFORE YOU START.

**Generated code inserts its own warnings.** Do not modify generated comments;
the generator overwrites them. Add your own signal word in the documentation
that wraps the generated code. If the generated warning misclassifies the risk,
open an issue with the generator project.

> **Generated (leave as-is):** `// CAUTION: This method is deprecated.`
>
> **Your wrapper:** WARNING: THE `legacy/client.go` FILE CONTAINS DEPRECATED METHODS. DEPRECATED METHODS MAY BE REMOVED IN A FUTURE VERSION. THE REMOVAL OF THESE METHODS CAN BREAK YOUR APPLICATION. MIGRATE TO THE `v2/client.go` API.

**A BREAKING change overlaps with a WARNING.** Use one signal word. Mention the
breaking nature in the body.

> **Non-STE:** BREAKING: WARNING: The encrypt function now requires a key parameter.
>
> **STE:** WARNING: THE `encrypt` FUNCTION NOW REQUIRES A `key` PARAMETER. THIS IS A BREAKING CHANGE. UPDATE ALL CALLERS TO PASS A KEY ARGUMENT. IF YOU DO NOT PASS A KEY, THE FUNCTION THROWS AN ERROR AND THE DATA IS NOT ENCRYPTED.

**Translation.** Translate the signal words with the standard term for each
language. Do not invent new signal words. Keep the format identical: uppercase
word, colon, single space.

| Language | WARNING | CAUTION |
|----------|---------|---------|
| English | WARNING | CAUTION |
| Spanish | ADVERTENCIA | PRECAUCIÓN |
| French | AVERTISSEMENT | ATTENTION |
| German | WARNUNG | VORSICHT |
| Japanese | 警告 | 注意 |

### Grammar notes for 7.1

- **Placement.** The signal word is the first word of the instruction. Do not
  indent it. Do not put text before it (`Important: WARNING: ...` is wrong).
- **Punctuation.** The signal word is followed by a colon and one space.
- **Case.** Write the signal word in uppercase. Uppercase is part of the signal,
  not emphasis. `Warning:` and `warning:` are both wrong.
- **Structure.** Command or condition → consequence → risk escalation, in that
  order, in one sentence or several.
- **Verb form.** Imperative mood. Use "do not" for prohibitions. Do not use
  "should," "must," or "needs to."
- **Visual distinction.** In rendered output the signal word must stand out:
  bold, color, or a border in Markdown/HTML; an admonition directive
  (`.. WARNING::`) in reStructuredText. Do not rely on uppercase alone.

**Risk vocabulary.** Name the risk with a specific noun. Do not write
"problems," "issues," or "trouble."

| WARNING-level risk nouns | CAUTION-level risk nouns |
|--------------------------|--------------------------|
| Security breach | Unexpected behavior |
| Data loss | Performance degradation |
| System corruption | Incorrect results |
| Unauthorized access | Connection failure |
| Credential theft | Memory exhaustion |
| Data leak | Application crash |
| Privilege escalation | Configuration drift |

### Checklist for 7.1

- [ ] The signal word matches the real risk level, not the topic.
- [ ] Security, data loss, and system corruption use WARNING.
- [ ] Unexpected behavior, performance, and incorrect results use CAUTION.
- [ ] Mixed levels with one WARNING-level risk use WARNING.
- [ ] The signal word is first, uppercase, followed by a colon and a space.
- [ ] Only one signal word per instruction.
- [ ] The risk noun is specific, not vague.
- [ ] Technical code nouns are in backticks.
- [ ] Third-party conventions are translated, not copied.
- [ ] The signal word is visually distinct in the rendered output.

**See also:** Rule 5.3 (imperative form), Rule 7.2 (command or condition first),
Rule 7.3 (risk explanation), Rules 1.1/1.6/1.10/1.11 (approved words, one term
per concept).

---



## rules-sec8.md

# Level 3 — Section 8: Punctuation Rules (Rules 8.1–8.7)

This slice covers STE-Code **Section 8 — Punctuation**. It adapts ASD-STE100 Issue 9, Section 8 for code documentation. Use it when you generate or review:

- README files, API reference docs, docstrings, inline comments
- commit messages, error messages, configuration comments, specification documents

**Scope boundary:** These rules govern documentation *prose*. They do **not** apply to source code or to any text inside code blocks / inline code spans (backticks). A JavaScript example that shows `const x = 5;` is correct and keeps its semicolon.

**Word-count limits referenced throughout:** procedural sentences ≤ 20 words; descriptive sentences ≤ 25 words. Sentence boundaries are the period (`.`), question mark (`?`), and exclamation mark (`!`).

---

## Rule 8.1 — Use All Standard English Punctuation Marks but Not the Semicolon (;)

**Rule:** You can use all standard English punctuation marks but not the semicolon (;).

**Why:** The semicolon (;) lets you pack two or more independent clauses into one sentence. In code documentation this makes sentences hard to parse — especially for non-native English readers. The semicolon also means different things in C, C++, Java, JavaScript, Rust, Go (statement terminator), which causes cognitive interference when the same symbol appears in prose.

**The fix is always the same:** split the semicolon-joined sentence into two or more independent sentences. Each stands alone with its own subject and verb.

### Examples

Non-STE: `Call the function to parse the response data; handle any errors that occur.`
STE:    `Call the function to parse the response data. Handle any errors that occur.`

Non-STE: `The cache is invalid after a write operation; you must flush it before the next read.`
STE:    `The cache is invalid after a write operation. You must flush it before the next read.`

Non-STE: `POST /sessions creates a new session and returns a token; the token must be included in the Authorization header of subsequent requests.`
STE:    `A POST request to /sessions makes a new session and returns a token. You must include the token in the Authorization header of all later requests.`

Non-STE: `Invalid port number; specify a value between 1024 and 65535.`
STE:    `The port number is not valid. Specify a value between 1024 and 65535.`

### Per-document-type guidance

- **README files:** Write a feature as one sentence, its rationale as a second. Use a connecting word (Rule 4.4) only if the relationship needs to be explicit.
- **API docs:** Write the primary effect as one sentence, the secondary effect as a second.
- **Docstrings / inline comments:** Use a bullet list for multiple return conditions. Use separate sentences for multiple side effects.
- **Commit messages:** Each body sentence states one fact. If you want a semicolon, you are combining two facts — split them.
- **Error messages:** Write the condition as one sentence, the recovery action as a second. Prefer the pattern `X is not valid. Do Y to fix this.`
- **Config comments / test docs:** Write purpose as one sentence, trade-off or assertion as a second.

### Edge cases

1. **Code blocks** — Semicolons inside fenced/indented code and inline backticks (`const x = 5;`) are code syntax, not prose. Keep them.
2. **Generated docs** — Semicolons spliced in by OpenAPI/JSDoc/protobuf generators are generator defects; you are exempt, but apply the rule to the source comments you write.
3. **Quoted strings** — Keep semicolons inside quoted error/log text. Surrounding prose must obey the rule.
4. **Super-comma lists** — Do not use semicolons to separate complex list items. Use a bullet list or table instead:
   - Non-STE: `The endpoint accepts three query parameters: sort, which sets the sort field; order, which must be "asc" or "desc"; and limit, which caps the result count.`
   - STE: bullet list with one line per parameter.
5. **Chat / informal** — Rule applies to formal docs (README, API docs, docstrings, commits, errors). It does **not** apply to chat or PR-thread discussion; commit messages are permanent and always apply.
6. **Regex / data strings** — Keep the semicolon inside the code span holding the data; prose uses periods only.

### Cross-references
Rule 1.1 (approved connecting words), Rule 3.1 (simple sentences), Rule 4.1 (short sentences), Rule 4.4 (connecting words), Rule 8.2 (hyphens).

---

## Rule 8.2 — Use Hyphens (-) to Connect Words That Are Directly Related

**Rule:** Use hyphens (-) to connect words that are directly related. A hyphen signals that two or more words function as a single concept.

**Five categories of hyphenation** (apply the same in code documentation):

1. **Compound adjectives before a noun:** `high-priority task`, `read-only file`, `thread-safe method`, `event-driven architecture`, `type-safe interface`, `run-time error`, `end-to-end test`, `point-to-point connection`, `server-side rendering`, `client-side validation`, `just-in-time compilation`, `fire-and-forget pattern`.
2. **Two-word fractions or numbers:** `seventy-two`, `one hundred and twenty-eight`, `three-fourths`, `forty-seven`.
3. **Uppercase-or-number + noun (shape/configuration):** `L-shaped bracket`, `T-shaped connector`, `64-bit register`, `8-byte alignment`, `128-bit value`, `3-prong connector`.
4. **Verb whose first part is a noun/other part of speech:** `dry-run`, `hot-reload`, `cold-start`, `hard-code`, `soft-delete`, `short-circuit`.
5. **Prefix ends in vowel, root starts with vowel:** `pre-initialized`, `re-entrant`, `de-allocated`, `anti-aliasing`, `re-indexed`.

**A hyphen is different from a dash.** The hyphen joins words into one concept; the dash (—) separates ideas, shows a range (`lines 12-48`), or signals a pause. Keep the two distinct.

### Examples

- Non-STE: `// The high priority task must acquire the write lock before it can modify the shared data structure.`
- STE:    `// The high-priority task must get the write lock before it can change the shared data structure.`

- Non-STE: `A read only file descriptor to open the configuration for parsing.`
- STE:    `A read-only file descriptor to open the configuration for parsing.`

- Non-STE: `git commit -m "Add end to end test for auth flow"`
- STE:    `git commit -m "Add end-to-end test for auth flow"`

### Per-document-type guidance

- **README:** `battle-tested`, `production-ready`, `cross-platform`, `well-documented`, `auto-generated`, `multi-threaded`.
- **API docs:** `non-negative integer`, `null-terminated string`, `zero-based index`, `read-only reference`, `thread-safe access`, `idempotent operation`, `fail-fast strategy`.
- **Docstrings:** `well-formed JSON string`, `null-terminated buffer`, `deep-copied instance`, `newline-delimited list`.
- **Commit/error:** `thread-safe cache`, `null-terminated input`, `non-negative integer`.

### Paradigm-specific key terms

- **OOP:** `read-only property`, `lazy-initialized singleton`, `thread-safe collection`, `reference-counted pointer`.
- **Functional:** `pure-function semantics`, `higher-order function`, `persistent-data structure`, `lazily-evaluated sequence`, `lock-free CAS loop`.
- **Procedural:** `null-terminated string`, `zero-initialized struct`, `statically-linked binary`, `newline-delimited output`.
- **Declarative:** `left-joined table`, `fully-qualified column name`, `user-provided input`, `well-formed document`, `base64-encoded value`.
- **Systems:** `move-semantics transfer`, `borrow-checked reference`, `memory-mapped I/O`, `copy-on-write page`, `lock-free stack`, `use-after-free bug`.

### Edge cases

1. **Hyphenated tool names** (`create-react-app`, `eslint-plugin-react`): keep the name as-is; do not add a second hyphen when used as a modifier.
2. **Code keywords** (`typeof`, `nonlocal`, `FULL OUTER JOIN`): hyphenate in prose when used as a compound adjective, but reproduce the keyword exactly in code spans.
3. **Generated output:** do not manually hyphenate generator output; configure the generator if you control it, else add a NOTE.
4. **Established unhyphenated compounds** (`filename`, `namespace`): keep the established form if it is unambiguous and consistent.
5. **URL path segments** (kebab-case, e.g. `/api/user-settings`): keep the exact path form; hyphenate prose compound adjectives normally.

### Grammar notes

- **Attributive (before noun) = hyphen; predicative (after verb) = no hyphen:** `The thread-safe collection` vs `The collection is thread safe`.
- **Adverb ending in -ly: no hyphen** — `a fully qualified name`, NOT `a fully-qualified name`.
- **"self-" prefix always takes a hyphen:** `self-contained`, `self-signed`, `self-healing`.
- **Temporary compounds:** `write lock` (separate) vs `write-lock` (compound noun before another noun); `run time` (noun phrase) vs `run-time` (compound adjective).

### Cross-references
Rule 1.1 (approved words), Rule 1.5 (technical nouns), Rule 1.9 (short technical nouns), Rule 1.11 (consistent terms), Rule 8.1 (punctuation), Rule 8.6 / 8.7 (hyphenated counts as one word).

---

## Rule 8.3 — Use of Parentheses

**Rule:** You can use parentheses for seven purposes:

1. References to code modules, diagrams, or text — `Call the request handler (Figure 3, Module A).`
2. Letters or numbers that identify items in a diagram or text — `Disconnect the endpoints (2) and (12) from the load balancer (8).`
3. Identifying work steps in a procedure — `(1) Install the dependency package (4) in the project directory (8).`
4. Including abbreviations — `A Command Line Interface (CLI) is a text-based interface...`
5. Giving singular and plural at once — `Before you run the test(s), set the environment variable(s).`
6. Explaining words or part of a sentence — `Increase the timeout slowly (not more than 1000 ms each step).`
7. Including an alternative — `Use the left (right) API key for the staging (production) environment.`

**Key patterns:**

- **Abbreviation placement:** always `Full Term (ABBR)` — never the reverse. After first definition, use only the abbreviation.
- **Never nest parentheses.** If you need a nested aside, split into sentences.
- **Parenthetical counts as a separate sentence** with its own word-count limit (Rule 8.5).
- **Period goes outside** the closing parenthesis for a sentence-ending parenthetical that is not a complete sentence (`Set the log level to debug (recommended for development).`). A complete-sentence parenthetical should instead be its own sentence.

### Examples

- Non-STE: `A Representational State Transfer Application Programming Interface, or REST API, is an architectural style...`
- STE:    `A Representational State Transfer Application Programming Interface (REST API) is an architectural style...`

- Non-STE: `Run the migration on all database shard servers, the primary and all replica instances, before you deploy.`
- STE:    `Run the migration on all database shard(s) before you deploy.`

- Non-STE: `Cannot find the config file you specified; looked in /etc/myapp/config.yaml, ~/.config/myapp/config.yaml, and ./config.yaml...`
- STE:    `Cannot find the configuration file (searched: /etc/myapp/config.yaml, ~/.config/myapp/config.yaml, ./config.yaml).`

### Per-document-type guidance

- **README:** define abbreviations on first use; reference related docs concisely `(refer to docs/getting-started.md)`.
- **API docs:** explain parameter constraints or units `(ms)`; wrap status codes `(404 Not Found)`.
- **Docstrings:** show types/ranges `(1 to 30000)`; only clarify what the type system cannot express.
- **Commit messages:** `(auth)`, `(issue #482)`, `(regression from v2.3)` — short scope/issue identifiers.
- **Error messages:** put diagnostic data (paths, line numbers, actual vs expected) at the end in parentheses.

### Edge cases

1. **Framework names that are common words** (`Flask`, `React`): add a brief parenthetical on first use — `React (a JavaScript UI library)`.
2. **Code keywords** (`()`, `<T>`): keep the code literal exact; explain in a separate sentence, not a nested parenthesis.
3. **Generated docs:** leave auto-inserted signatures/types untouched; apply the rule to human-written description fields.
4. **Nested parentheses:** split the sentence instead.
5. **CLI help text:** prefer alternative-use (`--verbose (--quiet)`) or explanation (`--timeout MS (default: 5000)`) patterns.

### Cross-references
Rule 1.1 (approved words), Rule 1.3 (approved meanings), Rule 1.9 (short technical nouns), Rule 5.1 / 6.3 (length, steps), Rule 8.2 (hyphens ≠ parentheses). Square brackets `[ ]` are reserved for optional parameters in code syntax — use parentheses, not brackets, for prose asides.

---

## Rule 8.4 — Colon in a Vertical List

**Rule:** In a vertical list, a colon (:) has the same effect on word count as a period and shows the end of a sentence.

- The introductory text before the colon obeys the length limits: ≤ 20 words (procedural), ≤ 25 words (descriptive).
- Each list item after the colon counts as a **new sentence** with its own limit (20 / 25 words).
- A colon before a vertical list is **always** a sentence boundary. Enumerated items are always vertical, never inline.

### Examples

Non-STE (31-word intro burying three cases):
`To handle all possible error conditions, the following exception types must be caught...: database connection timeouts..., authentication failures..., and validation errors...`

STE:
```
To handle possible error conditions, the error handler catches these exception types:
- Database connection timeout
- Authentication failure
- Validation error.
```

STE (config profiles):
```
The configuration file supports these environment profiles:
- Development
- Staging
- Production.
```

### Per-document-type guidance

- **README:** keep the introduction to the category; move version/compat notes into list items or a separate sentence.
- **API docs:** name the endpoint/resource and state what it enumerates; put type/default/optionality in each item.
- **Docstrings:** `Args:`, `Returns:`, `Raises:` introductions are usually trivially compliant; keep custom headers short.
- **Commit messages:** the subject line is NOT a list intro; keep any body intro short.
- **Error messages:** short intro (`The command failed for one of these reasons:`); each cause/recovery step is a separate sentence.

### Paradigm-specific guidance

- **OOP:** name the class/method in the intro; put type/default/constraint in each item.
- **Functional:** name the type/function; describe each variant/arm independently.
- **Procedural:** write a short goal before the colon, then imperative steps.
- **Declarative:** name the resource/option; one value/rule/setting per item.
- **Systems (safety-critical):** enumerate each precondition/safety condition as its own item; never bury it in the intro.

### Edge cases

1. **Inline code in intro:** each backtick token counts as one word (e.g. `docker-compose` = 1 word). Prefer intros with ≤ 15 words and few code tokens.
2. **Nested lists:** limit to one level; parent items are short category headings with their own colon.
3. **Code blocks inside list items:** the prose intro obeys the limit; the block itself is exempt.
4. **Long framework names:** move them into the list items; keep the intro generic.
5. **Generated docs:** obey the rule in the source comments you write; accept generator boilerplate (`Options:`, `Commands:`).

### Cross-references
Rule 1.1 (approved words in items), Rule 3.1 (one subject-verb-object per item), Rule 4.1 (length at two points: intro + each item), Rule 6.3 (procedural lists), Rule 8.1 (colon replaces semicolon-joined enumerations). Use a colon, **not** an em-dash (—), to introduce a vertical list.

---

## Rule 8.5 — Parentheses and Word Count

**Rule:** Text in parentheses counts as **one word** in the enclosing sentence. But the words inside the parentheses also form a **separate sentence** and must obey the length limit.

Identifiers in parentheses (a number, a letter, an alphanumeric identifier, or an abbreviation) count as one word.

Two categories of parentheticals:

- **Identifier parentheticals** — a number, letter, code, or abbreviation: `(10)`, `(EACCES)`, `(CI/CD)`, `(v2.1)`. Count as one word; no sentence-length limit (not prose).
- **Explanatory parentheticals** — prose that explains or qualifies: `(the DEBUG flag is off)`, `(the worker runs every 60 seconds)`. Count as one word in the main sentence but form a separate sentence subject to 20/25-word limits.

**Examples:**

- `Make sure that the DEBUG environment variable is set to false (the DEBUG flag is off).` — 12 words in the main sentence; the parenthetical is a 5-word separate sentence.
- `Remove the health check flag (10).` — 5 words; the identifier `(10)` is one word.
- `Configuration of a Continuous Integration/Continuous Deployment (CI/CD) Pipeline` — 7 words; `(CI/CD)` is one word.

**Key principle:** Use parentheses for clarifications, examples, and secondary qualifications. **Never** use parentheses for safety conditions, required steps, or warnings the reader must act on — those deserve their own sentence or a labeled block (`BREAKING`, `DEPRECATED`, `NOTE`).

### Examples

- Non-STE: `...production cluster (the DEBUG flag must be explicitly disabled for all production workloads to prevent accidental log leakage).`
- STE:    `Make sure that the DEBUG environment variable is set to false (the DEBUG flag is off).`

- Non-STE: `Cannot write to the configuration file (check that the file exists and is not read-only, that the parent directory is writable, and that your user account has the necessary file permissions...).`
- STE:
  ```
  Error: Cannot write to the configuration file.
  To fix this problem:
  - Make sure that the file exists.
  - Make sure that the file is not read-only.
  - Make sure that the parent directory is writable.
  - Make sure that your user account has the necessary permissions.
  ```

### Per-document-type guidance

- **README:** split long conditional asides into their own sentence before the instruction.
- **API docs:** keep parentheticals to identifiers/short qualifiers `(int, optional)`, `(default: 30)`; move conditional logic to a NOTE.
- **Docstrings:** keep parentheticals short; move algorithmic explanations out.
- **Commit messages:** issue refs `(#1234)` and scope `(auth)` are identifiers (one word each); put justification in the body, not parentheses.
- **Error messages:** each parenthetical `(Error code: EACCES)` is a separate sentence; recovery steps belong in separate sentences, not a parenthetical.

### Edge cases

1. **Function-call notation** (`authenticate()`, `parse(input)`): backtick-delimited code tokens are atomic — one word; the parens inside are not Rule 8.5 parentheticals.
2. **URLs in parentheses:** an identifier-like URL counts as one word; if the parenthetical also has explanatory text, that text forms a separate sentence.
3. **Nested parentheses:** do not use them; eliminate one level by making the outer aside its own sentence.
4. **Library names with parens** (`expect()`): keep in backticks (one word); parens are part of the identifier.
5. **Generated docs:** follow the rule for parentheticals you write; accept auto-inserted defaults.

### Cross-references
Rule 1.5 / 1.6 (technical nouns in parentheticals), Rule 3.1 (parenthetical is a simple sentence), Rule 3.3 (long parentheticals signal a paragraph restructure), Rule 4.1 (limit applies to the parenthetical too), Rule 8.1 (no semicolons inside parentheticals), Rule 8.4 (parenthetical inside a list item).

---

## Rule 8.6 — Elements That Count as One Word

**Rule:** When counting words for sentence length, count each of these as **one word**:

1. **Numbers** — `13`, `16`, `twenty-one`. (Do not count numbers that identify paragraphs or work steps — they are document numbering.)
2. **Numbers with units of measurement** — `10 ms`, `20 MB`, `10 μs`, `10 milliseconds`.
3. **Abbreviations** (acronyms/initialisms) — `VPN`, `OWASP`, `CI/CD`, `JWT`, `a.m.`.
4. **Alphanumeric identifiers** — `No. 1`, `E36L7`, `cache.miss.count`, `http.client.retry.max.attempts`.
5. **Quoted text** — `"Service Overview"`, backtick-quoted code (`C = (A - B) - 0.063 mm`), inline `<code>`, formulas. Each quoted span = one word.
6. **Titles, headings, and text on UI elements/labels** — `Operations Runbook`, `Error Handling and Recovery`, dialog/warning text you cannot change.
7. **Proper nouns** of individuals, groups, organizations, geopolitical entities — `Linus Torvalds`, `Apache Software Foundation`, `AWS Lambda`, `Azure AD B2C`.

**Why this matters:** applying Rule 8.6 collapses many multi-word elements into single-word counts, so sentences that look too long are often compliant. This is the largest reduction in API docs and README files (highest identifier/abbreviation density).

### Examples

- `The JWT authentication middleware must validate the signature of each incoming request. The token must have an expiry time of not more than 360 seconds to be valid for processing.` — `JWT` (1 word), `360 seconds` (1 word).
- `In application.properties, set http.client.retry.max.attempts to 5. Set http.client.retry.backoff.millis to 1000.` — each property name is an alphanumeric identifier (1 word); `5` and `1000` are numbers (1 word).
- `Call useUserProfile(userId) to get the current user profile.` — `useUserProfile(userId)` is quoted text (1 word).
- `In the Kubernetes manifest, set the checkout container to 250m CPU and 512Mi memory.` — `250m CPU`, `512Mi` are numbers with units (1 word each).

### Per-document-type guidance

- **README:** project names, badge URLs, version numbers, tool abbreviations each = 1 word.
- **API docs:** endpoint paths, HTTP status codes, parameter names each = 1 word.
- **Docstrings:** parameter/return/exception types each = 1 word.
- **Commit messages:** issue IDs, branch names, command names each = 1 word.
- **Error messages:** error codes, field names, type identifiers each = 1 word.

### Edge cases

1. **Framework names with "unapproved" words** (`Express`, `Swift`, `React`): proper nouns, 1 word; do not rewrite them.
2. **Code keywords** (`class`, `return`): quoted text, 1 word; keep them — do not replace with synonyms.
3. **Generated code/comments:** count as one word (category 6/7) when you cannot change them.
4. **Nested quoted text:** the outer backtick/`<code>` boundary defines the span; everything inside = 1 word.
5. **Semantic versions / hashes:** `1.2.3-alpha.1+build.456`, commit `a1b2c3d`, digest `sha256:abc...` = 1 word each. `Version 1.2.3` = 2 words.
6. **Document part numbers:** rule/section numbers (`Rule 8.7`), step numbers (`Step 3`), and ticket IDs (`PROJ-4821`, alphanumeric identifier) are not quantity counts.

### Cross-references
Rule 1.1 (proper nouns/identifiers exempt from approved-word check), Rule 1.5 / 1.6 (technical nouns), Rule 1.14 (American spelling of proper nouns), Rule 8.7 (hyphenated = one word), Rule 4.1/4.2 (sentence-length limits this rule feeds).

---

## Rule 8.7 — Hyphenated Words Count as One Word

**Rule:** Hyphenated words count as one word. A hyphenated group (compound adjective or long technical noun) is a single unit and counts as one word for sentence-length measurement.

### Case 1: Hyphenated compound adjectives (before a noun)

`read-only file descriptor`, `thread-safe singleton`, `event-driven architecture`, `low-latency cache`, `client-side rendering pipeline`, `end-to-end test suite`, `backward-compatible API`. The hyphen is a pre-noun signal only: after the noun or a linking verb, write the words separately and count each — `The singleton is thread safe` (5 words, not 4).

### Case 2: Long hyphenated technical nouns

The whole hyphenated group counts as one word; the following words are separate:
- `build-time environment variable` → `build-time` / `environment` / `variable`
- `client-side rendering pipeline` → `client-side` / `rendering` / `pipeline`
- `end-to-end test suite` → `end-to-end` / `test` / `suite`
- `check-out request handler` → `check-out` / `request` / `handler`

### Why it matters

STE-Code limits procedural sentences to 20 words and descriptive to 25 (Rules 4.1, 4.2). Counting each word inside a hyphenated term over-reports length and may break a limit the sentence actually meets.

- `The build-time environment variable must point to the staging cluster.` → 10 words (`build-time` is 1).
- `The thread-safe singleton must cache the read-only file descriptor.` → 9 words (`thread-safe` and `read-only` are 1 each).

### Interaction with other rules

- **Rule 8.2 (hyphens):** hyphenate per 8.2, then count the unit as one word per 8.7.
- **Rule 8.6:** a hyphenated word is a separate case — it is not also an abbreviation or identifier. Do not double-count.

### Common code-domain hyphenated terms (each = one word before a noun)

| Term | Type |
|------|------|
| read-only, write-only, thread-safe, event-driven | compound adjective |
| client-side, server-side, end-to-end, backward-compatible, low-latency | compound adjective |
| build-time, run-time, sign-in, check-out, request-response | technical noun |

When a term in this table follows the noun or a linking verb, write it as separate words and count each.

### Cross-references
Rule 8.2 (when to hyphenate), Rule 8.6 (other one-word elements), Rule 4.1 / 4.2 (sentence-length limits).

---

## Quick Reference — Section 8 at a Glance

| Rule | One-line summary |
|------|------------------|
| 8.1 | No semicolons in prose. Split into two or more sentences. |
| 8.2 | Hyphenate directly related words (compound adjectives, number+noun, prefix-vowel). |
| 8.3 | Use parentheses for refs, IDs, steps, abbreviations, `(s)`, explanations, alternatives. Never nest. |
| 8.4 | A colon before a vertical list is a sentence boundary; intro ≤ 20/25 words, each item is a new sentence. |
| 8.5 | Parenthetical text = 1 word in the main sentence but a separate sentence with its own limit. |
| 8.6 | Numbers, units, abbreviations, identifiers, quoted text, titles, proper nouns each count as 1 word. |
| 8.7 | Hyphenated words count as 1 word. |

**Remember:** these rules govern documentation *prose* only. Source code and text inside code blocks / backticks are exempt.



## rules-sec9.md

# Level 3 — Section 9: Word & Sentence Rules (9.1–9.4)

STE-Code controlled-language rules for code documentation, distilled for LLM consumption.
Covers the four "word-level fallback and quality" rules: **9.1** (restructure when a
word-for-word replacement fails), **9.2** (use each approved word with its correct meaning
and part of speech), **9.3** (do not make phrasal verbs), and **9.4** (consistent style).

All examples are code-domain. No aerospace terms. Apply these rules whenever you generate
or rewrite code documentation (READMEs, API docs, docstrings, commit messages, error
messages, generated/AI output, infra-as-code, and systems docs).

## How to use this as an LLM reference

Apply the rules in this order for every sentence you write:

1. **Rule 1.1** — Use only approved words. Look up the word in the STE-Code dictionary
   (or the synonym preferences in Rule 9.4). Try a word-for-word replacement first.
2. **Rule 9.1** — If no approved word with the same part of speech exists, or a
   word-for-word replacement changes the meaning, restructure the sentence.
3. **Rule 9.2** — After you choose or restructure, check every approved word is used with
   its approved meaning and approved part of speech.
4. **Rule 9.3** — Replace any phrasal verb (verb + particle) with a single approved verb.
5. **Rule 9.4** — Use the same term, verb, and sentence structure for the same concept
   everywhere in the document and project.

Rule 9.1 is the escape hatch when the dictionary cannot supply a direct replacement.
Rules 9.2–9.4 are the quality gates that keep the result correct, unambiguous, and
consistent.

---

# Rule 9.1 — Use a Different Sentence Construction When a Word-for-Word Replacement Is Not Sufficient

**Core rule:** When a word is not approved, first try a word-for-word replacement with an
approved alternative of the same part of speech that keeps the meaning. If that is
impossible, rewrite the sentence with a different structure that uses only approved words
and keeps the same technical meaning.

**You must restructure when:**
1. The grammatical structure must change to fit the approved alternative.
2. A word-for-word replacement gives a meaningless or unclear result.
3. The approved alternative changes the meaning.
4. The word to replace is not in the controlled terminology at all.

When no replacement works, identify the purpose of the sentence and use different words,
verb forms, shorter sentences, or drop unnecessary information to get the same result.

## Quick check before restructuring
- Same part of speech? Approved alternative exists? Meaning unchanged? → **Replace** (no restructure).
- Otherwise → **Restructure** (Rule 9.1).

## Per-document-type guidance

**README files** — first doc a developer reads; keep clear and short.
- Passive descriptions → active instructions.
- Move complex explanations to a separate doc.
- Use bullet points, not long paragraphs.
- Remove marketing language ("leverages async I/O to facilitate…") → state the fact.

> Non-STE: This library leverages asynchronous I/O to facilitate high-throughput data processing.
> STE:     This library uses async I/O. It can process large quantities of data quickly.

**API documentation** — strict structure; keep parameter names unchanged (Rule 1.5).
- Restructure the description around the approved word.
- Use a different grammatical subject if the original subject depends on an unapproved word.
- Split compound descriptions into one sentence per parameter or behavior.

> Non-STE: This endpoint facilitates the retrieval of user profiles.
> STE:     This endpoint gets user profiles.

**Docstrings / inline comments** — most constrained; short, next to code.
- Keep code symbols unchanged. Never change a symbol to match an approved word.
- Use the approved verb form even if the sentence gets longer.
- If replacement is impossible in the space, drop the sentence and link to a longer doc.

> Non-STE: """Computes the aggregate of the supplied metrics and persists them."""
> STE:     """Gets the total of the metrics and saves them."""

**Commit messages** — short summary + blank line + body.
- Imperative summary ("Add feature", not "Added feature").
- Replace unapproved verbs with approved technical verbs.
- Complex change? Write a shorter message; put details in the PR.

> Non-STE: Implemented utilization of the cached connection pool to expedite request handling.
> STE:     Use the cached connection pool to make requests faster.

**Error messages** — short, clear, actionable; appear in logs/terminals.
- Tell the user what happened and what to do.
- Remove jargon the user cannot act on.
- Use "cannot" / "do not", keep code symbols and stack traces unchanged.

> Non-STE: The application encountered an unrecoverable exception while attempting to instantiate the connection pool.
> STE:     The application cannot start the connection pool. Look at the log for more data.

**Generated code / automated output** — the generated code itself is NOT subject to the
rules. Only your description of it must comply. Keep generated symbol names unchanged
(technical nouns, Rule 1.5); describe their function with approved words.

## Paradigm-specific guidance

**Object-oriented (Java, C++, C#, Python classes)** — class/interface/method names are
technical nouns.
- "provides an abstraction that facilitates" → "lets you use the same … methods".
- "contract" / "guarantee" / "enforce" (interfaces) → restructure ("All classes that use
  this interface must have a `save` method").
- Keywords "extend" / "override" / "specialize" are technical nouns when naming the
  keyword; unapproved verbs in prose → replace.

> Non-STE: The `BaseRepository` class provides an abstraction that facilitates data access operations across multiple database backends.
> STE:     The `BaseRepository` class lets you use the same data access methods with different databases.

**Functional (Haskell, Elixir, Clojure, Rust)** — type signatures are code (unchanged).
- "maps over" / "folds" / "lifts" are technical verbs when naming an operation; in general
  description, replace ("applies a function to each element").
- Monad/functor descriptions: state the practical effect, not abstract math.

> Non-STE: This function `fmap`s the provided transformation over the `Maybe` value, yielding a new `Maybe` that encapsulates the transformed result.
> STE:     This function applies the transformation to the `Maybe` value. If it is `Just x`, the result is `Just (f x)`. If it is `Nothing`, the result is `Nothing`.

**Procedural (C, Go, Bash)** — steps, memory, system calls.
- "allocate"/"free" are technical verbs; "deallocate" is not approved → "free"/"release".
- Shell "pipe"/"redirect"/"subshell" are technical nouns when naming features; unapproved
  as general verbs ("send the output of A to B").

> Non-STE: The program allocates a buffer on the heap, then deallocates it after processing to prevent memory leaks.
> STE:     The program gets a buffer from the heap. After it uses the buffer, it releases the memory to prevent memory leaks.

**Declarative (SQL, Terraform, Kubernetes YAML)** — desired state, not procedures.
- Keep field names as technical nouns; restructure the surrounding prose.
- "orchestrates the rollout of …" → "makes three copies of the Pod. If a Pod stops, the system starts a new Pod automatically."

**Systems (Rust ownership, C memory)** — keywords as code are unchanged; in prose check
the dictionary. "borrow"→"get a reference to"; "own"→"has"/"controls"; "move" is approved
but Rust-specific ("gives"/"moves").

## Edge cases
- **Framework names that are also unapproved words** (e.g. `Flask`, `Vite`, `Tailwind`):
  technical nouns, keep unchanged; never use as a verb ("Use Flask with the service", not
  "Flask the service").
- **Code keywords that conflict with approved words** (`use`, `move`, `return`, `break`):
  code-font keyword = technical noun; prose word follows the dictionary.
- **Quoted log/error output**: keep exact; your explanation follows the rules.
- **Restructuring loses precision** (e.g. security audit): split + add an approved-word
  clarifying note, or keep the term in code font with a glossary definition, or (internal
  expert audience) keep it as a technical noun with an approved-word definition on first use.

## Grammar patterns (reuse these)
- **Adjective → verb:** "X is visible" → "make sure that you can see X". ("is accessible" →
  "you can open"; "is extensible" → "you can add to".)
- **Noun → verb:** "perform the retrieval of X" → "get X". ("the service performs the
  validation of each request" → "the service checks each request".)
- **Split long sentences** before a conjunction/conditional, or between cause→effect,
  problem→solution. After splitting, each sentence must be self-contained.
- **Remove unnecessary info:** marketing adjectives, redundant modifiers, implementation
  detail that belongs in code, historical context that belongs in a changelog.

## Cross-references
Rule 1.1 (approved words — try first), Rule 1.4 (short sentences), Rule 1.5 (technical
nouns — do not replace), Rule 1.7 (don't verb technical nouns), Rule 1.12 (technical
verbs — do not replace), Rule 3.1 (simple tenses), Rule 5.1 (length limits), Rule 6.1
(active voice), Rule 9.2 / 9.3 / 9.4 (apply after restructuring).

---

# Rule 9.2 — Use Each Approved Word Correctly

**Core rule:** Every approved word in your documentation must be used with its **correct
meaning** and its **correct part of speech** (as listed in the STE-Code dictionary). Most
approved words have exactly one approved meaning; use only that meaning. Words approved as a
noun are not automatically approved as a verb, and vice versa.

**Decision rule:** Before using a word, read its dictionary entry. If the meaning or part of
speech you need is not the approved one, do a word-for-word replacement with a different
approved word, or restructure (Rule 9.1).

## Part-of-speech traps (most common violations)

- **"log"** — noun only (the record). Not a verb. "Log the error" → "Write the error to the log."
- **"help"** — verb only (to assist). Not a noun. "The config help" → "The configuration help text."
- **"damage"** — noun only. "The call damaged the stack" → "The call caused damage to the stack."
- **"execute"** — not approved. "Execute the script" → "Run the script."
- **"flush"** — approved as BOTH verb ("remove remaining data from a buffer") and adjective
  ("one surface fully touches a different surface"): "Flush the output buffer" vs "Make sure
  the connector is flush with the port."
- **"get"** (verb, obtain) vs **`GET`** (HTTP method, technical noun). "Send a GET request to get the data."
- **"set"** — verb ("put into a state") and noun ("a group of items"). "the set timeout" is
  ambiguous → "the timeout value that you set".
- **"run"** — verb only; noun only in "test run"/"dry run". "do a run" → "run the tests".
- **"build"** — verb and noun (the result/version). Prefer "build the project" / "the build
  output" over bare "the build".
- **"check"** — verb only; noun only in "health check"/"type check". "do a check" → "check".
- **"return"** — verb ("give back"); "the return value" OK (noun adjunct), but "the return of
  the function" is not. "The function returns a User object."
- **"fix"** — verb only. "a fix for the bug" → "correct the bug".
- **"update"** — verb only. "an update to the config" → "update the config".
- **"make"** — verb "to create". Avoid light-verb phrases: "make a call"→"call"; "make a
  request"→"send a request". "make a copy of the file" is OK (new thing created).
- **"use"** — verb; don't use "using" as a preposition ("Using this method, you can…" → "Use
  this method to…"). (`using` in C# is a keyword = technical noun.)

## Per-document-type guidance

**README** — every verb/noun must be approved and used in its approved sense. "leverage"→
"use"; "facilitate"→"help"/"let you"; "functionality"→"feature"; "capability"→"can".
"Run the tests after you build the project" (not "after the build").

**API docs** — precise. "GET" (method) vs "get" (verb); "set the timeout" vs "a set of
endpoints"; "the function returns a value" not "the return of the function".

**Docstrings** — "do" only as a general main verb ("Do the setup"); for specific actions use
the specific verb ("Run the migration"). "make a call"→"call"; "make a request"→"send a
request".

**Commit messages** — imperative summary with approved verb: "Add feature" not "Implement
feature"; "Add breaking change" not "Introduce breaking change". "fix" verb OK; "a fix" noun
not. "Update the config" not "Ship an update to the config".

**Error messages** — use "cannot" not "unable to"/"failed to": "Cannot open the config file".
Use "must" only when the user must act to continue. "If the problem continues, look at the
log for more data."

## Paradigm-specific guidance

**OO (Java/C++/C#/Python)** — keywords as code font are technical nouns; in prose they are
unapproved verbs: `extend`→"is a child of"/"inherits from"; `implements`→"uses the
interface"; `override`→"replaces the parent method"; `abstract`→"base class; you cannot make
an instance".

> Non-STE: The `PaymentProcessor` abstract class implements the `TransactionHandler` interface and provides a default implementation for the `validate` method, which subclasses can override.
> STE:     The `PaymentProcessor` base class uses the `TransactionHandler` interface. It gives a default `validate` method. Child classes can replace this method.

**Functional (Haskell/Elixir/Clojure/Rust)** — function names are technical nouns; in prose
use approved verbs: "maps over"→"applies … to each element"; "reduce"→"combine the elements
into a single value"; "filter"→"remove elements that do not match"; "apply"→"use".

**Procedural (C/Go/Bash)** — `free()` is a function name (technical noun); in prose "free the
memory" (verb) or "the memory is free" (adjective). "open" (verb) not adjective "available";
"close" (verb) not adjective "near". "read" verb, not noun ("read the data" not "do a read").

> Non-STE: After you allocate memory on the heap with `malloc`, you must deallocate it with `free` when the program no longer needs it. Failing to free allocated memory causes memory leaks.
> STE:     After you get memory from the heap with `malloc`, you must free the memory with `free` when the program does not need it. If you do not free the memory, the program uses more memory over time.

**Declarative (SQL/Terraform/K8s YAML)** — SQL keywords `CREATE`/`SELECT`/`DROP` are technical
nouns; in prose "make a table", "get rows", "remove the table". `terraform apply` is a
command; "use `terraform apply` to make the changes".

> Non-STE: The `Deployment` resource creates and manages a set of replicated Pods. It ensures that the specified number of Pods are running at all times.
> STE:     The `Deployment` resource makes and controls a set of Pod copies. It makes sure that the set number of Pods runs at all times.

**Systems (Rust/C)** — keyword meanings are technical: `move` (ownership) is an approved
technical verb; `borrow`→"get a reference to"; `drop` (Rust) is an approved technical verb;
"own"→"has". Keep `&`/`borrow checker`/`ownership` as technical nouns.

## Words approved as multiple parts of speech
- **build** — verb (construct) and noun (result/version). Be specific: "the build output", not bare "the build".
- **run** — verb; noun only in "test run"/"dry run".
- **set** — verb ("put into a state") and noun ("a group of items").
- **check** — verb; noun only in "health check"/"type check"/"lint check".
- **flush** — verb and adjective (see above).

## Edge cases
- **Framework/tool names that are also unapproved words** (`Express`, `Flask`, `Fresh`,
  `FastAPI`): technical nouns, keep in code font/capitalization; never verb them ("Use the
  `Express` framework to write your API routes" not "Express your API").
- **Keywords that are also approved words** (`use`, `move`, `return`, `break`): code-font
  keyword = technical noun; prose follows the dictionary. "Do not break the API contract" →
  "Do not change the API contract" (only physical separation uses "break").
- **Generated code symbols** — keep unchanged; describe their function with approved words.
  If public API, wrap with an approved name. If you author the generator, apply the rules to
  its templates.
- **Quoted errors/logs** — keep exact; explain with approved words.

## Grammar notes
- **One meaning per word:** each approved word has one approved meaning; express other
  meanings with a different word.
- **Noun-verb boundary:** approved-verb-only words must not be used as nouns ("run"→"run the
  program", not "do a run"); approved-noun-only words must not be used as verbs ("log"→"write
  to the log", not "log the error").
- **Dictionary is the source of truth:** when unsure, look it up. After restructuring
  (Rule 9.1), re-apply Rule 9.2 to the new sentence.

## Cross-references
Rule 1.1 (approved words), 1.2 (part of speech), 1.3 (approved meanings), 1.4 (approved
verb/adjective forms), 1.5 (technical nouns exempt), 1.7 (don't verb technical nouns), 1.12
(technical verbs — use their correct technical meaning), 9.1 (restructure when no replacement),
9.3 (no phrasal verbs), 9.4 (consistent style). The STE-Code Dictionary (A–Z) is the
authoritative reference.

---

# Rule 9.3 — When You Use Two Words Together, Do Not Make Phrasal Verbs

**Core rule:** Do not combine an approved verb with a preposition/particle to make a phrasal
verb (a phrase whose meaning differs from its parts). Replace a phrasal verb with a single
approved verb that has the same meaning. Only a few phrasal verbs are explicitly approved
(see list below), and they have a restricted meaning.

**Test:** If you can remove the preposition and the sentence keeps ~the same meaning, it is a
prepositional phrase (permitted, e.g. "write the config to the file"). If removing the
preposition changes the meaning completely, it is a phrasal verb (not approved, e.g. "write
up the report" = compose formally).

## Common phrasal-verb → approved-verb replacements
- put out → emit (compiler "puts out a warning" → "emits a warning")
- give off → return (function "gives off an error code" → "returns an error code")
- carry out → do (task "carries out the deallocation" → "does the deallocation")
- set up → configure / install / create (init with params = configure; place files = install; from nothing = create)
- run through → execute / complete
- look at → examine / inspect
- filter out → remove (note: "filter" alone is an approved technical verb)
- pick out → select
- kick off / kick in → start
- break down → divide / separate / analyze
- go on → continue
- hook into / tap into → connect to / subscribe to (also slang — doubly non-compliant)
- clean up → remove / delete / tidy
- fix up → correct / repair
- speed up → accelerate / make faster
- cut down → reduce / decrease
- wire up → connect
- strip out / rip out → remove
- flesh out → complete / expand
- hand off → send / transfer
- tear down → release
- spin up → start
- bring up → create
- hold onto → keep a reference to
- give up (lock) → release
- carve out → allocate
- reach out to → send a request to

## Per-document-type guidance
**README** — one approved verb per heading/paragraph: "Set up the project" → "Install the
project"; "Run through the quickstart" → "Complete the quickstart"; "Check out the examples" →
"Examine the examples".

**API docs** — verb must match the operation exactly: "Looks up a user" → "Finds a user"; GET
"gets" not "pulls down"; POST "creates"/"sends" not "puts in".

**Docstrings** — "Runs through and picks out" → "Examines and selects"; "Sets up and kicks off"
→ "Configures and starts".

**Commit messages** — one approved verb per change category (table above). "Clean up the
endpoints" → "Remove the endpoints".

**Error messages** — "Could not hook up to the database" → "Could not connect to the
database"; "blew up" → "failed"; "out of whack … sort it out" → "not consistent … correct it".

**Changelogs** — "did away with" → "removed"; "added back" → "restored"; "ironed out" →
"corrected"; "phased out" → "ended support for".

## Paradigm-specific guidance
**OO** — "sets up the object state" → "initializes"; "tears down resources" → "releases";
"hands off ownership" → "transfers ownership"; "looks up the dependency" → "finds"; "wraps up
the transaction" → "completes".

**Functional** — "maps over and filters out" → "applies a transformation to each element and
removes"; "pipes through" → "sends through"; "folds down" → "combines into"; "reaches out to"
→ "sends a request to".

**Procedural (C/Go/Bash)** — "free up" → "release"/"free"; "hands back" → "returns"; "reach
out and pull down" → "send a request and get"; "go through and pick out" → "examine and
select"; "put together and send off" → "make and send".

**Declarative** — "brings up EC2 instances" → "creates"; "spins up pods" → "starts"; "tears
down the index" → "removes"; "joins together" → "joins … with".

**Systems (Rust/C)** — "hands off ownership" → "transfers ownership"; "holds onto the
captured variable" → "keeps a reference to"; "gives up the lock" → "releases the lock";
"carves out a region" → "allocates".

## Approved phrasal verbs (restricted meaning — use as-is)
| Phrasal verb | Restricted meaning | Example |
|---|---|---|
| log in / log out | Start/end an authenticated session | "The user must log in before they can access the dashboard." |
| follow up | Take further action after an initial step | "Follow up the installation with the configuration step." |
| back up | Make a copy for safekeeping | "Back up the database before you apply the migration." |
| roll back | Return to a previous state | "Roll back the deployment if the health check fails." |

Do not use "sign in/out", "log on/off". "back up" is approved ONLY for copies, not movement
or support.

## Edge cases
- **Framework/tool names that are phrasal verbs** (`setuptools`, `cleanup`, `rollback`): the
  name is a technical noun (keep). Describe its behavior with an approved verb
  (`setuptools`.configures…, not `sets up`).
- **Keywords that are phrasal-verb components** (`break`, `continue`, `throw`, `catch`): as
  keywords/technical verbs they are approved ("the `break` statement exits the loop"; "the
  handler catches the error"). But "breaks out of the loop" / "catches up with the stream" are
  phrasal verbs → "exits the loop" / "synchronizes with the stream".
- **Not every verb+preposition is a phrasal verb** — prepositional phrases of location/direction/
  time are permitted ("runs on the server", "flows from A to B", "write the config to the file").
- **Generated docs** — apply the rule to the source docstrings; the generator output inherits
  compliance. Third-party generated docs you cannot edit need not be corrected.
- **No single approved verb exists** — apply Rule 9.1 (rewrite the sentence): "calls back the
  caller" → "sends the result to the caller through a callback"; "warms up" → "loads the data".

## Why this matters
Phrasal verbs cause **ambiguity** (multiple meanings), **non-native comprehension difficulty**,
and **poor searchability** (a search for "remove" misses "take off"/"strip out"). The
"one word where possible" principle: prefer a single approved verb over a 2–3 word phrase.

## Cross-references
Rule 1.1 (approved words), 1.2 (part of speech — the particle is not a direction preposition),
1.4 (approved verb forms), 1.11 (one term per concept — don't alternate "set up"/"configure"),
1.12 (technical verbs: don't replace "serialize" with "turn into a string"), 9.1 (rewrite when
no single verb fits), 9.2 (each word in a non-phrasal combo must carry its approved meaning).

---

# Rule 9.4 — When You Select Terminology or Wording, Always Use a Consistent Style

**Core rule:** Use the same term for the same thing, the same verb for the same action, and
the same sentence structure for the same type of instruction — everywhere in the document and
across the project. Different wording for the same concept forces the reader to ask "is this
the same thing?" and causes confusion and bugs.

**Three consistency domains (each maintained independently):**
1. **Lexical** — one term per concept (grep-auditable). Don't alternate "configuration file" /
   "settings file" / "config".
2. **Syntactic** — same structure for the same action. All setup steps start with an imperative
   verb + purpose clause; don't switch to passive/conditional for some.
3. **Semantic** — one meaning per term across files/modules/types. If "build" = "compile and
   link" in the README, it must not mean "compile, link, and package" in CI docs.

## Per-document-type guidance
- **README** — one term for the project artifact ("library" not "library"/"package").
- **API docs** — one name per endpoint/method/parameter; prose must match the schema field name
  (`createdAt` in schema → don't call it "creation date"/"timestamp"/"created time" in prose).
- **Docstrings** — use the same term as the function signature. Param `max_retries` → don't call
  it "maximum attempts"/"retry limit" in the body.
- **Commit messages** — one imperative verb per change category ("Add" for new features; don't
  mix "Introduce"/"Insert"/"Create").
- **Error messages** — same code → same text every time (`E_CONNECT_FAIL` must say the same
  string in every module so logs are searchable).
- **CLI help** — the `--output` description must match in `--help`, man pages, docs, and errors.

## Paradigm-specific guidance
**OO** — in a class hierarchy, reuse the base-class docstring template for overridden methods
(`connect()` everywhere says "Establishes a connection to the remote host, with …"). Don't
abbreviate class names inconsistently (`UserRepository` not `UserRepo`/`the user repo`).

**Functional** — one anchor phrase for pure functions ("returns a new list"); don't say
"produces a result"/"yields output". One metaphor for `IO` ("a description of an effect" not
"a computation"/"an action").

**Procedural (C/Go/Bash)** — predictable step structure on every I/O step ("Write the buffer to
the file descriptor" not "Output the data to the fd"). Same error-check pattern for every
`if err != nil`.

**Declarative** — same phrase per resource type ("a virtual machine in AWS EC2" not
"EC2 instance"/"AWS VM"/"cloud server"). Use `ConfigMap`/`Pod` consistently; never "config map"/
"configmap"/"configuration map".

**Systems (Rust/C)** — "ownership", "borrow", "lifetime", "move" are precise terms of art; never
substitute synonyms ("The function takes ownership of the buffer. The function moves the
buffer." not "takes possession"/"relinquishes control").

## Worked examples
- **Verb consistency:** "Install the dependencies. Then download the source. After that, set the
  environment variables. Finally, start the database." (not "fetch"/"set up"/"get … running")
- **Noun consistency across README/API/error:** "authentication library" is the only term (not
  "auth"/"module"/"package").
- **API reference structure:** every endpoint description starts with a third-person singular
  verb; "retrieves"/"gets" unified to "returns".
- **Commit convention:** all new features use "Add".
- **Error consistency:** one failure mode → one message "Cannot connect to the remote host" in
  every service (searchable across logs).
- **CLI flags:** each flag uses the same template "Enables/Disables [adjective] output".

## Edge cases
- **Framework-mandated terminology** — defer to the framework: use "props" (React) everywhere,
  never "properties"/"arguments". Consistency beats STE-Code synonym preference for proper names.
- **Generated docs** — fix the source docstrings, not the generated output. For conventional-
  commit changelogs, CI must reject non-standard verbs rather than emit inconsistent text.
- **Cross-project (monorepo)** — per-service docs follow the service glossary; system-level docs
  define a system-wide glossary that maps each system term to its service-level term.
- **Multiple valid industry names** — pick one ("GitHub Actions workflow" OR "pipeline"),
  document it in the glossary, never alternate.
- **Version rename** — each version's docs use that version's canonical name; migration guides
  must state the rename explicitly.

## Grammar notes
- **Cognitive load of synonymy** — every synonym forces a "is X the same as Y?" test that steals
  attention from content.
- **Structural parallelism** — a predictable template lets the reader scan for the action verb
  and skip scaffolding.
- **Term drift** — terminology drifts under multi-author maintenance. When you add content,
  search the existing doc for the terms you plan to use and match the convention.
- **Cross-language consistency** — Python `connect()` and TypeScript `connect()` must share the
  same description template.

## Preferred synonym table (pick one, use everywhere)
use (not utilize/leverage/employ) · start (not initiate/commence/bootstrap) · show (not
display/render/present) · make (not create/generate/produce) · get (not retrieve/fetch/obtain) ·
set (not configure/assign/establish) · check (not verify/validate/ensure) · remove (not
delete/eliminate/purge) · keep (not retain/preserve/maintain) · send (not transmit/dispatch/
forward). Variation in technical documentation is a defect, not a stylistic virtue.

## Cross-references
Rule 1.1 (approved words — cannot be consistent while alternating approved/unapproved),
Rule 1.3 (approved meanings — one meaning per word), Rule 1.5 (technical nouns exempt from the
dictionary but NOT from consistency), Rule 1.11 (one term per concept — lexical foundation of
9.4), Rule 9.1 (restructure rather than introduce a synonym), Rule 9.2 (a word used incorrectly
in one place breaks the consistency chain). The canonical synonym table (spec Section 1) is the
starting point; Rule 9.4 is the discipline that sustains it.


# === tier level4 ===


# STE-Code Level 4 — distilled index

> + extensions + reference catalogue

## Sub-documents

- 01-principles.md
- 02-synonyms.md
- 03-dictionary.md
- 04-templates.md
- 05-grammar.md
- 06-extensions.md
- 07-catalogue.md
- rules-sec1-part1.md
- rules-sec1-part2.md
- rules-sec2.md
- rules-sec3.md
- rules-sec4.md
- rules-sec5.md
- rules-sec6.md
- rules-sec7.md
- rules-sec8.md
- rules-sec9.md



## 01-principles.md

# Level 4 — Core Principles (Words: Rules 1.1–1.14) + Extensions + Reference Catalogue

Level 4 contains the complete core-principles slice of STE-Code, plus the
extension vocabulary and the vendor/community reference catalogue that lower
tiers omit. Use this file when you generate, review, or lint code
documentation with an LLM.

Section 1 of STE-Code governs **words**: which words you may use, in which part
of speech, with which meaning, and in which form. Every other section assumes
these fourteen rules already hold.

Three gates decide whether a word is allowed:

1. The word is **approved in the controlled terminology** (STE-Code part 2), or
2. The word is a **code-domain technical noun** (Rule 1.5, 19 categories), or
3. The word is a **code-domain technical verb** (Rule 1.12, 4 categories).

A word that passes no gate must be replaced, or the sentence must be
restructured so that approved words carry the meaning.

Definitions:

- **Controlled terminology** — the STE-Code approved word list. Each entry gives
  one part of speech and one approved meaning, plus the approved verb and
  adjective forms.
- **Code-domain technical noun** — a noun term for a specified concept in
  software development, applicable to a subject field (Rule 1.5, 19 categories).
- **Code-domain technical verb** — a verb term for a specified operation or
  process in software development (Rule 1.12, 4 categories).

Rule index:

| Rule | Statement |
|------|-----------|
| 1.1 | Use words that are approved, code-domain technical nouns, or code-domain technical verbs. |
| 1.2 | Use approved words only as the specified part of speech. |
| 1.3 | Use approved words only with their approved meanings. |
| 1.4 | Use only the approved forms of verbs and adjectives. |
| 1.5 | You can use words you can include in a code-domain technical noun category. |
| 1.6 | Use an unapproved word only when it is a code-domain technical noun or part of one. |
| 1.7 | Do not use code-domain technical nouns as verbs. |
| 1.8 | Use code-domain technical nouns approved in your project, company, industry, or subject field. |
| 1.9 | When you must select a code-domain technical noun, use one that is short and easy to understand. |
| 1.10 | Do not use regional, slang, or jargon words as code-domain technical nouns. |
| 1.11 | Do not use different code-domain technical nouns for the same item. |
| 1.12 | You can use verbs you can include in a code-domain technical verb category. |
| 1.13 | Do not use code-domain technical verbs as nouns. |
| 1.14 | Use American English spelling unless other official directives tell you differently. |

---

## Rule 1.1 — Use approved words, code-domain technical nouns, or code-domain technical verbs

In code documentation, use words that are:

- approved in the project controlled terminology,
- code-domain technical nouns, or
- code-domain technical verbs.

The controlled terminology gives the words most frequently used in code
documentation. It also lists words that are **not** approved, with approved
alternatives. Your project glossary or terminology database holds the technical
nouns and technical verbs of your subject field; always check it first.

Worked vocabulary swaps:

| Do not write | Write | Why |
|---|---|---|
| execute the script | run the script | "run" is the approved verb for executing programs |
| generate the artifact | make the artifact | "make" is approved; "generate" is not |
| utilize / leverage the cache | use the cache | inflated verb |
| bootstrap / initiate the service | start the service | "start" is approved |
| configure the runtime | set the runtime behavior | "set" is approved |
| retrieve / fetch the record | get the record | "get" is approved |
| transmit the payload | send the data | "send" is approved |
| validate / verify the input | check the input | "check" is approved |
| unable to connect | cannot connect | "cannot" is approved |
| invalid / malformed data | incorrect data | "correct" is the approved adjective |

Technical terms stay: `UserAuthenticator` is a code-domain technical noun,
`serialize` is a code-domain technical verb, and both are permitted although
neither is in the controlled terminology.

Examples by documentation type:

> **Non-STE (README):** To begin utilizing the build toolchain, you must first
> generate the distributable artifact, then execute the compiled binary to
> bootstrap the local development service.
>
> **STE:** Use the build tool to make the binary. Run the binary to start the
> local service.

> **Non-STE (JSDoc):** Fetches a user record. The duration in milliseconds the
> client shall await a response prior to terminating the connection attempt.
>
> **STE:** Gets a user record. The time in milliseconds that the client waits
> for a response before it stops the connection.

> **Non-STE (cli error):** Unable to establish connection to the database.
> Please verify your credentials and retry.
>
> **STE:** Cannot connect to the database. Check your credentials and try again.

Paradigm notes:

- **Object-oriented** — prose uses approved verbs (make, get, set, call, send,
  keep). Class, method, and pattern names stay as technical nouns.
- **Functional** — `map`, `fold`, `reduce`, `filter`, `compose`, and `curry` are
  code-domain technical verbs. "Pure function" is a compound technical noun.
- **Procedural** — each step starts with an approved imperative verb. "Allocate"
  is not approved (write "make a buffer"). "Free" and "dereference" are
  code-domain technical verbs.
- **Declarative** — SQL keywords and resource kind names are technical terms.
  "Provision" is not approved (use "make" or "set up"); "orchestrate" is not
  approved (use "control" or "manage").
- **Systems** — "own", "borrow", and "move" are Rust technical verbs. "Dangling
  pointer" and "undefined behavior" are compound technical nouns (category 15).

---

## Rule 1.2 — Use approved words only as the specified part of speech

Each entry in the controlled terminology carries one label: verb (v), noun (n),
adjective (adj), adverb (adv), preposition (prep), conjunction (conj), pronoun
(pron), or article (art). Use the word only in that grammatical role.

- "Query" is an approved **noun**, not a verb. Write "Send a query to the
  database", not "Query the database".
- "Static" is an approved **adjective**, not a verb. Write "Make the variable
  static", not "Static the variable".
- Some words carry more than one label. "Call" is an approved verb and an
  approved noun; the position in the sentence shows the function.

If the word you want is not in the controlled terminology:

1. Find the word in a standard English dictionary.
2. Find the best synonym that is approved in the STE-Code controlled terminology.
3. Use that approved word, or write a different sentence construction.

When you replace a word, make sure that the meaning does not change.

| Violating form | Part-of-speech error | Approved replacement |
|---|---|---|
| Query the database / Cache the result / Queue the job / Log the error | technical noun used as verb | Send a query / Keep the result in the cache / Put the job in the queue / Write the error in the log |
| Docker the app / Git the change / Kubectl the pod | tool name used as verb | Use Docker / Save with Git / Use `kubectl` |
| Secure the endpoint / Empty the buffer / Silent the log | adjective used as verb | Make the endpoint secure / Make the buffer empty / Make the log silent |
| Static the variable / Ready the worker / Live the connection | adjective used as verb | Make the variable static / Make the worker ready / Make the connection live |
| Utilize / Leverage / Employ the service | inflated verb | Use the service |
| Commence the build / Initiate the transfer / Terminate the process | inflated verb | Start the build / Start the transfer / Stop the process |
| Orchestrate the services / Facilitate the sync | unapproved verb | Control the services / Help the sync |

> **Non-STE:** Docker the app and deploy to production. If it fails, rollback.
>
> **STE:** Use Docker to make a container for the application. Deploy the
> container to production. If the deployment fails, roll back to the previous
> version.

---

## Rule 1.3 — Use approved words only with their approved meanings

Each approved word has one specified meaning, often narrower than the standard
English meaning. Do not use an approved word with any other meaning.

- The approved meaning of the verb **follow** is "come after, go after". Use it
  only for sequence: "Do the steps that follow."
- The approved meaning of the verb **obey** is "to do that which the procedures
  or instructions tell you". Use it for compliance: "Obey the instructions."

Four-step check for every approved word you write:

1. **Identify the part of speech** as you used it in the sentence.
2. **Look up the approved meaning** for that part of speech in the controlled
   terminology.
3. **Ask: does my sentence use exactly that meaning?** If not, the word fails —
   even when the word is approved and the sentence reads well.
4. **Replace or restructure** so the approved word carries its approved meaning.

Worked check:

> **Sentence:** The background worker runs every night.
> **Step 1:** "runs" is a verb.
> **Step 2:** Approved meaning of "run" = "execute a program or command".
> **Step 3:** The writer means "operates on a schedule". The meaning does not match.
> **Step 4:** Rewrite: "The background worker operates every night."

---

## Rule 1.4 — Use only the approved forms of verbs and adjectives

The controlled terminology gives each approved verb with its approved forms, and
each approved adjective in the base form with the comparative and superlative
forms where applicable.

Verb entry: `COMPILE (v), COMPILES, COMPILED, COMPILED`

| Infinitive / imperative | Simple present | Simple past | Past participle (as adjective) |
|---|---|---|---|
| (To) Compile / Compile | Compile(s) | Compiled | Compiled |

Forms that are not listed are not permitted: "compilating" and "compilates" are
both incorrect.

Adjective entry: `FAST (adj) (FASTER, FASTEST)` — base form *fast*, comparative
*faster*, superlative *fastest*. Adjectives that make their comparative and
superlative with "more" and "most" have no extra forms in the terminology,
because "more" and "most" are approved words.

Do not use the "-ing" form as a main verb in procedural writing unless the
controlled terminology lists it.

> **Non-STE:** The compiler is compilating the source files every time you save
> the document.
>
> **STE:** The compiler compiles the source files each time you save the document.

> **Non-STE:** This algorithm is more fast than the previous one.
>
> **STE:** This algorithm is faster than the previous one.

> **Non-STE:** After installing the dependencies, you can start compiling the
> project by running the build script.
>
> **STE:** After you install the dependencies, compile the project with the build
> script.

---

## Rule 1.5 — Code-domain technical noun categories

A code-domain technical noun is a noun term for a specified concept in software
development, applicable to a subject field. The controlled terminology cannot
list them all, because each project uses different ones; keep yours in the
project glossary or terminology database.

You may use a code-domain technical noun in procedural and descriptive writing
when you can put it in one or more of these **nineteen** categories. The words
shown are examples only, not a complete list.

| # | Category | Example terms |
|---|---|---|
| 1 | Code components, modules, and libraries | class, controller, helper, hook, middleware, mixin, module, package, plugin, provider, repository, service, utility |
| 2 | Computing devices and their components | CPU, disk, GPU, keyboard, laptop, memory, monitor, mouse, printer, screen, server, smartphone, tablet, terminal |
| 3 | Development tools, environments, and support equipment | CLI, compiler, debugger, Docker, editor, IDE, Git, Jest, linter, loader, Prettier, terminal, test runner, TypeScript, webpack |
| 4 | Data structures, types, and formats | array, boolean, buffer, CSV, enum, hash map, integer, JSON, linked list, object, queue, stack, string, struct, tree, tuple, XML, YAML |
| 5 | Infrastructure, deployment, and platforms | AWS, CI/CD, container, deployment, Heroku, Kubernetes, load balancer, Node.js, pipeline, pod, production, staging, Vercel |
| 6 | Systems, subsystems, and architectural components | API gateway, authentication layer, caching layer, client, database layer, message broker, microservice, proxy, rate limiter, REST API, routing layer, server, WebSocket |
| 7 | Mathematical, algorithmic, and scientific terms | Big O notation, binary search, coefficient, complexity, exponent, hash function, iteration, logarithm, matrix, recursion, regex, sorting algorithm, time complexity, traversal |
| 8 | Interface elements and navigation | button, checkbox, dialog, dropdown, footer, header, menu, modal, navigation bar, radio button, scrollbar, sidebar, tab, text field, toggle, tooltip |
| 9 | Numbers, units of measurement, and time | byte, gigabyte (GB), hertz (Hz), hour (h), kilobyte (KB), megabyte (MB), millisecond (ms), minute, nanosecond (ns), second (s), terabyte (TB) |
| 10 | Quoted text (text you cannot change: error messages, code snippets, UI labels, log output) | `Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused` |
| 11 | Professional roles, teams, and organizations | administrator, backend developer, contributor, DevOps engineer, frontend developer, Google, maintainer, Microsoft, product owner, QA engineer, reviewer, scrum master, user |
| 12 | Official documents, API references, and standards | API reference, changelog, code of conduct, contributing guide, diagram, figure, Getting Started guide, HTTP specification, note, paragraph, README, release notes, RFC, section, table, warning |
| 13 | Runtime environments and operational conditions | development, environment variable, garbage collection, heap, hot reload, live reload, memory leak, production, sandbox, stack trace, staging, test, thread, timeout, virtual machine |
| 14 | Colors | black, blue, cyan, gray, green, magenta, orange, red, white, yellow |
| 15 | Defects, errors, and fault terminology | assertion failure, bug, crash, deadlock, defect, exception, hang, infinite loop, memory leak, null pointer, race condition, regression, stack overflow, timeout, type error |
| 16 | Computer science, information, and communication technology | AI, algorithm, authentication, authorization, blockchain, containerization, cryptography, database, encoding, encryption, firewall, hashing, internet, machine learning, metadata, neural network, protocol, query, sandbox, schema, token, virtualization |
| 17 | Legal and licensing terms | Apache 2.0, BSD license, compliance, copyright, GPL, license, MIT license, open source, proprietary, terms of service, third-party, trademark, warranty |
| 18 | Database and storage terminology | connection pool, cursor, foreign key, index, migration, NoSQL, ORM, PostgreSQL, primary key, query, Redis, relation, row, schema, seed, SQL, SQLite, stored procedure, table, transaction, view |
| 19 | Network and protocol terminology | DNS, endpoint, HTTP, HTTPS, IP address, localhost, middleware, packet, port, request, response, route, socket, SSH, TCP, TLS, UDP, URL, VPN, WebSocket |

Note on category 14: colors are adjectives, but STE-Code identifies them as
code-domain technical nouns. Comparative and superlative forms of colors (for
example "blacker", "the reddest") are not permitted.

---

## Rule 1.6 — Unapproved words are permitted only inside technical nouns

A word that the controlled terminology marks as not approved fails when you use
it as a general noun or adjective, and passes when it is part of a recognized
code-domain technical noun.

**"Handler"** — not approved; the alternative is "function (n)".

> **Non-STE:** The handler processes each incoming event.
>
> **STE:** The function processes each incoming event.
>
> **STE:** The event handler processes each incoming event. ("Event handler" is a
> code-domain technical noun, category 1.)

**"Main"** — not approved as a general adjective; the alternative is
"primary (adj)".

> **Non-STE:** The main configuration has the latest values.
>
> **STE:** The primary configuration has the latest values.
>
> **STE:** Merge the feature branch into the main branch. ("Main branch" is a
> code-domain technical noun, category 5. Do not write "primary branch".)

**"Base"** — not approved for a surface location; the alternative is "bottom
(n)". "Base" stays inside the technical nouns "base case" (category 7) and "base
class" (category 1).

> **Non-STE:** Copy the files to the base of the build folder.
>
> **STE:** Copy the files to the bottom of the build folder.

---

## Rule 1.7 — Do not use code-domain technical nouns as verbs

Use a code-domain technical noun only as a noun, or as an adjective inside a
different technical noun. Restructure the sentence with an approved verb.

> **Non-STE:** Database the user records before the migration.
>
> **STE:** Store the user records in the database before the migration.

> **Non-STE:** Cache the API responses to improve performance.
>
> **STE:** Store the API responses in the cache to improve performance.

A word can be a technical noun **and** a technical verb when it fits a category
in Rule 1.5 and a category in Rule 1.12. Your project glossary decides:

> **STE (noun):** Write a log entry for each failed request.
>
> **STE (verb):** Log each failed request.

> **See also:** Rule 1.5, Rule 1.12, Rule 1.13.

---

## Rule 1.8 — Use the technical nouns approved in your project or field

If your project, company, industry, or subject field already has an approved
name for a class, module, function, method, variable, component, or process, use
that name. These names live in your project glossary, API documentation, coding
standards, or company documentation. Do not invent your own names for items that
already have established names. The source of truth is the repository.

> **STE:** The dashboard page has a `UserTable` component and a `FilterPanel`
> component.

> **Non-STE:** The account controller manages login and user profile operations.
>
> **STE:** The `AccountController` manages authentication and user profile
> operations.

---

## Rule 1.9 — Select short, easy technical nouns

When no approved technical noun exists in your project, company, industry, or
subject field, select one that is short (not more than three words) and easy to
understand. Do not write a long descriptive phrase when a shorter term is
enough. When the context identifies the item — a code snippet, a line number, a
diagram, an API reference — use the shortest unambiguous term. Add one or two
adjectives only when clarification is necessary.

```javascript
// client.js — line 42
async function fetchUtility(url) {
  const response = await fetch(url);
  return response.json();
}
```

> **Non-STE:** Call the asynchronous JavaScript XML HTTP request wrapper utility
> function (line 42) to get the serialized JSON payload from the remote
> application programming interface endpoint.
>
> **STE:** Call the `fetchUtility` function (line 42) to get the JSON data from
> the API endpoint.

---

## Rule 1.10 — No regional, slang, or jargon words as technical nouns

Some technical words are used only inside confined communities or single
technology ecosystems. They are not easy to understand for readers from a
different background or stack. Code documentation is read by junior developers,
developers from other language communities, and non-native English speakers: a
word that one subculture finds clear can be opaque to every other reader. Always
select well-known words.

| Do not write | Write |
|---|---|
| Remove all the cruft from the legacy module. | Remove all the unnecessary code from the legacy module. |
| The function monkeys with the input data before validation. | The function changes the input data before validation. |
| Bikeshedding delayed the API design by two weeks. | Unnecessary discussion about small details delayed the API design by two weeks. |
| I spent the morning yak shaving before I could write the test. | I spent the morning completing unrelated prerequisite tasks before I could write the test. |
| Replace the foo and bar placeholders with real values. | Replace the example and placeholder values with real values. |

---

## Rule 1.11 — One technical noun per item

Do not use a different code-domain technical noun in another part of your
documentation for the same item. Changing the name of one item between sections
forces the reader to decide whether you mean the same item or a different one.
The source of truth for the name is the code: the class, function, module,
table, resource, environment variable, or configuration key as it is defined in
the repository.

> **Non-STE:**
> 1. Initialize the UserService class to start the session manager.
> 2. Call the authenticate method on the AccountManager to verify a user.
> 3. The UserHandler returns a session token that you send in later requests.
>
> **STE:**
> 1. Initialize the UserService class to start the session manager.
> 2. Call the authenticate method on the UserService to verify a user.
> 3. The UserService returns a session token that you send in later requests.

> **Non-STE:** "/api/login path", "authentication route", "login endpoint" —
> three names for one endpoint.
>
> **STE:** Use "/api/login endpoint" in every sentence, because the OpenAPI file
> defines the path as `/api/login`.

---

## Rule 1.12 — You can use verbs you can include in a code-domain technical verb category

A code-domain technical verb is a verb term that refers to a specified operation
or process in software development and is applicable to a subject field. The
controlled terminology does not include them all; keep yours in the project
glossary or terminology database.

Code-domain technical verbs must obey the same rules as other approved verbs.
Use them in procedural and descriptive texts when you can put them in one or more
of these four categories (examples only, not a complete list):

1. **Development processes**
   - a) Write and modify code: compile, concatenate, import, inject, instantiate,
     lint, minify, marshal, optimize, polyfill, refactor, resolve, shim, stub,
     substitute, tokenize, transpile, trace, vectorize
   - b) Test and verify code: assert, benchmark, debug, fuzz, instrument, mock,
     profile, snapshot, spy, stub, unit-test
   - c) Build and package: bundle, deploy, package, publish, release, tag, version
   - d) Manage dependencies: hoist, install, link, lock, pin, update, upgrade

2. **Computer processes and applications**
   - a) Input and output: click, copy, cut, digitize, enter, paste, press, print,
     scan, swipe, tap, type
   - b) UI and application operations: clear, close, delete, deselect, disable,
     drag, enable, encrypt, erase, filter, hide, highlight, invalidate, maximize,
     minimize, navigate, open, save, scroll, select, show, sort, store, submit,
     toggle, validate, zoom in, zoom out
   - c) System operations: abort, authenticate, authorize, boot, cache,
     communicate, configure, debug, deserialize, download, format, hydrate,
     initialize, install, load, log, manage, mount, process, reboot, render,
     retry, serialize, spawn, synchronize, throttle, update, upgrade, upload

3. **Instructions and information for applicable subject fields**
   - a) Algorithmic, mathematical, data: aggregate, bisect, compute, concatenate,
     convert, count, decode, encode, escape, filter, hash, index, map, merge,
     normalize, parse, pipeline, precompute, recalculate, reduce, tokenize,
     transform, validate, verify
   - b) Database and storage: backup, compact, flush, index, migrate, persist,
     query, replicate, restore, roll back, seed, shard, upsert, vacuum,
     write-ahead
   - c) Network and communication: broadcast, connect, disconnect, establish,
     forward, handshake, intercept, listen, poll, proxy, reject, resolve, route,
     send, stream, timeout, tunnel, unsubscribe, webhook
   - d) Security and authentication: authenticate, authorize, decrypt, decode,
     encode, encrypt, hash, revoke, salt, sanitize, sign, validate, verify

4. **Legal and licensing terms** — only for legal and regulatory texts:
   acknowledge, assign, comply with, conform to, disclose, enforce, explain,
   grant, inform, license, modify, notify, permit, regulate, sign, supersede,
   waive

If there is an approved verb in the controlled terminology that accurately gives
the instruction or information, use the approved verb. Do not use a code-domain
technical verb if you can write the same sentence with approved words.

> **Non-STE:** If you detect a null pointer exception in the parser, fix it before
> the response returns to the client.
>
> **STE:** If you find a null pointer exception in the parser, fix it before the
> response returns to the client.

> **STE:** Read the API key from the configuration file. ("Enter" is a
> code-domain technical verb, category 2 a.)

> **Non-STE:** Run the database migration to version 3, then verify the row
> counts before you open the service.
>
> **STE:** Run the migration of the database schema to version 3, then check the
> row counts before you open the service. (Prefer approved "run" + technical noun
> "migration" over the technical verb "migrate" when precision is not lost.)

Dual-category note: a word may be both a technical verb (Rule 1.12) and a
technical noun (Rule 1.5). For example `deploy` is a technical verb (category 1
c) and a technical noun (category 5); `serialize` is a technical verb and also a
method name (technical noun). Let your project glossary decide the role.

---

## Rule 1.13 — Do not use code-domain technical verbs as nouns

Use code-domain technical verbs only as verbs, not as nouns. If you need a noun,
find an approved noun or a code-domain technical noun with the equivalent meaning.

The most common violation is the **light verb construction**: a weak verb (do,
make, perform, execute, run) paired with a nominalized technical verb.

| Do not write | Write |
|---|---|
| Make a commit of your changes | Commit your changes |
| Do a compile of the source files | Compile the source files |
| Execute a rollback of the migration | Roll back the migration |
| The import of the module takes ten seconds | The import operation for the module takes ten seconds |
| The merge of the feature branch caused a conflict | The merge operation of the feature branch caused a conflict |

Dual-category exception: when a word fits both a technical verb category (Rule
1.12) and a technical noun category (Rule 1.5), you may use it as a noun.

| Word | Technical Verb | Technical Noun |
|------|---------------|---------------|
| build | 1 c) Build and package | 3) Development tools |
| deploy | 1 c) Build and package | 5) Infrastructure, deployment, and platforms |
| test | 1 b) Test and verify code | 3) Development tools |
| commit | 2 c) System operations | 4) Data structures |
| merge | 1 c) Build and package | 4) Data structures |
| release | 1 c) Build and package | 5) Infrastructure, deployment, and platforms |
| patch | 1 a) Write and modify code | 4) Data structures |
| log | 2 c) System operations | 13) Runtime environments |
| import | 1 a) Write and modify code | 4) Data structures |

Article test: if you can put "a / an / the" before the word and the sentence
stays grammatical, the word is acting as a noun. If it is not a dual-category
word, the usage violates Rule 1.13. "The build failed" is correct (dual-category);
"the compile failed" is wrong (compile is only a technical verb).

Quoted tool output (Rule 1.5 category 10) is exempt: a compiler message that says
"compile error" is text you did not write and must not be changed.

> **See also:** Rule 1.5, Rule 1.7, Rule 1.12.

---

## Rule 1.14 — Use American English spelling unless other official directives tell you differently

Use the spelling specified in the STE-Code controlled terminology (American
English). Use a different spelling only if other project specifications, style
guides, contracts, or official directives apply.

If quoted text has British English spelling — an error message, a code comment, a
user interface label, terminal output — do not change it. Keep the quoted text as
it is (Rule 8.6). The surrounding prose must use American English spelling.

Common British → American pairs:

| British | American | Context |
|---------|----------|---------|
| colour | color | UI, terminal, theming |
| behaviour | behavior | feature descriptions, bug reports |
| organise / organise | organize | restructuring, refactoring |
| analyse / analyse | analyze | profiling, data processing |
| licence (noun) | license | software license, license key |
| defence | defense | security fixes |
| centre | center | layout, positioning |
| initialise | initialize | object initialization |
| serialise | serialize | object serialization |
| optimise | optimize | performance optimization |
| parametrise | parameterize | parameterized types |
| cancelled | canceled | canceled operations |
| customise | customize | custom behavior |
| minimise | minimize | rollout minimization |
| synchronise | synchronize | state sync |
| traveller | traveler | traveler pattern |

> **Non-STE:** The log file shows the colour of each output line. Initialise the
> variable before you use it in the loop.
>
> **STE:** The log file shows the color of each output line. Initialize the
> variable before you use it in the loop.

> **STE:** The terminal shows the message `Colour profile not recognised`.
> (Quoted terminal output keeps its British spelling; the prose around it uses
> American English.)

> **See also:** Rule 8.6 — Use Quoted Texts Correctly.

---

## Extension adjectives (Level 4 additions)

These adjectives are approved extensions to the controlled terminology, added for
the code domain. Use them as the specified part of speech (Rule 1.2).

| Adjective | Definition | STE example |
|-----------|------------|-------------|
| idempotent | Describes an operation that produces the same result when applied more than once, with no extra side effects after the first run. | Make the retry handler idempotent so a second call with the same input does not duplicate the record. |
| immutable | Describes a data structure or value that cannot be changed after it is created, which prevents accidental shared-state bugs. | Keep the request context immutable so concurrent threads cannot overwrite each other's values during a single operation. |
| atomic | Describes an operation that completes fully or not at all, with no partial result visible to other processes. | Wrap the balance update in an atomic transaction so the debit and credit always succeed or fail together. |
| thread-safe | Describes code that functions correctly when accessed by multiple threads at the same time without external locking. | Mark the singleton constructor thread-safe so two threads can call it on first use without creating two instances. |
| asynchronous | Describes a call or task that starts and returns before its work finishes, so the caller can do other work meanwhile. | Make the file upload asynchronous so the user interface stays responsive while the transfer runs in the background. |
| concurrent | Describes tasks that make progress within the same time period, interleaved by the scheduler rather than strictly sequentially. | Run the test suites in concurrent processes so the full check finishes in a fraction of the time. |

Full extension inventory (nouns + verbs + adjectives) lives in
`ste-code/artifacts/level4/06-extensions.md`.

---

## Reference catalogue (Level 4 additions)

These external references inform STE-Code's controlled vocabulary. They are NOT
part of the standard and are kept in `.agents/reference/` (outside final/) per
project rule. Listed here as a catalogue.

| Reference | Type | Source |
|---|---|---|
| Microsoft Writing Style Guide | page | https://learn.microsoft.com/en-us/style-guide/welcome/ |
| MicrosoftDocs/microsoft-style-guide (GitHub source) | page | https://github.com/MicrosoftDocs/microsoft-style-guide |
| Google Style Guides | page | https://google.github.io/styleguide/ |
| Kong/apiglossary | page | https://github.com/Kong/apiglossary |
| dwyl/technical-glossary | raw | https://raw.githubusercontent.com/dwyl/technical-glossary/main/README.md |
| jvalentino/glossary | page | https://github.com/jvalentino/glossary |
| GitHub Official Glossary | page | https://docs.github.com/en/get-started/learning-about-github/github-glossary |
| DevOps Style Guide Glossary | page | https://tydukes.github.io/coding-style-guide/glossary/ |
| ryanwi software-terms.dic | raw | https://gist.githubusercontent.com/ryanwi/6135845/raw/software-terms.dic |
| OpenSTE.org | pointer | https://openste.org/ |
| en-wl/wordlist (SCOWL) | page | https://github.com/en-wl/wordlist |
| MichaelWehar 5000-more-common | raw | https://raw.githubusercontent.com/MichaelWehar/Public-Domain-Word-Lists/master/5000-more-common.txt |
| dwyl/english-words | pointer | https://github.com/dwyl/english-words |

Full catalogue (with local mirror paths) lives in
`ste-code/artifacts/level4/07-catalogue.md`.




## 02-synonyms.md

# Level 4 — Synonyms and Approved Words: Technical Noun Categories

Source rule: STE-Code Rule 1.5 (adapted from ASD-STE100 Issue 9, Rule 1.5).

## Rule 1.5 (code-domain)

You can use a term that fits one or more technical noun categories.

A technical noun in code documentation is a noun term that names a specified
software concept and applies to a given codebase, library, or system.

The approved-word dictionary does not list project-specific technical nouns:
every codebase, framework, and ecosystem uses different terminology. Take those
terms from your project glossary, API reference, or architecture decision
records (ADRs), and keep them there.

Use technical nouns in procedural and descriptive code documentation only when
they fit at least one category below.

## How an LLM should apply this

1. Before writing a noun, ask: is it in the approved dictionary?
2. If not, ask: does it fit a technical noun category?
3. If yes — use the exact project name (`UserRepository`, `POST /api/v1/users`,
   `lodash@4.17.20`), not a vague placeholder.
4. If no — rewrite with an approved word. Do not invent terminology.

Vague nouns are never technical nouns. Replace them.

| Do not write | Write |
|---|---|
| thing, stuff, item (unspecified) | the named class, endpoint, file, or field |
| the data, the info | the `UserResponse` DTO, the `id` field |
| the tool, the system | `ESLint`, the `orders-service` microservice |

### Example pair

| Non-STE | STE |
|---|---|
| Use the thing to call the function that gets data from the database. | Use the `fetchUser` method of the `UserRepository` to retrieve a `User` record from the `PostgreSQL` database. |
| *("thing", "gets data" — no technical nouns; ambiguous)* | *(`fetchUser`, `UserRepository`, `User`, `PostgreSQL` — classified technical nouns: categories 1, 6, 19)* |

## The 19 technical noun categories (code domain)

A term is approved as a technical noun if it belongs to at least one category.
Categories are numbered as in the standard; the code-domain scope and the
approved example vocabulary follow each heading.

### Category 1 — API and library components

Scope: everything named in API reference documentation, SDK manifests, or
interface definition files.

*endpoint, method, parameter, query parameter, path parameter, request body, response body, header, status code, module, class, interface, type alias, enum, constant, decorator, middleware, route handler, serializer, DTO, model, schema, callback, hook, plugin*

| Non-STE | STE |
|---|---|
| Call the thing that makes users. | Call the `POST /api/v1/users` endpoint with a `CreateUserRequest` body to create a `User` resource. |
| The thing you get back has the ID and name. | The `UserResponse` DTO contains the `id` (UUID) and `displayName` (string) fields. |
| Pass the options object to configure the behavior. | Pass a `RetryPolicy` enum value to the `maxRetries` parameter of the `fetchWithRetry` function. |

### Category 2 — Applications, services, and their subsystems

Scope: deployable units and the locations that are part of them.

*web application, mobile app, desktop client, CLI tool, microservice, monolith, API gateway, load balancer, database server, message broker, cache layer, container, pod, cluster, frontend, backend, admin panel, user dashboard, authentication service, payment service, notification service, search engine, CDN, reverse proxy, serverless function, cron job, worker process*

| Non-STE | STE |
|---|---|
| The thing that runs the website broke. | The `nginx` reverse proxy on the `web-01` frontend server stopped responding. |
| Log into the admin area. | Log into the `AdminPanel` at `https://admin.example.com`. |
| The background job processor handles emails. | The `EmailWorker` process in the `worker` pod handles outbound email delivery. |

### Category 3 — Development tools, SDKs, and their components

*IDE, code editor, terminal emulator, compiler, interpreter, transpiler, bundler, linter, formatter, debugger, profiler, package manager, version control system, CI runner, test framework, assertion library, mocking library, static analyzer, API client, database client, container runtime, orchestration tool, IaC tool, monitoring dashboard, log aggregator, feature flag service, secrets manager*

| Non-STE | STE |
|---|---|
| Run the check tool to find problems. | Run `ESLint` with the `@company/eslint-config` preset to find lint violations. |
| Use the test thing to verify the code. | Use the `Jest` test framework with `@testing-library/react` to verify component behavior. |
| The build tool makes the final files. | The `Webpack` bundler, configured via `webpack.config.js`, produces the production bundle in `dist/`. |

### Category 4 — Dependencies, packages, and technical debt

Scope: consumed material that can cause regressions or malfunctions.

*dependency, transitive dependency, package, library, framework, runtime, polyfill, shim, vendor bundle, dead code, deprecated API, legacy module, orphaned code, code smell, TODO comment, FIXME comment, zombie import, circular dependency, peer dependency, dev dependency, optional dependency, pinned version, lockfile, SBOM, supply chain artifact, third-party script, ad-hoc patch, monkey-patch, workaround code*

| Non-STE | STE |
|---|---|
| Watch out for old stuff that nobody uses anymore. | Remove the deprecated `UserService.legacyCreate()` method — it is dead code with zero callers as of v3.2. |
| There's a problem with one of the things we installed. | The `lodash@4.17.20` transitive dependency introduces a prototype pollution vulnerability (CVE-2020-8203). |
| Don't use the thing from the old library. | Replace the deprecated `moment` package with the `date-fns` library in the `OrderTimeline` component. |

### Category 5 — Hosting, CI/CD, and deployment infrastructure

*cloud provider, region, availability zone, data center, Kubernetes cluster, namespace, Docker registry, artifact repository, build pipeline, deployment pipeline, staging environment, production environment, sandbox environment, on-premise server, virtual machine, bare-metal host, edge location, CDN endpoint, storage bucket, message queue, event bus, API gateway endpoint, load balancer target group, auto-scaling group, service mesh, ingress controller*

| Non-STE | STE |
|---|---|
| Deploy to the cloud place. | Deploy the `orders-service` container image to the `us-east-1` `production` Kubernetes cluster in namespace `orders`. |
| The pipeline builds and ships the code. | The `deploy-prod` GitHub Actions workflow builds the Docker image, pushes it to `ECR`, and applies the `kustomize` overlay for `production`. |

### Category 6 — Systems, architecture, and their configurations

Scope: the structure, operation, composition, and system design of software.

*architecture, design pattern, layered architecture, hexagonal architecture, microservice, event-driven architecture, CQRS, event sourcing, pub/sub, message queue, event bus, database shard, read replica, write-ahead log, connection pool, circuit breaker, retry policy, rate limiter, cache layer, CDN edge, feature flag, A/B test variant, canary deployment, blue-green deployment, rolling update, service registry, configuration provider, secret store, reverse proxy, API gateway route, middleware chain, plugin system, dependency injection container, ORM, migration runner*

| Non-STE | STE |
|---|---|
| The system uses a pattern to handle failures gracefully. | The `PaymentGateway` client uses a `CircuitBreaker` pattern — after 5 consecutive failures, it opens and returns cached fallback responses for 30 seconds. |
| The config changes depending on where it's running. | The `FeatureFlags` service resolves the `enable_new_checkout` flag from `LaunchDarkly` based on the `X-Environment` header (`staging` or `production`). |

### Category 7 — Algorithms, data structures, and formulas

*algorithm, data structure, Big-O notation, time complexity, space complexity, hash table, binary tree, linked list, graph, trie, bloom filter, LRU cache, consistent hashing, recursion, memoization, dynamic programming, greedy algorithm, backtracking, binary search, quicksort, mergesort, topological sort, Dijkstra, BFS, DFS, A\*, Paxos, Raft, two-phase commit, saga pattern, idempotency key, eventual consistency, CAP theorem, ACID, BASE, vector clock, Lamport timestamp, Merkle tree, shard key, partition key, compound index, covering index, query plan, cardinality, selectivity, normalization, denormalization, OLTP, OLAP, ETL, stream processing, batch processing, map-reduce, actor model, CSP, semaphore, mutex, atomic operation, CAS,* `O(n log n)`, `f(x) = x² + 3x - 2`

| Non-STE | STE |
|---|---|
| The search is fast because it uses a good algorithm. | The `SearchIndex` uses a `BloomFilter` (`O(k)` lookup, where `k` is the number of hash functions) to skip negative lookups before falling back to a `B-Tree` index scan. |
| The function remembers results so it doesn't recompute. | `computeShippingCost(addressHash)` is memoized with an `LRU Cache` (capacity 1024, `O(1)` eviction) to avoid redundant API calls. |

### Category 8 — Codebase navigation and project structure

*directory, subdirectory, file path, import path, package root, module root, workspace root, monorepo root, source directory, test directory, build output, entry point, barrel export, index file, re-export, absolute import, relative import, path alias, symlink, Git root, branch, tag, commit, HEAD, upstream, origin, fork, submodule, subtree, vendor directory, node_modules, virtual environment, GOPATH, classpath, namespace, package scope, module scope, public API surface, internal package, private module, exported symbol*

| Non-STE | STE |
|---|---|
| The file is in the utils folder somewhere. | The `formatCurrency` helper is in `src/shared/utils/formatting.ts`, re-exported from the barrel file at `src/shared/utils/index.ts`. |
| Go to the branch where the fix was made. | Check out the `hotfix/payment-timeout` branch from `origin` (forked from `main` at commit `a3f8b2c`). |

### Category 9 — Numbers, units of measurement, and time

*latency, throughput, response time, p50, p95, p99, p999, ops/sec, req/sec, RPM, RPS, QPS, TPS, bytes, KB, MB, GB, TB, KiB, MiB, ms, µs, ns, s, min, hr, CPU core, thread count, memory usage, heap size, stack size, GC pause, cold start time, warm start time, bootstrap time, build time, deploy time, MTTR, MTBF, uptime, downtime, error rate, success rate, availability (99.9%, 99.99%), RPO, RTO, SLO, SLI, SLA, concurrency, connection count, pool size, batch size, page size, offset, limit, TTL, timeout, interval, poll interval, retry delay, backoff multiplier, rate limit (tokens/sec), quota, sample rate, cardinality*

| Non-STE | STE |
|---|---|
| The API is pretty fast most of the time. | The `GET /search` endpoint has a p95 latency of 120 ms and a p99 latency of 350 ms at 5000 RPM. |
| Give it time to try again if it fails. | Configure the `RetryPolicy` with a `baseDelay` of 200 ms, a `maxDelay` of 5 s, and an exponential backoff multiplier of 2.0 (max 3 retries). |

### Category 10 — Quoted text

Scope: text you cannot change — error messages, log output, API responses, UI
string literals, command-line output.

*error message, stack trace, log line, HTTP response body, JSON payload, XML response, environment variable value, CLI flag, command option, shell command output, status code text, exception message, assertion message, deprecation warning, compiler diagnostic, linter rule ID, test failure message, benchmark output, profiler report, API route pattern, SQL query string, GraphQL query, regex pattern, glob pattern, cron expression, semantic version string, git commit hash, UUID string, JWT token (example),* `"Connection refused"`, `"404 Not Found"`, `"TypeError: Cannot read properties of undefined"`, `"--config=./prod.yaml"`, `"npm ERR! code ERESOLVE"`

| Non-STE | STE |
|---|---|
| If you get an error about the database, restart it. | If the application logs `"FATAL: sorry, too many clients already"` from `PostgreSQL`, restart the `pgbouncer` connection pooler. |
| Run the command with the flag that skips tests. | Run `./gradlew build -x test` (the `-x` flag excludes the `test` Gradle task from the build lifecycle). |

Quoted text is reproduced verbatim, even when it breaks other STE-Code rules.

### Category 11 — Roles, teams, and organizations

*maintainer, author, contributor, reviewer, approver, code owner, release manager, on-call engineer, SRE, DevOps engineer, security champion, triage team, core team, steering committee, technical lead, staff engineer, principal engineer, intern, vendor, client, stakeholder, end user, GitHub organization, npm organization, Docker Hub organization, CNCF, Apache Software Foundation, Linux Foundation, Mozilla, Google, Microsoft, OpenAPI Initiative, ECMA, ISO, W3C, IETF, OWASP,* `CODEOWNERS` file, `@backend-team`, `@security-reviewers`

### Category 12 — User interface elements and accessibility

*button, text input, checkbox, radio button, dropdown, select menu, toggle, slider, modal, dialog, tooltip, popover, toast, snackbar, banner, tab, accordion, breadcrumb, pagination, carousel, card, table, data grid, form, form field, label, placeholder, icon, avatar, badge, spinner, progress bar, skeleton loader, navbar, sidebar, footer, header, search bar, filter panel, drawer, split pane, context menu, keyboard shortcut, hotkey, focus trap, skip link, screen reader label, ARIA role, ARIA attribute, landmark region, heading hierarchy*

### Category 13 — User data, preferences, and session state

*user profile, display name, avatar URL, email address, phone number, billing address, shipping address, payment method, credit card, subscription plan, usage quota, rate limit bucket, API key, access token, refresh token, ID token, session cookie, CSRF token, user preference, theme setting, language locale, timezone, notification setting, opt-in flag, consent record, bookmark, watchlist, shopping cart, wishlist, search history, recently viewed, draft content, clipboard data, localStorage key, IndexedDB store, browser fingerprint, device ID, push notification token*

### Category 14 — Health, diagnostics, and observability

*health check, liveness probe, readiness probe, startup probe, heartbeat, ping, metric, trace, span, log level, structured log, correlation ID, trace ID, span ID, alert, incident, SLO, SLI, error budget, burn rate, on-call rotation, escalation policy, runbook, playbook, postmortem, root cause analysis (RCA), mean time to recovery (MTTR), mean time to detection (MTTD), anomaly detection, threshold breach, saturation, latency tail, error spike, traffic drop, resource exhaustion, memory pressure, disk pressure, CPU throttling, GC thrashing, connection storm, thundering herd, cascading failure, split-brain, partition, degraded state, brownout, blackout*

### Category 15 — Documents, standards, and their structural parts

*README, CHANGELOG, CONTRIBUTING, LICENSE, CODE_OF_CONDUCT, SECURITY, GOVERNANCE, ARCHITECTURE, ADR (Architecture Decision Record), RFC (Request for Comments), API reference, OpenAPI spec, GraphQL schema, AsyncAPI spec, style guide, coding standard, linting rules, PR template, issue template, discussion template, release notes, migration guide, upgrade guide, getting started guide, quickstart, tutorial, how-to guide, explanation, reference, concept document, FAQ, glossary, onboarding guide, runbook, playbook, incident report, postmortem, design doc, technical spec, product requirements document (PRD), test plan, test case, acceptance criteria, Definition of Done, Definition of Ready, service level agreement (SLA), terms of service (TOS), privacy policy, cookie policy, data processing agreement (DPA), semantic versioning (SemVer), conventional commits, Git commit message format, doc comment, TSDoc, JSDoc, godoc, docstring, annotation, attribute, decorator doc, heading, subheading, section, subsection, paragraph, code block, table, list, admonition (note, warning, tip, danger, caution, important), hyperlink, cross-reference, footnote, bibliography, index, glossary entry, TOC (table of contents)*

### Category 16 — Environmental and operational conditions

Scope: runtime environments, execution contexts, and operating parameters that
affect software behavior.

*production, staging, development, testing, CI, localhost, operating system, OS version, kernel version, distribution, CPU architecture (x86_64, arm64), Node.js version, Python version, Java version, Go version, browser, browser version, rendering engine, screen resolution, viewport size, device type, network condition (offline, slow 3G, 4G, WiFi), Docker image, container runtime, Kubernetes version, cloud region, availability zone, environment variable, build flag, feature flag state, A/B test bucket, configuration profile, Spring profile, Rails environment, NODE_ENV, DEBUG mode, verbose logging, trace level, read-only mode, maintenance mode, degraded mode, dark mode, high contrast mode, reduced motion, forced colors, RTL locale, daylight saving time transition, leap second, timezone offset*

### Category 17 — Colors and theme tokens

*primary, secondary, accent, success, warning, error, info, neutral, background, surface, text, border, divider, shadow, overlay, red, green, blue, yellow, orange, purple, pink, teal, cyan, gray, black, white, transparent, hex code* (`#FF5733`, `#1A1A2E`)*, RGB* (`rgb(255, 87, 51)`)*, RGBA* (`rgba(26, 26, 46, 0.8)`)*, HSL* (`hsl(12, 100%, 60%)`)*, CSS custom property* (`--color-primary-500`, `--color-text-on-primary`)*, design token, color ramp, color scale (50-900), light mode, dark mode, high contrast mode, color blindness safe palette, WCAG contrast ratio, semantic color, brand color*

Colors in design systems are technical nouns. Do not use comparative forms
("darker", "lightest") — reference the specific design token or color ramp step.

### Category 18 — Damage terms: bugs, errors, and failure modes

*crash, segfault, null pointer exception, type error, reference error, syntax error, range error, stack overflow, buffer overflow, memory leak, resource leak, dangling pointer, use-after-free, double free, race condition, deadlock, livelock, starvation, priority inversion, ABA problem, torn read, torn write, dirty read, non-repeatable read, phantom read, lost update, write skew, serialization anomaly, split-brain, network partition, timeout, connection reset, DNS failure, TLS handshake failure, certificate expiry, HTTP 500, HTTP 502, HTTP 503, HTTP 504, rate limit exceeded, quota exceeded, out of memory (OOM), disk full, inode exhaustion, file descriptor exhaustion, thread pool exhaustion, connection pool exhaustion, GC thrashing, cache stampede, cache penetration, cache avalanche, hot partition, data corruption, bit rot, checksum failure, hash collision, infinite loop, infinite recursion, integer overflow, integer underflow, floating point precision error, off-by-one error, SQL injection, XSS, CSRF, prototype pollution, deserialization vulnerability, dependency confusion, supply chain attack, CVE, CWE, zero-day*

### Category 19 — Computer science, information and communication technology

*API, REST, GraphQL, gRPC, WebSocket, SSE, HTTP/2, HTTP/3, TCP, UDP, TLS, mTLS, OAuth 2.0, OIDC, SAML, JWT, API key, CORS, CSP, HSTS, DNS, CDN, IP, IPv4, IPv6, CIDR, VPN, VPC, subnet, firewall rule, WAF, DDoS, load balancing, reverse proxy, forward proxy, caching, compression, serialization (JSON, Protobuf, MessagePack, Avro), encoding (Base64, URL encoding, UTF-8, ASCII), hashing (SHA-256, bcrypt, Argon2), encryption (AES-256-GCM, RSA, ECDSA), Unicode, emoji, regex, glob pattern, SQL, NoSQL, ORM, migration, seed data, transaction, ACID, BASE, sharding, replication, partitioning, indexing, normalization, denormalization, message queue, pub/sub, event sourcing, CQRS, saga, distributed transaction, consensus, leader election, service discovery, circuit breaker, bulkhead, retry, backoff, idempotency, rate limiting, throttling, API versioning, semantic versioning, feature flag, canary release, blue-green deployment, rolling update, immutable infrastructure, infrastructure as code, configuration as code, GitOps, observability, telemetry, tracing, metrics, logging, profiling, APM, RUM, continuous integration, continuous delivery, continuous deployment, DevOps, DevSecOps, Git, Docker, Kubernetes, Helm, Terraform, Ansible*

## Extension categories (STE-Code additions)

The nineteen categories above map the source standard. STE-Code adds three
further categories for terminology that code documentation needs and that has
no aerospace counterpart. Use them the same way: a term is approved if it fits.

### Category 20 — Operations, release management, and lifecycle

*deployment, release, rollout, rollback, hotfix, patch, minor release, major release, breaking change, deprecation, end-of-life (EOL), sunset, migration, upgrade path, backward compatibility, forward compatibility, downtime, maintenance window, zero-downtime deployment, graceful shutdown, drain, scale up, scale down, scale out, scale in, autoscaling, horizontal scaling, vertical scaling, incident, outage, service disruption, failover, disaster recovery, backup, restore, point-in-time recovery, snapshot, retention policy, runbook execution, playbook, on-call handoff, escalation, war room, status page, SLA breach, SLO violation, error budget policy, change freeze, code freeze, release train, sprint, iteration, milestone, roadmap, epic, user story, bug ticket, triage, priority (P0, P1, P2, P3), severity (SEV0, SEV1, SEV2, SEV3), service level objective, operational level agreement (OLA), underpinning contract (UC), vendor management, procurement, onboarding, offboarding, access revocation, audit log, compliance check, penetration test, vulnerability scan, security patch, responsible disclosure, coordinated vulnerability disclosure (CVD)*

### Category 21 — Licenses, compliance, and legal terms

*license, open-source license, proprietary license, MIT License, Apache 2.0 License, GPLv3, LGPL, BSD, AGPL, MPL, Unlicense, Creative Commons, EULA, terms of service (TOS), privacy policy, cookie policy, data processing agreement (DPA), service level agreement (SLA), contributor license agreement (CLA), Developer Certificate of Origin (DCO), copyright, trademark, patent, intellectual property, attribution, copyleft, permissive license, compliance, regulatory compliance, GDPR, CCPA, HIPAA, SOC 2, ISO 27001, PCI DSS, FedRAMP, FISMA, export control, EAR, ITAR, sanctions list, embargo, data residency, data sovereignty, data retention policy, right to erasure, right to access, data subject request (DSR), personal data, PII (Personally Identifiable Information), PHI (Protected Health Information), sensitive data, data classification, data handling policy, acceptable use policy, code of conduct, vendor risk assessment, security questionnaire (CAIQ, SIG), audit report, attestation, SOC report, penetration test report, vulnerability disclosure policy, bug bounty program terms, responsible disclosure policy, indemnification, limitation of liability, warranty disclaimer, governing law, jurisdiction, severability, force majeure, assignment, termination, survival clause, third-party notice, open-source attribution, NOTICE file, SBOM (Software Bill of Materials)*

### Category 22 — Test fixtures, mock data, and placeholders

Scope: sample entities used in code examples, test cases, and documentation
demonstrations.

*test fixture, mock object, stub, spy, fake, dummy, test double, seed data, sample data, example record, placeholder, synthetic data, faker data, lorem ipsum,* `"John Doe"`, `"Jane Smith"`, `"Acme Corp"`, `"example.com"`, `"test@example.com"`, `"user_12345"`, `"order_abc"`, `"00000000-0000-0000-0000-000000000000"`, `"foo"`, `"bar"`, `"baz"`, `"qux"`, `"quux"`, `"spam"`, `"eggs"`, `"ham"`, `"hello world"`, `"TODO"`, `"FIXME"`, `"HACK"`, `"XXX"`, `"WIP"`, `"tmp"`, `"scratch"`, `"sandbox"`, `"playground"`, `"hello-world-app"`, `"my-first-repo"`, `"boilerplate"`, `"starter-kit"`, `"todo-mvc"`, `"FakeUser"`, `"MockOrderRepository"`, `"StubPaymentGateway"`, `"InMemoryDatabase"`, `"NullLogger"`, `TestUserFactory.create()`, `Fixtures.defaultUser()`, `faker.internet.email()`

## Reference catalogue: where project technical nouns come from

Do not invent terms. Take unlisted technical nouns from a source of record and
record them in the project glossary before use:

| Source | Supplies |
|---|---|
| Project glossary / terminology database | Approved project-specific nouns |
| API reference, OpenAPI/GraphQL schema | Endpoint, type, field, and parameter names |
| Architecture Decision Records (ADRs) | Architecture and component names |
| `CODEOWNERS`, org charts | Role and team names |
| Package manifest and lockfile | Exact dependency names and versions |
| Standards bodies (ISO, W3C, IETF, OWASP, ECMA) | Protocol, format, and security terms |

Rules for glossary entries:

1. One term, one meaning. Do not use two terms for the same concept.
2. Record the category number the term belongs to.
3. Spell and capitalize the term exactly as the source of record does
   (`PostgreSQL`, `Node.js`, `Kubernetes`).
4. If a term fits no category, it is not a technical noun — rewrite the sentence
   with approved words.



## 03-dictionary.md

# Level 4 — Reference Dictionary (A–Z)

> **Source:** `ste-code/final/rules/a-dictionary.md` — the complete STE-Code adapted dictionary (A–Z).
> **Adapted from:** ASD-STE100 Issue 9, Part 2 — Dictionary (pages 149–434), with aerospace examples replaced by code-domain examples.
> **Tier:** Level 4 — full reference catalogue. This is the LLM-optimized distillation: the Original / Code-domain / Ref boilerplate is dropped; each entry keeps its approval status and its STE / Non-STE code-example pair(s).

## How to read this dictionary

- **`✓`** after a word = approved in STE-Code. **`✗`** = not approved; the STE / Non-STE pair shows the approved alternative to use.
- **(v)** verb · **(n)** noun · **(adj)** adjective · **(adv)** adverb · **(prep)** preposition · **(conj)** conjunction · **(pron)** pronoun · **(art)** article · **(TN)** code-domain Technical Noun · **(TV)** code-domain Technical Verb.
- Each entry lists the approval status, then `STE:` (approved form) and `Non-STE:` (the form to avoid) example pairs.
- `For other meanings, use: X, Y` points to approved words for distinct senses of the same spelling.
- `(retained)` marks a word kept from the source standard with no direct code-domain equivalent.

Use this list to choose approved words when an LLM generates code documentation (API docs, commit messages, README sections, code comments). Prefer approved words; when a word is marked `✗`, rewrite with the STE form shown.

---

## How  ✓


# A

## A (art)  ✓

- STE: A config file is included in the root directory.  |  Non-STE: Config files included in root directory.

## ABANDON (v)  ✗

Not approved. Use the STE form below.
- STE: If the build fails, stop the deployment pipeline.  |  Non-STE: If the build fails, abandon the deployment pipeline.
- STE: If the values are incorrect, terminate the test run.  |  Non-STE: If the values are incorrect, abandon the test procedure.

## ABILITY (n)  ✗

Not approved. Use the STE form below.
- STE: One configuration can handle requests for all the endpoints.  |  Non-STE: One configuration has the ability to handle requests for all the endpoints.

## ABLE (adj)  ✗

Not approved. Use the STE form below.
- STE: If you can run the script, do the applicable checks.  |  Non-STE: If you are able to run the script, do the applicable checks.

## ABNORMAL (adj)  ✗

Not approved. Use the STE form below.
- STE: Watch for unusual log entries.  |  Non-STE: Watch for abnormal log entries.
- STE: If you find an incorrect value in the output, do a debug run.  |  Non-STE: If you find an abnormal value in the output, do a debug run.

## ABNORMALITY (n)  ✗

Not approved. Use the STE form below.
- STE: Examine the reported stack trace for bugs.  |  Non-STE: Examine the reported stack trace for abnormalities.

## ABOUT (prep)  ✓

- STE: For data about the configuration of the module, refer to the README.  |  Non-STE: For data regarding the configuration of the module, refer to the README.
- STE: The build takes approximately 5 minutes.  |  Non-STE: The build takes about 5 minutes.
- STE: This document covers topics around testing and deployment.  |  Non-STE: This document covers topics about testing and deployment.
- For other meanings, use: APPROXIMATELY (adv), AROUND (prep)

## ABOVE (prep)  ✓

- STE: Move the cursor above the target line.  |  Non-STE: Move the cursor to a position above the target line.
- STE: The response time must be more than 200 ms.  |  Non-STE: The response time must be above 200 ms.
- For other meanings, use: MORE THAN

## ABRASIVE (adj)  (retained)

Retained from the source standard (no direct code-domain equivalent).

## ABRUPT (adj)  ✗

Not approved. Use the STE form below.
- STE: The watchdog prevents sudden shutdown of the service.  |  Non-STE: The watchdog prevents abrupt shutdown of the service.
- STE: If the process stops suddenly, examine the logs.  |  Non-STE: If the process comes to an abrupt stop, examine the logs.

## ABSENCE (n)  ✗

Not approved. Use the STE form below.
- STE: If none of the tests fail, continue the deployment.  |  Non-STE: In the absence of test failures, continue the deployment.
- STE: If the tests are not failing, continue the deployment.  |  Non-STE: In the absence of test failures, continue the deployment.
- STE: If there is no error in the output, continue the procedure.  |  Non-STE: In the absence of errors in the output, continue the procedure.

## ABSENT (adj)  ✗

Not approved. Use the STE form below.
- STE: If one or more files are missing, add an entry in the changelog.  |  Non-STE: If one or more files are absent, add an entry in the changelog.

## ABSOLUTELY (adv)  ✗

Not approved. Use the STE form below.
- STE: Make sure that the connection is fully established.  |  Non-STE: Make sure that the connection is absolutely established.

## ABSORB (v)  ✓

- STE: The buffer absorbs the input data.  |  Non-STE: The buffer takes up the input data.
- STE: The cache layer absorbs the load from repeated queries.  |  Non-STE: The cache layer mitigates the load from repeated queries.

## ABSORPTION (n)  ✗

Not approved. Use the STE form below.
- STE: Measure the time that is necessary for the log system to absorb the incoming events.  |  Non-STE: Measure the rate of absorption of incoming events by the log system.

## ABUNDANT (adj)  ✗

Not approved. Use the STE form below.
- STE: Log the errors with a large quantity of context data.  |  Non-STE: Log the errors with abundant context data.

## ABUT (v)  ✗

Not approved. Use the STE form below.
- STE: The widget touches the boundary of the container.  |  Non-STE: The widget abuts the boundary of the container.

## ACCELERATE (v)  ✗

Not approved. Use the STE form below.
- STE: A larger buffer size increases the speed of data transfer.  |  Non-STE: A larger buffer size accelerates data transfer.
- STE: To make the build process faster, use parallel compilation.  |  Non-STE: To accelerate the build process, use parallel compilation.

## ACCEPT (v)  ✓

- STE: Accept the pull request if it passes all checks.  |  Non-STE: Merge the pull request if it passes all checks.

## ACCEPTABLE (adj)  ✗

Not approved. Use the STE form below.
- STE: A response time of 200 ms is permitted.  |  Non-STE: A response time of 200 ms is acceptable.
- STE: If the condition of the build is not satisfactory, run it again.  |  Non-STE: If the condition of the build is not acceptable, run it again.
- STE: Before you deploy the update, make sure that it is ready.  |  Non-STE: Before you deploy the update, make sure that it is acceptable.

## ACCEPTANCE (n)  ✗

Not approved. Use the STE form below.
- STE: Before you accept the merge request, do the specified review checklist.  |  Non-STE: Before acceptance of the merge request, do the specified review checklist.

## ACCESS (n)  ✓

- STE: Get access to the repository for the authentication module.  |  Non-STE: Access the repository for the authentication module.

## ACCESSIBLE (adj)  ✗

Not approved. Use the STE form below.
- STE: Scroll the view until you can get access to the functions that have public annotations.  |  Non-STE: Scroll the view until the functions with public annotations are accessible.

## ACCIDENT (n)  ✓

- STE: To prevent accidents, make sure that the backups are configured.  |  Non-STE: To prevent accidents, ensure that backups are in place.

## ACCIDENTAL (adj)  ✓

- STE: To prevent accidental deletion of the files, confirm the operation.  |  Non-STE: To prevent inadvertent deletion of the files, confirm the operation.

## ACCIDENTALLY (adv)  ✓

- STE: If you accidentally press the delete key, restore the file from the recycle bin.  |  Non-STE: If you inadvertently press the delete key, restore the file from the recycle bin.

## ACCOMMODATE (v)  ✗

Not approved. Use the STE form below.
- STE: Different configurations let you handle different types of input.  |  Non-STE: Different configurations accommodate different types of input.

## ACCOMPLISH (v)  ✗

Not approved. Use the STE form below.
- STE: Do this build step first.  |  Non-STE: Accomplish this build step first.
- STE: The pipeline must complete this stage in 5 minutes.  |  Non-STE: The pipeline must accomplish this stage in 5 minutes.

## ACCORDING  ✗

Not approved. Use the STE form below.
- STE: To configure the module, refer to the developer's guide.  |  Non-STE: Configure the module according to the developer's guide.

## ACCOUNT  ✗

Not approved. Use the STE form below.
- STE: Make sure that you track all dependencies and packages.  |  Non-STE: All dependencies and packages must be accounted for.

## ACCUMULATE (v)  ✗

Not approved. Use the STE form below.
- STE: If logs collect in the buffer, flush them.  |  Non-STE: If logs accumulate in the buffer, flush them.

## ACCUMULATION (n)  ✗

Not approved. Use the STE form below.
- STE: Remove large quantities of obsolete logs.  |  Non-STE: Remove large accumulations of obsolete logs.
- STE: If errors collect frequently, examine the connection for issues.  |  Non-STE: If accumulation of errors is frequent, examine the connection for issues.

## ACCURACY (n)  ✗

Not approved. Use the STE form below.
- STE: The precision of the calculation can change.  |  Non-STE: The accuracy of the calculation can change.

## ACCURATE (adj)  ✓

- STE: The measurement must be accurate.  |  Non-STE: The measurement must be precise.
- STE: Apply the patch accurately on the target branch.  |  Non-STE: Put the patch accurately on the target branch.

## ACHIEVE (v)  ✗

Not approved. Use the STE form below.
- STE: Set the flag to get maximum performance.  |  Non-STE: Set the flag to achieve maximum performance.

## ACQUIRE (v)  ✗

Not approved. Use the STE form below.
- STE: The module gets this data from three endpoints.  |  Non-STE: The module acquires this data from three endpoints.

## ACRID (adj)  ✗

Not approved. Use the STE form below.

## ACROSS (prep)  ✓

- STE: Search across all modules for the deprecated function.  |  Non-STE: Search all modules for the deprecated function.

## ACT (v)  ✗

Not approved. Use the STE form below.
- STE: The event trigger invokes the handler.  |  Non-STE: The event trigger acts on the handler.

## ACTION (n)  ✗

Not approved. Use the STE form below.
- STE: Do the steps that follow.  |  Non-STE: Do the following actions.
- STE: Do not do this procedure in the production environment.  |  Non-STE: This action must not be done in the production environment.
- STE: Do this task in the staging environment.  |  Non-STE: Do this action in the staging environment.

## ACTIVATE (v)  ✓

- STE: The build pipeline activates the deployment mode.  |  Non-STE: The build pipeline triggers the deployment mode.
- STE: Start the container.  |  Non-STE: Activate the container.
- For other meanings, use: START (v)

## ACTIVE (adj)  ✓

- STE: Read the config from the active branch.  |  Non-STE: Read the config from the current branch.

## ACTIVITY (n)  ✗

Not approved. Use the STE form below.
- STE: A contributor can do these review tasks.  |  Non-STE: A contributor can do these review activities.
- STE: Do this procedure in the development branch.  |  Non-STE: Do this activity in the development branch.
- STE: Do this work in a clean workspace.  |  Non-STE: Do this activity in a clean workspace.

## ACTUATE (v)  ✗

Not approved. Use the STE form below.
- STE: Start the server.  |  Non-STE: Actuate the server.
- STE: Run the script.  |  Non-STE: Actuate the script.

## ACTUATION (n)  ✗

Not approved. Use the STE form below.
- STE: Monitor the operation of the background worker.  |  Non-STE: Monitor the actuation of the background worker.

## ADAPT (v)  ✓

- STE: Adapt the connector to the database schema.  |  Non-STE: Adjust the connector to fit the database schema.
- STE: The middleware layer adapts to the protocol of the connected services.  |  Non-STE: The middleware layer conforms to the protocol of the connected services.

## ADD (v)  ✓

- STE: Add 5 lines of configuration to the file.  |  Non-STE: Append 5 lines of configuration to the file.

## ADDITION (n)  ✗

Not approved. Use the STE form below.
- STE: To get the correct behavior, add special flags, as necessary.  |  Non-STE: To get the correct behavior through the addition of special flags, as necessary.

## ADDITIONAL (adj)  ✗

Not approved. Use the STE form below.
- STE: This section gives more information about deployment.  |  Non-STE: This section gives additional information about deployment.

## ADEQUATE (adj)  ✗

Not approved. Use the STE form below.
- STE: Make sure that buffers have sufficient capacity and throughput.  |  Non-STE: Make sure that buffers have adequate capacity and throughput.

## ADHERE (v)  ✗

Not approved. Use the STE form below.
- STE: The patch must attach correctly.  |  Non-STE: The patch must adhere correctly.
- STE: Obey the coding standards.  |  Non-STE: Adhere to the coding standards.

## ADHESION (n)  ✗

Not approved. Use the STE form below.

## ADJACENT (adj)  ✓

- STE: Do not modify the adjacent function.  |  Non-STE: Do not modify the function that is next to it.
- STE: The config file is located adjacent to the main module.  |  Non-STE: The config file is located next to the main module.

## ADJOINING (adj)  ✗

Not approved. Use the STE form below.
- STE: Align the imports with the adjacent modules.  |  Non-STE: Align the imports with the adjoining modules.

## ADJUST (v)  ✓

- STE: Adjust the timeout to the value given in Table 1.  |  Non-STE: Tune the timeout to the value given in Table 1.
- STE: The auto-scaler adjusts to sudden changes in load.  |  Non-STE: The auto-scaler adapts to sudden changes in load.

## ADJUSTABLE (adj)  ✓

- STE: The two parameters are adjustable.  |  Non-STE: The two parameters can be tuned.
- STE: Make sure that the adjustment is in the limits given in Table 1.  |  Non-STE: Make sure that the tuning is in the limits given in Table 1.

## ADMIT (v)  ✗

Not approved. Use the STE form below.
- STE: Open the port to let traffic go into the container.  |  Non-STE: Open the port to admit traffic into the container.

## ADOPT (v)  ✗

Not approved. Use the STE form below.
- STE: If the build fails, use this fallback script.  |  Non-STE: Adopt this fallback script if the build fails.

## ADVANCE (n)  ✗

Not approved. Use the STE form below.
- STE: The forward movement of the iterator must be sequential.  |  Non-STE: The advance of the iterator must be sequential.

## ADVANCE (v)  ✗

Not approved. Use the STE form below.
- STE: Set the pointer to the next node.  |  Non-STE: Advance the pointer to the next node.
- STE: Move the cursor forward.  |  Non-STE: Advance the cursor.

## ADVERSE (adj)  ✗

Not approved. Use the STE form below.
- STE: Refer to Section 6 for instructions about how to handle bad network conditions.  |  Non-STE: Refer to Section 6 for instructions about how to handle adverse network conditions.

## ADVISABLE (adj)  ✗

Not approved. Use the STE form below.
- STE: The technical lead recommends that you rebuild the containers at intervals of two weeks.  |  Non-STE: It is advisable to rebuild the containers at intervals of two weeks.

## ADVISE (v)  ✗

Not approved. Use the STE form below.
- STE: Tell the reviewer that the changes are ready.  |  Non-STE: Advise the reviewer that the changes are ready.
- STE: The security officer recommends the applicable authentication protocol.  |  Non-STE: The security officer advises on the applicable authentication protocol.

## AFFECT (v)  ✗

Not approved. Use the STE form below.
- STE: Thread locks have an unwanted effect on the scheduler.  |  Non-STE: Thread locks affect the scheduler.

## AFT (adj)  ✓


## AFTER (conj)  ✓

- STE: After you deploy the update, do a smoke test.  |  Non-STE: Following deployment of the update, do a smoke test.

## AGAIN (adv)  ✓

- STE: Run the test again.  |  Non-STE: Rerun the test.

# B

## BACK (adj)  ✓

- STE: Revert to the back version.  |  Non-STE: Revert to the previous version.
- STE: Navigate back to the previous page.  |  Non-STE: Go backwards to the previous page.

## BACK  ✗

Not approved. Use the STE form below.
- STE: Save the database before the migration.  |  Non-STE: Back up the database before the migration.
- STE: Copy the configuration files.  |  Non-STE: Back up the configuration files.

## BAD (adj)  ✓

- STE: Refer to Section 6 for instructions about how to handle bad build states.  |  Non-STE: Refer to Section 6 for instructions about how to handle unsatisfactory build states.

## BALANCE (n)  ✓

- STE: Make sure that the load is in balance across all nodes.  |  Non-STE: Make sure that the load is balanced across all nodes.
- STE: Balance the workload across all workers.  |  Non-STE: Distribute the workload across all workers.

## BASE (n)  ✗

Not approved. Use the STE form below.
- STE: The foundation of the architecture is the data layer.  |  Non-STE: The base of the architecture is the data layer.
- STE: Start from the root of the project.  |  Non-STE: Start from the base of the project.

## BE (v)  ✓

- STE: If there is an error in the log, restart the service.  |  Non-STE: If an error exists in the log, restart the service.
- STE: Unhandled exceptions are dangerous.  |  Non-STE: Unhandled exceptions constitute a danger.

## BECAUSE (conj)  ✓

- STE: Do not use raw input, because it is a security risk.  |  Non-STE: Do not use raw input, since it is a security risk.

## BECOME (v)  ✓

- STE: The connection becomes unstable.  |  Non-STE: The connection turns unstable.

## BEFORE (conj)  ✓

- STE: Before you run the migration, read the release notes.  |  Non-STE: Prior to running the migration, read the release notes.

## BEGIN (v)  ✓

- STE: Begin the build process.  |  Non-STE: Initiate the build process.

## BELOW (prep)  ✓

- STE: See the example below the code block.  |  Non-STE: See the example beneath the code block.

## BEND (v)  ✓


## BETWEEN (prep)  ✓

- STE: Put the middleware between the client and the server.  |  Non-STE: Insert the middleware between the client and the server.

## BLOCK (n)  ✓

- STE: Put a comment block above the function.  |  Non-STE: Add documentation above the function.

## BOND (v)  ✓


## BOTTOM (n)  ✓

- STE: Scroll to the bottom of the file.  |  Non-STE: Scroll to the end of the file.
- STE: The bottom layer of the stack is the database.  |  Non-STE: The lowest layer of the stack is the database.

## BRACKET (n)  ✓

- STE: Use square brackets for array access.  |  Non-STE: Use the bracket notation for array access.

## BREAK (v)  ✓

- STE: Do not break the public API.  |  Non-STE: Do not cause breaking changes to the public API.
- STE: Break out of the loop when the flag is set.  |  Non-STE: Exit the loop when the flag is set.

## BRING (v)  ✗

Not approved. Use the STE form below.
- STE: Get the dependencies into the container.  |  Non-STE: Bring the dependencies into the container.

## BROAD (adj)  ✗

Not approved. Use the STE form below.
- STE: Wide test coverage.  |  Non-STE: Broad test coverage.

## BUG (n)  ✓

- STE: Use the bug tracker to log defects.  |  Non-STE: Use the issue tracker to log defects.

## BUILD (v)  ✗

Not approved. Use the STE form below.
- STE: Compile the project.  |  Non-STE: Build the project.

## BURN (v)  ✓

- STE: Burn the ISO image to the USB drive.  |  Non-STE: Write the ISO image to the USB drive.

## BUT (conj)  ✓

- STE: The build passes, but the tests fail.  |  Non-STE: The build passes, however the tests fail.

## BY (prep)  ✓

- STE: Build the project by the CMake tool.  |  Non-STE: Build the project using CMake.
- STE: Authenticate by OAuth.  |  Non-STE: Authenticate via OAuth.

## BYTE (n)  ✓

- STE: The buffer holds 1024 bytes.  |  Non-STE: The buffer has a size of 1024 bytes.

# C

## CALCULATE (v)  ✓

- STE: Calculate the checksum of the file.  |  Non-STE: Compute the checksum of the file.

## CALL (v)  ✗

Not approved. Use the STE form below.
- STE: Name the function "init."  |  Non-STE: Call the function "init."
- STE: Contact the administrator.  |  Non-STE: Call the administrator.

## CAN (v)  ✓

- STE: A misconfiguration can cause a crash.  |  Non-STE: A misconfiguration could cause a crash.
- STE: You can run the script after the build is completed.  |  Non-STE: You are able to run the script after the build is completed.

## CANCEL (v)  ✓

- STE: Cancel the deployment pipeline.  |  Non-STE: Abort the deployment pipeline.

## CANNOT (v)  ✓

- STE: You cannot access this endpoint without authentication.  |  Non-STE: You are unable to access this endpoint without authentication.

## CAPABLE (adj)  ✗

Not approved. Use the STE form below.
- STE: The service can recover from failures automatically.  |  Non-STE: The service is capable of recovering from failures automatically.

## CARE (n)  ✗

Not approved. Use the STE form below.
- STE: Be careful when you change the configuration.  |  Non-STE: Take care when changing the configuration.

## CARRY (v)  ✗

Not approved. Use the STE form below.
- STE: Move the data to the cache.  |  Non-STE: Carry the data to the cache.

## CARRY  ✗

Not approved. Use the STE form below.
- STE: Do the review.  |  Non-STE: Carry out the review.

## CASE (n)  ✗

Not approved. Use the STE form below.
- STE: If the flag is true, log the event.  |  Non-STE: In case the flag is true, log the event.
- STE: Add a switch case for the error state.  |  Non-STE: Handle the error case.

## CATCH (v)  ✓

- STE: Catch the exception and log it.  |  Non-STE: Trap the exception and log it.

## CAUSE (v)  ✓

- STE: The null pointer caused the crash.  |  Non-STE: The null pointer resulted in the crash.

## CAUTION (n)  ✓

- STE: Obey the cautions in this README.  |  Non-STE: Follow the cautions in this README.

## CENTER (n)  ✓

- STE: Align the text to the center.  |  Non-STE: Center the text.

## CHANGE (v)  ✓

- STE: Change the function signature.  |  Non-STE: Modify the function signature.
- STE: Record the changes in the changelog.  |  Non-STE: Log the changes in the changelog.

## CHECK (n)  ✓

- STE: Do a check of the input values.  |  Non-STE: Validate the input values.

## CHECK (v)  ✗

Not approved. Use the STE form below.
- STE: Do a check of the values.  |  Non-STE: Check the values.
- STE: Verify the data integrity.  |  Non-STE: Check the data integrity.

## CHOOSE (v)  ✗

Not approved. Use the STE form below.
- STE: Select the correct configuration.  |  Non-STE: Choose the correct configuration.

## CLEAN (v)  ✓

- STE: Clean the temporary files.  |  Non-STE: Delete the temporary files.

## CLEAR (adj)  ✓

- STE: A clear code path for the request.  |  Non-STE: An unobstructed code path for the request.
- STE: Clear documentation for the API.  |  Non-STE: Understandable documentation for the API.

## CLICK (n)  ✓

- STE: Click the "Submit" button.  |  Non-STE: Press the "Submit" button.

## CLOSE (v)  ✓

- STE: Close the file handle.  |  Non-STE: Release the file handle.

## CODE (n)  ✓

- STE: The code is in the `src/` directory.  |  Non-STE: The source is in the `src/` directory.

## COLLECT (v)  ✓

- STE: Collect the metrics from all nodes.  |  Non-STE: Gather the metrics from all nodes.

## COME (v)  ✓

- STE: When the service comes online, start the tests.  |  Non-STE: When the service starts, start the tests.

## COMMENT (n)  ✓

- STE: Add a comment to explain the algorithm.  |  Non-STE: Document the algorithm in the code.

## COMMIT (v)  ✓

- STE: Commit the changes to the repository.  |  Non-STE: Save the changes to the repository.

## COMPARE (v)  ✓

- STE: Compare the hash value with the expected hash.  |  Non-STE: Check the hash value against the expected hash.

## COMPATIBLE (adj)  ✓

- STE: The library is compatible with version 3.0.  |  Non-STE: The library works with version 3.0.

## COMPILE (v)  ✗

Not approved. Use the STE form below.
- STE: Compile the source files.  |  Non-STE: Build the source files.

## COMPLETE (v)  ✓

- STE: Complete the setup wizard.  |  Non-STE: Finish the setup wizard.

## COMPONENT (n)  ✓

- STE: The component is imported in the module.  |  Non-STE: The component is used in the module.

## COMPRESS (v)  ✓

- STE: Compress the log files before archiving.  |  Non-STE: Zip the log files before archiving.

## CONDITION (n)  ✓

- STE: The condition of the build is satisfactory.  |  Non-STE: The build state is good.
- STE: If the condition is true, continue.  |  Non-STE: If the conditional evaluates to true, continue.

## CONFIGURATION (n)  ✓

- STE: The configuration file is in YAML format.  |  Non-STE: The config file is in YAML format.

## CONFIRM (v)  ✗

Not approved. Use the STE form below.
- STE: Make sure that the build is successful.  |  Non-STE: Confirm that the build is successful.

## CONNECT (v)  ✓

- STE: Connect the client to the server.  |  Non-STE: Establish a connection between the client and the server.

## CONTAIN (v)  ✓

- STE: The module contains the helper functions.  |  Non-STE: The module includes the helper functions.

## CONTACT (v)  ✓

- STE: Contact the system administrator.  |  Non-STE: Get in touch with the system administrator.

## CONTINUE (v)  ✓

- STE: If the build passes, continue the deployment.  |  Non-STE: If the build passes, proceed with the deployment.

## CONTROL (n)  ✓

- STE: The control of the access is role-based.  |  Non-STE: Access is role-based.
- STE: Control the workflow with the dashboard.  |  Non-STE: Manage the workflow with the dashboard.

## COPY (v)  ✓

- STE: Copy the config to the staging environment.  |  Non-STE: Duplicate the config to the staging environment.

## CORRECT (adj)  ✓

- STE: Make sure that the test results are correct.  |  Non-STE: Verify that the test results are correct.

## CORRECTLY (adv)  ✓

- STE: Make sure that the package is correctly installed.  |  Non-STE: Ensure the package is correctly installed.

## COUNT (v)  ✓

- STE: Count the records in the database.  |  Non-STE: Get the count of records in the database.

## COVER (n)  ✓


## CRASH (v)  ✓

- STE: If the application crashes, read the logs.  |  Non-STE: If the application fails, read the logs.

## CREATE (v)  ✓

- STE: Create a new instance of the class.  |  Non-STE: Instantiate a new object of the class.

## CUT (v)  ✓

- STE: Cut the text and paste it in the new location.  |  Non-STE: Move the text to the new location.

# D

## DAMAGE (n)  ✓

- STE: The damage to the data is irreversible.  |  Non-STE: The data corruption is irreversible.

## DANGER (n)  ✗

Not approved. Use the STE form below.
- STE: This operation has a risk of data loss.  |  Non-STE: There is a danger of data loss with this operation.

## DANGEROUS (adj)  ✓

- STE: This command is dangerous.  |  Non-STE: This command poses a danger.

## DATA (n)  ✓

- STE: The data is stored in the cache.  |  Non-STE: The information is stored in the cache.

## DEACTIVATE (v)  ✓

- STE: Deactivate the background worker.  |  Non-STE: Disable the background worker.

## DEBUG (v)  ✓

- STE: Debug the application with the attached profiler.  |  Non-STE: Troubleshoot the application with the attached profiler.

## DECREASE (v)  ✓

- STE: Decrease the timeout value.  |  Non-STE: Lower the timeout value.

## DEEP (adj)  ✓

- STE: Deep directory structure.  |  Non-STE: Nested directory structure.

## DEFAULT (n)  ✓

- STE: The default value is 8080.  |  Non-STE: The initial value is 8080.

## DEFECT (n)  ✓

- STE: Log the defect in the tracking system.  |  Non-STE: Log the bug in the tracking system.

## DEFINE (v)  ✓

- STE: The header file defines the interface.  |  Non-STE: The header file declares the interface.

## DELETE (v)  ✗

Not approved. Use the STE form below.
- STE: Remove the file from the directory.  |  Non-STE: Delete the file from the directory.

## DEPLOY (v)  ✓

- STE: Deploy the application to production.  |  Non-STE: Release the application to production.

## DEPRECATED (adj)  ✓

- STE: The deprecated function will be removed in version 4.0.  |  Non-STE: The outdated function will be removed in version 4.0.

## DESIGN (n)  ✓

- STE: The design of the API follows REST principles.  |  Non-STE: The architecture of the API follows REST principles.

## DESTROY (v)  ✗

Not approved. Use the STE form below.
- STE: Break the old session.  |  Non-STE: Destroy the old session.

## DEVELOP (v)  ✓

- STE: Develop the feature in a separate branch.  |  Non-STE: Build the feature in a separate branch.

## DIFFERENT (adj)  ✓

- STE: The two implementations have different performance.  |  Non-STE: The two implementations differ in performance.

## DIMENSION (n)  ✓

- STE: The array has three dimensions.  |  Non-STE: The array is three-dimensional.

## DIRECTORY (n)  ✓

- STE: The source files are in the `src/` directory.  |  Non-STE: The source files are in the `src/` folder.

## DISABLE (v)  ✓

- STE: Disable the feature flag.  |  Non-STE: Turn off the feature flag.

## DISCARD (v)  ✓

- STE: Discard the deprecated code.  |  Non-STE: Remove the deprecated code.

## DISCONNECT (v)  ✓

- STE: Disconnect the socket.  |  Non-STE: Close the socket.

## DISPLAY (v)  ✓

- STE: The terminal displays the log output.  |  Non-STE: The terminal shows the log output.

## DIVIDE (v)  ✓

- STE: Divide the tasks among the workers.  |  Non-STE: Distribute the tasks among the workers.

## DO (v)  ✓

- STE: Do the build step.  |  Non-STE: Execute the build step.

## DOCUMENT (v)  ✓

- STE: Document the public API.  |  Non-STE: Write docs for the public API.

## DOWN (adv)  ✓

- STE: Scroll down the page.  |  Non-STE: Scroll to the lower part of the page.
- STE: The server is down.  |  Non-STE: The server is not operational.

## DOWNLOAD (v)  ✓

- STE: Download the package from the registry.  |  Non-STE: Get the package from the registry.

## DRAIN (v)  ✓

- STE: Drain the connection pool.  |  Non-STE: Empty the connection pool.

## DRAW (v)  ✓

- STE: Draw the architecture diagram.  |  Non-STE: Create the architecture diagram.

## DROP (v)  ✓

- STE: Drop the table from the database.  |  Non-STE: Delete the table from the database.

## DRY (adj)  ✓


# E

## EACH (adj)  ✓

- STE: Each module has a README file.  |  Non-STE: Every module has a README file.

## EASY (adj)  ✓

- STE: The setup is easy.  |  Non-STE: The setup is straightforward.

## EDIT (v)  ✓

- STE: Edit the configuration file with a text editor.  |  Non-STE: Modify the configuration file with a text editor.

## EFFECT (n)  ✓

- STE: The effect of the change is small.  |  Non-STE: The impact of the change is small.

## EJECT (v)  ✓

- STE: Eject the volume.  |  Non-STE: Unmount the volume.

## ELEMENT (n)  ✓

- STE: Each element of the list has an index.  |  Non-STE: Each item of the list has an index.

## ELSE (adv)  ✓

- STE: If the value is null, return 0; else return the value.  |  Non-STE: If the value is null, return 0; otherwise return the value.

## EMPTY (adj)  ✓

- STE: An empty string.  |  Non-STE: A zero-length string.

## ENABLE (v)  ✓

- STE: Enable the debug mode.  |  Non-STE: Turn on the debug mode.

## END (n)  ✓

- STE: The end of the file.  |  Non-STE: The final byte of the file.
- STE: End the session.  |  Non-STE: Terminate the session.

## ENSURE (v)  ✗

Not approved. Use the STE form below.
- STE: Make sure that the database is connected.  |  Non-STE: Ensure that the database is connected.

## ENTER (v)  ✗

Not approved. Use the STE form below.
- STE: Type your password.  |  Non-STE: Enter your password.

## ENVIRONMENT (n)  ✓

- STE: The staging environment is a copy of production.  |  Non-STE: The staging setup is a copy of production.

## EQUAL (adj)  ✓

- STE: The two hashes are equal.  |  Non-STE: The two hashes are the same.
- STE: The result equals zero.  |  Non-STE: The result is zero.

## ERASE (v)  ✓

- STE: Erase the sensitive data from memory.  |  Non-STE: Wipe the sensitive data from memory.

## ERROR (n)  ✓

- STE: The error occurred at line 42.  |  Non-STE: The issue occurred at line 42.

## ESTABLISH (v)  ✗

Not approved. Use the STE form below.
- STE: Make a connection.  |  Non-STE: Establish a connection.

## EVALUATE (v)  ✓

- STE: Evaluate the expression at runtime.  |  Non-STE: Compute the expression at runtime.

## EVENT (n)  ✓

- STE: The event triggers the callback.  |  Non-STE: The event fires the callback.

## EXAMINE (v)  ✓

- STE: Examine the code for security issues.  |  Non-STE: Review the code for security issues.

## EXAMPLE (n)  ✓

- STE: This is an example of a correct API call.  |  Non-STE: This demonstrates a correct API call.

## EXCEPT (prep)  ✗

Not approved. Use the STE form below.
- STE: All modules except the database module are available.  |  Non-STE: All modules other than the database module are available.

## EXECUTE (v)  ✓

- STE: Execute the script from the terminal.  |  Non-STE: Run the script from the terminal.

## EXPAND (v)  ✓

- STE: Expand the macro at compile time.  |  Non-STE: The macro is substituted at compile time.

## EXPLAIN (v)  ✗

Not approved. Use the STE form below.
- STE: Describe the error condition.  |  Non-STE: Explain the error condition.

## EXPORT (v)  ✓

- STE: Export the function from the library.  |  Non-STE: Make the function available from the library.

## EXTEND (v)  ✓

- STE: Extend the base class to add new methods.  |  Non-STE: Subclass the base class to add new methods.

# F

## FAIL (v)  ✓

- STE: If the test fails, examine the logs.  |  Non-STE: If the test does not pass, examine the logs.

## FAILURE (n)  ✗

Not approved. Use the STE form below.
- STE: If the service stops, restart it.  |  Non-STE: In case of service failure, restart it.

## FALL (v)  ✓


## FALSE (adj)  ✓

- STE: If the condition is false, skip the block.  |  Non-STE: If the condition does not hold, skip the block.

## FAST (adj)  ✓

- STE: Fast response time.  |  Non-STE: Low latency.

## FATAL (adj)  ✓

- STE: A fatal error occurred.  |  Non-STE: A critical error occurred.

## FETCH (v)  ✓

- STE: Fetch the records from the database.  |  Non-STE: Retrieve the records from the database.

## FIELD (n)  ✓

- STE: The `email` field of the form must be validated.  |  Non-STE: The `email` input of the form must be validated.

## FILE (n)  ✓

- STE: The configuration file is in TOML format.  |  Non-STE: The config is in TOML format.

## FILL (v)  ✓

- STE: Fill the array with default values.  |  Non-STE: Initialize the array with default values.

## FILTER (n)  ✓

- STE: Filter the results by status.  |  Non-STE: Select only the results that match the status.

## FIND (v)  ✓

- STE: Find the root cause of the error.  |  Non-STE: Determine the root cause of the error.

## FINISH (v)  ✓

- STE: Finish the setup.  |  Non-STE: Complete the setup.

## FIRST (adj)  ✓

- STE: Define the variable first.  |  Non-STE: Initially define the variable.

## FIT (v)  ✗

Not approved. Use the STE form below.
- STE: Install the package.  |  Non-STE: Fit the package into the project.

## FIX (v)  ✓

- STE: Fix the memory leak.  |  Non-STE: Resolve the memory leak.

## FLAG (n)  ✓

- STE: Set the debug flag to true.  |  Non-STE: Enable the debug flag.

## FLOW (n)  ✓

- STE: The flow of data through the pipeline.  |  Non-STE: The data stream through the pipeline.
- STE: The data flows through the channel.  |  Non-STE: The data passes through the channel.

## FOLLOW (v)  ✗

Not approved. Use the STE form below.
- STE: Obey the coding guidelines.  |  Non-STE: Follow the coding guidelines.

## FOR (prep)  ✓

- STE: For examples, refer to the README.  |  Non-STE: To see examples, refer to the README.

## FORCE (n)  ✓

- STE: Force the application to restart.  |  Non-STE: Compel the application to restart.

## FORMAT (n)  ✓

- STE: The file format is JSON.  |  Non-STE: The file is in JSON.

## FORWARD (adv)  ✓

- STE: Move the pointer forward.  |  Non-STE: Advance the pointer.

## FREE (adj)  ✓

- STE: The code is free of errors.  |  Non-STE: The code has no errors.

## FROM (prep)  ✓

- STE: Import the module from the package.  |  Non-STE: Import the module out of the package.

## FULL (adj)  ✓

- STE: Full test suite.  |  Non-STE: Complete test suite.

## FUNCTION (n)  ✓

- STE: The function returns a string.  |  Non-STE: The method returns a string.
- STE: The function of the middleware is to authenticate requests.  |  Non-STE: The role of the middleware is to authenticate requests.

# G

## GET (v)  ✓

- STE: Get the data from the API.  |  Non-STE: Fetch the data from the API.
- STE: The service gets unstable under load.  |  Non-STE: The service becomes unstable under load.

## GIVE (v)  ✓

- STE: This section gives the build instructions for the module.  |  Non-STE: This section provides the build instructions for the module.

## GO (v)  ✓

- STE: Go to the next phase of the pipeline.  |  Non-STE: Proceed to the next phase of the pipeline.

## GOOD (adj)  ✓

- STE: Good test coverage.  |  Non-STE: Satisfactory test coverage.

## GROUP (n)  ✓

- STE: Group the tests by module.  |  Non-STE: Organize the tests by module.

# H

## HANDLE (v)  ✗

Not approved. Use the STE form below.
- STE: Process the exception.  |  Non-STE: Handle the exception.

## HAPPEN (v)  ✗

Not approved. Use the STE form below.
- STE: An exception occurred during initialization.  |  Non-STE: An exception happened during initialization.

## HARD (adj)  ✓

- STE: A hard limit on the number of connections.  |  Non-STE: A strict limit on the number of connections.

## HAVE (v)  ✓

- STE: The class has two methods.  |  Non-STE: The class contains two methods.

## HEAD (n)  ✓

- STE: The head of the queue.  |  Non-STE: The front of the queue.

## HELP (n)  ✓

- STE: This README helps you to set up the project.  |  Non-STE: This README assists you in setting up the project.

## HIGH (adj)  ✓

- STE: High load on the server.  |  Non-STE: Heavy load on the server.

## HIT (v)  ✓

- STE: Hit the endpoint with a GET request.  |  Non-STE: Send a GET request to the endpoint.

## HOLD (v)  ✓

- STE: Hold the lock until the operation completes.  |  Non-STE: Keep the lock until the operation completes.

## HOOK (n)  ✓

- STE: Use a pre-commit hook to validate the code.  |  Non-STE: Use a pre-commit script to validate the code.

## HOW (adv)  ✓

- STE: How to compile the project.  |  Non-STE: Instructions to compile the project.

# I

## IDENTIFY (v)  ✓

- STE: Identify the source of the memory leak.  |  Non-STE: Find the source of the memory leak.

## IF (conj)  ✓

- STE: If the status code is 500, retry the request.  |  Non-STE: In the event of a 500 status code, retry the request.

## IGNORE (v)  ✓

- STE: Ignore the case sensitivity.  |  Non-STE: Do not consider the case sensitivity.

## IMMEDIATELY (adv)  ✓

- STE: Restart the service immediately.  |  Non-STE: Restart the service right away.

## IMPLEMENT (v)  ✓

- STE: Implement the interface.  |  Non-STE: Code the interface.

## IMPORT (v)  ✓

- STE: Import the module at the top of the file.  |  Non-STE: Include the module at the top of the file.

## IMPORTANT (adj)  ✓

- STE: Important security note.  |  Non-STE: Critical security note.

## IN (prep)  ✓

- STE: In the directory `src/lib/`.  |  Non-STE: Within the directory `src/lib/`.

## INCLUDE (v)  ✓

- STE: The package includes the dependencies.  |  Non-STE: The package contains the dependencies.

## INCORRECT (adj)  ✓

- STE: Incorrect syntax.  |  Non-STE: Wrong syntax.

## INCREASE (v)  ✓

- STE: Increase the buffer size.  |  Non-STE: Make the buffer larger.

## INDEX (n)  ✓

- STE: The index of the element is 0.  |  Non-STE: The position of the element is 0.

## INDICATE (v)  ✗

Not approved. Use the STE form below.
- STE: The log shows the error type.  |  Non-STE: The log indicates the error type.

## INITIALIZE (v)  ✓

- STE: Initialize the variable to zero.  |  Non-STE: Set the variable to zero initially.

## INPUT (n)  ✓

- STE: Validate the user input.  |  Non-STE: Validate the data entered by the user.

## INSERT (v)  ✗

Not approved. Use the STE form below.
- STE: Put the record into the database.  |  Non-STE: Insert the record into the database.

## INSPECT (v)  ✗

Not approved. Use the STE form below.
- STE: Review the code for vulnerabilities.  |  Non-STE: Inspect the code for vulnerabilities.

## INSTALL (v)  ✓

- STE: Install the package with npm.  |  Non-STE: Set up the package with npm.

## INSTRUCTION (n)  ✓

- STE: Obey the instructions in the README.  |  Non-STE: Follow the instructions in the README.

## INTERFACE (n)  ✓

- STE: The interface defines three methods.  |  Non-STE: The contract defines three methods.

## INVALID (adj)  ✓

- STE: An invalid token.  |  Non-STE: A bad token.

## ISOLATE (v)  ✓

- STE: Isolate the component for unit testing.  |  Non-STE: Separate the component for unit testing.

## IT (pron)  ✓

- STE: The package. It is in the registry.  |  Non-STE: The package is in the registry.

# J

## JOIN (v)  ✓

- STE: Join the two strings.  |  Non-STE: Concatenate the two strings.

# K

## KEEP (v)  ✓

- STE: Keep the connection open.  |  Non-STE: Maintain the connection.

## KEY (n)  ✓

- STE: The key for the cache entry is the user ID.  |  Non-STE: The identifier for the cache entry is the user ID.

## KILL (v)  ✓

- STE: Kill the process with SIGTERM.  |  Non-STE: Terminate the process with SIGTERM.

## KNOW (v)  ✓

- STE: You must know the API specification.  |  Non-STE: You must be familiar with the API specification.

# L

## LARGE (adj)  ✓

- STE: A large dataset.  |  Non-STE: A big dataset.

## LAST (adj)  ✓

- STE: Execute the teardown last.  |  Non-STE: Execute the teardown at the end.

## LAYER (n)  ✓

- STE: The data access layer handles queries.  |  Non-STE: The data tier handles queries.

## LEFT (adj)  ✓

- STE: Align the text left.  |  Non-STE: Align the text to the left.

## LENGTH (n)  ✓

- STE: The length of the array is 10.  |  Non-STE: The array has 10 elements.

## LESS (adj)  ✓

- STE: Less memory usage.  |  Non-STE: Lower memory usage.

## LET (v)  ✓

- STE: Let the process complete before you restart.  |  Non-STE: Allow the process to complete before you restart.

## LEVEL (n)  ✓

- STE: Set the log level to debug.  |  Non-STE: Set the logging severity to debug.

## LIBRARY (n)  ✓

- STE: Import the standard library.  |  Non-STE: Include the standard library.

## LIFT (v)  ✓

- STE: Lift the function to a separate module.  |  Non-STE: Extract the function to a separate module.

## LIGHT (adj)  ✓

- STE: A light process with small memory footprint.  |  Non-STE: A lightweight process.

## LIMIT (n)  ✓

- STE: Limit the number of requests.  |  Non-STE: Restrict the number of requests.

## LINE (n)  ✓

- STE: The error is at line 42.  |  Non-STE: The error is on line 42.

## LINK (n)  ✓

- STE: Link the library to the project.  |  Non-STE: Connect the library to the project.

## LIST (n)  ✓

- STE: List the files in the directory.  |  Non-STE: Show the files in the directory.

## LOAD (n)  ✓

- STE: Load the configuration file.  |  Non-STE: Read the configuration file.

## LOCATE (v)  ✗

Not approved. Use the STE form below.
- STE: Find the error in the logs.  |  Non-STE: Locate the error in the logs.

## LOCK (v)  ✓

- STE: Lock the mutex.  |  Non-STE: Acquire the mutex.

## LOG (n)  ✓

- STE: Log the error to the file.  |  Non-STE: Write the error to the file.

## LONG (adj)  ✓

- STE: A long process.  |  Non-STE: A time-consuming process.

## LOOK (v)  ✓

- STE: Look at the error message.  |  Non-STE: Examine the error message.

## LOOP (n)  ✓

- STE: The for loop iterates 10 times.  |  Non-STE: The iteration runs 10 times.

## LOOSE (adj)  ✓

- STE: Loose coupling between modules.  |  Non-STE: Decoupled modules.

## LOW (adj)  ✓

- STE: Low latency.  |  Non-STE: Minimal delay.

## LOWER (v)  ✓

- STE: Lower the log level.  |  Non-STE: Reduce the log level.

# M

## MAIN (adj)  ✗

Not approved. Use the STE form below.
- STE: The primary cause of the crash is a null pointer.  |  Non-STE: The main cause of the crash is a null pointer.

## MAKE (v)  ✓

- STE: Make a copy of the file.  |  Non-STE: Create a copy of the file.

## MAKE  ✓

- STE: Make sure that the tests pass.  |  Non-STE: Ensure that the tests pass.

## MANAGE (v)  ✓

- STE: The package manager manages dependencies.  |  Non-STE: The package manager handles dependencies.

## MANDATORY (adj)  ✓

- STE: The API key is mandatory.  |  Non-STE: The API key is required.

## MANUAL (adj)  ✓

- STE: Manual review of the code.  |  Non-STE: Human review of the code.
- STE: Read the manual before you start.  |  Non-STE: Read the docs before you start.

## MANY (adj)  ✓

- STE: Many requests per second.  |  Non-STE: Numerous requests per second.

## MAP (v)  ✓

- STE: Map the array to uppercase.  |  Non-STE: Transform each element of the array.

## MARK (n)  ✓

- STE: Mark the function as deprecated.  |  Non-STE: Flag the function as deprecated.

## MATCH (v)  ✓

- STE: The pattern must match the input.  |  Non-STE: The pattern must correspond to the input.

## MATERIAL (n)  ✓

- STE: Refer to the training material.  |  Non-STE: Refer to the training resources.

## MAXIMUM (adj)  ✓

- STE: Maximum connections is 100.  |  Non-STE: The limit is 100 connections.

## MEASURE (v)  ✓

- STE: Measure the response time.  |  Non-STE: Calculate the response time.

## MEMORY (n)  ✓

- STE: The application uses 256 MB of memory.  |  Non-STE: The application uses 256 MB of RAM.

## MERGE (v)  ✓

- STE: Merge the feature branch into main.  |  Non-STE: Combine the feature branch into main.

## MESSAGE (n)  ✓

- STE: The error message describes the issue.  |  Non-STE: The error text describes the issue.

## METHOD (n)  ✓

- STE: The method takes two parameters.  |  Non-STE: The function takes two parameters.

## MINIMUM (adj)  ✓

- STE: The minimum password length is 8.  |  Non-STE: The password must be at least 8 characters.

## MINUS (prep)  ✓

- STE: The value is total minus overhead.  |  Non-STE: The value is total less overhead.

## MISSING (adj)  ✓

- STE: A missing dependency.  |  Non-STE: A dependency that is not installed.

## MIX (v)  ✓

- STE: Do not mix concerns in a single module.  |  Non-STE: Do not combine concerns in a single module.

## MODE (n)  ✓

- STE: The debug mode shows more information.  |  Non-STE: Debug builds show more information.

## MODEL (n)  ✓

- STE: The user model has three fields.  |  Non-STE: The user schema has three fields.

## MODIFY (v)  ✗

Not approved. Use the STE form below.
- STE: Change the file permissions.  |  Non-STE: Modify the file permissions.

## MODULE (n)  ✓

- STE: Each module has its own namespace.  |  Non-STE: Each package has its own namespace.

## MONITOR (v)  ✓

- STE: Monitor the server logs.  |  Non-STE: Watch the server logs.

## MORE (adj)  ✓

- STE: More memory allocation.  |  Non-STE: Additional memory allocation.

## MOST (adj)  ✓

- STE: Most errors occur at startup.  |  Non-STE: The majority of errors occur at startup.

## MOVE (v)  ✓

- STE: Move the file to the archive.  |  Non-STE: Transfer the file to the archive.

## MUCH (adj)  ✓

- STE: Not much memory usage.  |  Non-STE: Low memory usage.

## MUST (v)  ✓

- STE: You must validate all inputs.  |  Non-STE: You have to validate all inputs.

# N

## NAME (n)  ✓

- STE: Name the variable `count`.  |  Non-STE: Call the variable `count`.

## NEAR (adj)  ✓

- STE: Near the end of the file.  |  Non-STE: Close to the end of the file.

## NECESSARY (adj)  ✓

- STE: It is necessary to restart the service.  |  Non-STE: You must restart the service.

## NEED (v)  ✗

Not approved. Use the STE form below.
- STE: You must install the dependencies.  |  Non-STE: You need to install the dependencies.

## NEVER (adv)  ✓

- STE: Never store passwords in plain text.  |  Non-STE: Do not store passwords in plain text under any circumstances.

## NEW (adj)  ✓

- STE: A new instance of the class.  |  Non-STE: A fresh instance of the class.

## NEXT (adj)  ✓

- STE: The next iteration.  |  Non-STE: The following iteration.

## NO (adj)  ✓

- STE: No errors in the output.  |  Non-STE: Zero errors in the output.

## NONE (pron)  ✓

- STE: None of the tests fail.  |  Non-STE: All tests pass.

## NORMAL (adj)  ✗

Not approved. Use the STE form below.
- STE: The usual behavior is to return zero.  |  Non-STE: The normal behavior is to return zero.

## NOT (adv)  ✓

- STE: Do not use deprecated functions.  |  Non-STE: Avoid using deprecated functions.

## NOTE (n)  ✓

- STE: Add a note in the code.  |  Non-STE: Add a comment in the code.

## NULL (adj)  ✓

- STE: The pointer is null.  |  Non-STE: The pointer is empty.

## NUMBER (n)  ✓

- STE: The number of records is 100.  |  Non-STE: The count of records is 100.

# O

## OBJECT (n)  ✓

- STE: Create a new object of the User class.  |  Non-STE: Instantiate the User class.

## OBEY (v)  ✓

- STE: Obey the coding standards.  |  Non-STE: Follow the coding standards.

## OCCUR (v)  ✓

- STE: An exception occurred at runtime.  |  Non-STE: An exception was thrown at runtime.

## OF (prep)  ✓

- STE: The name of the function.  |  Non-STE: The function's name.

## OFF (adv)  ✓

- STE: Turn off the feature flag.  |  Non-STE: Disable the feature flag.

## ON (adv)  ✓

- STE: Turn on the debug mode.  |  Non-STE: Enable the debug mode.

## ONLY (adv)  ✓

- STE: Only the admin can run this command.  |  Non-STE: Solely the admin can run this command.

## OPEN (v)  ✓

- STE: Open the file for reading.  |  Non-STE: Read the file.
- STE: An open port on the firewall.  |  Non-STE: A listening port on the firewall.

## OPERATE (v)  ✓

- STE: Operate the application through the CLI.  |  Non-STE: Run the application through the CLI.

## OPERATION (n)  ✓

- STE: The operation of the request is asynchronous.  |  Non-STE: The request is processed asynchronously.

## OPTION (n)  ✗

Not approved. Use the STE form below.
- STE: You can use an alternative configuration.  |  Non-STE: You have the option to use another configuration.

## OR (conj)  ✓

- STE: Use Python or Node.js.  |  Non-STE: Use Python; alternatively use Node.js.

## ORDER (n)  ✓

- STE: Execute the steps in the given order.  |  Non-STE: Execute the steps sequentially.

## OTHER (adj)  ✓

- STE: The other endpoint returns JSON.  |  Non-STE: The alternative endpoint returns JSON.

## OUTPUT (n)  ✓

- STE: The output of the command is a list.  |  Non-STE: The command prints a list.

## OVER (prep)  ✗

Not approved. Use the STE form below.
- STE: More than the threshold.  |  Non-STE: Over the threshold.

## OVERRIDE (v)  ✓

- STE: Override the default behavior in the subclass.  |  Non-STE: Replace the default behavior in the subclass.

# P

## PACKAGE (n)  ✓

- STE: Install the package with pip.  |  Non-STE: Install the library with pip.

## PAGE (n)  ✓

- STE: The landing page of the application.  |  Non-STE: The home screen of the application.

## PARAMETER (n)  ✓

- STE: The function takes two parameters.  |  Non-STE: The function accepts two arguments.

## PART (n)  ✓

- STE: A part of the documentation.  |  Non-STE: A section of the documentation.

## PASS (v)  ✓

- STE: The test passes.  |  Non-STE: The test succeeds.

## PASTE (v)  ✓

- STE: Paste the text into the editor.  |  Non-STE: Insert the copied text into the editor.

## PATH (n)  ✓

- STE: The path to the config file is `/etc/app/`.  |  Non-STE: The location of the config file is `/etc/app/`.

## PATTERN (n)  ✓

- STE: The regex pattern matches the input.  |  Non-STE: The regular expression matches the input.

## PERFORM (v)  ✗

Not approved. Use the STE form below.
- STE: Do the build.  |  Non-STE: Perform the build.

## PERFORMANCE (n)  ✓

- STE: The performance of the query is good.  |  Non-STE: The query runs fast.

## PERMANENT (adj)  ✓

- STE: Write the data to permanent storage.  |  Non-STE: Write the data to persistent storage.

## PERMIT (v)  ✗

Not approved. Use the STE form below.
- STE: The API lets you send 100 requests per minute.  |  Non-STE: The API permits 100 requests per minute.

## PERSON (n)  ✓

- STE: Only one person can access the account.  |  Non-STE: Only a single user can access the account.

## PIPE (n)  ✓

- STE: Use a pipe to connect the commands.  |  Non-STE: Use the pipe operator to connect the commands.

## PLACE (n)  ✓

- STE: Place the hook in the lifecycle at the right position.  |  Non-STE: Insert the hook into the lifecycle.

## PLUS (prep)  ✓

- STE: The total is the base plus the overhead.  |  Non-STE: The total is the sum of the base and overhead.

## POINT (n)  ✓

- STE: The entry point of the application is `main()`.  |  Non-STE: The application starts at `main()`.

## PORT (n)  ✓

- STE: The application listens on port 8080.  |  Non-STE: The application uses port 8080.

## POSITION (n)  ✓

- STE: The position of the element in the array is 0.  |  Non-STE: The index of the element in the array is 0.

## POSSIBLE (adj)  ✓

- STE: A possible solution is to increase the timeout.  |  Non-STE: One solution could be to increase the timeout.

## POWER (n)  ✓

- STE: The processing power of the server is sufficient.  |  Non-STE: The server has enough CPU.

## PREPARE (v)  ✓

- STE: Prepare the environment for deployment.  |  Non-STE: Set up the environment for deployment.

## PREVENT (v)  ✓

- STE: Use parameterized queries to prevent SQL injection.  |  Non-STE: Use parameterized queries to avoid SQL injection.

## PREVIOUS (adj)  ✓

- STE: The previous version had a bug.  |  Non-STE: The prior version had a bug.

## PRIMARY (adj)  ✓

- STE: The primary key of the table is the `id` field.  |  Non-STE: The main key of the table is the `id` field.

## PROBLEM (n)  ✓

- STE: Identify the root cause of the problem.  |  Non-STE: Find what caused the issue.

## PROCEDURE (n)  ✓

- STE: Do the deployment procedure.  |  Non-STE: Follow the deployment procedure.

## PROCESS (n)  ✗

Not approved. Use the STE form below.
- STE: Process the request synchronously.  |  Non-STE: Handle the request synchronously.

## PROVIDE (v)  ✗

Not approved. Use the STE form below.
- STE: The function returns the result.  |  Non-STE: The function provides the result.

## PULL (v)  ✓

- STE: Pull the latest changes from the repository.  |  Non-STE: Fetch the latest changes from the repository.

## PUSH (v)  ✓

- STE: Push the commit to the remote.  |  Non-STE: Upload the commit to the remote.

## PUT (v)  ✓

- STE: Put the value in the variable.  |  Non-STE: Assign the value to the variable.

# Q

## QUALITY (n)  ✓

- STE: Code quality is important.  |  Non-STE: The standard of the code is important.

## QUANTITY (n)  ✓

- STE: A large quantity of data.  |  Non-STE: A lot of data.

## QUERY (n)  ✓

- STE: The query returns 10 rows.  |  Non-STE: The SQL statement returns 10 rows.

## QUICK (adj)  ✓

- STE: Process the request quickly.  |  Non-STE: Process the request fast.

# R

## RAISE (v)  ✓

- STE: Raise an exception when the value is null.  |  Non-STE: Throw an exception when the value is null.

## RANGE (n)  ✓

- STE: The port range is 8000-8080.  |  Non-STE: The ports go from 8000 to 8080.

## READ (v)  ✓

- STE: Read the file from disk.  |  Non-STE: Load the file from disk.

## READY (adj)  ✓

- STE: The build is ready for deployment.  |  Non-STE: The build can be deployed.

## RECEIVE (v)  ✓

- STE: Receive the HTTP response.  |  Non-STE: Get the HTTP response.

## RECOMMEND (v)  ✓

- STE: The style guide recommends this format.  |  Non-STE: The style guide suggests this format.

## RECORD (v)  ✓

- STE: Record the error in the log.  |  Non-STE: Log the error.

## REDUCE (v)  ✗

Not approved. Use the STE form below.
- STE: Decrease the memory usage.  |  Non-STE: Reduce the memory usage.

## REFER (v)  ✓

- STE: Refer to the API documentation for details.  |  Non-STE: See the API documentation for details.

## REFRESH (v)  ✓

- STE: Refresh the page to see the changes.  |  Non-STE: Reload the page to see the changes.

## REJECT (v)  ✓

- STE: Reject the commit if tests fail.  |  Non-STE: Deny the commit if tests fail.

## RELEASE (v)  ✓

- STE: Release the new version to production.  |  Non-STE: Publish the new version to production.
- STE: Release the memory after use.  |  Non-STE: Free the memory after use.

## REMAINING (adj)  ✓

- STE: Fix the remaining warnings.  |  Non-STE: Fix the leftover warnings.

## REMOVE (v)  ✓

- STE: Remove the deprecated function.  |  Non-STE: Delete the deprecated function.

## REPAIR (v)  ✓

- STE: Repair the broken build.  |  Non-STE: Fix the broken build.

## REPEAT (v)  ✓

- STE: Repeat the operation for each item.  |  Non-STE: Loop through the items and do the operation.

## REPLACE (v)  ✓

- STE: Replace the old library with the new one.  |  Non-STE: Swap the old library for the new one.

## REPORT (n)  ✓

- STE: Report the bug in the issue tracker.  |  Non-STE: Log the bug in the issue tracker.

## REQUEST (n)  ✓

- STE: The HTTP request returns 200 OK.  |  Non-STE: The HTTP call returns 200 OK.

## REQUIRE (v)  ✗

Not approved. Use the STE form below.
- STE: You must install Node.js.  |  Non-STE: The project requires Node.js.

## RESOURCE (n)  ✓

- STE: Free the resources after use.  |  Non-STE: Release the resources after use.

## RESPONSE (n)  ✓

- STE: The response contains the user data.  |  Non-STE: The reply contains the user data.

## RESTART (v)  ✓

- STE: Restart the service.  |  Non-STE: Stop and start the service.

## RESULT (n)  ✓

- STE: The result of the query is an empty set.  |  Non-STE: The query returns no rows.

## RETRY (v)  ✓

- STE: Retry the request after 5 seconds.  |  Non-STE: Try the request again after 5 seconds.

## RETURN (v)  ✓

- STE: The function returns the computed value.  |  Non-STE: The function gives back the computed value.

## REVIEW (n)  ✗

Not approved. Use the STE form below.
- STE: Examine the code for issues.  |  Non-STE: Review the code for issues.

## RIGHT (adj)  ✓

- STE: Align the text right.  |  Non-STE: Align the text to the right.

## RISK (n)  ✓

- STE: The risk of data loss is small.  |  Non-STE: There is little chance of data loss.

## ROOT (n)  ✓

- STE: The config file is in the root of the project.  |  Non-STE: The config file is at the top level of the project.
- STE: Run the command as root.  |  Non-STE: Run the command with superuser privileges.

## ROUTE (n)  ✓

- STE: The route `/users` returns the user list.  |  Non-STE: The endpoint `/users` returns the user list.

## RULE (n)  ✓

- STE: The validation rule checks the email format.  |  Non-STE: The validation checks the email format.

## RUN (v)  ✓

- STE: Run the script from the terminal.  |  Non-STE: Execute the script from the terminal.

# S

## SAFE (adj)  ✓

- STE: A safe default value prevents crashes.  |  Non-STE: A sensible default value prevents crashes.
- STE: For data safety, encrypt the backup.  |  Non-STE: For security, encrypt the backup.

## SAME (adj)  ✓

- STE: The two functions return the same result.  |  Non-STE: The two functions return identical results.

## SAMPLE (n)  ✓

- STE: A code sample is in the `examples/` directory.  |  Non-STE: An example is in the `examples/` directory.

## SAVE (v)  ✓

- STE: Save the file to disk.  |  Non-STE: Write the file to disk.

## SCHEDULE (v)  ✓

- STE: Schedule the job to run daily.  |  Non-STE: Set the job to run daily.

## SEARCH (v)  ✓

- STE: Search the logs for error messages.  |  Non-STE: Look through the logs for error messages.

## SECTION (n)  ✓

- STE: Refer to the Security section of the README.  |  Non-STE: See the Security part of the README.

## SEE (v)  ✓

- STE: See the documentation for details.  |  Non-STE: Refer to the documentation for details.

## SELECT (v)  ✓

- STE: Select the database from the list.  |  Non-STE: Choose the database from the list.

## SEND (v)  ✓

- STE: Send the request to the server.  |  Non-STE: Make the request to the server.

## SEPARATE (adj)  ✗

Not approved. Use the STE form below.
- STE: Keep the modules isolated from each other.  |  Non-STE: Keep the modules separate from each other.

## SEQUENCE (n)  ✓

- STE: Execute the steps in the given sequence.  |  Non-STE: Execute the steps in order.

## SERVER (n)  ✓

- STE: The server listens on port 443.  |  Non-STE: The service listens on port 443.

## SERVICE (n)  ✓

- STE: The authentication service is down.  |  Non-STE: The auth service is not running.

## SET (n)  ✓

- STE: Set the variable to 10.  |  Non-STE: Assign 10 to the variable.

## SHORT (adj)  ✓

- STE: A short timeout of 1 second.  |  Non-STE: A brief timeout of 1 second.

## SHOW (v)  ✓

- STE: The command shows the file contents.  |  Non-STE: The command displays the file contents.

## SHUT  ✗

Not approved. Use the STE form below.
- STE: Stop the server.  |  Non-STE: Shut down the server.

## SIGNAL (n)  ✓

- STE: Send a SIGTERM signal to the process.  |  Non-STE: Terminate the process.

## SIMPLE (adj)  ✓

- STE: A simple function with one responsibility.  |  Non-STE: A straightforward function with one responsibility.

## SINGLE (adj)  ✓

- STE: A single instance of the application.  |  Non-STE: One instance of the application.

## SIZE (n)  ✓

- STE: The size of the file is 2 MB.  |  Non-STE: The file is 2 MB.

## SLOW (adj)  ✓

- STE: Slowly increase the timeout value.  |  Non-STE: Gradually increase the timeout value.

## SMALL (adj)  ✓

- STE: A small amount of memory is allocated.  |  Non-STE: A negligible amount of memory is allocated.

## SOCKET (n)  ✓

- STE: Open a socket on port 3000.  |  Non-STE: Create a connection on port 3000.

## SOLUTION (n)  ✓

- STE: The solution to the memory leak is to use weak references.  |  Non-STE: Fix the memory leak by using weak references.

## SOME (adj)  ✓

- STE: Some tests fail under load.  |  Non-STE: A few tests fail under load.

## SOURCE (n)  ✓

- STE: Find the source of the bug.  |  Non-STE: Locate where the bug originates.

## SPACE (n)  ✓

- STE: Make sure that there is sufficient disk space.  |  Non-STE: Check that there is enough disk space.

## SPECIAL (adj)  ✓

- STE: Use the special config for staging.  |  Non-STE: Use the staging-specific config.

## SPECIFIED (adj)  ✓

- STE: Use the specified port number from the config.  |  Non-STE: Use the port number that is given in the config.

## SPEED (n)  ✓

- STE: The speed of the query is fast.  |  Non-STE: The query is fast.

## STACK (n)  ✓

- STE: Push the value onto the stack.  |  Non-STE: Add the value to the stack.

## STAGE (n)  ✗

Not approved. Use the STE form below.
- STE: During this step, do not merge the branch.  |  Non-STE: At this stage, do not merge the branch.

## STANDARD (adj)  ✓

- STE: Follow the standard coding conventions.  |  Non-STE: Follow the usual coding conventions.

## START (n)  ✓

- STE: Start the application.  |  Non-STE: Launch the application.

## STATE (n)  ✗

Not approved. Use the STE form below.
- STE: Examine the condition of the system.  |  Non-STE: Examine the state of the system.

## STATUS (n)  ✓

- STE: The status of the service is "healthy."  |  Non-STE: The service is healthy.

## STAY (v)  ✓

- STE: Make sure that the connection stays open.  |  Non-STE: Keep the connection open.

## STEP (n)  ✓

- STE: Do steps 1 through 5 in the given order.  |  Non-STE: Follow the procedure steps 1-5.

## STOP (v)  ✓

- STE: Stop the process.  |  Non-STE: Kill the process.
- STE: When the errors stop, check the logs.  |  Non-STE: When the errors cease, check the logs.

## STORE (v)  ✗

Not approved. Use the STE form below.
- STE: Keep the config files in version control.  |  Non-STE: Store the config files in version control.

## STREAM (n)  ✓

- STE: Process the data as a stream.  |  Non-STE: Process the data in chunks.

## STRING (n)  ✓

- STE: The response returns a JSON string.  |  Non-STE: The response returns JSON text.

## STRONG (adj)  ✓

- STE: Use a strong password.  |  Non-STE: Use a secure password.

## STRUCTURE (n)  ✓

- STE: The structure of the project follows MVC.  |  Non-STE: The project layout follows MVC.

## SUFFICIENT (adj)  ✓

- STE: Make sure that there is sufficient disk space.  |  Non-STE: Make sure that there is enough disk space.

## SUDDEN (adj)  ✓

- STE: If the service fails suddenly, read the logs.  |  Non-STE: If the service fails unexpectedly, read the logs.

## SUPPLY (n)  ✓

- STE: Supply the API key as a query parameter.  |  Non-STE: Provide the API key as a query parameter.

## SURFACE (n)  ✓

- STE: The API surface of the library is small.  |  Non-STE: The public interface of the library is small.

## SYSTEM (n)  ✓

- STE: The authentication system uses JWT.  |  Non-STE: The authentication module uses JWT.

# T

## TABLE (n)  ✓

- STE: The `users` table has four columns.  |  Non-STE: The `users` database table has four columns.

## TAG (n)  ✓

- STE: Add a version tag to the commit.  |  Non-STE: Mark the commit with a version number.

## TAKE (v)  ✗

Not approved. Use the STE form below.
- STE: The query consumes 100 ms.  |  Non-STE: The query takes 100 ms.

## TASK (n)  ✓

- STE: The asynchronous task runs in the background.  |  Non-STE: The background job runs asynchronously.

## TELL (v)  ✓

- STE: The log file tells you the error location.  |  Non-STE: The log file shows you the error location.

## TEMPORARY (adj)  ✓

- STE: Create a temporary file for the intermediate data.  |  Non-STE: Create a temp file for the intermediate data.

## TERMINATE (v)  ✓

- STE: Terminate the hung process.  |  Non-STE: Kill the hung process.

## TEST (n)  ✓

- STE: Run the unit tests before you merge.  |  Non-STE: Execute the test suite before merging.

## TEST (v)  ✗

Not approved. Use the STE form below.
- STE: Do a test of the module.  |  Non-STE: Test the module.

## TEXT (n)  ✓

- STE: The response body contains plain text.  |  Non-STE: The response body is a string.

## THAN (conj)  ✓

- STE: The new version is faster than the previous version.  |  Non-STE: The new version outperforms the previous version.

## THAT (conj)  ✓

- STE: Make sure that the tests pass.  |  Non-STE: Ensure the tests pass.

## THE (art)  ✓

- STE: The function returns a value.  |  Non-STE: Function returns a value.

## THEN (adv)  ✓

- STE: Compile the code. Then, run the tests.  |  Non-STE: Compile the code and subsequently run the tests.

## THICK (adj)  ✓


## THREAD (n)  ✓

- STE: Run the task in a separate thread.  |  Non-STE: Run the task in parallel.

## THROUGH (prep)  ✓

- STE: Route the request through the proxy.  |  Non-STE: Pass the request via the proxy.

## THROW (v)  ✓

- STE: The function throws an error on invalid input.  |  Non-STE: The function raises an error on invalid input.

## THUS (adv)  ✓

- STE: The token expires. Thus, the request fails.  |  Non-STE: The token expires; therefore, the request fails.

## TIME (n)  ✓

- STE: The response time is 200 ms.  |  Non-STE: The latency is 200 ms.

## TIMEOUT (n)  ✓

- STE: Set the timeout to 30 seconds.  |  Non-STE: Configure a 30-second time limit.

## TO (prep)  ✓

- STE: Navigate to the settings page.  |  Non-STE: Go to the settings page.

## TOKEN (n)  ✓

- STE: Pass the token in the Authorization header.  |  Non-STE: Include the token in the request.

## TOO (adv)  ✓

- STE: Too many open connections.  |  Non-STE: Excessively many open connections.

## TOP (adj)  ✓

- STE: The top of the file contains the imports.  |  Non-STE: The beginning of the file contains the imports.

## TOUCH (v)  ✓

- STE: Touch the file to update its modification date.  |  Non-STE: Update the file timestamp.

## TRACK (v)  ✓

- STE: Track the changes with git.  |  Non-STE: Monitor the changes with git.

## TRAIN (v)  ✓

- STE: Train the model on the training set.  |  Non-STE: Fit the model to the training data.

## TRANSFER (v)  ✓

- STE: Transfer the file via SCP.  |  Non-STE: Copy the file via SCP.

## TRIGGER (v)  ✓

- STE: The event triggers the callback.  |  Non-STE: The event fires the callback.

## TRUE (adj)  ✗

Not approved. Use the STE form below.
- STE: The condition is true.  |  Non-STE: The condition evaluates to truth.

## TRY (v)  ✓

- STE: Try the request again.  |  Non-STE: Retry the request.

## TURN (v)  ✓

- STE: Turn on the feature flag.  |  Non-STE: Enable the feature flag.

## TYPE (n)  ✓

- STE: The type of the variable is string.  |  Non-STE: The variable is a string.

# U

## UNDER (prep)  ✗

Not approved. Use the STE form below.
- STE: Below the threshold.  |  Non-STE: Under the threshold.

## UNLOCK (v)  ✓

- STE: Unlock the mutex.  |  Non-STE: Release the mutex.

## UNSTABLE (adj)  ✓

- STE: The connection is unstable.  |  Non-STE: The connection is flaky.

## UNTIL (prep)  ✓

- STE: Retry the request until it succeeds.  |  Non-STE: Keep retrying the request while it fails.

## UNUSUAL (adj)  ✓

- STE: Watch for unusual log entries.  |  Non-STE: Watch for unexpected log entries.

## UP (adv)  ✓

- STE: Bring the service up.  |  Non-STE: Start the service.

## UPDATE (v)  ✓

- STE: Update the package to the latest version.  |  Non-STE: Upgrade the package to the latest version.

## USE (v)  ✓

- STE: Use the API to fetch data.  |  Non-STE: Utilize the API to fetch data.

## USUAL (adj)  ✓

- STE: Usually, the request returns 200 OK.  |  Non-STE: Typically, the request returns 200 OK.

# V

## VALID (adj)  ✗

Not approved. Use the STE form below.
- STE: Make sure that the input is correct.  |  Non-STE: Make sure that the input is valid.

## VALIDATE (v)  ✓

- STE: Validate the user input before processing.  |  Non-STE: Check the user input before processing.

## VALUE (n)  ✓

- STE: The value of the environment variable is "production".  |  Non-STE: The environment variable is set to "production".

## VARIABLE (n)  ✓

- STE: Declare the variable before use.  |  Non-STE: Define the variable before use.

## VERIFY (v)  ✗

Not approved. Use the STE form below.
- STE: Make sure that the signature is correct.  |  Non-STE: Verify the signature.

## VERSION (n)  ✓

- STE: The current version is 3.2.1.  |  Non-STE: The release is 3.2.1.

## VERY (adv)  ✓

- STE: Increase the value very slowly.  |  Non-STE: Increment the value in tiny steps.

## VIA (prep)  ✗

Not approved. Use the STE form below.
- STE: Authenticate through OAuth.  |  Non-STE: Authenticate via OAuth.

## VIEW (n)  ✓

- STE: The log view shows recent entries.  |  Non-STE: The log display shows recent entries.

## VISIBLE (adj)  ✗

Not approved. Use the STE form below.
- STE: Make sure that you can see the output in the terminal.  |  Non-STE: Make sure that the output is visible in the terminal.

## VISUAL (adj)  ✓

- STE: Do a visual inspection of the UI.  |  Non-STE: Visually inspect the UI.

## VOLUME (n)  ✓

- STE: Mount the volume to the container.  |  Non-STE: Attach the storage to the container.

# W

## WAIT (v)  ✓

- STE: Wait for the asynchronous task to complete.  |  Non-STE: Block until the async task finishes.

## WANT (v)  ✓

- STE: Install the package that you want.  |  Non-STE: Install the desired package.

## WARNING (n)  ✓

- STE: The compiler shows a warning for the deprecated function.  |  Non-STE: The compiler warns about the deprecated function.

## WATCH (v)  ✗

Not approved. Use the STE form below.
- STE: Monitor the log output for errors.  |  Non-STE: Watch the log output for errors.

## WE (pron)  ✓

- STE: We recommend using the latest API.  |  Non-STE: The team recommends using the latest API.

## WEAK (adj)  ✓

- STE: A weak reference does not prevent garbage collection.  |  Non-STE: A soft reference does not prevent garbage collection.

## WEIGHT (n)  ✓

- STE: The weight of the config value is 0.5.  |  Non-STE: The priority of the config value is 0.5.

## WHEN (conj)  ✓

- STE: When the build finishes, deploy the artifact.  |  Non-STE: After the build finishes, deploy the artifact.

## WHERE (conj)  ✓

- STE: Find the line where the error occurred.  |  Non-STE: Find the line at which the error occurred.

## WHILE (conj)  ✓

- STE: Log the progress while the script runs.  |  Non-STE: Log the progress as the script executes.

## WHOLE (adj)  ✗

Not approved. Use the STE form below.
- STE: Examine all of the codebase.  |  Non-STE: Examine the whole codebase.

## WIDE (adj)  ✓

- STE: Wide test coverage.  |  Non-STE: Broad test coverage.

## WILL (v)  ✓

- STE: The docs will help you to set up the project.  |  Non-STE: The docs are going to help you set up the project.

## WITH (prep)  ✓

- STE: Compare the result with the expected value.  |  Non-STE: Compare the result against the expected value.

## WITHOUT (prep)  ✓

- STE: Run the build without caching.  |  Non-STE: Run the build with caching disabled.

## WORK (n)  ✓

- STE: Do the work in a dedicated branch.  |  Non-STE: Do the task in a dedicated branch.

## WORKER (n)  ✓

- STE: The worker processes jobs from the queue.  |  Non-STE: The background job processor handles the queue.

## WRITE (v)  ✓

- STE: Write the result to a file.  |  Non-STE: Save the result to a file.

## WRONG (adj)  ✗

Not approved. Use the STE form below.
- STE: Mark the variable as private to prevent incorrect usage.  |  Non-STE: Mark the variable as private to prevent wrong usage.

# Y

## YES (adv)  ✓

- STE: Does the test pass? Yes or no?  |  Non-STE: Is the test passing? Affirmative or negative?

## YET (conj)  ✗

Not approved. Use the STE form below.
- STE: Compile the project, but skip the tests.  |  Non-STE: Compile the project, yet skip the tests.

## YET (adv)  ✗

Not approved. Use the STE form below.
- STE: Do not deploy the feature at this time.  |  Non-STE: Do not deploy the feature yet.

## YOU (pron)  ✓

- STE: You can run the script from the command line.  |  Non-STE: The user can run the script from the command line.

## YOUR (adj)  ✓

- STE: If you get an error in your terminal, read the logs.  |  Non-STE: If an error appears in the terminal, read the logs.

# Z

## ZERO (n)  ✓

- STE: Initialize the counter to zero.  |  Non-STE: Set the counter to 0.

## List  ✓


## Summary  ✓



## 04-templates.md

# Level 4 — Document Templates + Extension Vocabulary + Reference Catalogue

This slice gives the fill-in templates for every code-documentation type, the
sentence-level rules that govern them, the STE-Code extension vocabulary that
lower tiers omit, and the vendor/community reference catalogue.

It pairs with `01-principles.md` (word rules 1.1–1.14), `02-synonyms.md` (the 19
technical noun categories), and `03-dictionary.md` (controlled terminology).

Use this file when an LLM must **produce** or **review** a concrete document:
a review comment, a pull-request description, a README procedure, an API entry,
a docstring, a commit message, or an error message.

## Contract for every template

1. **Word gate** — each word passes one of: approved in the controlled
   terminology, a code-domain technical noun (Rule 1.5, 19 categories), or a
   code-domain technical verb (Rule 1.12).
2. **Imperative action** — every instruction line starts with a base verb. No
   modal verb, no passive voice, no gerund (Rule 5.3).
3. **One technical noun per item** — name the same symbol the same way every
   time, in backticks, uninflected (Rules 1.5, 1.11).
4. **Condition first** — a condition precedes its command and is separated by a
   comma (Rule 5.4).
5. **Active voice** — passive only when the agent is unknown (Rule 3.6).
6. **Consistent style** — one term, one syntax, one meaning per concept
   (Rule 9.4).

---

## Governing rules

### Rule 5.3 — Imperative (command) form for instructions

Write every instruction in the imperative: start with a base verb, omit the
implied subject "you", give one direct instruction.

- Do not use passive voice ("The tests are run by CI"), gerunds ("Running the
  tests…"), or modal verbs ("can", "could", "should", "may", "might", "would").
- Do not put "must" before an imperative in a standard instruction. Reserve
  "must" for WARNING and CAUTION blocks (security, data loss, safety):
  "WARNING: IF YOU MUST REMOVE THE DATABASE, FIRST MAKE A BACKUP."
- Use the base verb: "Set the port to 8080", not "The port should be set to
  8080".

Document-type boundaries:

| Document type | Imperative applies to | Descriptive applies to |
|---|---|---|
| README | install, configure, build, quick-start | goals, features, architecture |
| API docs | setup, auth walkthroughs, getting started | endpoint behavior, responses |
| Docstrings / comments | shell-script headers, Makefile targets | function and method behavior |
| Commit messages | subject line | body rationale |
| Error messages | the recovery instruction | the failure statement |

> **Non-STE:** The test suite can be executed with `npm test`.
>
> **STE:** Run the unit tests with `npm test`.

> **Non-STE:** Before you delete the branch, you must push all local commits.
>
> **STE:** Before you remove the branch, push all local commits to the remote.

### Rule 5.4 — Descriptive statement before the command

When the reader must know a condition before they act, write the condition as a
descriptive statement, then a **comma**, then the imperative command. The comma
is required: its position decides which verb an adverb modifies.

> **STE:** If the connection pool is full, reject the request.
> (comma after "full" → "reject" is the command)
>
> **STE:** If the connection pool is full automatically, reject the request.
> (comma after "automatically" → the pool fills on its own)

- Keep one condition per sentence. Write each condition–command pair of a
  multi-step procedure as its own step.
- Apply this shape inside T2 (`Result` → `Required change`), T4 (`Scope` sets
  the condition), T5 (`How` steps), T7, T8, and T11.

> **Non-STE:** Run the database migration after you set `DATABASE_URL` and
> confirmed the server accepts connections.
>
> **STE:** After you set the `DATABASE_URL` variable, run the database migration.

### Rule 3.6 — Active voice

The subject does the action. Passive voice is permitted in descriptive writing
only when the agent is unknown.

Test: ask "by whom or by what?" If the sentence answers that question, it is
passive — make the agent the subject.

- **Passive:** The connections are opened by a pool manager.
- **Active:** A pool manager opens the connections.
- **Passive, agent unknown, allowed:** During transmission, the data was
  corrupted.

### Rule 9.4 — Consistent style

Use the same style every time the same type of step occurs. Audit three
dimensions independently:

- **Lexical** — one term per concept ("configuration file", never alternating
  with "settings file" or "config").
- **Syntactic** — the same grammatical template for the same action type.
- **Semantic** — a term keeps one meaning across every file, module, and
  document type.

Per document type:

| Document type | Consistency requirement |
|---|---|
| README | one word for the project artifact ("library", not "package" later) |
| API docs | one name per endpoint and parameter across all references |
| Docstrings | the same term as the signature (`max_retries`, not "maximum attempts") |
| Commit messages | one imperative verb per change category ("Add", never mixed with "Introduce") |
| Error messages | one error code produces the same text every time |
| CLI / help text | a flag description matches `--help`, man pages, docs, errors |

```markdown
## Non-STE (inconsistent)
1. Open the configuration file in a text editor.
2. Change the port number in the settings file.
3. Save the config and close it.
4. Compile the project with the build command.
5. Make the binary for the target platform.

## STE (consistent)
1. Open the configuration file in a text editor.
2. Change the port number in the configuration file.
3. Save the configuration file and close it.
4. Build the project with the build command.
5. Build the binary for the target platform.
```

### Rule 1.5 grammar — technical nouns in running text

Identifiers, file paths, type names, commands, and status codes are code-domain
technical nouns. Apply this grammar in all template prose:

- **Backticks, no inflection.** Write `getUser`, `null`, `OrderService`. Not
  "the `getUser`s". Acronym plurals: `APIs`, not `API's`.
- **One name per item (Rule 1.11).** `getUser` stays `getUser` — not "the
  getter", then "that helper".
- **Articles.** "the" for a specific instance, "a"/"an" for an indefinite one,
  no article for a plural general reference.
- **Possessive only for roles and organizations (category 11).** "the user's
  session data", but "the configuration of the `Docker` container".
- **Capitalization.** Proper nouns keep theirs (`TypeScript`, `PostgreSQL`);
  common technical nouns are lowercase unless they start the sentence.
- **Quoted keywords and status codes (category 10).** `if`, `return`, `class`,
  `404 Not Found`, `500` are quoted text, never a bare number.

---

## Template selection

| Situation | Template |
|-----------|----------|
| One line or one hunk in a diff | T1 — Inline review comment |
| A defect the author must fix before merge | T2 — Blocking review finding |
| An optional improvement | T3 — Non-blocking suggestion |
| Summary on the whole pull request | T4 — PR review summary |
| PR description the author writes | T5 — PR description |
| Reply to review feedback | T6 — Author response |
| Setup / install / build steps | T7 — README procedure |
| API endpoint reference entry | T8 — API doc entry |
| Function or method docstring | T9 — Docstring |
| A completed change | T10 — Commit message |
| A runtime failure the user sees | T11 — Error message |

---

## T1 — Inline review comment

```text
<observation>: one sentence, one subject, present tense.
<effect>: one sentence that gives the result of the observation.
<action>: one imperative sentence.
```

> The `getUser` function returns `undefined` when `id` is `0`.
> The caller in `UserController` then reads a property of `undefined`.
> Return `null` for an unknown `id`, and check the result in `UserController`.

Constraints: imperative action (Rule 5.3); one name per item (Rule 1.11); no
technical noun used as a verb (Rule 1.7) — "Send a request to the `/users`
endpoint", not "Endpoint the request".

## T2 — Blocking review finding

```text
**Finding:** <one sentence: what is wrong>
**Location:** `<path>:<line>` in `<symbol>`
**Cause:** <one sentence>
**Result:** <one sentence: what fails, and when>
**Required change:** <one imperative sentence>
```

> **Finding:** The `saveOrder` method does not do a check of the `quantity` field.
> **Location:** `src/orders/service.ts:142` in `OrderService.saveOrder`
> **Cause:** The method writes the request body to the database with no check.
> **Result:** A negative `quantity` value is written to the `orders` table.
> **Required change:** Reject a request when `quantity` is less than `1`.

The field label carries the obligation, so do not add "must" as an intensifier.

## T3 — Non-blocking suggestion

```text
**Suggestion (optional):** <one imperative sentence>
**Reason:** <one sentence>
```

> **Suggestion (optional):** Move the three retry constants into `RetryPolicy`.
> **Reason:** The same three values occur in `HttpClient` and in `QueueWorker`.

Mark the item optional in the first word. Use no hedge words ("maybe",
"perhaps", "just") — Rule 1.10.

## T4 — PR review summary

```text
**Decision:** Approve | Request changes | Comment
**Scope:** <one sentence: what the pull request changes>
**Blocking findings:** <count>
1. <one sentence each, with `path:line`>
**Optional suggestions:** <count>
1. <one sentence each>
**Verification:** <one sentence: what you ran or read>
```

> **Decision:** Request changes
> **Scope:** The pull request adds a rate limiter to the `/api/v1/login` route.
> **Blocking findings:** 1
> 1. `src/middleware/rateLimit.ts:58` — The limiter counts a failed request and a successful request in the same bucket.
> **Optional suggestions:** 1
> 1. Give the `WINDOW_MS` constant a unit in its name.
> **Verification:** I ran `npm test` and read the diff in `src/middleware`.

`Decision` is one of the three approved values — no fourth value, no sentence.

## T5 — PR description (author)

```text
## What
<one to three sentences. One subject in each sentence.>

## Why
<one to three sentences. Give the cause, then the result.>

## How
1. <imperative sentence>
2. <imperative sentence>

## Test
- <one sentence per check, with the command in backticks>

## Risk
<one sentence. Write "None." when there is no risk.>
```

> ## What
> This pull request adds a retry to the `PaymentClient.charge` method.
> ## Why
> The payment gateway returns `503` during a deployment. The current client fails
> the order on the first `503` response.
> ## How
> 1. Add a `RetryPolicy` class with three attempts and an exponential delay.
> 2. Call `RetryPolicy.execute` from `PaymentClient.charge`.
> ## Test
> - Run `npm test -- payment` to check the new unit tests.
> - Send a request to the sandbox gateway to check the delay values.
> ## Risk
> A retry can create a duplicate charge if the gateway accepted the first
> request. The client sends an idempotency key to prevent this result.

`How` steps are imperative (Rule 5.3). `What` and `Why` are descriptive but
still use approved words and one name per item.

## T6 — Author response to feedback

```text
**Comment:** <link or `path:line`>
**Response:** Done | Changed | Not changed
**Detail:** <one sentence>
```

> **Comment:** `src/middleware/rateLimit.ts:58`
> **Response:** Changed
> **Detail:** The limiter now counts only a failed request in the login bucket.

Use one of the three approved values. Use no "LGTM", "nit", or "wontfix"
(Rule 1.10).

## T7 — README procedure (install / configure / build)

Use the imperative only in procedural steps. Keep one condition–command pair per
step (Rule 5.4). Name the same file, command, and variable identically in all
steps (Rule 9.4).

```text
## Setup

Clone the repository.
Install the dependencies with `npm install`.
Set the `DATABASE_URL` environment variable in `.env`.
After the dependencies install without errors, run the development server with `npm run dev`.
```

> **Non-STE:** First you need to have Node.js version 18 or higher installed then
> run `npm install` and after all dependencies finish downloading if there are no
> errors you can run `npm run build`…
>
> **STE:** Make sure that Node.js version 18 or higher is installed. Run `npm
> install`. After the dependencies install without errors, run `npm run build`.

Descriptive README sections (About, Features, Architecture) use declarative
sentences — they do not instruct the reader to act.

## T8 — API doc entry (endpoint reference)

Endpoint behavior is descriptive. The imperative applies to setup, auth
walkthroughs, and getting-started steps. State the condition that triggers an
error before you describe the response (Rule 5.4).

```text
### GET /users

Gets the list of users.

Request:
GET /users HTTP/1.1
Authorization: Bearer ***

Response:
200 OK — a JSON array of user records.

Errors:
If the client sends more than 100 requests per minute, the API returns a
`429 Too Many Requests` status code. The response includes a `Retry-After`
header that shows the wait time.
```

> **Non-STE:** You can authenticate by sending a POST request to `/auth/login`
> with your credentials, and you should include the returned token in the
> Authorization header.
>
> **STE:** Send a POST request to `/auth/login` with your credentials. Include
> the returned token in the `Authorization` header.

## T9 — Docstring (function / method)

Describe what the code does, in the active voice (Rule 3.6), not what the reader
must do. State preconditions before behavior (Rule 5.4). Use the same term as
the signature (Rule 9.4).

```python
def get_profile(user_id: int) -> Profile:
    """Return the profile data for the given user ID.

    Query the database for the row that matches `user_id` and return
    a Profile object. If the user does not exist, raise ValueError.
    """
    return db.query(Profile).filter_by(id=user_id).one()
```

> **Non-STE:** Gets a user record. The duration in milliseconds the client shall
> await a response prior to terminating the connection attempt.
>
> **STE:** Gets a user record. The time in milliseconds that the client waits for
> a response before it stops the connection.

## T10 — Commit message

The subject line is imperative and completes "If applied, this commit will…"
(Rule 5.3). The body may use descriptive sentences. Use one imperative verb per
change category across the project (Rule 9.4).

```text
Fix the race condition in the connection pool

The pool returned the same connection to two threads under load.
Add a lock around the checkout path so each thread gets a unique
connection. The retry test in tests/test_pool.py now passes.
```

> **Non-STE:** Fixed the race condition in the connection pool.
>
> **STE:** Fix the race condition in the connection pool.

> **Non-STE:** When the connection pool reaches max connections, add a mutex lock
> around pool access to prevent a race condition.
>
> **STE:** When the connection pool reaches its maximum capacity, add a mutex
> lock around pool access to prevent a race condition.

## T11 — Error message

Describe what failed, then give a recovery instruction, separated by a period or
a newline. One error code produces the same text every time (Rule 9.4).

```python
raise RuntimeError(
    "The port 8080 is already in use. "
    "Set a different port with the --port option."
)
```

> **Non-STE:** Port is already in use.
>
> **STE:** The port 8080 is already in use. Set a different port with the
> `--port` option.

> **Non-STE:** Invalid configuration file. Check the schema.
>
> **STE:** The configuration file failed schema validation. Check the
> `config.schema.json` file for required fields.

---

## Approved verbs for action lines

Use these code-domain technical verbs in the imperative line of any template.
Use the base form for an instruction (Rule 5.3) and the third-person form for a
statement of fact.

| Verb | Use it for |
|------|-----------|
| add | New code, a new field, a new file |
| remove | Deleted code or a deleted field |
| replace | One item exchanged for another |
| move | Code relocated with no change in behavior |
| rename | A new name for the same item |
| return | The value a function gives back |
| throw / raise | An error the code emits |
| catch / handle | An error the code accepts |
| validate | A check on input |
| reject | A refused input or request |
| call | Invocation of a function or method |
| read / write | Access to a file, field, or record |
| log | A record written to the audit trail or log |
| test | A check that runs in the test suite |

Do not use a verb from this table as a noun (Rule 1.13): "The function returns a
value", not "The return of the function".

## Forbidden words in template prose

| Forbidden | Reason | Use instead |
|-----------|--------|-------------|
| nit, LGTM, WIP, PTAL, IMO | jargon (Rule 1.10) | the full template label |
| smelly, hacky, ugly, clean | subjective, not approved (Rule 1.1) | the concrete defect |
| stuff, thing, some code | not a technical noun (Rule 1.5) | the identifier in backticks |
| leverage, utilize | not approved (Rule 1.3) | use |
| behaviour, initialise, colour | British spelling (Rule 1.14) | behavior, initialize, color |
| we should maybe possibly | hedging (Rule 1.1) | one imperative sentence |
| delete (verb) | not approved (Rule 1.1) | remove |
| execute (verb) | not approved (Rule 1.1) | run |
| compile (verb) | not approved (Rule 1.1) | build |

## Dictionary excerpt — instruction and template words

A focused slice of the controlled terminology (full list in `03-dictionary.md`).
UPPERCASE = approved; ✗ = not approved, use the listed alternative. Parts of
speech: (v) verb, (n) noun, (adj) adjective, (conj) conjunction, (TN/TV)
code-domain technical noun/verb.

| Word | PoS | Approved? | STE example | Non-STE to replace |
|------|-----|-----------|-------------|--------------------|
| ADD | (v) | ✓ | Add 5 lines of configuration to the file. | Append 5 lines of configuration to the file. |
| AFTER | (conj) | ✓ | After you deploy the update, do a smoke test. | Following deployment of the update, do a smoke test. |
| BEFORE | (conj) | ✓ | Before you run the migration, read the release notes. | Prior to running the migration, read the release notes. |
| CHECK | (n) | ✓ | Do a check of the input values. | Validate the input values. |
| CHECK | (v) | ✗ | Do a check of the values. / Verify the data integrity. | Check the values. |
| CLICK | (v) (TV) | ✓ | Click the "Submit" button. | Press the "Submit" button. |
| CREATE | (v) | ✓ | Create a new instance of the class. | Instantiate a new object of the class. |
| DELETE | (v) | ✗ | Remove the file from the directory. | Delete the file from the directory. |
| IF | (conj) | ✓ | If the status code is 500, retry the request. | In the event of a 500 status code, retry the request. |
| INSTALL | (v) | ✓ | Install the package with npm. | Set up the package with npm. |
| MAKE | (v) | ✓ | Make a copy of the file. | Create a copy of the file. |
| OPEN | (v) | ✓ | Open the file for reading. | Read the file. |
| REMOVE | (v) | ✓ | Remove the deprecated function. | Delete the deprecated function. |
| REPLACE | (v) | ✓ | Replace the old library with the new one. | Swap the old library for the new one. |
| RUN | (v) | ✓ | Run the script from the terminal. | Execute the script from the terminal. |
| SAVE | (v) | ✓ | Save the file to disk. | Write the file to disk. |
| SELECT | (v) | ✓ | Select the database from the list. | Choose the database from the list. |
| SET | (v) | ✓ | Set the variable to 10. | Assign 10 to the variable. |
| TYPE | (n) (TN) | ✓ | The type of the variable is string. | The variable is a string. |
| USE | (v) | ✓ | Use the API to fetch data. | Utilize the API to fetch data. |
| WHEN | (conj) | ✓ | When the build finishes, deploy the artifact. | After the build finishes, deploy the artifact. |

Mapping notes for template authors:

- **execute → run**, **compile → build**, **delete → remove**, **instantiate →
  create**, **assign → set**, **utilize/leverage → use**, **press (UI) →
  click**, **choose → select**, **swap → replace**, **validate (verb) → do a
  check / verify**, **write (file) → save**.
- **IF / WHEN / AFTER / BEFORE** are approved for condition and sequence
  clauses (Rule 5.4). Keep the comma between the clause and the command.
- **CHECK** is approved as a noun with "do a check of"; do not use it as a verb.
- **TYPE** is a technical noun for a data type; do not use it as a verb
  ("type the command" → "enter the command").

---

## Extension vocabulary (level 4 and above)

These adjectives are approved additions to the controlled terminology for the
code domain. Lower tiers omit them. Each entry gives one part of speech and one
approved meaning. Use the adjective to describe a property of code or an
operation; do not use it as a noun or a verb.

### idempotent (adj)

Describes an operation that produces the same result when applied more than
once, with no extra side effects after the first run.

> **STE:** Make the retry handler idempotent so a second call with the same
> input does not duplicate the record.
>
> **Non-STE:** Leverage an idempotent retry handler so a duplicate invocation
> will not create a redundant record.

### immutable (adj)

Describes a data structure or value that cannot be changed after it is created,
which prevents accidental shared-state defects.

> **STE:** Keep the request context immutable so concurrent threads cannot
> overwrite each other's values during a single operation.
>
> **Non-STE:** Utilize an immutable request context so concurrent threads will
> not overwrite shared values during processing.

### atomic (adj)

Describes an operation that completes fully or not at all, with no partial
result visible to other processes.

> **STE:** Wrap the balance update in an atomic transaction so the debit and the
> credit always succeed or fail together.
>
> **Non-STE:** Employ an atomic transaction to encapsulate the balance update so
> debit and credit always commit or roll back together.

### thread-safe (adj)

Describes code that functions correctly when more than one thread accesses it at
the same time, without external locking.

> **STE:** Make the singleton constructor thread-safe so two threads can call it
> on first use without creating two instances.
>
> **Non-STE:** Leverage a thread-safe singleton constructor so concurrent
> threads will not instantiate duplicate objects on first access.

### asynchronous (adj)

Describes a call or task that starts and returns before its work finishes, so
the caller can do other work meanwhile.

> **STE:** Make the file upload asynchronous so the user interface stays
> responsive while the transfer runs in the background.
>
> **Non-STE:** Utilize an asynchronous upload mechanism so the user interface
> remains responsive while the transfer executes in the background.

### concurrent (adj)

Describes tasks that make progress within the same time period, interleaved by
the scheduler rather than strictly sequentially.

> **STE:** Run the test suites in concurrent processes so the full check
> finishes in less time.

Extension summary:

| Word | PoS | Approved | Applies to |
|------|-----|----------|-----------|
| idempotent | adj | ✓ | repeated operations, retries |
| immutable | adj | ✓ | values, data structures |
| atomic | adj | ✓ | transactions, all-or-nothing operations |
| thread-safe | adj | ✓ | shared code under multiple threads |
| asynchronous | adj | ✓ | calls that return before completion |
| concurrent | adj | ✓ | interleaved tasks |

---

## Reference catalogue (vendor and community)

These external references inform the STE-Code controlled vocabulary. They are
**not** part of the standard. They are kept outside the standard, in
`.agents/reference/`, and are listed here as a catalogue.

| Reference | Type | Source |
|---|---|---|
| Microsoft Writing Style Guide | page | https://learn.microsoft.com/en-us/style-guide/welcome/ |
| MicrosoftDocs/microsoft-style-guide | page | https://github.com/MicrosoftDocs/microsoft-style-guide |
| Google Style Guides | page | https://google.github.io/styleguide/ |
| Kong/apiglossary | page | https://github.com/Kong/apiglossary |
| dwyl/technical-glossary | raw | https://raw.githubusercontent.com/dwyl/technical-glossary/main/README.md |
| jvalentino/glossary | page | https://github.com/jvalentino/glossary |
| GitHub Official Glossary | page | https://docs.github.com/en/get-started/learning-about-github/github-glossary |
| DevOps Style Guide Glossary | page | https://tydukes.github.io/coding-style-guide/glossary/ |
| ryanwi software-terms.dic | raw | https://gist.githubusercontent.com/ryanwi/6135845/raw/software-terms.dic |
| OpenSTE.org | pointer | https://openste.org/ |
| en-wl/wordlist (SCOWL) | page | https://github.com/en-wl/wordlist |
| MichaelWehar 5000-more-common | raw | https://raw.githubusercontent.com/MichaelWehar/Public-Domain-Word-Lists/master/5000-more-common.txt |
| dwyl/english-words | pointer | https://github.com/dwyl/english-words |

Use the catalogue to check whether a candidate term already has an accepted
form. A term found only in a reference is **not** approved by that fact alone —
it must still pass the three gates in `01-principles.md`.

---

## Checklist before you publish

1. Each sentence has one subject.
2. Each item has one name, used every time (Rule 1.11).
3. Each identifier is in backticks and is not inflected.
4. Each action is one imperative sentence (Rule 5.3).
5. Each condition comes before its command, separated by a comma (Rule 5.4).
6. Voice is active; passive appears only when the agent is unknown (Rule 3.6).
7. Terminology is consistent across the document and the project (Rule 9.4).
8. No word from the forbidden table is present.
9. Extension adjectives are used as adjectives only.
10. Spelling is American English (Rule 1.14).




## 05-grammar.md

# Level 4 — Grammar: Sentence Construction and Technical Noun Phrasing

Rules 2.1–2.3 of STE-Code govern how you build sentences in code
documentation: how to write technical nouns, how long a noun phrase may be,
and how to hyphenate compound modifiers. This slice is the "grammar" layer —
it sits on top of the word rules (Section 1) and below the sentence-type
rules (Section 3+).

When you generate or review code documentation with an LLM, apply these three
rules before any sentence leaves your hands:

1. Keep every technical noun phrase to **three words or fewer** (Rule 2.1).
2. When a noun must be longer, **write it in full on first use**, then use a
   short form or approved abbreviation (Rule 2.2).
3. **Hyphenate only related words used as one unit**, never a chain of more
   than three words (Rule 2.3).

These rules exist because a reader scans docs fast. A stacked noun such as
`authentication_token_expiration_refresh_interval_setting` hides which part
owns which. The fix is plain English structure: short nouns joined by
prepositions.

---

## Rule 2.1 — Keep technical nouns short

To keep multi-word technical nouns short, use prepositions (for example "of,"
"on," "in," and "for") and explain the multi-word technical nouns. Write each
multi-word technical noun as a short noun that uses prepositions to make the
meaning clear.

A technical noun that the code domain uses — a module name, a class name, a
configuration key, an endpoint path, an error type, or a test fixture — must
stay short so the reader can parse it without effort.

### Why this matters in code documentation

- A reader scans docs fast. A stacked noun hides the ownership tree: the
  setting belongs to the interval, the interval belongs to the expiration,
  the expiration belongs to the token.
- Short technical nouns match how code is already structured. A config key, a
  class, or a JSON field is one short concept. Prepositions in the sentence
  show how those short concepts relate.
- Follow the Microsoft and Google style guides: use short, plain words. Do not
  use `utilize`, `leverage`, or `employ` when `use` is enough. Do not use
  `commence`, `initiate`, or `terminate` when `start` and `stop` are enough.
  Keep the verb simple and the noun short.
- Approved code-domain adjectives stay attached to the short noun they modify:
  `idempotent`, `immutable`, `thread-safe`, `atomic`, `nullable`,
  `deprecated`, `stateless`, `backward-compatible`, `asynchronous`,
  `concurrent`, `deterministic`. Write `the idempotent retry policy`, not
  `idempotentretrypolicy`.

### How to apply the rule

1. Find a noun that stacks two or more modifiers (a "noun chain").
2. Split the chain at the ownership or containment points.
3. Connect the parts with `of`, `on`, `in`, or `for`.
4. If a part is itself a code component, name it with its short technical noun
   (its class, key, or file), not a merged word.
5. In instruction text, use the approved verbs: `set`, `get`, `make`, `show`,
   `check`, `remove`, `send`, `start`, `stop`, `use`, `update`. Do not use
   `configure` for `set`, `retrieve` for `get`, `delete`/`purge` for
   `remove`, or `display` for `show`.

### Examples in STE-Code

| Non-STE (stacked noun) | STE (short nouns + prepositions) |
|---|---|
| Authentication token expiration refresh interval setting | Setting of the refresh interval of the expiration of the authentication token |
| Install the forward service request validator middleware config tags. | Install the config tags on the validator middleware of the request of the forward service. |
| Remove the database migration script output directory lock files. | Remove the lock files that lock the output directory of the migration script of the database. |
| Adjust to obtain cache invalidation hook alignment with the event emitter. | Adjust the cache invalidation hook until it aligns with the event emitter. |
| Payment gateway timeout retry exhaustion notification handler. | Handler of the notification of the exhaustion of the retry of the timeout of the payment gateway. |
| User account profile avatar image storage bucket policy update. | Update of the policy of the storage bucket of the image of the avatar of the profile of the user account. |
| The inbound request rate limit window reset schedule controls the burst. | The schedule of the reset of the window of the rate limit of the inbound request controls the burst. |
| The background worker queue overflow alert suppression rule runs on the staging cluster. | The alert suppression rule on the overflow of the background worker queue runs on the staging cluster. |

```yaml
# STE-Code: short keys, one concept per level
auth:
  token:
    expiration:
      refresh_interval_seconds: 300   # setting of the refresh interval of the expiration of the authentication token

# Non-STE: one long key hides the relationship (do not write this)
authentication_token_expiration_refresh_interval_setting: 300
```

```python
# STE-Code doc comment
def get_refresh_interval(token):
    """Return the setting of the refresh interval of the expiration of the authentication token."""
    return token.expiration.refresh_interval_seconds
```

> **See also:** Rule 1.5 (what counts as a technical noun), Rule 1.3 (keep
> verbs and nouns plain: use, set, get, remove, check, update, show), Rule 2.2
> (write long technical nouns in full), Rule 2.3 (hyphenate related words).

---

## Rule 2.2 — Write long technical nouns in full

When a technical code noun has more than three words, write it in full. Then
use one of these methods to make the technical code noun clear:

- Give a shorter form of the technical code noun.
- Use hyphens (-) between words that you use as one unit.
- Use prepositions (for example "of," "on," "in," "for," and "to") to split a
  long noun into short, separate parts (see Rule 2.1).

A long multi-word code noun can be a long technical noun, or it can be a
combination of shorter technical nouns. Frequently, it is not possible to divide
technical code nouns into smaller parts because they are the technical nouns
that your company, framework, or subject field uses. Thus, you must write
technical code nouns as they are, in their approved form.

### Method 1 — Shorter form of technical code nouns

If a long technical code noun comes from an official code document (for
example, an API specification, a schema, an OpenAPI file, or an architecture
diagram), write it in full the first time that it occurs in the text. Then, if
it is possible, explain the technical code noun and in the remaining text of
your document, use a shorter form or an approved abbreviation.

Before you do this procedure, initialize the user session cache invalidation
lock handler (the handler that locks the cache of the user session, referred to
in this procedure as the "invalidation lock handler").

In this example, you write "user session cache invalidation lock handler" in
full. Then, after an explanation, you give a shorter technical code noun:
"invalidation lock handler." This shorter technical code noun has three words
and obeys rule 2.1.

```python
# STE-Code: write the long technical code noun in full, then use the short form
def initialize_session_lock(user_id: str) -> None:
    """Initialize the user session cache invalidation lock handler.

    The invalidation lock handler locks the cache of the user session so that
    a background job cannot read stale data while a write is in flight.
    """
    handler = UserSessionCacheInvalidationLockHandler(user_id)
    handler.engage()   # from here, refer to it as the "invalidation lock handler"
```

The Main Form Validation Module (MFVM) is a TypeScript module that includes a
Main Export Controller Unit (MECU) and a Data Bridge (DB). The MFVM is installed
in the application core layer and operates in the form submission system. The
function of the MFVM is to validate and submit the form data from the Main Form
Provider (MFP) to the data stores and the validation hooks. The Dynamic Config
Unit (DECU) sends events to operate the MFVM.

In this example, the explanation is not necessary because the text gives all the
necessary information about the module. You write all official technical code
nouns that include more than three nouns in full the first time that they
occur. Then, in the remaining parts of the text, you use their related approved
abbreviations.

```typescript
// STE-Code: abbreviation defined on first use, then reused
// The Main Form Validation Module (MFVM) is a TypeScript module that
// includes a Main Export Controller Unit (MECU) and a Data Bridge (DB).
interface FormPayload { fields: Record<string, unknown>; }

class MainFormValidationModule {       // MFVM
  constructor(
    private readonly exportController: MainExportControllerUnit,  // MECU
    private readonly bridge: DataBridge,                          // DB
    private readonly config: DynamicConfigUnit,                  // DECU
  ) {}

  submit(payload: FormPayload): void {
    this.config.onEvent("submit", () => this.exportController.run(payload));
  }
}
```

If an approved technical code noun includes three words or less, it is not
necessary to use abbreviations.

You can use abbreviations that come from your official code documentation but
be careful. A text full of abbreviations in a procedure, although shorter, is
not easy to read.

```yaml
# STE-Code: name each part in full; do not pack the parts into letter codes
controller:
  data_transformer_assembly:   # (8)  part of the view body
  pipeline_validator_assembly: # (15) sits on its seat
  buffer_assembly:             # (17) part of the view body

# Non-STE (do not write this):
#   parts: [DTA_8, PVA_15, BA_17, VB_20]
```

### Method 2 — Use prepositions to break up a long noun

When a long technical code noun is a chain of short nouns (for example "user
authentication token refresh failure retry policy"), it is hard to read and
easy to parse the wrong way. Make the main noun the head of the sentence, then
add the rest with prepositions. Put the key noun first, then attach the
modifiers with "of," "on," "in," "for," or "to." This keeps each part short
while the full idea stays clear.

| Non-STE | STE |
|---|---|
| Configure the user authentication token refresh failure retry policy before you deploy the service to production. | Configure the retry policy for the failure of the refresh of the user authentication token before you deploy the service to production. |
| Install the background worker queue overflow alert suppression rule on the staging cluster. | Install the alert suppression rule on the overflow of the background worker queue on the staging cluster. |
| Remove the database connection pool exhaustion recovery timeout configuration parameter from the settings file. | Remove the configuration parameter that sets the recovery timeout for the exhaustion of the database connection pool from the settings file. |
| Update the build script to obtain output directory naming consistency with the package convention. | Update the build script until the output directory naming is consistent with the package convention. |

```python
# STE-Code: the short noun keeps the function name and the docstring clear
def set_recovery_timeout(pool, seconds: float) -> None:
    """Set the configuration parameter that sets the recovery timeout
    for the exhaustion of the database connection pool."""
    pool.config["recovery_timeout_seconds"] = seconds
```

### Method 3 — Hyphenate words that you use as one unit

When two or more words act as a single modifier before a noun, use a hyphen (-)
to show that they are one unit. This stops the reader from grouping the words
the wrong way. In code prose, hyphenate compound modifiers such as
"request-response," "read-write," "build-time," "out-of-band," "end-to-end,"
and "run-time." Do not hyphenate the modifier when the first word is an adverb
that ends in "-ly" (for example "a publicly documented API" stays open).

| Non-STE | STE |
|---|---|
| Set the request response mapping handler to the new schema before the migration. | Set the request-response mapping handler to the new schema before the migration. |
| Run the build time configuration check after you compile the module. | Run the build-time configuration check after you compile the module. |
| Add an end to end test for the payment flow before you merge the change. | Add an end-to-end test for the payment flow before you merge the change. |
| Use the out of band signal to stop the long running job. | Use the out-of-band signal to stop the long-running job. |

```python
# STE-Code: hyphenated modifiers are one unit in code identifiers too
def handle_request_response(handler: "RequestResponseMappingHandler") -> None:
    """Set the request-response mapping handler to the new schema."""
    handler.apply(schema=SCHEMA_V2)

def run_build_time_check() -> None:
    """Run the build-time configuration check after you compile the module."""
    ...
```

Note: Hyphenation groups words into one unit but does not make a long technical
noun short. If the hyphenated unit still has more than three words (for example
"request-response mapping handler"), write it in full the first time, then use
the shorter form ("mapping handler") in the rest of the text.

### How to apply the rule in code documentation

1. Find the long technical code noun (more than three words) in your sentence.
2. Write it in full the first time it occurs. If it comes from an official
   source (API spec, schema, architecture diagram), keep the exact approved
   form.
3. Give a shorter form or an approved abbreviation right after the full form, in
   parentheses.
4. In the rest of the document, use only the shorter form or the approved
   abbreviation.
5. If the noun is a chain of short nouns, split it with prepositions so each
   part is short (see Rule 2.1).
6. If two or more words act as one modifier, hyphenate them.
7. Do not fill a procedure with abbreviations. A short, clear noun is better
   than a string of letters.

> **Microsoft / Google style note:** Use short, plain words. Do not use
> `utilize`, `leverage`, or `employ` when `use` is enough. Do not use
> `commence`, `initiate`, or `terminate` when `start` and `stop` are enough.
> Keep the verb simple and the noun short.

> **See also:** Rule 2.1 (keep technical nouns to three words or fewer), Rule
> 1.5 (technical noun categories), Rule 1.3 (use approved words: use, set, get,
> make, show, check, remove, send, start, stop).

---

## Rule 2.3 — Use hyphens between words used as one unit

A hyphen is a punctuation mark that connects words or parts of words. Use
hyphens between words to show how related words operate as one unit. This
method will make the multi-word code nouns that you use agree with rule 2.1.
Hyphenated words always count as one word, so a hyphenated code noun fills only
one of the three-word slots that rule 2.1 allows for a noun phrase.

Do not connect words that are not related, because the hyphen will change the
meaning of the multi-word code noun. If you are not sure, only explain the
multi-word code noun in the clearest way. Then, use a shorter form, an approved
verb such as `get`, `set`, `make`, `start`, or an official approved
abbreviation from your glossary.

If an approved technical code noun includes hyphens — for example
`input-output stream`, `thread-safe queue`, or `backward-compatible API` — do
not change it. If it is too long, write it in full the first time it occurs and
then use the recommended method for shorter technical nouns that this rule
specifies.

Do not use hyphens to make groups of more than three words. If you hyphenate
all the words, this multi-word code noun will not be easy to read and
understand. Keep the hyphen group to at most three words; split longer chains
with prepositions such as `of`, `on`, or `in`.

### Examples in STE-Code

| Example | Note |
|---|---|
| Make sure that the fail-safe shutdown-handler connection is safe. | (3 words: make / sure / connection) |
| Inspection of the request rate-limit device. | (3 words: inspection / of / device) |
| The thread-safe queue keeps the order of the write operations. | (3 words: queue / keeps / order) |
| Remove the backward-compatible API client before you make the change. | (3 words) |

When a hyphen joins two related words, the pair counts as one unit. Apply this
in procedural and descriptive code documentation so that the reader can parse
the noun without re-reading it.

#### Full example — hyphenate related words, keep to three words

A README step that names a combined component must keep the three-word limit of
rule 2.1. Hyphenate only the related pair; do not chain every word.

> **Non-STE:** Move the `main-feature-flag-rollback-handler` trigger to start
> the test run. (2 words, but not correct — four words joined as one unit)
>
> **STE:** Move the `main-feature-flag` rollback-handler trigger to start the
> test run. (3 words: move / trigger / run)

```bash
# STE-Code compliant: the hyphen joins the related pair only
make test trigger=rollback-handler flag=main-feature-flag
```

```python
# STE: the multi-word noun is "main-feature-flag" (1 unit) + "rollback-handler"
# (1 unit) + "trigger" (1 unit)
def move_trigger(main_feature_flag: str, rollback_handler: str) -> None:
    """Move the main-feature-flag rollback-handler trigger to start the test run."""
    trigger = f"{main_feature_flag}:{rollback_handler}"
    start_test_run(trigger)
```

#### Full example — do not hyphenate a three-word approved technical noun

When the official name of a component is three words or less, leave the spaces.
Hyphenating it changes the count and can confuse the reader.

> **Non-STE:** A. Remove the `data-adapter` assembly (8) from the view body
> (20). B. Remove the `pipeline-validator` assembly (15) from its seat.
>
> **STE:** A. Remove the `data adapter` assembly (8) from the view body (20).
> B. Remove the `pipeline validator` assembly (15) from its seat.

```python
# STE: "data adapter" and "pipeline validator" are each a 2-word technical
# noun, not hyphenated
def remove_assembly(name: str, part_id: int) -> None:
    """Remove the data adapter assembly (part_id) from the view body."""
    detach(name, part_id)
    log(f"removed {name} assembly {part_id}")

remove_assembly("data adapter", 8)
remove_assembly("pipeline validator", 15)
```

#### Full example — keep a hyphen that the official name already has

If your official code documentation or an approved standard already hyphenates
a technical noun, keep the hyphen. Removing it changes the term.

> **Non-STE:** Do not write: The `input output stream` is part of the logging
> system.
>
> **STE:** WRITE: The `input-output stream` is part of the logging system.

```python
# STE: "input-output stream" keeps its hyphen because the standard defines it
# that way
class LoggingSystem:
    def __init__(self, stream: "InputOutputStream") -> None:
        # The input-output stream is part of the logging system.
        self.stream = stream

    def write(self, message: str) -> None:
        self.stream.push(message)
```

```yaml
# STE-Code config excerpt
logging:
  # The input-output stream is part of the logging system.
  input-output-stream:
    buffer-size: 4096
    flush-on-error: true
```

> **See also:** Rule 2.1 (write nouns as nouns and keep noun phrases to three
> words), Rule 1.5 (where hyphenated code terms such as `thread-safe queue` and
> `backward-compatible API` are defined), Rule 2.2 (use approved verbs and keep
> sentences short).

---

## Quick reference for LLMs

When you write or review code documentation, enforce these grammar checks in
order:

1. **Noun length** — Every technical noun phrase has at most three words.
   Split longer chains with prepositions (`of`, `on`, `in`, `for`, `to`).
2. **Long nouns** — A noun longer than three words is written in full on first
   use, then referred to by a short form or approved abbreviation defined in
   parentheses on first use.
3. **Hyphens** — Hyphenate only a related pair or triple used as one modifier
   before a noun (`request-response`, `build-time`, `end-to-end`). Never
   hyphenate a chain of more than three words; never hyphenate a 3-word
   approved technical noun (`data adapter`, not `data-adapter`).
4. **Verbs** — Pair technical nouns with short approved verbs: `set`, `get`,
   `make`, `show`, `check`, `remove`, `send`, `start`, `stop`, `use`,
   `update`. Avoid inflated verbs (`utilize`, `leverage`, `commence`,
   `initiate`, `terminate`).
5. **Abbreviations** — An abbreviation is allowed only when it is defined in
   official documentation on first use and reused consistently. Do not fill a
   procedure with abbreviation strings.

These three rules (2.1–2.3) plus the word rules (1.1–1.14) are the grammar
core of STE-Code for code documentation.



## 06-extensions.md

# Level 4 — Extensions & Reference Catalogue

This slice is the machine-readable extension catalogue that sits on top of the
core STE-Code rules (Levels 1–3). It lists the approved vocabulary, adjectives,
domain terms, component names, and a catalogue of documented anti-patterns that
violate the STE principles (P1–P9).

Use this file when you generate code documentation with an LLM: instruct the
model to (1) use only the approved verbs listed here, (2) prefer the approved
adjectives and domain terms, and (3) avoid every anti-pattern in the catalogue.
Each entry shows a short definition, an STE-conformant code example, and the
non-STE wording it replaces.

Scope of this slice:
- Approved verbs and their rejected synonyms
- Code-domain adjectives (approved modifiers)
- Domain terms (field-specific vocabulary)
- Approved component and data-structure nouns
- Verb usage examples (how the approved verbs apply in context)
- Anti-pattern catalogue (non-STE → STE rewrites)

## Approved verbs

Use the approved verb. Reject the listed synonyms — they are jargon or longer
words that add no technical precision.

| Verb | Replaces (rejected) | Definition | STE example |
|------|---------------------|------------|-------------|
| use | utilize, leverage, employ | Apply an existing function, library, or component without modifying it | Use the logger to record the request identifier before you return the response. |
| start | initiate, commence, bootstrap | Begin execution of a process, service, or background task | Start the worker process before the test suite connects to the message queue. |
| stop | terminate, halt, kill | End execution of a running process in a controlled manner | Stop the server before you change the configuration file and restart the service. |
| show | display, render, present | Make a value, status, or result visible to the user | Show the total request count on the dashboard after each successful batch completes. |
| make | create, generate, produce | Build or construct a new object, file, or data structure | Make a backup copy of the database before you run the migration script. |
| get | retrieve, fetch, obtain | Read or obtain a value, record, or resource from a store | Get the user profile from the cache before you render the account page. |
| set | configure, assign, establish | Assign a specific value to a variable, field, or option | Set the timeout to thirty seconds before you open the network connection. |
| check | verify, validate, ensure | Examine a condition to confirm it matches the expected result | Check that the response status is 200 before you parse the JSON body. |
| do | perform, execute, carry out | Run a defined operation as part of a larger flow | Do the cleanup step after the test finishes to remove the temporary files. |
| send | transmit, dispatch, forward | Transfer a message, request, or event to another component | Send the alert to the notification service when the job fails three times. |
| remove | delete, eliminate, purge | Take out a file, record, or component so it is no longer present | Remove the stale cache entry after the TTL expires to free memory. |
| keep | retain, preserve, maintain | Continue to hold a value or resource in its current state | Keep the connection open until all buffered messages have been written to disk. |
| add | append, insert, include | Put an extra element into a collection or configuration | Add the new middleware to the request pipeline before you deploy the service. |
| change | modify, alter, update | Make a controlled modification without replacing the whole item | Change the log level to debug before you reproduce the intermittent failure. |
| write | persist, save, store | Put data into a file, database, or output stream | Write the parsed metrics to the output file before the process exits. |
| read | load, parse, ingest | Obtain data from a file, stream, or input source | Read the configuration from the environment file at startup and apply the values. |
| connect | attach, link, associate | Establish a communication channel between two components | Connect the client to the database before the application starts to serve traffic. |
| close | shut, release, disconnect | End an open connection, file handle, or stream | Close the file handle after the last record is written to prevent data loss. |

Rejected synonyms (do NOT use): **utilize** and **leverage** are rejected spellings
of `use`. Both add length without meaning. Always rewrite to `use`.

## Code-domain adjectives

Preferred modifiers. Keep each adjective attached to the short noun it modifies
(write `the idempotent retry policy`, not `idempotentretrypolicy`).

| Adjective | Definition | STE example |
|-----------|------------|-------------|
| idempotent | An operation that produces the same result when applied more than once, with no extra side effects after the first run | Make the retry handler idempotent so a second call with the same input does not duplicate the record. |
| immutable | A data structure or value that cannot change after creation, preventing shared-state bugs | Keep the request context immutable so concurrent threads cannot overwrite each other's values during a single operation. |
| atomic | An operation that completes fully or not at all, with no partial result visible to other processes | Wrap the balance update in an atomic transaction so the debit and credit always succeed or fail together. |
| thread-safe | Code that works correctly when accessed by multiple threads at the same time without external locking | Mark the singleton constructor thread-safe so two threads can call it on first use without creating two instances. |
| asynchronous | A call or task that starts and returns before its work finishes, so the caller can do other work meanwhile | Make the file upload asynchronous so the user interface stays responsive while the transfer runs in the background. |
| concurrent | Tasks that make progress within the same time period, interleaved by the scheduler rather than strictly sequentially | Run the test suites in concurrent processes so the full check finishes in a fraction of the single-threaded time. |
| deterministic | A function whose output depends only on its inputs, with no hidden state or time-based variation | Keep the hash function deterministic so the same key always maps to the same bucket across restarts. |
| deprecated | An API or feature that still works but that maintainers plan to remove, so avoid new use | Mark the old login endpoint deprecated and show a warning that points to the new token-based method. |
| nullable | A field or variable that can hold a null value to indicate the absence of a meaningful value | Make the middle-name field nullable so the profile save does not fail when the value is absent. |
| serializable | An object that can be converted to a byte stream and rebuilt elsewhere without losing its data | Make the session object serializable so the cache layer can store it and restore it on the next request. |
| stateless | A service that keeps no client data between requests, making horizontal scaling simpler and safer | Build the authentication proxy stateless so any node can answer a request without shared session memory. |
| backward-compatible | A change that older clients can still use without modification because the old interface still works | Keep the API response backward-compatible so existing mobile apps keep working after the schema update. |
| read-only | A resource or mode that permits inspection but forbids any write, update, or delete | Open the database handle read-only during reports so the query tool cannot change production data by mistake. |
| recursive | A function that calls itself with a smaller part of the problem until it reaches a base case | Write the directory walker recursive so it visits every nested folder without a manual loop stack. |
| monotonic | A counter or clock that only increases and never goes backward, making ordering safe | Use a monotonic sequence for the event id so replays never create a lower number than a prior record. |
| transitive | A permission or relation that flows through a chain, so a grant to a group reaches its members | Make the role grant transitive so a user in a child team inherits the parent team's read access automatically. |
| volatile | A memory value that another thread or device can change at any time, so the compiler must reload it | Declare the status flag volatile so the loop reads the hardware register again instead of using a cached copy. |
| hierarchical | Data or permissions arranged in parent-child levels where a child inherits settings from its ancestor | Store the configuration in a hierarchical map so a child setting overrides only the matching branch of the tree. |
| normalized | A database schema arranged to remove redundant data and reduce update anomalies across tables | Keep the user table normalized so the address lives in one row and every order references it by id. |
| incremental | A build or update that processes only the changed parts instead of recomputing the whole result | Run an incremental compile so the tool rebuilds only the modules whose source changed since the last run. |

## Domain terms

Field-specific vocabulary. Use the term; the "replaces" column lists the vague or
informal wording it should displace.

| Term | Domain | Definition | Replaces |
|------|--------|------------|----------|
| orchestrator | containerization | A control plane that schedules, deploys, and manages containerized workloads across a cluster | scheduler, cluster manager, container manager |
| subnet | networking | A logical partition of an IP network that groups addresses so routers can forward traffic between isolated segments | network slice, IP range, address block |
| mock | testing | A test double that simulates a dependency and verifies the code under test calls it as expected | stub, fake, dummy object |
| telemetry | observability | Automated collection and transmission of metrics, traces, and logs to a central analysis backend | instrumentation data, system signals, monitoring output |
| pipeline | CI/CD | An automated sequence of build, test, and deploy stages that moves a change from commit to production | build chain, workflow, job stream |
| index | database | A secondary structure that maps column values to row locations so queries avoid full table scans | lookup table, secondary structure, access path |
| authentication | security | Verifying the identity of a user, service, or device before granting access to protected resources | auth, login check, identity confirmation |
| idempotency | distributed systems | A property of an operation that produces the same final result whether it runs once or multiple times with the same input | repeat safety, retry proof, safe re-execution |
| autoscaling | cloud | A mechanism that automatically increases or decreases running instances in response to measured load or schedule | elastic resize, self-adjust, dynamic capacity |
| hydration | frontend | The process where a browser attaches event handlers and interactive state to server-rendered HTML | client boot, attach behavior, re-render bind |
| rebase | version control | An operation that moves a branch's commits onto the tip of another branch so history stays linear | transplant, replay commits, restack |
| eviction | caching | The policy by which a cache removes entries when it reaches its size limit or entries exceed their TTL | purge rule, drop policy, clearance |
| broker | message queue | A middleware server that receives messages from producers and routes them to consumers while buffering during outages | message hub, relay, dispatcher |
| pagination | API design | A response strategy that splits a large collection into numbered or cursor-based pages for bounded, predictable fetches | paged results, chunking, windowing |
| latency | performance | The elapsed time between a system receiving a request and returning the first or last byte of the response | response delay, wait time, lag |
| rollout | deployment | The controlled procedure that releases a new version to production, often in stages, so failures affect only part of traffic | push, ship, go-live |
| structured log | logging | A log entry emitted as machine-readable key-value fields instead of free text so systems can parse and aggregate it | plain log, text log, raw print |
| race condition | concurrency | A defect where two or more concurrent operations access shared state without synchronization and the result depends on execution order | timing bug, collision, concurrent fault |
| cipher | encryption | An algorithm that transforms plaintext into ciphertext and back using a key so only key holders can read the data | crypto scheme, codec, scrambler |
| alert | monitoring | A notification fired when a metric crosses a defined threshold so an operator can investigate or a runbook can trigger remediation | warning, trigger, notification event |

## Approved component and data-structure nouns

Component and data-structure names to use in code documentation. Each replaces a
vaguer description.

| Noun | Definition | Replaces | STE example |
|------|------------|----------|-------------|
| AuthenticationService | A service that verifies user credentials and issues access tokens for protected API endpoints | login handler, auth component, credential service | Use the AuthenticationService to verify the user token before each protected request reaches the handler. |
| CacheManager | A component that controls cached-data lifecycle and removes entries when they exceed their TTL | cache store, memoization layer, buffer manager | Use the CacheManager to store the compiled template and reuse it on the next page load. |
| Logger | A component that records application events with a severity level to a configurable destination | log writer, event recorder, trace emitter | Use the Logger to record the request duration after the handler finishes the operation. |
| RateLimiter | A component that constrains requests a client can send in a fixed window to protect the service | throttle controller, request governor, flow regulator | Use the RateLimiter to stop a single client from sending more than one hundred requests per minute. |
| HttpClient | A component that sends HTTP requests to a remote server and returns the response with status code and body | request sender, web caller, rest client | Use the HttpClient to send the user data to the registration endpoint and read the response code. |
| Result<T, E> | A generic sum type that represents either a successful value of type T or an error of type E | either type, outcome wrapper, try result | Use a Result<T, E> to show the outcome of the parse operation without throwing an exception. |
| ConfigMap | A data structure that stores key-value application settings read at startup | settings object, configuration holder, option store | Use the ConfigMap to store the database address and read it when the service starts. |
| TreeNode | A data structure that holds a value and references to child nodes forming a hierarchical tree | node element, tree item, hierarchy unit | Use a TreeNode to store each directory and attach its children when you build the file tree. |
| Payload | The data carried by a network message or function call, separate from headers and routing metadata | data bundle, message body, request content | Use the Payload to send the order details and keep the headers small for faster transmission. |
| ConnectionPool | A data structure that keeps open database connections ready for reuse to reduce overhead | socket group, session store, connection cache | Use the ConnectionPool to get a database connection and return it after the query finishes. |
| BuildPipeline | A sequence of automated steps that compile, test, and package source into a deployable artifact on each commit | compile flow, build chain, assembly process | Use the BuildPipeline to run the unit tests and stop the release when a test fails. |
| MigrationScript | A script that applies a controlled schema change and records the version in a tracking table | schema update, database patch, version step | Use the MigrationScript to add the new column and check the schema version before you deploy. |
| DeployStep | A single automated action in a deployment plan that moves a build to a target environment and reports status | rollout action, release task, push operation | Use the DeployStep to start the service on the staging host and check the health endpoint. |
| IdleState | A condition in which a component performs no work and waits for an external signal to become active | inactive mode, standby condition, dormant status | Use the IdleState to show that the worker has finished its tasks and waits for new work. |
| ErrorState | A condition in which a component has a fault and cannot process requests until it recovers or resets | failure mode, fault condition, broken status | Use the ErrorState to show the user that the upload failed and how to retry the operation. |
| Middleware | A reusable component that sits between the request and the handler to modify, inspect, or block the request | request filter, interceptor piece, pipeline part | Use the Middleware to check the request header and stop unauthorized calls before they reach the handler. |
| Plugin | A separable component that adds optional behavior to a host application without changing its core source | add-on module, extension part, optional unit | Use the Plugin to add the export feature and keep the core application small and stable. |
| Timeout | A duration that specifies the maximum time a component waits for an operation before it aborts | wait limit, expiry period, deadline value | Use the Timeout to stop the request when the server does not answer within five seconds. |
| AvailabilityZone | An isolated location within a cloud region with independent power, cooling, and network for fault tolerance | data region, server location, host area | Use the AvailabilityZone to place the replica so the failure of one zone does not stop the service. |
| LoggingSystem | A subsystem that collects, formats, and routes log records from many components to files, metrics, or dashboards | trace framework, log facility, record subsystem | Use the LoggingSystem to record the startup event and send the warning to the operations dashboard. |

## Verb usage examples

Concrete applications of the approved verbs in context. Each shows the STE
wording next to the non-STE wording it replaces.

| Pattern | Approved verb | STE example | Non-STE (rejected) |
|---------|---------------|-------------|--------------------|
| use-service-client | use | Use the client object to send requests to the payment gateway. | Utilize the client object to leverage the payment gateway for request transmission. |
| start-worker-process | start | Start the worker process before you run the migration job. | Initiate the worker process and commence the migration job execution. |
| stop-background-scheduler | stop | Stop the background scheduler before you restart the host. | Terminate the background scheduler and halt the host restart sequence. |
| show-configuration-table | show | The command shows the current configuration values as a table. | The command displays and renders the current configuration values as a presentable table. |
| make-connection | make | The factory function makes a new connection from the supplied parameters. | The factory function creates and generates a new connection from the supplied parameters. |
| get-user-record | get | Get the user record from the cache with the supplied identifier. | Retrieve and fetch the user record from the cache with the obtained identifier. |
| set-timeout-value | set | Set the timeout value to 30 seconds before you open the connection. | Configure and assign the timeout value to 30 seconds before you establish the connection. |
| check-response-status | check | Check that the response status is 200 before you parse the body. | Verify and validate that the response status is 200 before you ensure body parsing. |
| do-build-step | do | Do the build step before you deploy the application to staging. | Perform and execute the build step before you deploy the application to staging. |
| send-queue-message | send | The producer sends a message to the queue when the job finishes. | The producer transmits and dispatches a message to the queue when the job finishes. |
| remove-session-token | remove | Remove the expired session token from the store after the user logs out. | Delete and purge the expired session token from the store after the user logs out. |
| keep-lock | keep | Keep the lock for the shortest time that the critical section needs. | Retain and preserve the lock for the shortest time that the critical section requires. |
| add-middleware | add | Add the new middleware to the pipeline before you start the server. | Create the new middleware and configure it into the pipeline before you initiate the server. |
| put-uploaded-file | put | Put the uploaded file in the temporary directory until the scan completes. | Store the uploaded file in the temporary directory and retain it until the scan completes. |
| open-socket | open | Open the socket and read the response until the server closes it. | Establish the socket and read the response until the server closes it. |
| close-file-handle | close | Close the file handle after the write operation finishes. | Terminate the file handle after the write operation finishes. |
| change-log-level | change | Change the log level to debug before you reproduce the failure. | Configure the log level to debug before you reproduce the failure. |
| give-result-object | give | The method gives a result object that contains the parsed response. | The method returns a result object and utilizes the parsed response internally. |
| go-settings-page | go | Go to the settings page and select the export option. | Proceed to the settings page and leverage the export option. |

## Anti-pattern catalogue

Documented non-STE patterns with their STE rewrites. `violates` lists the STE
principles broken (P1 = approved words, P2 = present tense, P3 = active voice,
P4 = short sentences, P5 = unambiguous reference, P8 = define terms). Each entry
shows non-STE (rejected) → STE (required).

| ID | Pattern | Severity | Non-STE | STE |
|----|---------|----------|---------|-----|
| AP-001 | Future tense in procedural instructions | error | The system will send a confirmation email after the registration process completes successfully. | The system sends a confirmation email after registration completes. |
| AP-002 | Undefined acronym in error message | blocking | Error: DAG execution failed at T2. | Error: The scheduled workflow (DAG) failed at step T2. Open the dashboard to see the step log. |
| AP-003 | Passive voice obscures the actor | blocking | The configuration file is read by the service at startup and is validated before the connection is established. | The service reads the configuration file at startup. The service validates the file before it establishes the connection. |
| AP-004 | Nominalization instead of a direct verb | error | Perform the installation of the package and execute the initialization of the database before you commence the server. | Install the package and initialize the database before you start the server. |
| AP-005 | Avoided synonym "utilize" for "use" | error | Utilize the cache layer to reduce database load during peak traffic periods. | Use the cache layer to reduce database load during peak traffic. |
| AP-006 | Overlong sentence with nested clauses | warning | When the user submits the form which contains invalid data the application will display an error message and it will also log the failure so that the team can investigate the root cause later. | When the user submits a form with invalid data, the application shows an error message. The application also logs the failure so the team can investigate. |
| AP-007 | Contraction in procedural documentation | error | Don't close the socket until the response isn't fully received. | Do not close the socket until the response is fully received. |
| AP-008 | Jargon without definition | error | The ingress controller reconciles the desired state with the cluster and emits events on drift. | The ingress controller matches the cluster state to the configuration that you specify. It reports an event when the states differ. |
| AP-009 | Semicolon joining two independent instructions | error | Open the settings file; then change the port value to 8080. | Open the settings file. Change the port value to 8080. |
| AP-010 | Avoided synonym "leverage" for "use" | error | Leverage the retry queue to handle transient failures without dropping requests. | Use the retry queue to handle transient failures without dropping requests. |
| AP-011 | Ambiguous pronoun reference | warning | The client calls the server and it returns the token, then it validates it before it stores it in memory. | The client calls the server. The server returns the token. The client validates the token and then stores it in memory. |
| AP-012 | Avoided synonym "commence" for "start" | error | Commence the build pipeline after the tests pass in the staging environment. | Start the build pipeline after the tests pass in the staging environment. |
| AP-013 | Avoided synonym "terminate" for "stop" | error | Terminate the background worker before you release the database connection to prevent locks. | Stop the background worker before you release the database connection to prevent locks. |
| AP-014 | Contradictory instructions in the same section | blocking | Always enable caching for the reports endpoint. Never enable caching for the reports endpoint because it returns user-specific data. | Enable caching for the reports endpoint only when the response is identical for all users. Do not enable caching when the response contains user-specific data. |
| AP-015 | Regional spelling inconsistency | error | Customise the serialise function to normalise the colour values before you initialise the widget. | Customize the serialize function to normalize the color values before you initialize the widget. |
| AP-016 | Slang and informal phrasing | error | Just spin up a quick instance and hack the config until the thing stops crashing. | Start an instance and edit the configuration until the application stops crashing. |
| AP-017 | Undefined technical term in README | error | The handler emits a webhook to the broker on each mutation event. | The handler sends an HTTP request to the message broker on each data change event. The broker distributes the request to subscribers. |
| AP-018 | Weak style — verbose phrasing | info | In order to be able to make use of the new logging feature it is necessary to carry out an update of the agent to the most recent version. | To use the new logging feature, update the agent to the latest version. |
| AP-019 | Synonym for an approved term | info | The module obtains the credentials and subsequently dispatches the request to the upstream service. | The module gets the credentials and then sends the request to the upstream service. |
| AP-020 | Avoided synonym "employ" with nominalization | error | Employ the prepared statement to effect the retrieval of rows from the table in a safe manner. | Use the prepared statement to get rows from the table safely. |

### Quick reference for LLM prompting

- Always use approved verbs (use, start, stop, show, make, get, set, check, do,
  send, remove, keep, add, change, write, read, connect, close). Never use
  utilize, leverage, employ, initiate, commence, terminate, perform, execute.
- Write in present tense for procedural steps; never future tense (AP-001).
- Use active voice and name the actor (AP-003).
- Keep one instruction per sentence; never join with semicolons (AP-009).
- Define every acronym and technical term on first use (AP-002, AP-008, AP-017).
- Avoid contractions in procedural documentation (AP-007).
- Pick one regional spelling and stay consistent (AP-015).
- Do not pile synonyms or nominalize verbs (AP-004, AP-018, AP-020).

<!-- APPEND -->



## 07-catalogue.md

# Level 4 — Reference Catalogue

This slice lists the external references that informed the STE-Code controlled
vocabulary: style guides, glossaries, and word lists.

Status of these references:

- They are **not** part of the STE-Code standard. No rule in this standard is
  defined by them, and no entry here overrides a rule in Levels 1–3.
- They are **evidence sources**. When a word, spelling, or term needs a check,
  read the reference instead of guessing.
- Their local copies live in `.agents/reference/`, outside `final/`, per the
  project rule that keeps pipeline material out of the shipped standard.

How an LLM should use this slice:

- Do **not** import vocabulary from a reference directly into generated text.
  Use the approved verbs, adjectives, and domain terms in the extension
  catalogue (slice `06-extensions.md`) instead.
- Use this slice only to answer the question "where did this word come from?"
  or "is this spelling attested?" — that is, for provenance and verification.
- Treat a `pointer` entry as an address only: there is no local copy to read.

## Catalogue

Column meanings:

- **Reference** — the name of the source.
- **Type** — `page` (rendered document captured locally), `raw` (plain text or
  word-list file captured locally), `pointer` (address only, no local copy).
- **Source** — the upstream address; the link target is the local copy under
  `.agents/reference/` when one exists.

| Reference | Type | Source |
|---|---|---|
| Microsoft Writing Style Guide | page | [https://learn.microsoft.com/en-us/style-guide/welcome/](.agents/reference/microsoft-writing-style-guide.md) |
| MicrosoftDocs/microsoft-style-guide (GitHub source) | page | [https://github.com/MicrosoftDocs/microsoft-style-guide](.agents/reference/microsoft-style-guide-github.md) |
| Google Style Guides | page | [https://google.github.io/styleguide/](.agents/reference/google-style-guides.md) |
| Kong/apiglossary | page | [https://github.com/Kong/apiglossary](.agents/reference/kong-apiglossary.md) |
| dwyl/technical-glossary | raw | [https://raw.githubusercontent.com/dwyl/technical-glossary/main/README.md](.agents/reference/dwyl-technical-glossary.txt) |
| jvalentino/glossary | page | [https://github.com/jvalentino/glossary](.agents/reference/jvalentino-glossary.md) |
| GitHub Official Glossary | page | [https://docs.github.com/en/get-started/learning-about-github/github-glossary](.agents/reference/github-official-glossary.md) |
| DevOps Style Guide Glossary | page | [https://tydukes.github.io/coding-style-guide/glossary/](.agents/reference/devops-style-guide-glossary.md) |
| ryanwi software-terms.dic | raw | [https://gist.githubusercontent.com/ryanwi/6135845/raw/software-terms.dic](.agents/reference/ryanwi-software-terms.txt) |
| OpenSTE.org | pointer | [https://openste.org/](https://openste.org/) |
| en-wl/wordlist (SCOWL) | page | [https://github.com/en-wl/wordlist](.agents/reference/en-wl-wordlist.md) |
| MichaelWehar 5000-more-common | raw | [https://raw.githubusercontent.com/MichaelWehar/Public-Domain-Word-Lists/master/5000-more-common.txt](.agents/reference/michaelwehar-5000-common.txt) |
| dwyl/english-words | pointer | — |

## What each reference is good for

| Question | Read this reference |
|---|---|
| Is this sentence style acceptable in product documentation? | Microsoft Writing Style Guide; MicrosoftDocs/microsoft-style-guide |
| Is this code-comment or API-doc convention acceptable? | Google Style Guides |
| What is the accepted meaning of an API term? | Kong/apiglossary; GitHub Official Glossary |
| What is the accepted meaning of a general software term? | dwyl/technical-glossary; jvalentino/glossary |
| What is the accepted meaning of a build, deploy, or operations term? | DevOps Style Guide Glossary |
| Is this software spelling attested? | ryanwi software-terms.dic; en-wl/wordlist (SCOWL) |
| Is this a common English word, safe for a general reader? | MichaelWehar 5000-more-common; dwyl/english-words |
| What does baseline Simplified Technical English do here? | OpenSTE.org |

## Rules for using the catalogue

1. Check the STE-Code rules first. A reference never overrides Levels 1–3.
2. Check the extension catalogue next. If the word is already approved or
   already rejected there, the decision is made.
3. Only then read a reference, and read the local copy in `.agents/reference/`
   when one exists.
4. Record the reference you used when you propose a new approved term. A
   proposal with no reference is an invention and must be rejected.
5. Do not copy a reference's prose into generated documentation. Take the
   meaning, then write it in STE-Code: short sentence, approved verb, one
   instruction per sentence.
6. Where two references disagree, prefer the one closest to the domain of the
   text: style guides for prose, glossaries for terms, word lists for spelling.



## rules-sec1-part1.md

# Level 4 — Section 1 Rules, Part 1 (Words: 1.1–1.4, 1.10–1.14)

This sub-document holds the first part of Section 1 of STE-Code: the rules that
govern **words**. Nine rules are in this part: 1.1, 1.2, 1.3, 1.4, 1.10, 1.11,
1.12, 1.13, and 1.14. Rules 1.5 to 1.9 are in Part 2.

Use this file when you generate, review, or lint code documentation with an LLM.
Each rule below gives:

- the rule statement in one line,
- what the rule permits and forbids,
- the code-domain application per document type,
- paradigm notes where the rule behaves differently,
- worked Non-STE → STE pairs,
- edge cases, and
- the related rules.

Section 1 assumes three gates. A word is allowed when it passes at least one:

1. it is **approved in the controlled terminology** (STE-Code part 2), or
2. it is a **code-domain technical noun** (Rule 1.5, 19 categories), or
3. it is a **code-domain technical verb** (Rule 1.12, 4 categories).

A word that passes no gate must be replaced, or the sentence must be
restructured so that approved words carry the meaning.

Source for all rules in this part: adapted from ASD-STE100 Issue 9, Section 1.

---

## Rule 1.1 — Use approved words, code-domain technical nouns, or code-domain technical verbs

**Rule.** In code documentation, use words that are approved in the project
controlled terminology, or that are code-domain technical nouns, or that are
code-domain technical verbs.

The controlled terminology gives the words most frequently used in code
documentation. You may use a word that is not in the controlled terminology only
when you can put it in a technical-noun category (Rule 1.5) or a technical-verb
category (Rule 1.12). The controlled terminology also lists words that are not
approved, with the approved alternative for each.

Definitions:

- **Code-domain technical noun** — a noun term for a specified concept in
  software development, applicable to a subject field.
- **Code-domain technical verb** — a verb term for a specified operation or
  process in software development, applicable to a subject field.

Keep your technical nouns and technical verbs in a project glossary or
terminology database, and use that glossary as the source of truth.

Canonical examples:

- "run" is an approved verb in the controlled terminology.
- "UserAuthenticator" is a code-domain technical noun.
- "serialize" is a code-domain technical verb.

> **Non-STE:** Execute the script to do the task.
>
> **STE:** Run the script to do the task.

### Application by document type

**README files.** Procedural sections must start each step with an approved
imperative verb: "run" not "execute", "make" not "generate", "set" not
"configure". Descriptive sections must keep adjectives and adverbs to their
approved meanings: "large" not "substantial", "usual" not "conventional",
"correct" not "valid".

> **Non-STE:** To begin utilizing the build toolchain, you must first generate
> the distributable artifact. Then, execute the compiled binary to bootstrap the
> local development service, and utilize the environment variables to configure
> the runtime behavior before you initiate the server.
>
> **STE:** Use the build tool to make the binary. Run the binary to start the
> local service. Use the environment variables to set the runtime behavior of
> the application before you start the server.
>
> *Applied: utilizing → use; generate → make; execute → run; bootstrap → start;
> configure → set; initiate → start.*

**API documentation.** Function names, parameter names, type names, and endpoint
paths are code-domain technical nouns and pass Gate 2. The prose around them must
use approved words: "get" not "retrieve" or "fetch"; "send" not "transmit";
"remove" not "delete" or "purge"; "check" not "validate" or "verify".

> **Non-STE:** `@param {number} timeout` — The duration in milliseconds the
> client shall await a response prior to terminating the connection attempt.
>
> **STE:** `@param {number} timeout` — The time in milliseconds that the client
> waits for a response before it stops the connection.

**Docstrings and inline comments.** Use "do" not "perform", "check" not
"ensure", "make" not "construct". Comment markers `NOTE:`, `WARNING:`, and
`FIXME:` are permitted (approved nouns and code-domain technical nouns).

> **Non-STE:** `"""Performs validation on the input data to ensure it conforms
> to the expected schema."""`
>
> **STE:** `"""Checks the input data against the schema. Gives `True` when the
> data is correct and `False` when the data is not correct."""`

**Commit messages.** The most constrained form. Use the approved imperative
verbs "add", "fix", "remove", "update", "set", "make", "check", "run". Do not
use "implement" (use "add" or "make") or "optimize" (use "make faster" or "make
smaller"). "refactor" is a code-domain technical verb and is permitted under
Rule 1.12.

> **Non-STE:** `feat: implement JWT authentication middleware for API routes`
> / `perf: optimize database query performance in user listing endpoint`
>
> **STE:** `feat: add JWT authentication middleware for API routes`
> / `perf: make the database query faster in the user listing endpoint`

**Error messages.** Use "cannot" not "unable to"; "incorrect" or "not correct"
not "invalid" or "malformed"; "check" not "verify"; "try again" not "retry".

> **Non-STE:** `Error: Unable to establish connection to the database. Please
> verify your credentials and retry.`
>
> **STE:** `Error: Cannot connect to the database. Check your credentials and
> try again.`

### Paradigm notes

**Object-oriented (Java, C++, C#, Python classes).** Class, method, interface,
and design-pattern names are technical nouns (Rules 1.5 and 1.6). In prose: use
"make" not "instantiate" ("constructor" as a noun is permitted); "get" not
"retrieve"; "set" not "assign"; "call" for method invocation; "send" for message
passing; "keep" not "maintain"; "is a" and "has a" for inheritance and
composition.

> **Non-STE:** The UserRepository class is responsible for persisting and
> retrieving User entities. It leverages an ORM to abstract away the underlying
> SQL queries and encapsulates all data-access logic.
>
> **STE:** The UserRepository class keeps User records in the database and gets
> User records from the database. It uses an ORM to hide the SQL queries and
> holds all data-access logic.

**Functional (Haskell, Elixir, Clojure, Rust).** "pure function", "immutable",
"monad", "closure", and "higher-order function" are technical nouns. "fold",
"reduce", "filter", "compose", and "curry" are technical verbs (Rule 1.12).
"apply" and "pure" have both an approved general sense and a technical sense;
both are valid.

> **Non-STE:** This module furnishes a collection of pure utility functions for
> transforming and combining data structures in a declarative fashion.
>
> **STE:** This module gives a set of pure utility functions for changing and
> joining data structures.

**Procedural (C, Go, Bash).** Each step starts with an approved imperative verb:
"do", "make", "check", "set", "get", "run", "start", "stop", "send", "remove",
"keep". "allocate" is not approved — use "make" or "get". "free" and
"dereference" are technical verbs. Pointer terms are technical nouns.

> **Non-STE:** Allocate a buffer of the specified size on the heap. The caller
> is responsible for deallocating the buffer when it is no longer needed.
>
> **STE:** Make a buffer of the given size on the heap. The caller must free the
> buffer when the buffer is no longer necessary.

**Declarative (SQL, Terraform, Kubernetes YAML).** SQL keywords are technical
verbs; in code blocks they are quoted text (Rule 1.5, category 10). Terraform
resource types and Kubernetes kinds are technical nouns (category 5).
"provision" is not approved — use "make" or "set up". "orchestrate" is not
approved — use "control" or "manage". "declare" and "describe" are approved.

> **Non-STE:** This module provisions an auto-scaling group with a launch
> template. It orchestrates the deployment of EC2 instances across multiple
> availability zones to ensure high availability.
>
> **STE:** This module makes an auto-scaling group with a launch template. It
> controls the deployment of EC2 instances across many availability zones to
> give high availability.

**Systems (Rust ownership, C memory management).** "own", "borrow", and "move"
are technical verbs in Rust and are permitted even though their Rust meanings
differ from standard English. "dangling pointer" and "undefined behavior" are
compound technical nouns (category 15, defects and errors).

> **Non-STE:** The borrow checker ensures that references do not outlive the
> data they refer to, preventing dangling pointers and use-after-free bugs.
>
> **STE:** The borrow checker makes sure that references do not live longer than
> the data they point to. This prevents dangling pointers and use-after-free
> defects at compile time.

### More worked pairs

| Context | Non-STE | STE | Why |
|---|---|---|---|
| API return value | Returns a promise that resolves to an array of User objects, or rejects with an ApiError. | Gives a Promise that completes with a list of User objects. If the request does not complete, the Promise gives an ApiError. | "resolve"/"reject" replaced with approved "complete" and "gives an error"; split to keep each sentence short. |
| README feature | The application leverages machine learning algorithms to analyze user behavior patterns and generate personalized recommendations in real time. | The application uses machine learning to examine user behavior and make personal recommendations immediately. | leverage → use; analyze → examine; generate → make; personalized → personal; "real time" → "immediately"; redundant nouns removed. |
| Docstring | Validates the provided configuration object against the schema and populates default values for any missing fields. | Checks the given configuration object against the schema and adds default values for all missing fields. | validate → check; provided → given; populate → add; any → all. `ValidationError` stays (technical noun). |
| User-facing error | Unable to process your request at this time. Please verify your input and try again. If the problem persists, contact support. | Cannot process your request now. Check your input and try again. If the problem continues, speak to support. | unable to → cannot; at this time → now; verify → check; persists → continues; contact → speak to. |

### Edge cases

1. **Framework name that is also an unapproved word.** A product or framework
   name is a technical noun, even when the same string is an unapproved common
   word. Keep the name as written by its owner; do not translate it.
2. **Code keyword that conflicts with the rule.** Keywords inside code blocks
   are quoted text and are never rewritten. Only the surrounding prose is
   constrained.
3. **Generated documentation.** Text produced by a generator must still pass
   the three gates; fix it at the template or at the source docstring, not by
   hand-editing generated output.
4. **Technical verb used inside a compound noun.** A compound term such as
   "build step" or "parse tree" is a technical noun, not a verb-as-noun
   violation (see Rule 1.13).
5. **Non-English words and loanwords.** Do not use a loanword when an approved
   English word carries the meaning.

**Related:** Rules 1.2, 1.3, 1.4, 1.5, 1.6, 1.12.

---

## Rule 1.2 — Use approved words only as the specified part of speech

**Rule.** In the controlled terminology, each approved word has one specified
part of speech. Use the word only as that part of speech.

Canonical cases:

- "query" is an approved **noun**, not a verb. Do not write "Query the
  database"; write "Send a query to the database".
- "static" is an approved **adjective**, not a verb. Do not write "Static the
  variable"; write "Make the variable static".
- Some words are approved as more than one part of speech. "call" is an approved
  verb and an approved noun. The position in the sentence shows the function:
  "call the function" (verb), "a function call" (noun).

When you replace a word, check that the replacement does not change the meaning.
If the meaning changes, choose a different word or restructure the sentence.

If a word you want is not in the controlled terminology:

1. Find the word in a standard English dictionary.
2. Find the best synonym that is approved in the controlled terminology.
3. Use the approved word, or build a different sentence from other approved
   words.

### Preferred approved verbs (replacement table)

Choose the shortest approved verb that keeps the meaning. Both the Microsoft
Writing Style Guide and the Google developer documentation style guide warn
against inflated verbs such as "utilize", "leverage", "commence", "terminate",
and "initiate". STE-Code follows the same advice.

| Violating form (do not use) | Part-of-speech error | Approved replacement |
|---|---|---|
| Query the database / Cache the result / Queue the job / Log the error / Index the record | Technical noun used as verb | Send a query / Keep the result in the cache / Put the job in the queue / Write the error in the log / Use the index to find the record |
| Docker the app / Git the change / Kubectl the pod / Terraform the VPC | Tool name used as verb | Use Docker / Save with Git / Use `kubectl` / Use Terraform |
| Secure the endpoint / Empty the buffer / Silent the log | Adjective used as verb | Make the endpoint secure / Make the buffer empty / Make the log silent |
| Static the variable / Ready the worker / Live the connection | Adjective used as verb | Make the variable static / Make the worker ready / Make the connection live |
| Utilize the cache / Leverage the library / Employ the service | Unapproved verb (inflated) | Use the cache / Use the library / Use the service |
| Commence the build / Initiate the transfer / Terminate the process | Unapproved verb (inflated) | Start the build / Start the transfer / Stop the process |
| Orchestrate the services / Facilitate the sync | Unapproved verb | Control the services / Help the sync |

"clear" is approved as both a verb and an adjective, so "Clear the flag" is
allowed. The `make` + adjective pattern applies only to true adjectives such as
"secure" and "empty".

### Worked pairs

> **Non-STE:** Query the database for user records.
>
> **STE:** Send a query to the database for user records.

> **Non-STE (Docker Compose comment):**
> ```yaml
> # This compose file orchestrates three services:
> # - The API server, which endpoints the HTTP traffic
> # - The worker, which queues the background jobs
> # - The database, which stores the persistent data
> ```
>
> **STE:**
> ```yaml
> # This compose file controls three services:
> # - The API server, which handles HTTP traffic at its endpoints
> # - The worker, which puts background jobs in the queue
> # - The database, which keeps the persistent data
> ```

> **Non-STE:** `# Terraform the VPC, then Kubectl the pods into the cluster.`
>
> **STE:** `# Use Terraform to make the VPC. Use `kubectl` to apply the pod
> configuration to the cluster.`

**Related:** Rules 1.1, 1.3, 1.7 (technical nouns as verbs), 1.13 (technical
verbs as nouns).

---

## Rule 1.3 — Use approved words only with their approved meanings

**Rule.** Each approved word has a specified approved meaning, which is often
narrower than its meaning in standard English. Use the word only with that
meaning.

Carried over from the specification without change:

- "follow" means "come after, go after" — use it for the sequence of steps.
- "obey" means "to do what the procedures or instructions tell you" — use it to
  tell the reader to comply.

If you need a meaning the approved word does not have, choose another approved
word or restructure the sentence.

### Decision procedure

Run every approved verb, noun, adjective, and adverb through these four steps
before you publish:

1. **Identify the part of speech** as you actually used it. (Rule 1.2 governs
   this step; Rule 1.3 depends on it, because the part of speech selects the
   meaning.)
2. **Look up the approved meaning** for that part of speech in the controlled
   terminology.
3. **Ask the only question that matters:** does the sentence use the word with
   exactly that meaning? If not, the word fails — even when the word is approved
   and the sentence reads well.
4. **Replace or restructure.** Swap in an approved word whose meaning fits, or
   rewrite so the original word carries its approved meaning.

Worked check:

> **Sentence:** The background worker runs every night.
> **Step 1:** "runs" is a verb.
> **Step 2:** The approved meaning of the verb "run" is "execute a program or
> command".
> **Step 3:** The writer means "operates on a schedule", not "executes a
> program". The meaning does not match.
> **Step 4:** Rewrite as "The background worker operates every night."

This is the difference between documentation that is merely grammatical and
documentation that is unambiguous. A reader who sees "the job runs" assumes
execution; if you meant "the job continues", the documentation is wrong even
though "run" is an approved verb.

### Worked pairs

> **Non-STE:** Follow the configuration steps to set up the server.
>
> **STE:** Obey the configuration steps to set up the server.

> **Non-STE:** Apply the configuration to provision the resources. The plan will
> create three instances and join them to the load balancer.
>
> **STE:** Apply the configuration to make the resources. The plan will create
> three instances and connect them to the load balancer.

> **Non-STE:** Set this flag to "true" to enable debug mode. When enabled, the
> server will dump verbose logs to stdout. Setting this flag impacts performance
> significantly.
>
> **STE:** Set this flag to `true` to turn on debug mode. When debug mode is on,
> the server writes detailed logs to stdout. This setting decreases performance.
> Do not turn on debug mode in production.

> **Non-STE:** We call this pattern the Repository Pattern.
>
> **STE:** We name this pattern the Repository Pattern.
> *("call" is approved with the meaning "invoke", not "give a name to".)*

> **Non-STE:** The middleware serves the cached page to the user and then
> returns.
>
> **STE:** The middleware gives the cached page to the user and then goes back.

**Related:** Rules 1.1, 1.2, 1.4.

---

## Rule 1.4 — Use only the approved forms of verbs and adjectives

**Rule.** The controlled terminology gives each approved verb with its approved
forms, and each approved adjective in its base form with the comparative and
superlative forms where those use "-er"/"-est".

### The four-form model for verbs

Entry format: `COMPILE (v), COMPILES, COMPILED, COMPILED`

| Infinitive / imperative | Simple present | Simple past | Past participle (also adjective) |
|---|---|---|---|
| (to) compile / compile | compile(s) | compiled | compiled |

1. **Form 1 — infinitive and imperative.** The form used for every procedural
   step.
2. **Form 2 — simple present.** The form used for descriptive statements.
3. **Form 3 — simple past.** Used for events that already happened, mostly in
   changelogs and log output.
4. **Form 4 — past participle.** Used as an adjective and in the passive voice.
   For regular verbs it is identical to Form 3; the terminology lists it twice
   so the writer knows both uses are approved. Irregular verbs differ ("give" →
   "given" vs. "gave"; "run" → "run" vs. "ran").

Forms that are **not** in the model: the "-ing" form, the future with "will",
the conditional with "would", and any invented inflection ("compilating",
"compilates").

### The "-ing" restriction

The "-ing" form is the most frequent violation of Rule 1.4 in code
documentation, because it can be a continuous main verb ("the server is
running"), a gerund ("the running of the server"), or a participial adjective
("the running server"). The reader cannot always tell which.

In STE-Code the "-ing" form is permitted only when it is a code-domain technical
noun ("logging", "caching", "routing", "debugging") or part of a compound
technical term. It is never a main verb. The continuous aspect adds no
information: "the server runs" and "the server is running" describe the same
state, and the simple present is shorter.

> **Non-STE:** The operator is removing the panel. / The build is compiling the
> source files.
>
> **STE:** The operator removes the panel. / The build compiles the source
> files.

### The three-form model for adjectives

Entry format: `FAST (adj) (FASTER, FASTEST)`

1. **Base form:** fast, slow, large, small, clear.
2. **Comparative form:** faster, slower, larger, smaller, clearer — compares two
   items.
3. **Superlative form:** fastest, slowest, largest, smallest, clearest —
   identifies the extreme among three or more items.

Adjectives that form the comparative and superlative with "more" and "most" (for
example, "more correct", "most correct") have no listed forms, because "more"
and "most" are themselves approved words and the combination is predictable.

### Morphology of technical nouns and verbs

- **Technical nouns** have no verb forms, so the verb constraints do not apply.
  Compounds follow standard English morphology: "pod" → "pods".
- **Technical verbs** are not listed in the controlled terminology, so their
  forms must be predictable from standard English: "deploy, deploys, deployed,
  deployed". Where the pattern is irregular, the writer must apply the correct
  standard-English form. Rule 1.4 is therefore strictest for approved words and
  looser for technical terms.

### Why the limits help

The four-form model caps a verb at four surface forms and the three-form model
caps an adjective at three. Readers from any language background learn a small,
closed set of shapes, and never meet an invented form.

**Related:** Rules 1.1, 1.2, 1.3, 1.5, 1.7, 1.12, 1.13.

---

## Rule 1.10 — Do not use regional, slang, or jargon words as code-domain technical nouns

**Rule.** Do not use regional, slang, or jargon words as code-domain technical
nouns.

Some technical words are used only inside one community or one language
ecosystem. A reader from a different background or technology stack cannot
understand them. When you select a code-domain technical noun, always use a
well-known word. The same applies to slang and jargon: when only a small number
of persons understand a word, it causes confusion and non-effective
communication.

Code documentation is read by junior developers, by developers from other
language communities, and by non-native English speakers. A word that one
subculture finds clear can be opaque to every other reader.

### Worked pairs

| Kind | Non-STE | STE |
|---|---|---|
| Hacker jargon noun | Remove all the cruft from the legacy module. | Remove all the unnecessary code from the legacy module. |
| Slang verb | The `normalize()` function monkeys with the input data before validation. | The `normalize()` function changes the input data before validation. |
| Concept jargon | Bikeshedding delayed the API design by two weeks. | Unnecessary discussion about small details delayed the API design by two weeks. |
| Metaphor jargon | I spent the morning yak shaving before I could write the test. | I spent the morning completing unrelated prerequisite tasks before I could write the test. |
| Ops metaphor | Keep these nodes as cattle, not pets. | Treat these nodes as disposable resources that you can replace at any time. |

### Three problem categories

**Regional terms.** Words used only in one geographical area, and — in the code
domain — vocabulary from one technology ecosystem. A term common in the Ruby
community ("gem", "rake task") may be unknown to a Python developer. The danger
is that the reader thinks they understand the surface meaning and misses the
technical meaning.

**Slang.** Slang is usually metaphor: "spaghetti code", "brittle tests", "flaky
behavior". The pattern is adjective + noun where the adjective is not literal,
and the metaphor is culture-bound. Replace it with a literal description: "code
with complex control flow", "tests that fail intermittently", "behavior that is
not consistent".

**Jargon.** Technical vocabulary ("polymorphism", "memoization",
"serialization") has a precise, agreed meaning. Jargon ("grok", "cruft",
"bikeshedding") has a fuzzy, community-dependent meaning. Test: can you find the
term in a standard dictionary of computing with the same definition? If not, it
is probably jargon.

**Jargon abbreviations.** "DRY", "KISS", and "YAGNI" encode useful principles
but are not transparent. State the principle directly: "Remove duplicate code"
is clearer than "Apply DRY."

**Temporal jargon.** "modern", "legacy", "cutting-edge", and "state-of-the-art"
have no fixed meaning because time passes. Give the characteristic ("uses
async/await syntax") or the date ("written in 2018") instead.

### Edge cases

1. **Framework name that is also an unapproved word.** Rails, Spring, Django,
   Flask are technical nouns when used as proper nouns. Always capitalize them so
   the reader can tell them apart from the common noun.
2. **Code keyword that conflicts with the rule.** `goto`, `break`, `continue`,
   and `finally` have exact meanings in code. "The function breaks before the
   loop" is ambiguous. Write "the function exits before the loop" for the
   colloquial meaning, and "the function executes a break statement" for the
   keyword meaning.
3. **Generated documentation.** Auto-generated text (OpenAPI output, JSDoc
   stubs, godoc) reflects source code, not authored prose, so relaxed
   application is acceptable. Human-written descriptions inside generated docs
   must obey this rule.
4. **Community-standard abbreviations.** "API", "JSON", "SQL", and "HTML" are
   technical nouns. "AFAICT", "IIRC", and "IMHO" remain jargon — spell them out
   or remove them.
5. **When the jargon is the documented item.** A tool named with a jargon term
   keeps its name (it is a technical noun). The rule constrains the prose around
   the name: "Run ESLint to check your code", not "Run ESLint to lint your junk."

### Review checklist

1. Read the text aloud. Would a developer from another country understand every
   word?
2. Find every metaphor and idiom. Replace it with a literal description.
3. Find every abbreviation. Expand it on first use.
4. Find community nicknames. Replace them with standard terms.
5. Find temporal words ("modern", "legacy", "old"). Replace them with a specific
   date or characteristic.
6. Check every noun and verb against the controlled terminology (Rule 1.1) or
   justify it as a technical noun (Rule 1.5).
7. Confirm no slang verbs describe technical actions. "hit", "nuke", "yeet",
   "tweak", and "twiddle" are not approved.

Professional judgment is still necessary when you decide whether a term is
jargon or a necessary technical noun.

**Related:** Rules 1.1, 1.5, 1.6, 1.11, 1.12, 1.13, 1.14.

---

## Rule 1.11 — Do not use different code-domain technical nouns for the same item

**Rule.** When you select a code-domain technical noun for an item, use that same
noun everywhere in the documentation. Do not use a second noun for the same item.

Changing the name of one item between sections causes confusion: the reader must
work out whether you mean the same item or a different item. **The source of
truth for the noun is the code itself** — the class, function, module, table,
resource, environment variable, or configuration key as it is defined in the
repository.

Rule 1.11 is one of the most frequently violated rules in software
documentation, because projects accumulate names from many sources: class names,
route patterns, file paths, configuration keys, table names, and the colloquial
names developers use in conversation.

### Worked pairs

**Class name.** The repository defines one class, `UserService`.

> **Non-STE:**
> 1. Initialize the UserService class to start the session manager.
> 2. Call the authenticate method on the AccountManager to verify a user.
> 3. The UserHandler returns a session token that you send in later requests.
>
> **STE:**
> 1. Initialize the UserService class to start the session manager.
> 2. Call the authenticate method on the UserService to verify a user.
> 3. The UserService returns a session token that you send in later requests.

**API endpoint.** The OpenAPI file defines the path `/api/login`.

> **Non-STE:**
> 1. Send a request to the /api/login path to get a token.
> 2. The authentication route returns a JSON Web Token that you store in the
>    browser.
> 3. Include the token from the login endpoint in all later requests.
>
> **STE:**
> 1. Send a request to the /api/login endpoint to get a token.
> 2. The /api/login endpoint returns a JSON Web Token that you store in the
>    browser.
> 3. Include the token from the /api/login endpoint in all later requests.

Apply the same discipline to every named item:

| Item type | Source of truth | One name |
|---|---|---|
| Database table | The migration or schema file | `users`, not "the user table" then "the accounts table" |
| Configuration key | `config/database.yaml` | `database.pool_size`, not "pool size setting" then "connection limit" |
| CLI command | The command definition | `mycli sync`, not "the sync command" then "the sync tool" |
| Error type | The class definition | `ValidationError`, not "validation failure" then "schema error" |
| Environment variable | `.env` or the loader | `DATABASE_URL`, not "the DB string" then "the connection URL" |
| Git branch | The branch as pushed | `release/2.1`, not "the release branch" then "the 2.1 line" |

### Edge cases

1. **Framework names that are also unapproved words.** Keep the framework's own
   spelling and capitalization as the single name.
2. **Code keywords that conflict with the canonical noun.** When the canonical
   name collides with a language keyword, keep the code name and mark it as code
   with backticks.
3. **Different canonical names in different contexts.** When the same item has a
   code name and a user-facing name (for example, a class name and a UI label),
   state the mapping once and then use one name per audience consistently.
4. **Generated documentation.** The generator inherits the code names, so the
   fix belongs in the code, not in the generated file.
5. **Renaming during refactoring.** When you rename an item, rename it in every
   document in the same change. Do not leave both names in the corpus.

### Grammar notes

- **Definite article consistency.** Once you name an item, refer to it with the
  same article pattern each time.
- **Anaphora.** Do not replace the canonical noun with a pronoun when more than
  one item is in play; repeat the noun.
- **Compound nouns.** Keep the head noun fixed. "session token" must not become
  "token session" or "auth token" elsewhere.
- **Parallel structure in lists.** Every item in a list must name its subject in
  the same shape.

**Related:** Rules 1.1, 1.5, 1.6, 1.10, and Section 3 (verbs).



## rules-sec1-part2.md

# Level 4 — Section 1: Technical Noun Rules (Rules 1.5–1.9)

This sub-document is the LLM-optimized distillation of STE-Code Section 1 rules that
govern **technical nouns** — the words you may use outside the approved dictionary
because they name a precise code-domain concept. It covers Rules **1.5, 1.6, 1.7, 1.8,
and 1.9**.

Audience: people who use LLMs to generate code documentation and want the model to
obey STE-Code's technical-noun rules. Use this file as a constraint sheet: every
non-approved word in generated documentation must clear the gate described below.

Voice: plain, code-domain. No aerospace leakage. Examples use software terms only.

Cross-links (within the same level-4 artifact set):
- Rule 1.1 — Approved words (the dictionary you default to)
- Rule 1.2 — Part of speech
- Rule 1.3 — Approved meanings
- Rule 1.10 — No slang / jargon
- Rule 1.11 — One term per concept
- Rule 1.12 — Technical verbs allowed
- Rule 1.13 — Do not use technical verbs as nouns
- Rule 1.14 — American English spelling

---

# Rule 1.5 — You Can Use Code-Domain Technical Nouns

**Rule statement:** You may use a word that is not in the approved dictionary if it names
a precise software-development concept that fits one of the **19 code-domain categories**
below. Such a word is a *code-domain technical noun*. Use it only as a noun (or noun
modifier).

**Why it exists:** The approved dictionary cannot list every domain term (there are too
many, and every project uses different ones). Rule 1.5 is the gateway that lets
domain-specific vocabulary into STE-Code documentation without breaking the controlled
terminology.

**Requirements:**
- Register every code-domain technical noun you use in the **project glossary** (term,
  category, approved meaning, example sentence). Unregistered made-up names are not
  permitted (Rule 1.6 forbids them).
- Use an approved word whenever one exists. Use a technical noun only when no approved
  word names the concept.
- Categories are examples, not a closed list.

## The 19 code-domain categories (with example terms)

1. **Code components, modules, libraries** — class, controller, helper, hook, middleware,
   mixin, module, package, plugin, provider, repository, service, utility
2. **Computing devices and components** — CPU, disk, GPU, keyboard, laptop, memory,
   monitor, mouse, printer, screen, server, smartphone, tablet, terminal
3. **Development tools, environments, support equipment** — CLI, compiler, debugger,
   Docker, editor, IDE, Git, Jest, linter, loader, Prettier, terminal, test runner,
   TypeScript, webpack
4. **Data structures, types, formats** — array, boolean, buffer, CSV, enum, hash map,
   integer, JSON, linked list, object, queue, stack, string, struct, tree, tuple, XML, YAML
5. **Infrastructure, deployment, platforms** — AWS, CI/CD, container, deployment, Heroku,
   Kubernetes, load balancer, Node.js, pipeline, pod, production, staging, Vercel
6. **Systems, subsystems, architectural components** — API gateway, authentication layer,
   caching layer, client, database layer, message broker, microservice, proxy, rate
   limiter, REST API, routing layer, server, WebSocket
7. **Mathematical, algorithmic, scientific terms** — Big O notation, binary search,
   coefficient, complexity, exponent, hash function, iteration, logarithm, matrix,
   recursion, regex, sorting algorithm, time complexity, traversal
8. **Interface elements and navigation** — button, checkbox, dialog, dropdown, footer,
   header, menu, modal, navigation bar, radio button, scrollbar, sidebar, tab, text field,
   toggle, tooltip
9. **Numbers, units, time** — byte, GB, Hz, hour (h), KB, MB, ms, minute, ns, second (s), TB
10. **Quoted text** — texts you cannot change: error messages, code snippets, UI labels,
    log output. Example: `Cannot read properties of undefined`, `ENOENT: no such file`,
    `Submit` button, `404 Not Found`, `connection refused`
11. **Professional roles, teams, orgs** — administrator, backend developer, contributor,
    DevOps engineer, frontend developer, Google, maintainer, Microsoft, product owner,
    QA engineer, reviewer, scrum master, user
12. **Official documents, API references, standards** — API reference, changelog, code of
    conduct, contributing guide, diagram, figure, Getting Started guide, HTTP spec, note,
    paragraph, README, release notes, RFC, section, table, warning
13. **Runtime environments and operational conditions** — development, environment
    variable, garbage collection, heap, hot reload, live reload, memory leak, production,
    sandbox, stack trace, staging, test, thread, timeout, virtual machine
14. **Colors** — black, blue, cyan, gray, green, magenta, orange, red, white, yellow.
    Colors are adjectives but count as technical nouns here. Comparative/superlative forms
    (blacker, reddest) are forbidden.
15. **Defects, errors, faults** — assertion failure, bug, crash, deadlock, defect,
    exception, hang, infinite loop, memory leak, null pointer, race condition, regression,
    stack overflow, timeout, type error
16. **Computer science, ICT** — AI, algorithm, authentication, authorization, blockchain,
    containerization, cryptography, database, encoding, encryption, firewall, hashing,
    internet, machine learning, metadata, neural network, protocol, query, sandbox,
    schema, token, virtualization
17. **Legal and licensing** — Apache 2.0, BSD license, compliance, copyright, GPL, license,
    MIT license, open source, proprietary, terms of service, third-party, trademark,
    warranty
18. **Database and storage** — connection pool, cursor, foreign key, index, migration,
    NoSQL, ORM, PostgreSQL, primary key, query, Redis, relation, row, schema, seed, SQL,
    SQLite, stored procedure, table, transaction, view
19. **Network and protocol** — DNS, endpoint, HTTP, HTTPS, IP address, localhost,
    middleware, packet, port, request, response, route, socket, SSH, TCP, TLS, UDP, URL,
    VPN, WebSocket

## Application by documentation type (which categories to reach for)

- **README:** categories 1 (components), 3 (tools), 5 (infra), 17 (legal).
- **API docs:** categories 6 (systems), 18 (database), 19 (network).
- **Docstrings / comments:** categories 4 (types), 7 (algorithms), 15 (defects).
- **Commit messages:** categories 1 (components), 15 (defects), 18 (database).
- **Error messages:** categories 13 (runtime), 15 (defects), 19 (network).
- **Test specs:** categories 1 (components), 4 (types), 15 (defects).

## Grammar notes for technical nouns

- **Articles:** "the" for a specific instance, "a/an" for indefinite, none for plural
  general reference.
- **As modifiers:** a technical noun may modify another to form a compound (e.g.
  `Redis cache server`). Both parts must fit a recognized category.
- **Possessive ('s):** allowed only for category 11 (roles, orgs). Use "of" or
  noun-modifier for others: "the configuration of the Docker container", NOT "the Docker
  container's configuration".
- **Pluralization:** standard rules; acronyms take a lowercase "s" without apostrophe:
  "two APIs", "three SQL queries" (never "API's").
- **Capitalization:** proper nouns (language, company, product names) keep original case;
  common technical nouns are lowercase unless sentence-initial.

## Minimal examples

> Non-STE: The developer used the thing to get data from the storage layer and put it on the screen.
> STE: The frontend developer used the API client to get data from the database and show it on the UI.

> Non-STE: The endpoint leverages the middleware to authenticate the request and then kicks off a background job to crunch the data.
> STE: The endpoint uses the authentication middleware to check the request. The endpoint then starts a background job to process the data.

---

# Rule 1.6 — Use a Non-Approved Word Only as a Code-Domain Technical Noun

**Rule statement:** A word that is not approved in the controlled terminology may appear
only when it is a code-domain technical noun or part of a compound code-domain technical
noun. If it is neither approved (Rule 1.1) nor a technical noun (Rule 1.5), it is
forbidden.

**Why it exists:** Together with Rule 1.5, this forms a gate. An unapproved word must
belong to one of the 19 categories to be legal. Rule 1.5 defines *what qualifies*;
Rule 1.6 enforces *that only qualifying words pass*.

## The three-test decision gate

An unapproved word may stay ONLY if it clears all three tests. Fail any one → replace
with the approved alternative or restructure.

**Test 1 — Is the word unapproved?** Approved words skip this gate. Only unapproved
words enter. (e.g. "function" is approved → not tested; "handler" is unapproved → tested.)

**Test 2 — Is it a technical noun, or part of a compound technical noun?** It must be a
standalone noun in the 19 categories, or embedded in a compound that fits a category.
- "handler" alone → fails (not a recognized technical noun).
- "event handler" → passes (design-pattern term, category 1).
- "main" alone → fails (general adjective).
- "main branch" → passes (Git term, category 5).

**Test 3 — Is it used as a noun in the sentence?** Even a word that passes Test 2 must
function as a noun. If it is a verb/adjective/adverb, it fails (enforced by Rule 1.7).
- "The event handler processes the request." → noun → passes.
- "This class handlers the request." → "handlers" is a verb → fails. Use "processes" or
  "The request handler processes the request."

## Worked trace

> Non-STE: The main config loader backups the data through the handler pipeline.
> STE: The primary config loader makes an auxiliary copy of the data through the processing pipeline.

| Phrase | T1 unapproved? | T2 technical noun? | T3 noun use? | Result |
|---|---|---|---|---|
| main config loader | yes | "main" is a general adjective | — | "main" → "primary" |
| backups | yes | "backup" as verb is not a noun | verb | "makes an auxiliary copy" |
| handler pipeline | yes | not a recognized compound | noun but fails T2 | "processing pipeline" |

## Compound technical noun checklist

A compound counts as a technical noun only if ALL are true:
1. The words combine to name one concept the domain recognizes.
2. The compound fits one of the 19 categories.
3. Replacing the unapproved word with its approved alternative changes the recognized
   name and causes confusion.

Swap test: if you can replace the unapproved word with its approved alternative and the
term still names the same concept, it is NOT a technical noun → make the replacement. If
the swap produces a name no one in the domain would recognize, the compound IS a
technical noun and the unapproved word is permitted inside it.

## Distinction: technical noun vs. descriptive adjective

Criterion: does the compound appear in the official docs of the framework, language, or
standard? If yes → technical noun (permitted). If no → descriptive prose (replace).

- ✅ "Check out the main branch before you merge." (Git convention)
- ❌ "The main configuration has the latest values." → "primary configuration"
- ✅ "The base case returns the single-element array." (algorithmic term)
- ❌ "The base configuration is loaded first." → "primary configuration"
- ✅ "The event handler processes each request." (design-pattern term)
- ❌ "The handler processes each request." → "function"

## Dictionary reference (controlled-terminology entries)

- **BASE (n) — UNAPPROVED.** Alternatives: BOTTOM (surface/stack), ROOT (filesystem top).
  Permitted in compounds: "base case" (cat 7), "base class" (cat 1), "base URL" (cat 8).
- **MAIN (adj) — UNAPPROVED.** Alternative: PRIMARY. Permitted in "main branch" (cat 5)
  and "main function"/`main()` (cat 1, entry-point).
- **HANDLER (n) — UNAPPROVED.** Alternative: FUNCTION. Permitted in "event handler",
  "request handler" (cat 1).
- **BACKUP (n, v) — UNAPPROVED.** Alternatives: AUXILIARY (adj), "makes an auxiliary copy"
  (verb). Permitted in "backup file", `backup_logs` (cat 18), `/api/v1/backup` (cat 19).
- **BOTTOM (n), FUNCTION (n), PRIMARY (adj), AUXILIARY (adj), ROOT (n) — APPROVED.**

## Minimal examples

> Non-STE: The base setup leverages Express for the main API and MongoDB for the database backend. The handler backs up the data every night.
> STE: The primary setup uses Express for the main API and MongoDB for the database backend. The function makes an auxiliary copy of the data each night.

> Non-STE: POST /api/v1/backup — Authenticates the user and backups the records.
> STE: POST /api/v1/backup — Checks the user and makes an auxiliary copy of the records.

---

# Rule 1.7 — Do Not Use Code-Domain Technical Nouns as Verbs

**Rule statement:** Use a code-domain technical noun only as a noun (or as an adjective
inside another technical noun). Do NOT use it as a verb.

**Why it exists:** Verbing a noun loses its precise technical meaning. "Database" is a
specific storage system with ACID properties, schemas, queries. "To database" is unclear
— does it mean store, index, query, or replicate? The reader must guess.

**Core repair pattern:** replace the noun-verb with an approved verb + the noun in a
prepositional phrase. The preposition depends on the relationship:

| Noun-verb (wrong) | STE repair | Verb | Prep |
|---|---|---|---|
| Cache the data | Put the data in the cache | put | in |
| Queue the job | Add the job to the queue | add | to |
| Buffer the output | Write the output to a buffer | write | to |
| Socket the connection | Send the connection through a socket | send | through |
| Database the records | Store the records in the database | store | in |
| Docker the app | Package the app in a container | package | in |
| Git the changes | Commit the changes | commit | (none) |
| JSON the response | Encode the response as JSON | encode | as |

**Double-category exception:** some words are cataloged as BOTH a technical noun (Rule
1.5) and a technical verb (Rule 1.12). You may use them as verbs only in their approved
verb sense, and only if your project glossary lists the verb form. If the glossary lists
the word as a noun only, obey Rule 1.7.

| Word | Noun (Rule 1.5) | Verb (Rule 1.12) |
|---|---|---|
| cache | "The cache stores responses." (cat 16) | "Cache the responses." (cat 2c) |
| log | "Write a log entry." (cat 18) | "Log the error." (cat 2c) |
| queue | "Add the job to the queue." (cat 4) | "Queue the job for processing." (cat 3a) |
| filter | "Apply a filter." (cat 4/16) | "Filter the results." (cat 2b) |
| sort | "Use a merge sort." (cat 7) | "Sort the list by name." (cat 2b) |
| map | "Use a hash map." (cat 4) | "Map the function over the list." (cat 3a) |

RULE: decide the part of speech in your glossary. Do not mix noun and verb uses of the
same word in one paragraph without clear context. When the verb form implies the noun
(e.g. "Filter the results and sort the list"), do not also restate the noun.

## Paradigm-specific noun/verb tables (use the right construction)

**OOP:** interface → "Add an interface between …"; class → "Make a class for …";
subclass → "Make a subclass of …"; singleton → "Make the logger a singleton";
factory → "Use a factory to make …"; observer → "Add an observer for …";
dependency → "Inject the service as a dependency into …".

**Functional:** monad → "Wrap … in a monad"; functor → "Map the function over the
functor"; combinator → "Combine the parsers with a combinator"; closure → "Capture … in a
closure"; thunk → "Wrap … in a thunk"; lambda → "Write the function as a lambda".

**Procedural:** buffer → "Write … to a buffer"; pointer → "Get a pointer to …";
malloc → "Allocate … with `malloc`"; struct → "Put … in a struct"; heap → "Allocate … on
the heap"; stack → "Put … on the stack".

**Declarative:** table → "Store … in a table"; schema → "Apply a schema to …";
index → "Make an index on …"; YAML → "Write … in YAML"; pod → "Put … in a pod";
secret → "Store … as a secret".

**Systems:** mutex → "Lock the mutex before …"; semaphore → "Use a semaphore to control
access to …"; register → "Write to the register at …"; interrupt → "Send an interrupt to
…"; DMA → "Transfer … with DMA"; MMU → "Map … through the MMU".

## Edge cases

- **Brand / tool / framework names as verbs:** never. "Docker the app" → "Containerize the
  app"; "Google the error" → "Search for the error with Google"; "Kubernetes the
  services" → "Deploy the services with Kubernetes".
- **Framework names that are also English verbs:** keep as nouns. "Express the middleware"
  → "Write the middleware with Express"; "React to state changes" → "Respond to the state
  changes with React".
- **Code keywords used as verbs:** `class`, `import`, `return`, `yield` are nouns when you
  refer to them; quote them, use approved verbs: "make a `class`", "add the `import`
  statements".
- **Generated symbol names** (e.g. `toJson()`, `UserBuilder`): exempt from the rule, but
  refer to them as nouns in prose. Do not verb them.
- **Multi-word technical nouns:** keep the full phrase; do not drop a word to make a verb.
  "Load balance the requests" → "Distribute the requests with a load balancer";
  "feature flag the endpoint" → "Put the endpoint behind a feature flag";
  "circuit break the service" → "Apply a circuit breaker to the service".

## Minimal examples

> Non-STE: You must Docker the application, then Git the changes, and finally Webpack the bundle.
> STE: You must containerize the application, then commit the changes, and then bundle the code with Webpack.

> Non-STE: Cache the API responses to improve performance.
> STE: Store the API responses in the cache to improve performance.

---

# Rule 1.8 — Use the Standard, Approved Code-Domain Technical Noun

**Rule statement:** When more than one name exists for the same concept, use the name
that is approved in your project, company, industry, or subject field. Do not invent your
own name for an item that already has an established name. (Rule 1.5 tells you *whether* a
word is a technical noun; Rule 1.8 tells you *which* one to pick.)

**Why it exists:** Documentation must be traceable to the codebase. A reader who searches
for "user retrieval endpoint" will not find `GET /users/:id`. Use the exact approved name
so readers can locate the element in the source tree.

## Authority hierarchy for name selection

When several names compete, pick the most authoritative:

1. **Source code** — class/function/file/variable/type names (e.g. `UserRepository`).
2. **Language specification** — keyword, std-lib, built-in type names (e.g. `malloc`,
   `struct`, `pointer`, `Option`).
3. **Framework/library docs** — API, component, hook, config-key names (e.g. `useEffect`,
   `DATABASE_URL`).
4. **Project glossary** — project-specific terms registered under Rule 1.5.
5. **Industry standard** — design-pattern, protocol, algorithm, architecture names
   (e.g. Observer pattern, HTTPS, binary search).
6. **Company documentation** — internal system/service/team names.

Conflict rule: when source code differs from industry standard (e.g. class `DataStore`
but industry "Repository"), use the codebase name for the code element and the industry
name for the conceptual explanation — never mix levels for the same concept in one doc.

## Paradigm-specific: avoid → use

- **OOP:** "user manager" → `UserRepository`; "maker pattern" → Factory pattern; "wiring"
  → Dependency injection; "display pattern" → MVC; "data layer" → `IRepository<T>`.
- **Functional:** "maybe-type" → `Option`/`Maybe`; "IO box" → `IO` monad; "chaining" →
  Function composition; "destructuring" → Pattern matching; "frozen data" → Immutable
  data; "callback function" → Higher-order function.
- **Procedural:** "heap allocation" → `malloc`; "record/compound type" → `struct`;
  "memory reference" → `pointer`; "light thread" → `goroutine` (Go); "console/screen" →
  `stdout`; "shell vars" → Environment variables.
- **Declarative:** "compute instance" → `aws_instance`; "pod config" → `Pod`/`PodSpec`;
  "data fetch" → `SELECT` statement; "all-or-nothing unit" → `TRANSACTION`; "export block"
  → `output`; "project space" → `Namespace`.
- **Systems:** "move operation" → `move` semantics; "reference pass" → `borrow`; "free
  store" → `heap`; "call stack" → `stack`; "thread lock" → `Mutex`; "ISR function" → `ISR`.

## Grammar / formatting notes

- **As a modifier:** the approved noun stays the modifier. "The `UserRepository` interface"
  (correct) vs. "the user storage interface" (wrong).
- **Capitalization:** keep the source form. `userService` and `findById` (not
  `UserService`/`FindById`).
- **Definite article:** use "the" for a specific entity ("The `UserController` handles the
  request"); omit it for the general concept ("`UserController` is a common pattern").
- **In code vs prose:** the name is identical; only formatting (code block / inline code)
  changes.

## Edge cases

- **Codebase uses a non-standard name:** use the codebase name (`DataStore`) and mention
  the industry name in parentheses for comprehension: "The `DataStore` class (a Repository
  pattern implementation) …".
- **Two competing standards** (callback/handler/listener; hash map/dictionary/associative
  array): pick one per Rule 1.11, register it, prefer the language-ecosystem term (Java
  "map", Python "dictionary").
- **Acronyms:** use the approved acronym; define at first use unless the audience knows
  it. After definition, use only the acronym (do not alternate full form/acronym).
- **Framework renames a concept** (Django "view" vs others "component"/"controller"): in
  framework-specific docs use the framework's name; in general docs use the common term and
  note the variant.
- **Name changes during refactor:** use the target name; show the old name only as
  quoted, DEPRECATED text.
- **Package name varies by registry** (`python-dotenv` on PyPI vs `dotenv` on npm): in
  ecosystem docs use that registry's name; give the registry-qualified install command.

## Minimal examples

> Non-STE: The account controller manages login and user profile operations.
> STE: The `AccountController` manages authentication and user profile operations.

> Non-STE: The service uses secure web communication to send data between the client and the server.
> STE: The service uses HTTPS to send data between the client and the server.

---

# Rule 1.9 — Select a Short, Easy-to-Understand Technical Noun

**Rule statement:** When you must choose a code-domain technical noun and no approved name
exists, select one that is short (not more than three words) and easy to understand. Do
not use long descriptive phrases when a shorter term is sufficient.

**Why it exists:** Long noun phrases raise cognitive load — the reader parses a chain of
modifiers before reaching the head noun. Context permits brevity: the code, an API spec, a
diagram, or a preceding definition already identifies the item, so the short term is
enough.

**Context sources that permit the short form:**
- Code references (line number, function/class/file name)
- Diagrams / figures that label components
- A preceding definition ("the authentication service, called AuthService")
- An API spec that fully describes a type
- A following code snippet

When no context source is available, add one or two **disambiguating** adjectives only.
Remove "noise adjectives" (e.g. "the secure HTTPS protocol" — HTTPS is secure by
definition; "the configurable settings object" — all settings are configurable).

## Three-word limit — rationale and exceptions

The limit reflects working-memory capacity. Exceptions (keep the longer term; do not
invent a shorter one the community does not use):
1. **Established technical terms** — "abstract syntax tree", "single sign-on provider",
   "continuous integration pipeline".
2. **Framework/tool proper nouns** — "GitHub Actions workflow", "Amazon Web Services
   Lambda". Use given; abbreviate only if the abbreviation is itself a recognized noun
   (e.g. "AWS Lambda").
3. **Fully qualified type names** — `com.example.module.SubComponent`; use the short name
   after first reference.
4. **Shortening causes ambiguity** — keep the longer phrase.

## Long phrase → short form reference

| Long phrase | Short STE form | Context that permits it |
|---|---|---|
| asynchronous JavaScript XML HTTP request wrapper utility function | fetch utility | line number + snippet |
| serialized JSON payload from the remote API endpoint | JSON data from the API endpoint | field name + type |
| user account profile information data transfer object | `UserProfileDTO` | parameter already named |
| relational database management system server instance | database | port + "primary" |
| multi-platform containerized microservice orchestration layer | Kubernetes cluster | diagram / README title |
| dependency injection inversion of control container | DI container | preceding definition of DI |
| mutual exclusion lock primitive with timeout-bounded acquisition | mutex | class name in code |
| configuration, settings, and options parameters object | `Config` object | object is named `Config` |
| dynamically allocated resizable contiguous memory region utility | dynamic array | type is declared |
| horizontal pod autoscaling controller with CPU threshold | `HorizontalPodAutoscaler` resource | YAML `kind` field |

## Abbreviations and acronyms

- **Universal** (use on first reference, expansion optional): API, JSON, SQL, HTML, HTTP,
  URL, DNS, TCP, TLS, CPU, RAM, SSD.
- **Domain-specific** (expand on first use for a general audience): JWT, CORS, ORM, SPA,
  SSR.
- **Project-specific** (expand on first use in every doc): only after definition.

Do NOT invent abbreviations to satisfy this rule ("TransSec" for "Transport Layer
Security" fails Rule 1.8 — use the recognized short form "TLS").

## Edge cases

- **Short term less well-known than long** (e.g. "AST"): expand on first use — "abstract
  syntax tree (AST)" — then use "AST". If the audience knows it (compiler docs), use it
  directly. Ease test: would a 1-year-experience developer in this domain understand it?
- **Framework name is also a short word** (React, Go, Rust): use "the React framework" /
  "the Go language" on first use to disambiguate; bare name is fine afterward. Do not
  invent abbreviations.
- **Codebase uses long names internally** (`AbstractUserAuthenticationProviderFactoryBean`):
  Rule 1.8 wins for the name itself — use it as given. Rule 1.9 applies to surrounding
  prose: "the factory bean". Do not rename in code or references.
- **Shortening creates a homonym** ("pool" = thread/connection/object): keep the
  two-word form ("connection pool", "thread pool") unless the doc discusses exactly one
  kind throughout.
- **Generated docs** (JSDoc/Sphinx/godoc): the auto-generated portion is exempt, but any
  human-written `@description` / docstring summary must obey the rule.

## Minimal examples

> Non-STE: Remove the four stainless steel pan head machine screws (10) that attach the metallic machined flange (15) to the front housing cover (20).
> STE: Remove the four screws (10) that attach the flange (15) to the cover (20).

> Non-STE: The request body must contain a JSON object with a required string field named "emailAddress" that must match the standard internet electronic mail address format as defined by RFC 5322 …
> STE: The request body is a JSON object with these fields: `emailAddress` (string, required) — a valid email address; `displayName` (string, optional, max 100 characters); `subscribeToNewsletter` (boolean, optional, default: `false`).

---

# Quick reference — the five rules at a glance

| Rule | One-line constraint | Key mechanism |
|---|---|---|
| 1.5 | You may use a non-dictionary word if it names a code concept in 1 of 19 categories. | 19 categories; glossary registration required. |
| 1.6 | A non-approved word is legal only as a technical noun (or inside one). | 3-test gate: unapproved? → noun category? → used as noun? |
| 1.7 | Do not use a technical noun as a verb. | Approved verb + noun in prepositional phrase; double-category exception. |
| 1.8 | When names compete, use the approved/standard one. | Authority hierarchy (source code > spec > framework > glossary > industry > company). |
| 1.9 | Pick the short, clear form; context permits brevity. | ≤3 words; expand acronyms on first use; no invented abbreviations. |

**The only two kinds of words in STE-Code documentation:** approved STE-Code words (Rule
1.1) for common vocabulary, and code-domain technical nouns (Rule 1.5) for domain-specific
concepts. There is no third category. Rule 1.6 forbids everything else; Rules 1.7–1.9
govern how you use the technical nouns you keep.



## rules-sec2.md

# Level 4 — Section 2: Noun Phrases

Section 2 of STE-Code controls how you write technical nouns in code
documentation: API docs, README sections, commit messages, runbooks, code
comments, config files, and test names.

Three rules, one idea: **a technical noun must be short enough to parse on the
first read.**

| Rule | Statement | Primary tool |
|---|---|---|
| 2.1 | Keep technical nouns short. | Prepositions (`of`, `on`, `in`, `for`) |
| 2.2 | When a technical noun has more than three words, write it in full. | Short form or approved abbreviation on first use |
| 2.3 | Use hyphens between words used as one unit. | Hyphen, max three words per group |

Shared constraints across all three rules:

- Maximum three words in a noun phrase. A hyphenated unit counts as one word.
- Approved verbs only: `set`, `get`, `make`, `show`, `check`, `remove`, `send`,
  `start`, `stop`, `use`, `update`.
- Forbidden substitutions: `configure`→`set`, `retrieve`→`get`,
  `delete`/`purge`→`remove`, `display`→`show`, `utilize`/`leverage`/`employ`→`use`,
  `commence`/`initiate`→`start`, `terminate`→`stop`.
- Approved code-domain adjectives stay attached to the noun they modify:
  `idempotent`, `immutable`, `thread-safe`, `atomic`, `nullable`, `deprecated`,
  `stateless`, `backward-compatible`, `asynchronous`, `concurrent`,
  `deterministic`.

---

## Rule 2.1 — Keep Technical Nouns Short

> Source: ASD-STE100 Issue 9, Rule 2.1 · Group `005-rules-sec-2` · spec pages 60–63.

**Rule.** To keep multi-word technical nouns short, use prepositions (`of`,
`on`, `in`, `for`) and explain the multi-word technical noun. A technical noun
that the code domain uses — a module name, a class name, a configuration key,
an endpoint path, an error type, a test fixture — must stay short so that the
reader can parse it without effort.

When a phrase names a code component with more than a few words, break the
phrase into small nouns joined by prepositions. Do not stack modifiers into one
long noun.

**Why it matters.**

- A stacked noun such as `authentication_token_expiration_refresh_interval_setting`
  hides which part owns which. Prepositions show the tree: the setting belongs
  to the interval, the interval to the expiration, the expiration to the token.
- Short technical nouns match how code is already structured. A config key, a
  class, or a JSON field is one short concept; prepositions show how those
  concepts relate.
- Long merged identifiers are hard to grep and hard to read in a log line.

**Procedure.**

1. Find a noun that stacks two or more modifiers (a "noun chain").
2. Split the chain at the ownership or containment points.
3. Connect the parts with `of`, `on`, `in`, or `for`.
4. If a part is itself a code component, name it with its short technical noun
   (its class, key, or file), not a merged word.
5. In instruction text, use the approved verbs.

### Rewrite pairs

| Context | Non-STE (do not write) | STE-Code |
|---|---|---|
| Config key | Authentication token expiration refresh interval setting | Setting of the refresh interval of the expiration of the authentication token |
| Deployment labels | Install the forward service request validator middleware config tags. | Install the config tags on the validator middleware of the request of the forward service. |
| Cleanup task | Remove the database migration script output directory lock files. | Remove the lock files that lock the output directory of the migration script of the database. |
| Test setup | Adjust to obtain cache invalidation hook alignment with the event emitter. | Adjust the cache invalidation hook until it aligns with the event emitter. |
| API doc | Payment gateway timeout retry exhaustion notification handler. | Handler of the notification of the exhaustion of the retry of the timeout of the payment gateway. |
| Commit title | User account profile avatar image storage bucket policy update. | Update the policy of the storage bucket of the image of the avatar of the profile of the user account. |
| README | The inbound request rate limit window reset schedule controls the burst. | The schedule of the reset of the window of the rate limit of the inbound request controls the burst. |
| Code comment | The background worker queue overflow alert suppression rule runs on the staging cluster. | The alert suppression rule on the overflow of the background worker queue runs on the staging cluster. |

### Worked examples

Configuration key — one concept per level, relationship stated with `of`:

```yaml
# STE-Code
auth:
  token:
    expiration:
      refresh_interval_seconds: 300   # setting of the refresh interval of the
                                      # expiration of the authentication token

# Non-STE: one long key hides the relationship (do not write this)
authentication_token_expiration_refresh_interval_setting: 300
```

```python
# STE-Code doc comment
def get_refresh_interval(token):
    """Return the setting of the refresh interval of the expiration of the
    authentication token."""
    return token.expiration.refresh_interval_seconds
```

Deployment labels — name the target with prepositions so the reader knows what
the tag goes on:

```bash
# STE-Code: the tag goes on the validator middleware of the request
#           of the forward service
kubectl label pods \
  -l app=forward-service \
  middleware=validator \
  config=enabled
```

Cleanup task — approved verb `remove` (not `delete`, not `purge`):

```python
# STE-Code: remove the lock files that lock the output directory
#           of the migration script of the database
from pathlib import Path

def remove_migration_lock_files(db_name: str) -> int:
    """Remove the lock files that lock the output directory of the
    migration script of the database."""
    output_dir = Path("migrations") / db_name / "output"
    removed = 0
    for lock in output_dir.glob("*.lock"):
        lock.unlink()
        removed += 1
    return removed


# Test that checks the cleanup (use `check`, not `verify`)
def test_remove_migration_lock_files(tmp_path):
    out = tmp_path / "app" / "output"
    out.mkdir(parents=True)
    (out / "write.lock").write_text("")
    assert remove_migration_lock_files("app") == 1
    assert not any(out.glob("*.lock"))
```

Test setup — name the hook, then state what it aligns with:

```python
# STE-Code: adjust the cache invalidation hook until it aligns with the
#           event emitter
import time

def align_cache_hook(hook, emitter, timeout: float = 5.0) -> bool:
    """Adjust the cache invalidation hook until it aligns with the event emitter."""
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        if hook.target is emitter:
            return True
        hook.nudge()
    return False
```

API doc and log lines — split so each level is a short noun:

```python
# STE-Code: handler of the notification of the exhaustion of the retry
#           of the timeout of the payment gateway
class PaymentGatewayTimeoutRetryExhaustionNotificationHandler:
    """Handler of the notification of the exhaustion of the retry of the
    timeout of the payment gateway."""

    def handle(self, notice) -> None:
        log.error("retry of the timeout of the payment gateway is exhausted")
```

```text
# Non-STE log line (do not write this)
paymentgatewaytimeoutretryexhaustionnotificationhandler: retry failed
```

Commit title and README:

```text
# STE-Code commit title
Update the policy of the storage bucket of the image of the avatar of the
profile of the user account

# Non-STE commit title (do not write this)
useraccountprofileavatarimagestoragebucketpolicyupdate
```

```markdown
# STE-Code README
The schedule of the reset of the window of the rate limit of the inbound
request controls the burst. Set the window to 60 seconds.
```

Code comment — head noun first, then attach the rest with `on` and `of`:

```python
# STE-Code comment: the alert suppression rule on the overflow
# of the background worker queue runs on the staging cluster
def install_alert_rule(cluster: str) -> None:
    rule = AlertSuppressionRule(on=OverflowOf(WorkerQueue(background=True)))
    deploy(rule, cluster="staging")
```

**See also:** Rule 1.3 (approved words) · Rule 1.5 (technical noun categories) ·
Rule 2.2 (long nouns in full) · Rule 2.3 (hyphens).

---

## Rule 2.2 — Write Long Technical Nouns in Full

> Source: ASD-STE100 Issue 9, Rule 2.2 · `master.md#sec2-rule2.2`.

**Rule.** When a technical code noun has more than three words, write it in
full. Then use one of these methods to make it clear:

- **Method 1** — give a shorter form or an approved abbreviation.
- **Method 2** — use prepositions (`of`, `on`, `in`, `for`, `to`) to split the
  long noun into short parts (see Rule 2.1).
- **Method 3** — use hyphens between words that you use as one unit (see Rule 2.3).

A long multi-word code noun can be one long technical noun, or a combination of
shorter technical nouns. Frequently you cannot divide it, because it is the
technical noun that your company, framework, or subject field uses. In that
case write it as it is, in its approved form.

### Method 1 — Shorter form of technical code nouns

If a long technical code noun comes from an official code document (an API
specification, a schema, an OpenAPI file, or an architecture diagram), write it
in full the first time it occurs in the text. Then, where possible, explain it
and use a shorter form or an approved abbreviation in the rest of the document.

> Before you do this procedure, initialize the user session cache invalidation
> lock handler (the handler that locks the cache of the user session, referred
> to in this procedure as the "invalidation lock handler").

Here "user session cache invalidation lock handler" is written in full; after
the explanation the shorter noun is "invalidation lock handler" — three words,
which obeys Rule 2.1.

```python
# STE-Code: write the long technical code noun in full, then use the short form
def initialize_session_lock(user_id: str) -> None:
    """Initialize the user session cache invalidation lock handler.

    The invalidation lock handler locks the cache of the user session so that
    a background job cannot read stale data while a write is in flight.
    """
    handler = UserSessionCacheInvalidationLockHandler(user_id)
    handler.engage()   # from here, refer to it as the "invalidation lock handler"

# later in the document, use the short form:
#   The invalidation lock handler releases the cache when the write is done.
```

When the surrounding text already gives all the necessary information, no extra
explanation is needed — write each official noun in full on first use, define
its abbreviation, then reuse the abbreviation:

> The Main Form Validation Module (MFVM) is a TypeScript module that includes a
> Main Export Controller Unit (MECU) and a Data Bridge (DB). The MFVM is
> installed in the application core layer and operates in the form submission
> system. The function of the MFVM is to validate and submit the form data from
> the Main Form Provider (MFP) to the data stores and the validation hooks. The
> Dynamic Config Unit (DECU) sends events to operate the MFVM.

```typescript
// STE-Code: abbreviation defined on first use, then reused
interface FormPayload { fields: Record<string, unknown>; }

class MainFormValidationModule {       // MFVM
  constructor(
    private readonly exportController: MainExportControllerUnit,  // MECU
    private readonly bridge: DataBridge,                          // DB
    private readonly config: DynamicConfigUnit,                   // DECU
  ) {}

  submit(payload: FormPayload): void {
    this.config.onEvent("submit", () => this.exportController.run(payload));
  }
}
```

If an approved technical code noun has three words or fewer, abbreviations are
not necessary. Do not fill a procedure with letter codes:

| Do not write: | WRITE: |
|---|---|
| The primary parts of the controller are: - The DTA (8) - The PVA (15) - The BA (17) - The VB (20). | A. Remove the data transformer assembly (8) from the view body (20). B. Remove the pipeline validator assembly (15) from its seat. C. Remove the buffer assembly (17) from the view body (20). |
| A. Remove the DTA (8) from the VB (20). B. Remove the PVA (15) from its seat. C. Remove the BA (17) from the VB (20). | A. Remove the data transformer assembly (8) from the view body (20). B. Remove the pipeline validator assembly (15) from its seat. C. Remove the buffer assembly (17) from the view body (20). |

```yaml
# STE-Code: name each part in full; do not pack the parts into letter codes
controller:
  data_transformer_assembly:   # (8)  part of the view body
  pipeline_validator_assembly: # (15) sits on its seat
  buffer_assembly:             # (17) part of the view body

# Non-STE (do not write this):
#   parts: [DTA_8, PVA_15, BA_17, VB_20]
```

```python
# STE-Code: write the part names in full; use the approved verb `remove`
def disassemble_controller(view_body, validator_seat):
    view_body.remove(data_transformer_assembly)         # (8)
    validator_seat.remove(pipeline_validator_assembly)  # (15)
    view_body.remove(buffer_assembly)                   # (17)
```

### Method 2 — Use prepositions to break up a long noun

When a long technical code noun is a chain of short nouns (for example, "user
authentication token refresh failure retry policy"), it is hard to read and easy
to parse the wrong way. Make the main noun the head of the sentence, then attach
the rest with `of`, `on`, `in`, `for`, or `to`.

| Non-STE (do not write) | STE-Code |
|---|---|
| Configure the user authentication token refresh failure retry policy before you deploy the service to production. | Configure the retry policy for the failure of the refresh of the user authentication token before you deploy the service to production. |
| Install the background worker queue overflow alert suppression rule on the staging cluster. | Install the alert suppression rule on the overflow of the background worker queue on the staging cluster. |
| Remove the database connection pool exhaustion recovery timeout configuration parameter from the settings file. | Remove the configuration parameter that sets the recovery timeout for the exhaustion of the database connection pool from the settings file. |
| Update the build script to obtain output directory naming consistency with the package convention. | Update the build script until the output directory naming is consistent with the package convention. |

```python
# STE-Code: the short noun keeps the function name and the docstring clear
def set_recovery_timeout(pool, seconds: float) -> None:
    """Set the configuration parameter that sets the recovery timeout
    for the exhaustion of the database connection pool."""
    pool.config["recovery_timeout_seconds"] = seconds
```

A 4-to-6-word noun becomes a short head noun plus prepositional phrases. This is
useful for config keys, rule names, and error-handling terms that grow long.

### Method 3 — Hyphenate words that you use as one unit

When two or more words act as a single modifier before a noun, hyphenate them so
that the reader does not group the words the wrong way. In code prose,
hyphenate compound modifiers such as `request-response`, `read-write`,
`build-time`, `out-of-band`, `end-to-end`, and `run-time`. Do not hyphenate when
the first word is an adverb ending in `-ly` ("a publicly documented API").

| Non-STE (do not write) | STE-Code |
|---|---|
| Set the request response mapping handler to the new schema before the migration. | Set the request-response mapping handler to the new schema before the migration. |
| Run the build time configuration check after you compile the module. | Run the build-time configuration check after you compile the module. |
| Add an end to end test for the payment flow before you merge the change. | Add an end-to-end test for the payment flow before you merge the change. |
| Use the out of band signal to stop the long running job. | Use the out-of-band signal to stop the long-running job. |

```python
# STE-Code: hyphenated modifiers are one unit in code identifiers too
def handle_request_response(handler: "RequestResponseMappingHandler") -> None:
    """Set the request-response mapping handler to the new schema."""
    handler.apply(schema=SCHEMA_V2)

def run_build_time_check() -> None:
    """Run the build-time configuration check after you compile the module."""
    ...
```

Note: hyphenation groups words into one unit but does not make a long technical
noun short. If the hyphenated unit still has more than three words (for example,
"request-response mapping handler"), write it in full the first time, then use
the shorter form ("mapping handler") in the rest of the text.

### Expanded code-domain pairs

> **Non-STE:** The USCIlh must run before the shutdown hook releases the cache. If the USCIlh fails, the stale session remains.
>
> **STE:** Initialize the user session cache invalidation lock handler (the handler that locks the cache of the user session; in this procedure, we call it the "invalidation lock handler"). Run the invalidation lock handler before the shutdown hook releases the cache. If the invalidation lock handler fails, the stale session remains.

```python
# STE-Code: the long noun is written in full, then shortened for reuse
class UserSessionCacheInvalidationLockHandler:
    def engage(self) -> None: ...
    def release(self) -> None: ...

def shutdown_hook(session_id: str) -> None:
    handler = UserSessionCacheInvalidationLockHandler(session_id)
    handler.engage()          # invalidation lock handler
    if not handler.release():
        raise StaleSessionError(session_id)  # stale session remains
```

> **Non-STE:** The MFVM uses the MECU and the DB. The DECU sends events to the MFVM so that the MFVM can get data from the MFP.
>
> **STE:** The Main Form Validation Module (MFVM) is a TypeScript module that includes a Main Export Controller Unit (MECU) and a Data Bridge (DB). The Dynamic Config Unit (DECU) sends events to operate the MFVM, and the MFVM gets form data from the Main Form Provider (MFP).

```typescript
// STE-Code: abbreviation defined on first use, then reused in the text
const mfvm = new MainFormValidationModule(     // MFVM
  mecu,  // Main Export Controller Unit
  db,    // Data Bridge
  decu,  // Dynamic Config Unit
);
decu.onEvent("submit", () => mfvm.submit(mfp.getData()));  // MFP = Main Form Provider
```

> **Non-STE:** Call the DTA to configure the MFVM before you run the build, then check the MFVM output for errors.
>
> **STE:** Use the data transformer adapter to configure the main form validation module before you run the build. Then check the output of the main form validation module for errors.

```bash
# STE-Code: run the build after you configure the module
make configure MODULE=data-transformer-adapter   # data transformer adapter
make build MODULE=main-form-validation-module    # main form validation module
make test   MODULE=main-form-validation-module && echo "output checked for errors"
```

> **Non-STE:** Update the cross service request tracing correlation identifier generator after the schema change.
>
> **STE:** Update the correlation identifier generator for the tracing of the request across services after the schema change. (On first use, write "cross-service request tracing correlation identifier generator" in full, then refer to it as the "correlation identifier generator.")

```python
# STE-Code: write the long noun in full, then use the short form
def update_correlation_generator(schema: dict) -> None:
    """Update the cross-service request tracing correlation identifier generator.

    After the first use, this component is the correlation identifier generator.
    """
    CorrelationIdentifierGenerator.for_request_tracing().apply(schema)
```

> **Non-STE:** The CI pipeline docker image layer cache warming step now runs in parallel.
>
> **STE:** The cache warming step for the layer of the Docker image of the CI pipeline now runs in parallel. (On first use, write "CI pipeline Docker image layer cache warming step" in full, then refer to it as the "cache warming step.")

```yaml
# STE-Code: the step name is long on first use, then shortened in the runbook
jobs:
  warm_cache:   # cache warming step for the layer of the Docker image of the CI pipeline
    runs-on: ubuntu-latest
    strategy:
      matrix:
        layer: [base, deps, build]
    steps:
      - run: ./scripts/warm-cache.sh "${{ matrix.layer }}"
```

> **Non-STE:** Document the legacy database migration rollback failure notification webhook endpoint in the runbook.
>
> **STE:** Document the webhook endpoint for the notification of the failure of the rollback of the legacy database migration in the runbook. (On first use, write "legacy database migration rollback failure notification webhook endpoint" in full, then refer to it as the "notification webhook endpoint.")

```text
# STE-Code runbook entry
Document the webhook endpoint for the notification of the failure of the
rollback of the legacy database migration. After the first use, refer to it
as the "notification webhook endpoint" and add it to the on-call alert route.
```

### Procedure

1. Find the long technical code noun (more than three words) in your sentence.
2. Write it in full the first time it occurs. If it comes from an official
   source (API spec, schema, architecture diagram), keep the exact approved form.
3. Give a shorter form or an approved abbreviation right after the full form, in
   parentheses.
4. In the rest of the document, use only the shorter form or the abbreviation.
5. If the noun is a chain of short nouns, split it with prepositions (Rule 2.1).
6. If two or more words act as one modifier, hyphenate them (Rule 2.3).
7. Do not fill a procedure with abbreviations. A short, clear noun beats a string
   of letters.

**See also:** Rule 2.1 (three-word limit) · Rule 1.5 (noun categories and your
glossary) · Rule 1.3 (approved verbs: `use`, `set`, `get`, `make`, `show`,
`check`, `remove`, `send`, `start`, `stop`).

---

## Rule 2.3 — Use Hyphens Between Words Used as One Unit

> Source: ASD-STE100 Issue 9, Rule 2.3 · `master.md#sec2-rule2.3`.

**Rule.** A hyphen is a punctuation mark that connects words or parts of words.
Use hyphens between words to show that related words operate as one unit. This
method makes multi-word code nouns agree with Rule 2.1: hyphenated words always
count as one word, so a hyphenated code noun fills only one of the three word
slots that Rule 2.1 allows.

Constraints:

- Do not connect words that are not related — the hyphen changes the meaning of
  the multi-word code noun. If you are not sure, explain the noun in the clearest
  way, then use a shorter form, an approved verb (`get`, `set`, `make`, `start`),
  or an official abbreviation from your glossary.
- If an approved technical code noun already includes hyphens — `input-output
  stream`, `thread-safe queue`, `backward-compatible API` — do not change it. If
  it is too long, write it in full on first use, then use the shorter form.
- Do not hyphenate groups of more than three words. Keep a hyphen group to at
  most three words; split longer chains with prepositions (`of`, `on`, `in`).
- If an approved technical code noun has three words or fewer (`data adapter`,
  `pipeline validator`), hyphens are not necessary.

### Compliant examples

| Example | Note |
|---|---|
| Make sure that the fail-safe shutdown-handler connection is safe. | 3 words: make / sure / connection |
| Inspection of the request rate-limit device. | 3 words: inspection / of / device |
| The thread-safe queue keeps the order of the write operations. | 3 words: queue / keeps / order |
| Remove the backward-compatible API client before you make the change. | 3 words |

### Hyphenate the related pair only — do not chain every word

> **Non-STE:** Move the `main-feature-flag-rollback-handler` trigger to start the test run. (Reads as 2 words, but is not correct — four words joined as one unit.)
>
> **STE:** Move the `main-feature-flag` rollback-handler trigger to start the test run. (3 words: move / trigger / run)

```bash
# STE-Code compliant: the hyphen joins the related pair only
make test trigger=rollback-handler flag=main-feature-flag
```

```python
# STE: "main-feature-flag" (1 unit) + "rollback-handler" (1 unit) + "trigger" (1 unit)
def move_trigger(main_feature_flag: str, rollback_handler: str) -> None:
    """Move the main-feature-flag rollback-handler trigger to start the test run."""
    trigger = f"{main_feature_flag}:{rollback_handler}"
    start_test_run(trigger)
```

### Do not hyphenate a three-word approved technical noun

When the official name of a component is three words or fewer, leave the spaces.
Hyphenating it changes the count and can confuse the reader.

> **Non-STE:** A. Remove the `data-adapter` assembly (8) from the view body (20). B. Remove the `pipeline-validator` assembly (15) from its seat.
>
> **STE:** A. Remove the `data adapter` assembly (8) from the view body (20). B. Remove the `pipeline validator` assembly (15) from its seat.

```python
# STE: "data adapter" and "pipeline validator" are each a 2-word technical noun
def remove_assembly(name: str, part_id: int) -> None:
    """Remove the data adapter assembly (part_id) from the view body."""
    detach(name, part_id)
    log(f"removed {name} assembly {part_id}")

remove_assembly("data adapter", 8)
remove_assembly("pipeline validator", 15)
```

```text
# STE-Code migration note (descriptive)
Remove the data adapter assembly (8) from the view body (20).
Remove the pipeline validator assembly (15) from its seat.
```

### Keep a hyphen that the official name already has

If your official code documentation or an approved standard already hyphenates a
technical noun, keep the hyphen. Removing it changes the term.

> **Non-STE:** The `input output stream` is part of the logging system.
>
> **STE:** The `input-output stream` is part of the logging system.

```python
# STE: "input-output stream" keeps its hyphen because the standard defines it so
class LoggingSystem:
    def __init__(self, stream: "InputOutputStream") -> None:
        # The input-output stream is part of the logging system.
        self.stream = stream

    def write(self, message: str) -> None:
        self.stream.push(message)
```

```yaml
# STE-Code config excerpt
logging:
  # The input-output stream is part of the logging system.
  input-output-stream:
    buffer-size: 4096
    flush-on-error: true
```

**See also:** Rule 2.1 (the three-word limit that hyphenated units help you
meet) · Rule 1.5 (where hyphenated code terms such as `thread-safe queue` and
`backward-compatible API` are defined) · Rule 2.2 (pair hyphenated nouns with
short approved verbs such as `make`, `get`, `set`, `start`, `remove`).

---

## Checklist for Section 2

- [ ] No noun phrase has more than three words (a hyphenated unit counts as one).
- [ ] Noun chains are split at ownership points with `of`, `on`, `in`, or `for`.
- [ ] Every noun longer than three words is written in full on first use, with a
      shorter form or approved abbreviation given in parentheses.
- [ ] The rest of the document uses only the short form.
- [ ] Hyphens join related pairs only, never four or more words.
- [ ] Official hyphenated terms keep their hyphens; three-word approved nouns
      keep their spaces.
- [ ] Instruction text uses approved verbs only.



## rules-sec3.md

# Level 4 — Section 3: Verb Forms and Tenses

Section 3 of STE-Code controls how you write verbs in code documentation:
API docs, README sections, commit messages, runbooks, code comments, config
files, and test names.

Seven rules, one idea: **use only the simple, approved verb forms from the
STE-Code dictionary, in the active voice.**

| Rule | Statement | Watch for |
|---|---|---|
| 3.1 | Use only the verb forms that the dictionary gives. | Gerunds, participles used as verbs, unlisted inflections |
| 3.2 | Use only these verb forms and tenses of verbs. | Present/past perfect, progressive, future perfect |
| 3.3 | Use the past participle form as an adjective. | Past participle used as a verb with "have" |
| 3.4 | Do not use auxiliary verbs to make complex verb constructions. | "have/has/had + been + past participle" passives |
| 3.5 | Use the "-ing" form only as a technical noun or modifier. | Progressive verb forms ("is parsing") |
| 3.6 | Use the active voice. | Passive "is/are + past participle (by …)" |
| 3.7 | Use an approved verb, not a noun, to describe an action. | Noun phrases instead of verbs |

## Approved verb forms

Every approved verb in the STE-Code dictionary shows four forms, in this order:

```
WRITE (v)
WRITES
WROTE,
WRITTEN
```

| Line | Form | Example | Where used |
|---|---|---|---|
| 1 | Base (infinitive, imperative) | WRITE | "Write the log." / "to write the log" |
| 2 | Third-person singular, simple present | WRITES | "The logger writes the record." |
| 3 | Simple past | WROTE | "The job wrote the record." |
| 4 | Past participle (adjective only) | WRITTEN | "the written log" |

The simple future is not a separate line: make it with "will" + base form
("will write"). If a form is not on one of those four lines, it is not approved.

### Approved verb categories

1. **Development operations** — build, compile, test, lint, format, commit, push, deploy, rollback
2. **Data operations** — read, write, serialize, deserialize, parse, encode, decode, query, insert, migrate
3. **Application operations** — handle, route, authenticate, authorize, validate, schedule, dispatch, resolve
4. **Communication operations** — send, receive, publish, subscribe, stream, poll, broadcast, connect

Plain approved verbs (use instead of wordy substitutes): `use`, `start`,
`stop`, `show`, `make`, `get`, `set`, `check`, `do`, `send`, `remove`, `keep`.

### Only these six verb forms are approved

- Infinitive: "Use this flag to parse the file."
- Imperative: "Parse the file. Write the log."
- Simple present: "The parser reads the file."
- Simple past: "The build failed."
- Simple future: "The job will start at 02:00." (will + base form)
- Past participle as adjective: "the parsed file", "the deprecated method"

Not approved (convert away from these): present perfect (has parsed), past
perfect (had parsed), present/past progressive (is parsing, was parsing),
future progressive (will be parsing), perfect progressive (has been parsing),
gerunds used as verbs (parsing, validating), and all passive or compound
auxiliary constructions.

## Rule 3.1 — Use only the verb forms that the dictionary gives

Find the verb in the STE-Code dictionary. If the verb is not there, do not use
it; use an approved verb instead: `make` (not generate), `get` (not retrieve),
`check` (not verify), `use` (not utilize), `start` (not initiate),
`stop` (not terminate), `remove` (not delete), `show` (not render), `do`
(not execute), `keep` (not maintain).

If the verb is approved, use only its four listed forms. Do not invent new
forms:
- "Parsing", "parseable", and "parser" are not verb forms of PARSE. A noun
  such as "parser" is approved only when the dictionary or a technical-noun
  category gives it.
- Use the past participle only as an adjective ("the parsed manifest",
  "the deprecated method"). Do not build a verb with "have/has/had" or "get".

Example:
- Non-STE: The linter validates the file and is reporting the errors to the terminal.
- STE: The linter validates the file. It reports the errors to the terminal.

## Rule 3.2 — Use only these verb forms and tenses of verbs

Use only the six forms above. Do not use unapproved tenses.

| Unapproved form | Fix |
|---|---|
| present perfect ("has parsed") | simple past ("parsed") |
| past perfect ("had parsed") | simple past + "Then" ("parsed. Then …") |
| progressive ("is parsing", "was parsing") | simple present/past; if together, two sentences + "at the same time" |
| future progressive ("will be parsing") | simple future ("will parse") |
| passive with auxiliary ("is being parsed") | name the actor, active voice (Rule 3.6) |

Example:
- Non-STE: The linter has found three errors in the source file.
- STE: The linter found three errors in the source file.

- Non-STE: The server was processing the request when the timeout occurred.
- STE: The server processed the request. Then the timeout occurred.

## Rule 3.3 — Use the past participle form as an adjective

Use the past participle of an approved verb as an adjective:
- before a noun: "the parsed manifest"
- after "is", "becomes", or "stays": "the cache is initialized"

This is not passive voice. It shows the **condition** of something, not an
action an actor performs. If the sentence names an actor and an action
("the file was parsed by the loader"), that is passive voice — rewrite it
active (Rule 3.6).

Approved code-domain past participles (adjectives):

| Participle | Phrase | Condition it shows |
|---|---|---|
| parsed | the parsed manifest | The parser read the file. |
| serialized | the serialized record | In a transport format. |
| deserialized | the deserialized object | In memory again. |
| initialized | the initialized cache | Ready for use. |
| deprecated | the deprecated method | Old; do not use it. |
| allowed | the allowed memory | The limit the config gives. |
| corrupted | the corrupted index | The data is not correct. |
| locked | the locked row | Another transaction holds the row. |
| written | the written log | On disk. |
| given | the given options | The caller sends them. |
| built | the built artifact | The build made it. |
| signed | the signed token | Has a valid signature. |

Cautions:
- Do not make a participle from an unapproved verb. "delete" is not approved;
  write "the removed branch" (use REMOVE).
- Do not use a participle as a verb with "have/has/had" (Rule 3.2).
- Prefer the plain word: "started" not "commenced", "used" not "utilized",
  "stopped" not "terminated".

Example:
- Non-STE: The method has been deprecated by the API team in release 4.2.
- STE: The method is deprecated in release 4.2. Do not use the deprecated method in new code.

## Rule 3.4 — Do not use auxiliary verbs to make complex constructions

Do not combine a past participle with an auxiliary verb ("have", "be", "will",
"can", "must", "should", "is to be") to build compound tenses or passive voice.
Write the action with a simple approved form instead:

- "have/has/had + past participle" (perfect) → simple past, or simple past + "Then".
- "be + past participle" (passive) → active voice with a clear agent (Rule 3.6).
- "is to be + past participle" → imperative.
- "can be + past participle" → "you can + base verb" (reader is the agent).
- "will be + past participle + by + agent" → "will + base verb" with the agent named.

Example:
- Non-STE: The report will be generated by the scheduler.
- STE: The scheduler will generate the report.

- Non-STE: The connection pool has been created before the first query is sent.
- STE: The connection pool was created. Then the first query is sent.

## Rule 3.5 — Use the "-ing" form only as a technical noun or modifier

The "-ing" form is not approved as a verb (it appears only inside the
progressive tenses, which Rule 3.2 forbids). Use it only as:

1. A technical noun in a title or heading — Logging, Monitoring, Handling,
   Packaging, Shipping, Troubleshooting, Building, Deployment.
2. A modifier inside a technical noun — logging service, monitoring agent,
   routing table, switching relay, caching layer, building pipeline,
   binding configuration, streaming endpoint, rendering engine.

Approved "-ing" words in STE-Code:
- Nouns: logging, monitoring, routing, servicing
- Adjectives: matching, missing, remaining
- Pronoun: something
- Preposition: during

Do not pull the "-ing" word out of the technical noun and use it as a verb.
"The caching layer stores the result" is approved; "The layer is caching the
result" is not.

Example:
- Non-STE: The matching algorithm is comparing the remaining items during the iteration and it is removing the missing records.
- STE: The matching algorithm compares the remaining items during the iteration. It removes the missing records.

## Rule 3.6 — Use the active voice

Always use the active voice: the subject of the sentence does the action
("A does B"). In descriptive writing, passive voice is permitted only when the
agent (who or what does the action) is genuinely unknown.

Test for passive voice: ask "by whom or by what?" after the verb. If the
sentence answers it (or could, with the same meaning), it is passive. Convert
it to active by making the agent the subject.

Four conversion methods:

- **Method 1** (agent in "by"-phrase): move the agent to the subject.
  Non-STE: The API response is parsed by the middleware.
  STE: The middleware parses the API response.
- **Method 2**: change an infinitive verb to an active verb.
  STE: The profiler calculates the memory usage from these values.
- **Method 3** (procedural writing): change the verb to the imperative.
  Non-STE: The dependencies can be installed with the following command.
  STE: Install the dependencies with this command: npm install
- **Method 4** (agent not named): use "you" (reader) or "we" (your org).
  Non-STE: The configuration file can be edited with a text editor.
  STE: You can edit the configuration file with a text editor.

Per document type:
- **README:** imperative for install/build steps (reader is agent); active
  with the library/tool as subject in feature lists.
- **API docs:** method or function is the subject. "This method validates the
  input and returns a boolean." (not "is validated … is returned").
- **Docstrings/comments:** imperative summary line; active body with the
  function as subject.
- **Commit messages:** imperative ("Fix the authentication bug.") — the commit
  is the agent. (Generated changelogs are exempt.)
- **Error/log output:** name the component that detected the error
  ("The rate limiter rejected the request."). Passive is correct only when the
  agent is truly unknown ("The connection was reset.").

Paradigm guidance: in OO, the class/method is the agent; in functional, the
function is the agent ("The map function transforms each element"); in
procedural, the script/tool is the agent; in declarative (SQL, Terraform, k8s),
the engine/controller is the agent ("This query selects all rows", "The
deployment controller maintains three replicas"); in systems docs, the
allocator/mutex/channel is the agent ("The mutex controls access to the shared
state").

Quick reference:

| Passive | Active | Method |
|---|---|---|
| is returned by | returns | 1 |
| can be used to | you can use … to | 4 |
| is configured by | configures | 1 |
| is called when | calls | 1 |
| should be installed | install (imperative) | 3 |
| will be removed in | (we) will remove … in | 4 |

When converting, also check the replacement verb against the Canonical Synonym
Table: "The downstream pipeline uses the result" (not "is used by"); "The
scheduler makes the report every night" (not "is generated by").

## Rule 3.7 — Use an approved verb, not a noun, to describe an action

If an approved verb describes the action, use the verb. Verbs describe actions
more clearly than nouns: "validate the token" tells the reader to run the
check; "validation of the token" makes them ask whether to run, log, or skip it.

If a word is not approved as a verb, do not use it as a verb — use the noun
form instead (Rule 1.5). "Cache" is an approved technical noun but not an
approved verb, so write "Do a cache of the response" rather than "Cache the
response".

Preferred plain verbs: `use`, `start`, `stop`, `show`, `make`, `get`, `set`,
`check`, `do`, `send`, `remove`, `keep`. Avoid wordy substitutes: `utilize`→
`use`, `leverage`→`use`, `commence`→`start`, `terminate`→`stop`,
`initiate`→`start`, `generate`→`make`, `employ`→`use`.

Examples:
- Non-STE: The ohmmeter gives an indication of 450 ohms.
- STE: The ohmmeter shows 450 ohms.
- Non-STE: Before the initialization of the service, make sure that the config is valid.
- STE: Before you initialize the service, make sure that the config is valid.
- Non-STE: A read of the config, then a write of the config.
- STE: Read the config, then write the config.
- Non-STE: A transmission of the event, then a reception of the event.
- STE: Send the event, then receive the event.

## Cross-references

- Rule 1.1 — approved words (dictionary + Canonical Synonym Table)
- Rule 1.5 — technical noun categories (noun-form fallback when a word is not an approved verb)
- Rule 1.12 — approved technical verbs in their simple forms
- Rule 3.1 — only the dictionary's verb forms
- Rule 3.2 — only the six approved forms and tenses
- Rule 3.3 — past participle as adjective
- Rule 3.4 — no auxiliary-verb compounds
- Rule 3.5 — "-ing" only as technical noun or modifier
- Rule 3.6 — active voice
- Rule 3.7 — approved verb, not noun
- The STE-Code dictionary (a-dictionary.md) — full list of approved verbs and their four forms
- Extensions (06-extensions.md) — approved plain verbs (use, start, stop, show, make, get, set, check, do, send, remove, keep)
- Reference catalogue (07-catalogue.md) — full verb and noun reference



## rules-sec4.md

# Level 4 — Section 4: Sentence Construction (Rules 4.1–4.5)

Scope: how to build a single sentence of code documentation — one topic, all
words present, vertical lists for complex text, explicit connecting words, and
correct articles.

Source: adapted from ASD-STE100 Issue 9, Section 4. Examples are code-domain
only. Use this file as the operative rule set for API docs, docstrings, code
comments, README sections, commit messages, changelogs, CLI help, and error
text.

Two writing modes are referenced throughout:

- Descriptive writing — a class, module, type, or resource description. No
  imperative form. One fact per sentence.
- Procedural writing — a function, method, or CLI step. Imperative form. One
  instruction per sentence.

Quick index:

| Rule | Requirement |
| --- | --- |
| 4.1 | One topic per sentence. No abstract text. |
| 4.2 | Do not omit words. Do not use contractions. |
| 4.3 | Use a vertical list for complex text. |
| 4.4 | Use connecting words and connecting phrases. |
| 4.5 | Use an article or a demonstrative adjective before a noun. |

---

## Rule 4.1 — One topic per sentence, no abstract text

### Requirement

- In descriptive text, give each sentence one topic and do not use the
  imperative form. Give more information about that topic in the sentences that
  follow.
- In procedural text, give one instruction per sentence in the imperative form.
- Do not write abstract text. Show how to use a function or how a module
  operates. Give the value and the condition for each measurable claim.

Limits: 20 words maximum for a procedural sentence, 25 words maximum for a
descriptive sentence. Inline code spans and URLs do not count.

### Examples

Descriptive — split the topics:

> **Non-STE:** The `HttpClient` class has two internal buffers connected together and linked with callbacks between the request handler and the response dispatcher.
>
> **STE:** The `HttpClient` class has two internal buffers. The internal buffers are connected together with callbacks. These callbacks link the request handler to the response dispatcher.

```java
/**
 * STE:
 * The ConnectionPool manages a set of reusable TCP connections.
 * The connections are created lazily when the pool starts.
 * Each connection is validated when the caller checks it out.
 * Each connection is reset before the caller returns it to the pool.
 * The caller always receives a clean socket from the pool.
 */
public class ConnectionPool { /* ... */ }
```

Do not state a prohibition abstractly; state the action:

> **Non-STE:** No null values are permitted.
>
> **STE:** Make sure that the function does not return a null value.

```python
# STE:
def read_config(path: str) -> dict:
    """Load the configuration from the file at the given path.
    Return an empty dictionary if the file does not exist.
    Do not return null. Raise ConfigError if the file is not valid."""
```

Show the direction of change and the measured value:

> **Non-STE:** Different payload sizes will change the parse time.
>
> **STE:** When the payload size increases, the parse time increases.
>
> **STE:** The parse time is 2 milliseconds for a payload of 1 KB.

```go
// STE:
// ParseMessage decodes a message from the given byte slice.
// The function parses 1 KB of input in 2 milliseconds.
// When the input size doubles, the parse time increases by 1.8 milliseconds.
// The function returns ErrTooLarge if the input is larger than 4 MB.
func ParseMessage(buf []byte) (*Message, error)
```

Procedural — one instruction per step:

```python
# STE:
# 1. Build the HttpClient with the default configuration.
# 2. Set the timeout to 30 seconds.
# 3. Call the send method with the request object.
# 4. Check the response status code.
# 5. Read the response body into a string.
```

```bash
# STE:
# 1. Export the API token to the TOKEN variable.
# 2. Select the staging environment with the --env flag.
# 3. Run the deploy script.
# 4. Check the build log for the success message.
```

Declarative resource — one fact per sentence:

```hcl
# STE:
# The aws_s3_bucket resource creates a storage bucket for application logs.
# The bucket name is "app-logs".
# The bucket keeps a version of each object that you overwrite.
# The bucket encrypts each object with the AES256 algorithm.
resource "aws_s3_bucket" "logs" {
  bucket = "app-logs"
}
```

### By paradigm

- Object-oriented (Java, C++, C#, Python): class documentation is descriptive.
  Keep the class summary to one short sentence with one topic. Break method
  descriptions into numbered imperative steps.
- Functional (Haskell, Elixir, Clojure, Rust): type signatures are descriptive.
  State one property per sentence. Effectful functions use procedural steps.
- Procedural (C, Go, Bash): function documentation is a sequence of steps. Each
  step is one imperative sentence with one instruction.
- Declarative (SQL, Terraform, Kubernetes YAML): resource documentation is
  descriptive. Describe what the configuration does, one fact per sentence.
- Systems (Rust ownership, C memory): describe invariants and ownership rules in
  descriptive sentences. Use imperative steps only for unsafe operations.

### Edge cases

- Generated documentation: JSDoc, Sphinx, and `go doc` output may combine
  sentences. Apply the rule to the source docstrings, not to the generated file.
- Single-sentence module summary: the first docstring line may carry the purpose
  in one sentence. Expand the details below, one topic per sentence.
- Safety callouts (BREAKING, DEPRECATED, NOTE): keep the callout to one short
  sentence. Put detail in the paragraph that follows.
- Error messages: state what failed as one topic. Tell the reader how to fix it
  in a second sentence. Do not write "Invalid input occurred."
- Commit messages: one topic in the subject line. One change per bullet in the
  body.
- README sections: one idea per paragraph, one sentence per listed feature.

### Grammar notes

- Use the imperative verb first in a procedural step: call, set, pass, check,
  start, send, remove, add, make, use, run, build, test, deploy. Do not write
  "you should" or "the user must". Reserve "we recommend" for optional actions.
- Do not nest clauses deeper than two levels. Split them into sentences.
- Prefer the active voice. The subject must perform the action.
- Replace "performance may vary" with the measured value and its condition.

### Checklist

- [ ] The sentence has 20 words maximum (procedural) or 25 (descriptive).
- [ ] The sentence has one topic or one instruction.
- [ ] Procedural sentences use the imperative mood; descriptive sentences do not.
- [ ] The text shows how to use the code and is not abstract.
- [ ] Each descriptive sentence states one fact in the active voice.
- [ ] Each measurable claim gives the value and the condition.

### See also

Rule 1.1 (approved words), Rule 1.3 (approved meanings), Rule 4.2 (no omitted
words), Section 5 (procedural writing), Section 6 (descriptive writing).

---

## Rule 4.2 — Do not omit words or use contractions

### Requirement

Each sentence must have all its parts. Write all words in full. A shorter
sentence is not necessarily easier to read.

- Do not omit nouns. The reader must know which code element the sentence
  refers to.
- Do not omit verbs. The reader must understand the action that the code
  performs.
- Do not omit the subject. The reader must know which function, class, or
  module performs the action.
- Do not omit articles (the, a, an). An omitted article makes the sentence
  ambiguous about which element is specified.
- Do not use contractions. Write "do not", "is not", "are not", "cannot",
  "will not", "does not", and "did not" in full.

### Examples

Do not omit the subject:

> **Non-STE:** Can be a maximum length of 256 characters.
>
> **STE:** The input string can have a maximum length of 256 characters.

```python
def validate_username(name: str) -> bool:
    """Check whether the user name is valid.

    The user name can have a maximum length of 256 characters.
    The user name must contain only letters, digits, and underscores.
    """
    return len(name) <= 256 and name.isidentifier()
```

Do not omit the verb:

> **Non-STE:** The return value a boolean that indicates success.
>
> **STE:** The return value is a boolean that indicates success.

```java
/**
 * Attempts to lock the resource for exclusive access.
 *
 * The return value is a boolean that indicates success.
 * The method returns true when the lock is acquired.
 * The method returns false when the lock is already held.
 */
public boolean tryLock() { ... }
```

Do not omit the noun:

> **Non-STE:** The function returns the parsed.
>
> **STE:** The function returns the parsed configuration object.

```go
// LoadConfig reads the settings file and returns the parsed configuration object.
// The function returns an error when the file is missing or malformed.
func LoadConfig(path string) (*Config, error) { ... }
```

Do not omit articles:

> **Non-STE:** `validate` function checks input parameter.
>
> **STE:** The `validate` function checks the input parameter.

```typescript
/**
 * The `validate` function checks the input parameter.
 * The `validate` function returns a boolean that reports the result.
 * A missing input parameter causes the function to return false.
 */
function validate(input: Request): boolean { ... }
```

Do not use contractions:

> **Non-STE:** The method doesn't throw an exception when the input is null.
>
> **STE:** The method does not throw an exception when the input is null.

```csharp
/// <remarks>
/// The method does not throw an exception when the input is null.
/// The method returns null when the end of the stream is reached.
/// </remarks>
public Record? ReadNext(Stream? input) { ... }
```

Give the subject in a safety statement:

> **Non-STE:** BREAKING: MAKE SURE THAT THE DATABASE IS BACKED UP. IF NOT, THIS CAN CAUSE DATA LOSS.
>
> **STE:** BREAKING: MAKE SURE THAT THE DATABASE IS BACKED UP. A MISSING BACKUP CAN CAUSE DATA LOSS.

```markdown
## BREAKING CHANGES

BREAKING: MAKE SURE THAT THE DATABASE IS BACKED UP.
A MISSING BACKUP CAN CAUSE DATA LOSS.
The migration deletes the `sessions` table.
The migration runs automatically when you start version 3.0.
```

Repeat the article across parallel nouns:

> **Non-STE:** Remove the bolt and stop.
>
> **STE:** Remove the bolt and the stop.

Without the second article, the reader can read `stop` as a verb. In code
prose the same trap appears with words such as `lock`, `check`, `run`, and
`build`. Write "Remove the lock file and the build directory."

Keep the verb in a conditional step:

> **Non-STE:** If installed, remove the shims.
>
> **STE:** If shims are installed, remove them.

```python
# If shims are installed, remove them before you run the calibration.
# The calibration step reads the raw sensor values.
```

Do not contract inside a warning:

```markdown
> **WARNING**
> If your hands are wet, do not touch the USB power adapter.
> The adapter supplies current that can cause injury.
> Keep the adapter away from water while it is connected.
```

### By paradigm

- Object-oriented (Java, C#, C++, Python): write "The method returns…", "The
  constructor creates…", "The getter returns the value of the field."
- Functional (Haskell, Elixir, Clojure, F#): write each pattern-match arm as a
  full sentence with a verb. Add a subject such as "The type variable
  represents…". Write "The first law states that…".
- Procedural (C, Go, Bash, Rust): write "The function reads a configuration
  file." Write "The script removes the build directory."
- Declarative (SQL, Terraform, Kubernetes YAML, Ansible): write "The view
  returns the active users." Write "The resource creates a storage bucket."
- Systems (Rust unsafe code, C memory management): write "The caller must
  ensure that the pointer is valid." An omitted subject hides the party that
  owns the obligation and causes real bugs.

### Edge cases

- Commit message summary line: the 72-character limit permits a relaxed form.
  The body must follow the rule strictly: "The patch removes the unused import.
  The change does not alter the behavior of the function."
- CLI help text: terminal width permits a relaxed form such as `rm FILE`. The
  manual page must write "The command removes the file."
- A code token that looks like a contraction: a test named `won't`, a variable
  `can't`, or a map key `it's` is a technical code noun. Keep it in backticks
  and do not expand it. Write "The test `won't` checks the failure path."
- Error messages and log lines: a short error string may omit articles. The
  documentation that explains the error uses full sentences: "The error means
  that the connection is closed."
- Tables and lists: a cell may hold a short phrase. The column header and the
  surrounding prose supply the subject and the verb. Write the header "The
  function returns the status code", not "Returns status".

### Grammar notes

- Every sentence needs a subject, a verb, and the required articles.
- Repeat the article when two nouns joined by "and" are different things.
- Prefer plain dictionary verbs: "check" for verify, "make" for create, "get"
  for retrieve, "set" for configure, "remove" for delete, when the simpler word
  fits the meaning.

### Checklist

- [ ] Every sentence has a subject, a verb, and the required articles.
- [ ] No words are omitted to shorten the sentence.
- [ ] No contractions are used.
- [ ] The reader knows which element performs the action.
- [ ] Parallel nouns joined by "and" each keep their article.
- [ ] Code tokens that look like contractions stay in backticks.

### See also

Rule 1.1, Rule 1.3, Rule 4.1, Rule 4.3, Rule 4.4, Rule 4.5, Section 5,
Section 6.

---

## Rule 4.3 — Use a vertical list for complex text

### Requirement

When a sentence must include many items (parameters, return fields, error
codes, configuration options, environment variables, dependencies, test cases)
or many actions, put them in a vertical list.

When you make a vertical list:

- Put a colon (:) at the end of the introductory sentence.
- Identify each item with a number, a letter, a dash, or a bullet.
- Start each item with an uppercase letter.
- Use an article before the noun that is the subject of each item, where
  applicable.
- Put a period at the end of an item if it is a full sentence. An imperative
  step such as "Set the timeout value" is a full sentence.
- Do not put a period at the end of an item if it is not a full sentence.
- Do not put a comma or a semicolon at the end of an item.
- Put a period at the end of the last item.

Do not mix imperative instructions and descriptive statements in one list.

In safety instructions, put a negative command (DO NOT) on each item that needs
one. This makes the instruction more direct.

Each item must connect to the introductory text. Test the connection by reading
"Introductory text [item]" as one sentence.

Do not nest a second vertical list inside the primary list. Use the same level
for all items. If a sub-item needs a list, start a new introductory sentence
after the parent item, or use a table.

### Examples

Constructor parameters (descriptive):

> **Non-STE:** The `UserService` constructor accepts the database URL, the cache backend, and the maximum retry count.
>
> **STE:** The `UserService` constructor accepts these parameters:
> - The `database_url` for the PostgreSQL connection string.
> - The `cache_backend` for session storage.
> - The `max_retries` for transient failure handling.

```python
class UserService:
    """Manage application users and their sessions.

    The UserService constructor accepts these parameters:
    - The database_url for the PostgreSQL connection string.
    - The cache_backend for session storage.
    - The max_retries for transient failure handling.
    """

    def __init__(self, database_url, cache_backend, max_retries=3):
        self.database_url = database_url
        self.cache_backend = cache_backend
        self.max_retries = max_retries
```

Deployment steps (procedural, one mode only):

> **Non-STE:** To deploy the application: set the `DATABASE_URL` variable, the server binds to port 8080 after startup, run the migration command.
>
> **STE:** To deploy the application, do these steps:
> - Set the `DATABASE_URL` environment variable.
> - Run the `apply-migrations` command.
> - Start the server on port 8080.

The descriptive fact "The server binds to port 8080 after startup" goes in the
prose after the list, not inside it.

Error codes for an HTTP API:

> **STE:** The API returns these error codes:
> - `400 Bad Request` for a failed input validation.
> - `401 Unauthorized` for an expired or missing token.
> - `403 Forbidden` for insufficient permissions.
> - `404 Not Found` for a missing resource.

```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "unauthorized",
  "message": "The token is expired. Get a new token and send the request again."
}
```

Safety instruction with a negative command on each item:

```text
CAUTION: WHEN YOU ACCESS THE CONFIGURATION THROUGH THE ADMIN PANEL:

- DO NOT CHANGE THE SECRET KEY.
- DO NOT DISABLE THE AUDIT LOG.
```

Configuration options (declarative):

> **STE:** The `config.yaml` file has these top-level fields:
> - The `server.port` that sets the listen port.
> - The `log.level` that sets the log verbosity.
> - The `database.pool_size` that sets the maximum open connections.
> - The `features` that lists the enabled feature flags.

```yaml
server:
  port: 8080
log:
  level: info
database:
  pool_size: 20
features:
  - new_checkout
  - dark_mode
```

Data-transfer-object fields:

> **STE:** The `CreateUserRequest` object has these fields:
> - The `email` that gives the user login.
> - The `display_name` that gives the name that shows in the UI.
> - The `role` that gives the access level.

Return codes (procedural, Go):

> **STE:** The `openFile` function returns these codes:
> - `0` for a successful open.
> - `-1` for a missing path.
> - `-2` for insufficient permission.

```go
func openFile(path string) (int, error) {
    if _, err := os.Stat(path); errors.Is(err, os.ErrNotExist) {
        return -1, fmt.Errorf("the path %q is missing", path)
    }
    f, err := os.Open(path)
    if err != nil {
        return -2, fmt.Errorf("the user lacks permission for %q", path)
    }
    defer f.Close()
    return 0, nil
}
```

Test cases:

> **STE:** The `parse_interval` function passes these test cases:
> - Accept `"10s"` and return 10 seconds.
> - Accept `"0"` and return an error.
> - Accept `"abc"` and return an error.

Dependencies:

> **STE:** The project uses these dependencies:
> - `express` for HTTP routing.
> - `pg` for the PostgreSQL database.
> - `redis` for cache storage.

Environment variables:

> **STE:** The worker reads these environment variables:
> - The `LOG_LEVEL` that sets the log verbosity.
> - The `QUEUE_URL` that sets the message queue address.
> - The `MAX_WORKERS` that sets the maximum concurrent tasks.

```bash
export LOG_LEVEL=info
export QUEUE_URL=amqp://broker:5672/tasks
export MAX_WORKERS=8
```

### By paradigm

- Object-oriented: use a list for constructor parameters, public methods,
  data-transfer-object fields, and the exceptions that a method can send.
- Functional: use a list for each variant of a sum type or each pattern-match
  arm.
- Procedural (C, Go, Bash): use a list for function return codes. One code and
  its meaning per item.
- Declarative (SQL, Terraform, YAML): use a list for top-level fields. Use a
  separate list for the sub-fields of a complex field.
- Systems (Rust, C memory): use a list for ownership or lifecycle rules. One
  constraint per item.

### Edge cases

- Nested fields: do not nest lists. Use a new introductory sentence after the
  parent item, or a table.
- Generated documentation: generated API docs (JSDoc, Sphinx, rustdoc) may use
  tables. That is acceptable. Apply the rule to prose that a human writes.
- Very short lists: two or three very short items may stay inline. Use a
  vertical list when an item has more than five words or the inline sentence
  exceeds 25 words.
- Code blocks in items: put the code block after the item text, indented under
  the item. Do not start an item with a code fence.

### Grammar notes

- Each item must complete the introductory sentence grammatically.
- Use "the" or "a/an" consistently across all items. Put the article before the
  backticks when the item starts with a code identifier.
- An item with a verb phrase ("Set the timeout value") is a full imperative
  sentence and takes a period. An item that is a relative clause ("The
  `timeout` parameter that controls the delay") takes no period until the last
  item.

### Checklist

- [ ] The introductory sentence ends with a colon.
- [ ] Each item starts with an uppercase letter.
- [ ] Each item connects to the introductory text.
- [ ] No period on non-sentence items; a period on the last item.
- [ ] No mixed procedural and descriptive items in one list.
- [ ] No nested vertical lists.
- [ ] Each code sample comes after its item sentence.

### See also

Rule 1.1, Rule 1.6 (technical code nouns), Rule 4.1, Rule 4.2, Rule 5.1
(active voice in steps).

---

## Rule 4.4 — Use connecting words and connecting phrases

### Requirement

Connecting words and connecting phrases connect a topic in one sentence with an
idea in the sentence that follows. They give code documentation a logical
structure.

- Approved connecting words: "and", "but", "then", "thus".
- Approved connecting phrases: "as a result", "at the same time".
- Demonstrative adjectives ("this", "these") also connect ideas in related
  sentences. They must point back to a topic that the previous sentence named.
- In procedural documentation, use a connecting word when an explanation is
  necessary after a work step.
- In safety instructions, use a connecting word to connect the precaution to
  its reason.

| Connector | Use it for |
| --- | --- |
| and | A second, parallel fact or step |
| but | An exception, a limit, or a correction |
| then | A time sequence in a procedure |
| thus | A logical consequence |
| as a result | A state change caused by the previous sentence |
| at the same time | Concurrent work |
| this / these + noun | A reference back to the named topic |

### Examples

"and" — two related descriptions:

> **Non-STE:** `parseInput` validates the request payload and `formatOutput` serializes the response, and they're both called in the handler.
>
> **STE:** The `parseInput` function validates the request payload. And the `formatOutput` function serializes the response data.

"but" — an exception or an alternative:

> **Non-STE:** These error-handling rules are the minimum necessary for the API layer, although the local project conventions may specify additional ones.
>
> **STE:** These error-handling rules are the minimum necessary for the API layer. But the local project conventions can give other necessary error-handling rules.

"thus" — a logical consequence:

> **Non-STE:** If the validation step fails, the middleware sets an error code on the response object, so the downstream handler gets it and skips processing.
>
> **STE:** If the validation step fails, the middleware sets an error code on the response object. Thus, the downstream handler receives the error code and skips the processing step.

"as a result" — cause and effect:

> **Non-STE:** When the cache eviction policy runs, expired entries are removed, which frees up capacity for new entries.
>
> **STE:** When the cache eviction policy runs, expired entries are removed from the cache. As a result, the cache has free capacity for new entries.

"then" — a time sequence:

> **Non-STE:** Open the database connection, after that run the migration script, and finally start the API server.
>
> **STE:** Open the database connection. Then run the migration script. And then start the API server.

Demonstrative adjective in a procedure:

> **Non-STE:** Tag the deprecated methods with the `@deprecated` annotation; it helps developers migrate to the new API.
>
> **STE:** Tag the deprecated methods with the `@deprecated` annotation. This annotation will help developers during the migration to the new API.

Safety instruction:

> **Non-STE:** Always validate user input in this module because it prevents injection attacks.
>
> **STE:** BREAKING: ALWAYS VALIDATE USER INPUT IN THIS MODULE. THIS PRECAUTION WILL PREVENT INJECTION ATTACKS.

Making an implicit link explicit in API prose:

> **Non-STE:** POST /users creates a new user account and returns a 201 status. The response body contains the created user object with an auto-generated ID. The ID can be used in later requests to reference this user.
>
> **STE:** A POST request to `/users` makes a new user account. As a result, the API returns a 201 status code. And the response body contains the created user object with an auto-generated ID. You can use this ID in later requests to refer to the user.

Configuration description:

> **STE:** Set the `max_connections` value to 64 in the config file. As a result, the connection pool reuses idle sockets. And the average request latency decreases under load.

Test description:

> **STE:** The test seeds one row in the database. Thus, the delete endpoint removes that row. And the database has zero rows after the call.

Concurrency:

> **STE:** The worker fetches the page from the remote server. At the same time, the parser reads the response stream. And both tasks finish before the timeout.

Error behavior:

> **Non-STE:** The `read_file` function returns the contents; however, it raises `PermissionError` when the path is not readable.
>
> **STE:** The `read_file` function returns the contents of the file. But it raises a `PermissionError` when the path is not readable.

### By paradigm

- Object-oriented: state the class invariant in one sentence. Use "thus" to
  connect it to the behavioral guarantee of the public API. Use "this" to refer
  back to a private field. Use "and" to group related methods.
- Functional: state the input type in one sentence. Use "and" to connect the
  happy path to the error path. Use "thus" to connect a transformation step to
  the shape of the output.
- Procedural (C, Go, Bash): state the allocation step. Use "then" for
  initialization. Use "as a result" to connect processing to the final state.
- Declarative (SQL, Terraform, YAML): state the resource spec. Use "thus" to
  connect the spec to the reconciliation outcome. Use "this" to refer back to a
  named resource.
- Systems (Rust, C memory): state the ownership rule. Use "thus" to connect it
  to the compiler guarantee. Use "but" to introduce an unsafe escape hatch.

### Edge cases

- A connecting word that is also a framework name: the `Then` assertion library
  and the Rust `and_then` combinator are technical nouns. Keep them in
  backticks. A sentence-initial connecting word is not in backticks.
- "Then" ambiguity: "then" can mean time sequence or logical consequence. When
  the meaning is not clear, use "after" for time and "thus" for logic.
- Generated code comments: the rule applies to documentation you write. Do not
  edit generated comments to add connecting words.
- Long chains: limit a connecting-word chain to two or three sentences. Use a
  list or a table for more.
- Start of a section: do not open a new section with a connecting word. The
  heading provides the structural connection. Restate the topic so the section
  stands alone.

### Grammar notes

- Starting a sentence with "and" or "but" is permitted and encouraged. It gives
  short, independent sentences with an explicit link.
- "Thus" and "as a result" sit at the start of the second sentence. Do not use
  a semicolon before "thus".
- Prefer the adjective form of a demonstrative with an explicit noun ("this
  function", "these parameters").
- Keep two sentences joined by "and" parallel in structure.

### Checklist

- [ ] Each connecting word links a sentence to the one that follows.
- [ ] Only approved connecting words and phrases are used.
- [ ] Demonstrative adjectives refer back to a clearly introduced topic.
- [ ] No mixed procedural and descriptive modes inside one connected pair.
- [ ] Connecting-word chains do not exceed three sentences.

### See also

Rule 1.1, Rule 1.3, Rule 1.11 (one term per concept), Rule 3.1, Rule 4.1.

---

## Rule 4.5 — Use an article or a demonstrative adjective before a noun

### Requirement

Articles ("the", "a", "an") and demonstrative adjectives ("this", "these") show
the position of nouns and multi-word nouns. Use them correctly. Do not remove
them to shorten the text.

- Do not use an article in a general statement or before an abstract concept:
  performance, scalability, error handling, concurrency, backward
  compatibility.
- In short sentences, use an article before each noun. This helps readers and
  machine translation.
- In a long series of items, use the article only before the first noun.
- Repeat the article in a series when an adjective applies to one item only.
- Do not use a definite article directly before a code identifier. A function
  name, a class name, a variable name, a file name, an environment variable, an
  error code, and a version tag are proper nouns.
- Keep the noun after a demonstrative adjective. Do not write "this" or "these"
  alone.

### Examples

Article in a short instruction:

> **Non-STE:** Call callback function. Pass response object to handler and set retry flag.
>
> **STE:** Call the callback function. Pass the response object to the handler. Then set the retry flag.

Article in an API reference sentence:

> **Non-STE:** Method reads configuration file and returns settings object.
>
> **STE:** The `load` method reads the configuration file and returns the settings object.

No article in a general statement:

> **Non-STE:** The error handling is important for the production applications. A function throws the error when the input is not valid.
>
> **STE:** Error handling is important for production applications. The function throws an error when the input is not valid.

> **Non-STE:** The backward compatibility is a requirement for the public API.
>
> **STE:** Backward compatibility is a requirement for the public API. The `v2` endpoints keep the response shape of the `v1` endpoints.

Article only before the first noun in a long series:

> **Non-STE:** Delete temporary files, log files, cache entries, and lock files before you start the build.
>
> **STE:** Delete the temporary files, log files, cache entries, and lock files before you start the build.

> **STE:** Close the database connection, file handle, socket, and worker pool in the shutdown hook.

Repeat the article when an adjective applies to one item only:

> **Non-STE:** Register the new event listeners, timers, subscriptions, and cleanup callbacks.
>
> **STE:** Register the new event listeners, the timers, the subscriptions, and the cleanup callbacks. (Only the event listeners are new.)

> **Non-STE:** The release includes the deprecated helper functions, adapters, and CLI flags.
>
> **STE:** The release includes the deprecated helper functions, the adapters, and the CLI flags. (Only the helper functions are deprecated.)

No definite article before an identifier:

> **Non-STE:** Call the function `validateInput` before you send the request.
>
> **STE:** Call function `validateInput` before you send the request.
>
> **STE (alternative):** Call the `validateInput` function before you send the request.

> **STE:** Configure module `AuthService` in the container.
>
> **STE:** Set variable `LOG_LEVEL` to `debug`.
>
> **STE:** Error `ERR_TIMEOUT_1042` shows in the console log.
>
> **STE:** Install version 3.2.1 of the package.

Demonstrative adjective for sentence linking:

> **Non-STE:** The function returns a configuration object. Configuration object has three fields: host, port, and timeout.
>
> **STE:** The function returns a configuration object. This object has three fields: `host`, `port`, and `timeout`.

> **Non-STE:** The middleware writes two headers to the response. They are used by the cache layer.
>
> **STE:** The middleware writes two headers to the response. These headers control the behavior of the cache layer.

Commit message and release note:

> **Non-STE:** Fix race condition in scheduler; worker pool now waits for queue drain.
>
> **STE:** Fix the race condition in the scheduler. The worker pool now waits for the queue to become empty.

> **STE:** Adds retry logic to the `HttpClient` class. Removes deprecated method `sendSync`.

Error message and test description:

> **Non-STE:** Input not valid: field must be string.
>
> **STE:** The input is not valid. The `name` field must be a string.

> **Non-STE:** Test verifies handler returns 404 when record missing.
>
> **STE:** The test checks that the handler returns the status code 404 when the record is not in the database.

### By paradigm

- Object-oriented (Java, C#, Python, TypeScript): use the article to separate a
  class from an instance. "The `ConnectionPool` class manages a pool of
  database connections. Each instance keeps a list of open connections." Use no
  article before a bare identifier: "Call `connect`."
- Functional (Haskell, Elixir, F#, Scala): separate a type constructor from a
  value. "The `Ok(value)` pattern shows a successful result. A `Result` value
  is either `Ok` or `Err`." Write "immutability" and "referential transparency"
  with no article.
- Procedural (C, Go, Bash): separate a pointer from the value at the address.
  "The function receives a pointer to a buffer. The buffer must hold at least
  512 bytes."
- Declarative (SQL, Terraform, YAML, Kubernetes): separate a resource type from
  a resource instance. "A `Deployment` resource manages a set of pods. The
  `web` deployment runs three replicas." Write no article before a named
  resource: "Apply manifest `web-deployment.yaml`."
- Systems (Rust, C memory, embedded): make ownership and lifetime clear. "The
  pointer must point to an initialized region of memory. A borrow of the value
  must not outlive the owner."

### Edge cases

- Identifier compared with concept: `ConnectionPool` alone takes no article.
  "The `ConnectionPool` class" takes "the" because "class" is the noun. "Call
  `initialize`" takes no article. "The `initialize` function" takes "the".
- "a" compared with "an": use "an" before a vowel sound (an SQL query, an HTML
  element, an XML parser, an ID, an API key). Use "a" before a consonant sound
  (a URL, a Unix system, a UUID, a JSON payload, a `User` record).
- Headings, titles, table cells, and UI labels may omit the article. The first
  sentence below the heading obeys the full rule.
- A product name that starts with "The", such as `TheMovieDB`, is a proper
  noun. The leading "The" is part of the identifier.
- Plural types in a general statement take no article: "Iterators are lazy in
  this library." One identifiable item takes "the": "The iterator stops at the
  end of the sequence."
- Do not add an article inside a code block, a command, or a log line. The rule
  applies to prose only.
- Choose the article for the spoken form of an acronym: "an API", not "a API".
- Uncountable technical nouns (memory, throughput, latency, state) take no
  indefinite article. Write "The function allocates memory."

### Grammar notes

- "A" refers to any instance of a type. "The" refers to one specific,
  identifiable item. No article refers to the type or the concept as a whole.
- Use "a" for the first mention and "the" for each later mention.
- A code identifier is a proper noun. "Call `connect`" is correct. "Call the
  `connect`" is not correct.
- Write "this object" or "these headers". Do not use "this" or "these" alone.
- Put the article before the full multi-word noun: "the retry policy object".
- A possessive form replaces the article. Write "its return value" or "the
  return value of the method". Do not write "the its return value."

### Checklist

- [ ] Articles and demonstrative adjectives are used correctly and are not removed to shorten the text.
- [ ] No article appears before a general statement or an abstract concept.
- [ ] Short sentences use an article before each noun.
- [ ] A long series uses the article only before the first noun, unless an adjective applies to one item only.
- [ ] No definite article appears directly before a code identifier.
- [ ] "a" and "an" match the spoken sound of the term that follows.
- [ ] Each demonstrative adjective is followed by a noun and refers to one clear topic.

### See also

Rule 1.1, Rule 1.5 (technical nouns), Rule 1.11, Rule 3.1, Rule 4.1, Rule 4.4.

---

## Section 4 — Combined checklist

- [ ] One topic or one instruction per sentence (4.1).
- [ ] No abstract claim without a value and a condition (4.1).
- [ ] Every sentence has its subject, verb, and articles; no contractions (4.2).
- [ ] Complex enumerations use a vertical list of one mode only (4.3).
- [ ] Related sentences are joined by an approved connecting word (4.4).
- [ ] Articles and demonstratives are correct, and identifiers take no definite article (4.5).



## rules-sec5.md

# Level 4 — Section 5: Procedural Sentence Rules

Section 5 controls how you write the sentences of a *procedure* in code
documentation: setup steps, runbooks, API usage guides, commit messages,
debugging playbooks, and inline how-to comments.

Five rules, one idea: **every procedural sentence is short, carries one
instruction, uses the imperative form, states any condition first, and keeps
background in notes — not in the steps.**

| Rule | Statement | Watch for |
|---|---|---|
| 5.1 | Write short sentences (maximum 20 words). | Sentences over 20 words; comma splices; semicolons joining clauses |
| 5.2 | Write only one instruction per sentence. | Several actions joined by "and"/"then" in one sentence |
| 5.3 | Write instructions in the imperative (command) form. | Passive voice, modal verbs, gerunds used as instructions |
| 5.4 | Put the condition before the command, separated by a comma. | Conditions buried after the action; misplaced commas |
| 5.5 | Notes give information only, not instructions. | Instructions, requirements, or limits hidden inside a NOTE |

Scope: these rules apply to *procedural text*. Code blocks, terminal output,
string literals, and identifiers inside backticks are not counted. Notes and
descriptive sentences have a 25-word-per-sentence limit; procedural sentences
have a 20-word limit.

## Word-count basis (applies to 5.1 and 5.5)

- Count all words from the initial capital to the terminal punctuation.
- A hyphenated compound ("command-line") counts as one word.
- A number, symbol, or parenthetical reference counts as one word: "(2)" = 1,
  "HTTP/2" = 1.
- A code token inside backticks counts as one word regardless of length:
  `Result<T, E>` = 1 word, `async fn` = 2 words. Do not expand generics or
  type parameters into prose words.
- Subordinate-clause depth: limit to two levels. Flatten deeper embeddings into
  separate sentences.

## Rule 5.1 — Short Sentences (Maximum 20 Words)

Keep every sentence in a procedure to 20 words or fewer. Warnings and cautions
about security, data loss, or stability also obey the 20-word limit. Notes may
use up to 25 words per sentence because they carry information only.

Break long procedural sentences into shorter ones, each focusing on one part of
the task. This matters most when the reader types commands while reading.

Code-domain examples:

- Non-STE (27 w): Run the database migration script from the project root
  directory and then restart the application server to apply all pending schema
  changes to the production environment.
- STE (9 + 13 w): Run the database migration script from the project root
  directory. Then, restart the application server to apply all pending schema
  changes.
- Non-STE (30 w): Set the environment variable HTTP_TIMEOUT to the value 30000
  which represents the maximum number of milliseconds that the client will wait
  for a response from the upstream server.
- STE (8 + 17 w): Set the environment variable HTTP_TIMEOUT to 30000. This value
  is the maximum wait time in milliseconds for a response from the upstream
  server.

```bash
alembic upgrade head
systemctl restart payments.service
export HTTP_TIMEOUT=30000
```

CAUTION (18 w): IF YOU DELETE THE CONFIGURATION DIRECTORY WITHOUT A BACKUP, YOU
CANNOT RESTORE THE APPLICATION SETTINGS TO THEIR PREVIOUS STATE.

### Where this applies in code docs

- **README** — each install/config/quick-start step is one ≤20-word sentence.
- **API docs** — request/setup sentences obey 20 words; descriptive parameter
  prose may use 25.
- **Docstrings** — procedural sentences in a docstring obey 20 words; return
  value/side-effect descriptions may use 25.
- **Commit bodies** — procedural sentences obey 20 words; subject line is a
  separate 72-character constraint, not a word-count one.
- **Error messages** — action messages obey 20 words; pure status reports may
  use 25 (read under stress, keep short).

### How to split a long sentence

1. **Split at coordinating conjunctions** — replace "and"/"but"/"or" with a
   period; start the next sentence with "Then,"/"After that,"/"Next."
2. **Extract conditions** — move an "if X, then Y" clause into its own sentence
   that precedes or follows the instruction.
3. **Separate action from purpose** — instruction in one sentence, reason/result
   in the next.
4. **Use lists** — enumerate items as bullets; list items are not sentences and
   are exempt, but keep each item short.

**Coordinating-conjunction policy:** "and"/"but"/"or" may join two short related
clauses only when the total is ≤20 words. If over 20, split at the conjunction.

**Run-on / semicolon policy:** do not join independent clauses with semicolons.
Use periods. Each instruction gets its own sentence.

**Subordinate depth:** three or more levels of embedding is hard to parse and
usually over 20 words. Promote embedded clauses to their own sentences.

### Edge cases

- **Long framework/service names** — use the shortest accepted form on first
  use, define an abbreviation, then reuse it (e.g. "Amazon EKS" → "EKS"). The
  abbreviation counts as one word.
- **Generated docs** — apply the rule to the source docstrings/comments the
  generator reads; the output inherits compliance. If a generator cannot comply
  from compliant input, file a bug against the generator; do not hand-edit
  generated output. If fixing the source is impractical, apply the 25-word
  descriptive limit and document the exception.
- **Legal/compliance text** — disclaimers, license headers, and regulatory
  statements are not procedures; the 20-word limit does not apply. Keep them in a
  marked section (NOTE / "Legal" heading) separate from steps.
- **Code blocks in prose** — a sentence that introduces a multi-line code block
  must obey the limit on its own; the block itself is excluded from the count.

### Compliance checklist (5.1)

- [ ] Every procedural sentence ≤ 20 words.
- [ ] Every note sentence ≤ 25 words.
- [ ] Warnings/cautions ≤ 20 words.
- [ ] No comma splices (no two independent clauses joined by a comma).
- [ ] No semicolons joining independent clauses.
- [ ] Code blocks, output, and string literals excluded from counts.
- [ ] Backtick code tokens count as one word each.
- [ ] Long technical names abbreviated after first definition.
- [ ] Subordinate clauses ≤ two levels deep.
- [ ] Conjunctions join two clauses only when total ≤ 20 words.

## Rule 5.2 — One Instruction Per Sentence

Write only one instruction in each sentence unless two or more actions occur at
the same time and in one continuous motion. If a sentence carries several
instructions, the reader can miss or skip one. Use numbered or bulleted lists to
show the sequence of steps. There is no limit on the number of work steps.

Code-domain examples:

- Non-STE (37 w, 5 instructions): Open the configuration file in a text editor
  and locate the database section and change the connection string to point to
  the staging server and then save the file and close the editor.
- STE: (1) Open the configuration file in a text editor. (2) Locate the database
  section. (3) Change the connection string to point to the staging server.
  (4) Save the file. (5) Close the editor.

```markdown
1. Open `config/database.toml` in a text editor.
2. Find the `[database]` section.
3. Set `connection_string = "postgres://staging-db:5432/app"`.
4. Save the file.
5. Close the editor.
```

Exceptions — more than one instruction is allowed when:

- Two or more actions occur at the same time and are inseparable (hold Shift and
  click Reload; download and extract the archive).
- A result or measurement follows an action immediately, and splitting it would
  break the logical flow (one action: "Run the full test suite with coverage
  enabled. The total line coverage must be more than 80 percent.").

### Where this applies

- **README** — every numbered quick-start/install step is exactly one
  instruction; a result that must be checked is a second sentence in the same
  step.
- **API docs** — one sentence per endpoint operation; one sentence per parameter,
  per query param, per response field, per error code.
- **Docstrings** — one sentence per parameter, per return value, per raised
  exception, per side effect/precondition.
- **Commit subjects** — one imperative sentence, one change. Split the commit if
  changes are unrelated; use body bullets for related changes.
- **Error messages** — state one problem, give one action; do not combine
  failure paths with "or"/"and"/"also".

### Paradigm notes

- **OOP** — document each constructor parameter in its own sentence; number each
  step of a multi-step setup; do not chain method calls in one prose sentence.
- **Functional** — describe each pipeline stage (map/filter/reduce) in its own
  sentence; do not combine stages into one explanatory sentence.
- **Procedural (C/Go/Bash)** — one comment per executable statement; put the
  comment on the line before the command.
- **Declarative (SQL/Terraform/K8s)** — one sentence per resource, property, and
  constraint.
- **Systems (Rust ownership/C memory)** — state each invariant in its own
  sentence.

### Grammar notes

- **Single predicate** — an imperative sentence has exactly one main verb:
  "Install the package." (not "Install the package and configure the settings.").
- **Compound objects are not compound instructions** — "Remove the log files,
  cache files, and temporary directories." is one instruction (one verb, three
  objects).
- **"-ing" prohibition** — gerunds blur action/description and smuggle in hidden
  instructions; split them into numbered steps.
- **Subordinate clause test** — if the reader must satisfy a precondition in a
  subordinate clause, that precondition is itself an instruction and needs its
  own step: "Before you run the tests, set TEST_MODE=true." → (1) Set
  TEST_MODE=true. (2) Run the tests.

### Edge cases

- **Framework CLI names** — `docker compose up`, `kubectl apply`,
  `terraform destroy` are one technical noun phrase (Rule 1.5). Do not split the
  command name into separate instructions.
- **Error messages with cascading symptoms** — state the root cause first; list
  consequences in a separate descriptive sentence.
- **Multi-step test assertions** — describe each assertion in its own sentence;
  use one assertion message per condition.
- **Console logs during multi-step ops** — each log line reports one completed
  step or one result.

## Rule 5.3 — Imperative (Command) Form for Instructions

Write every instruction in the imperative (command) form: start the sentence
with the base verb. Common imperative verbs in code docs: run, set, open, save,
install, configure, restart, execute, copy, delete, create, add, enter, select,
click, type, check.

Do not use passive voice, gerunds, or modal verbs (can, could, should, may,
might) for instructions. Do not use "must" before the imperative in a standard
instruction. Reserve "must" for WARNING/CAUTION blocks where non-compliance is
severe.

Code-domain examples:

- Non-STE: The unit tests can be executed with the command `npm test`.
- STE: Run the unit tests with the command `npm test`.
- Non-STE: The old log files are to be removed before the new deployment.
- STE: Remove the old log files before the new deployment.
- Non-STE: It is recommended that you create a backup of the database before
  running the migration script.
- STE: Create a backup of the database before you run the migration script.

WARNING (correct use of "must"): IF YOU MUST STORE USER PASSWORDS, ALWAYS HASH
THEM WITH BCRYPT. DO NOT STORE PASSWORDS IN PLAIN TEXT. PLAIN-TEXT PASSWORDS CAN
CAUSE DATA BREACHES.

### Where the imperative form applies

- **README** — only procedural sections (install, config, build, quick-start).
  Descriptive sections (about, architecture, features) use declarative sentences.
- **API docs** — only setup/auth/getting-started instructions. Endpoint
  descriptions are third-person ("Returns a list of users") because they describe
  behavior.
- **Docstrings** — describe what the code does (declarative). Exception: shell
  script headers and Makefile targets that the reader runs directly.
- **Commit subjects** — imperative ("Fix the race condition"), matching Git's own
  convention. Bodies may use descriptive sentences for rationale.
- **Error messages** — describe what happened, then give a recovery instruction;
  separate with a period or newline.

### Grammar notes

- **Subject omission** — the imperative omits "you"; the reader is always the
  implied subject. Passive hides the agent ("The file is saved" — who saves it?).
- **Modal verb elimination** — "You can set the timeout" lets the reader treat
  the action as optional; "Set the timeout" does not.
- **"must" restriction** — imperative already conveys necessity; "must" is
  redundant except in WARNING/CAUTION.
- **Tense consistency** — the base verb form does not inflect; this eases
  translation and machine processing.

### Paradigm notes

- **OOP** — imperative for setup/config instructions; declarative for invariants
  and design rationale.
- **Functional** — imperative for build/REPL/setup; declarative for what a
  function does internally.
- **Procedural (C/Go/Bash)** — imperative dominates (build, compile, link,
  configure).
- **Declarative (SQL/Terraform/K8s)** — imperative only for the tooling that
  applies the state (`kubectl apply`, pipeline steps); the spec itself is
  descriptive.
- **Systems** — imperative in "how to comply" sections; descriptive for
  invariants and lifetimes.

### Edge cases

- **Framework name = verb** (React, Spring, Go, Make) — do not start a sentence
  with the name; prefix with an article or use a real verb: "Use React to build
  the UI." (not "React to state changes with hooks.").
- **Generated help/changelog text** — audit the generator template, not the
  output: `--help` text "Write the output to this file" (not "The output file is
  written here"); changelog "Add support for OAuth2" (not "Added support for
  OAuth2").
- **Code keywords that are English modals** (`try`, `await`, `yield`, `require`)
  — backtick them; do not start an imperative sentence with the keyword unless it
  is the verb: "Use `await` on the promise before you access the result."
- **Release notes** — imperative for upgrade/migration steps; past/present
  perfect for feature/bugfix descriptions.
- **Interactive tutorials** — label blocks clearly ("Run this command" vs "You
  will see output like this"); keep the imperative in the step labels.

## Rule 5.4 — Descriptive Statement Before the Command

When a step has a condition the reader must know first, write the condition as a
descriptive statement at the start of the sentence, then a comma, then the
instruction in the imperative form. The comma is mandatory: it marks where the
condition scope ends and the command scope begins.

The comma's position changes meaning. Compare:

- "If the service does not start, automatically restart it." (the restart is
  automatic)
- "If the service does not start automatically, restart it." (the reader restarts
  it manually)

Code-domain examples:

- Non-STE: Run the database migration script after you set DATABASE_URL to your
  production connection string and confirmed the server accepts connections.
- STE: After you set the `DATABASE_URL` environment variable, run the database
  migration script.
- Non-STE: You can call /users after you obtain a valid OAuth2 token and include
  it in the Authorization header.
- STE: After you get a valid OAuth2 access token from `/auth/token`, call the
  `/users` endpoint. Include the token in the `Authorization` header.
- Non-STE: The API returns 429 with a Retry-After header if the client exceeds
  100 requests per minute.
- STE: If the client sends more than 100 requests per minute, the API returns a
  `429 Too Many Requests` status code. The response includes a `Retry-After`
  header that shows the wait time.

### Where this applies

- **README** — one condition-command pair per step; do not chain several
  conditions in one sentence.
- **API docs** — state the error-triggering condition before the response; gate
  requests on a prerequisite token.
- **Docstrings** — state preconditions before behavior (precondition-before-
  action).
- **Commit messages** — context/problem before the fix (context-before-action).
- **Error messages** — problem before resolution; each corrective action is its
  own condition-command pair.

### Paradigm notes

- **OOP** — state preconditions on method calls before the call instruction; for
  constructors, state the required initial state.
- **Functional** — state the input condition before the transformation; treat
  each guard/pattern branch as a separate condition-result pair.
- **Procedural (C/Go/Bash)** — state the system-state check before the action;
  shell `if` maps directly to the condition clause.
- **Declarative (SQL/Terraform/K8s)** — apply the pattern to the operational
  wrapper (how to apply/run), not to the declarative spec itself.
- **Systems** — state safety conditions before the operation; use WARNING/BREAKING
  when the consequence is severe.

### Grammar notes

- **Comma as scope delimiter** — required, not optional. The reader's eye scans
  for it; it signals the transition from evaluation to action.
- **Adverb placement** — `[condition] , [adverb] [command]` → adverb modifies
  the command. `[condition with adverb] , [command]` → adverb modifies the
  condition. When both need an adverb, use two sentences.
- **Dependent-clause types** — time (before/after/when/until), conditional
  (if/unless/provided that), reason (because), purpose (to/in order to),
  concessive (although). Each dependent clause comes first, comma, then main
  clause. Do not reverse the order.
- **Multiple conditions** — prefer separate sentences (Strategy C): "Before you
  run the migration, make sure the server is running. After the server accepts
  connections, run the migration script." A compound "and" condition is
  acceptable only when short.
- **Works with 5.3** — pattern: `[condition clause] , [imperative verb] [object]`.
  The comma bridges the descriptive condition and the imperative command.

### Edge cases

- **Framework name = common word** (Next.js, Express) — the name is a technical
  noun; the comma-after-condition rule still applies: "Before you start the
  Next.js development server, set the environment variables."
- **Code keyword inside the condition** — the comma goes after the closing
  backtick: "If `response.status === 429`, wait for the duration in the
  `Retry-After` header."
- **Condition clause has its own commas** (an internal list) — restructure.
  Either introduce the list in a separate descriptive sentence, then use a
  comma-free condition ("If you change one or more of these parts, update the
  version number."), or keep the pattern only when the condition has at most one
  internal comma.
- **Condition implied by tool output** — state the observable output as the
  condition: "If the terminal shows 'Connection refused,' start the database
  server."
- **Generated docs** — relax for generated output, but keep Rule 5.4 in the
  source docstring/comment; for templates, place the condition placeholder first.

## Rule 5.5 — Notes Give Information Only, Not Instructions

A NOTE gives supplementary information that helps the reader understand context,
behavior, or background. A note must contain descriptive information only. It
must not contain instructions, requirements, limits, tolerances, or expected
results of a work step. Notes must not use the imperative form. Each sentence in
a note can have up to 25 words.

If a note holds information critical for preventing data loss, security issues,
or system damage, move it into a WARNING or CAUTION safety instruction. A note is
never a substitute for a safety instruction.

**The note test:** read the procedure without the notes. If the reader cannot do
the procedure correctly, move the missing information from the notes into work
steps and repeat the test.

Code-domain examples:

- STE note (descriptive only): NOTE: The API rate limiter allows a maximum of
  1000 requests per minute per client IP address on the free tier.
- Non-STE (instruction in a note): NOTE: When you update the dependencies, run
  `npm audit fix` to resolve known vulnerabilities.
- STE (instruction → work step): (5) Run the command `npm audit fix` to resolve
  known vulnerabilities.
- Non-STE (limit in a note): NOTE: The response time must be less than 200 ms
  under normal load.
- STE (limit → in the endpoint body, not a note): The response time must be less
  than 200 milliseconds under normal load conditions.
- Non-STE (safety in a note): NOTE: Do not run the migration on production without
  a full backup.
- STE (safety → WARNING): WARNING: DO NOT RUN THE MIGRATION SCRIPT ON THE
  PRODUCTION DATABASE WITHOUT A FULL BACKUP. RUNNING THE MIGRATION WITHOUT A
  BACKUP CAN CAUSE IRREVERSIBLE DATA LOSS.

### Where this applies

- **README** — notes explain why a dependency exists or a design decision; they
  do not install packages or run commands (those are numbered steps).
- **API docs** — notes explain behavior, side effects, constraints; they do not
  say "call endpoint X first" (that is a prerequisite step).
- **Docstrings** — notes describe behavior (e.g. "not thread-safe"); they do not
  say "call this only from the main thread" (that is a constraint in the
  description).
- **Commit bodies** — notes explain why a change was made; they do not give usage
  instructions (those belong in release notes).
- **Error messages** — fix guidance is part of the error text (descriptive +
  imperative), not a separate skipped NOTE.

### Paradigm notes

- **OOP** — notes describe design decisions or state constraints: "NOTE: The
  object enters a disposed state after a call to `dispose()`." (not "you must not
  call other methods").
- **Functional** — notes explain purity/performance: "NOTE: This function is
  pure. It has no side effects." (not "you can memoize it").
- **Procedural (C/Go/Bash)** — notes explain state between steps: "NOTE: The file
  descriptor stays open until the code calls `close()`."
- **Declarative (SQL/Terraform/K8s)** — notes explain platform behavior: "NOTE:
  The `depends_on` attribute controls resource creation order." (not "always set
  this").
- **Systems** — notes clarify compiler-enforced constraints: "NOTE: This function
  borrows the value immutably. The compiler rejects code that violates this
  constraint."

### Grammar notes

- **Descriptive vs imperative mood** — a note uses descriptive mood ("The cache
  expires after 300 seconds."). If a sentence is imperative, it is a work step or
  safety instruction, not a note.
- **Modal verbs in notes** — "can"/"may"/"will" are acceptable when they describe
  system behavior ("The system can process 500 concurrent connections."). "must"
  in a note is a warning sign: move it to a WARNING/CAUTION.
- **Sentence length** — each note sentence ≤ 25 words; split or move to the
  procedure body if longer.
- **Articles** — do not omit articles in notes; the article rule still applies.
- **Technical code nouns** — function/class/command names in notes are technical
  nouns (Rule 1.5); the words around them still must follow approved-vocabulary
  and part-of-speech rules.

### Edge cases

- **Framework names that look like verbs** (React, Express, Spring) — in a note
  they are proper nouns, not imperative verbs: "NOTE: The `React` component tree
  re-renders when the state changes."
- **Generated docs** — fix the source comment, not the generator output; do not
  rely on the generator to filter notes.
- **Interactive tutorials** — "try changing the value" is an instruction;
  acceptable only in exploratory tutorial exercises, never in reference/README/
  API docs.
- **Note that names a command without commanding** — allowed: "NOTE: The
  `terraform plan` command shows the changes Terraform will apply." (descriptive;
  the command name is a technical noun). "Run `terraform plan`" is an instruction
  and not a note.
- **Conditional descriptive clauses** — "if" in a note does not make it an
  instruction if the clause describes system behavior: "NOTE: The server returns
  503 if the upstream does not respond within 10 seconds." (descriptive). "If you
  get a 503, check the health endpoint" is a troubleshooting step, not a note.

## Cross-references (Section 5)

- **Rule 1.1** (Approved Words) — short, approved words make 20-word sentences
  easier; modal verbs in 5.3 often violate 1.1.
- **Rule 1.2** (Part of Speech) — wrong part of speech produces wordy
  constructions that exceed the limit.
- **Rule 1.4** (Approved Verb Forms) — non-standard verb forms add words; the
  base imperative form is the approved form.
- **Rule 1.5** (Technical Code Nouns) — long technical names are allowed;
  abbreviate after first definition to stay within the limit.
- **Rule 1.7** (No Technical Nouns as Verbs) — nominalizations add words
  ("perform an initialization" → "initialize").
- **Rule 1.12** (Technical Verbs) — short technical verbs (build, push, run,
  test, lint) keep sentences short.
- **Rule 5.3 ↔ 5.2** — split per 5.2, then check each sentence against 5.1; each
  split sentence must be imperative (5.3).
- **Rule 5.4 ↔ 5.3** — 5.4 supplies the condition, 5.3 supplies the verb form:
  `[condition] , [imperative verb] [object]`.
- **Rule 5.5 ↔ 5.3/5.4** — notes are descriptive only; a condition that leads to
  a command is a step, not a note.
- **Rule 7.1 / 7.2** (Risk Signal Words / Safety Instructions) — WARNING and
  CAUTION are the only contexts where "must" precedes an imperative; safety
  conditions use the condition-before-command pattern inside the safety block.
- **Rule 9.1** (Descriptive Writing) — notes contain descriptive text; Section 9
  applies fully.



## rules-sec6.md

# Level 4 — Section 6: Writing Practice (Rules 6.1–6.6)

This slice distills **Section 6 (Writing Practice)** of the STE-Code controlled
standard for people who use LLMs to generate code documentation. Section 1 controls
*which words* you may use. Section 6 controls *how you assemble them* — sentence
length, sentence structure, connective signals, and paragraph shape.

Section 6 applies to **descriptive** code documentation: README files, API reference
docs, docstrings, inline comments, commit messages, error messages, log entries,
changelogs, release notes, and configuration file comments. Procedural steps are
governed by Section 5; Section 6 still applies to any note or rationale inside a step.

## The six rules at a glance

| Rule | Requirement | Failure signal |
|---|---|---|
| 6.1 | Give information gradually. One subject per sentence. | Two independent clauses joined by `and`/`but`/`while`. |
| 6.2 | Use key words and key phrases for logical structure. Do not vary them. | The same concept named `client`, then `connection`, then `handle`. |
| 6.3 | Write short sentences. Maximum 25 words. | A sentence that needs a comma to be parsed at all. |
| 6.4 | Use paragraphs to show related information. Start with a topic sentence. | A wall of prose with no lead sentence. |
| 6.5 | Each paragraph has only one topic. | The topic sentences do not form an outline. |
| 6.6 | No paragraph has more than six sentences. | Seven or more sentences under one topic. |

The rules compose in order. Apply 6.1 to split compound sentences. Apply 6.3 to check
each resulting sentence against the 25-word limit. Apply 6.2 to connect them. Apply
6.4 to group them, 6.5 to keep each group single-topic, and 6.6 to cap the group size.

## Approved connectives

Use only these connecting words and phrases:

`and`, `but`, `then`, `thus`, `also`, `however`, `therefore`, `for example`,
`as a result`, `at the same time`.

Put the connective at the start of the sentence so the reader sees the signal before
the content. Do **not** use `moreover`, `furthermore`, `nevertheless`, `subsequently`,
`utilize`, or `leverage` as connectors. They are not in the approved set.

---

## Rule 6.1 — Give information gradually

**Rule.** In descriptive code documentation, give information gradually. Make sure that
each sentence contains only one subject. If you give too much information too quickly,
the documentation is not easy to understand, and the developer must read it again.

Do not combine multiple actions, multiple conditions, or multiple subjects in one
sentence.

### The single-subject test

The subject is the noun phrase that performs the action of the main verb.

- `The function validates the input and returns a result.` — **OK.** One subject, two
  verbs that share it.
- `The function validates the input and the middleware logs the result.` — **Split.**
  Two subjects. Write: `The function validates the input. The middleware logs the result.`

Conjunction guidance:

- **Coordinating** (`and`, `or`, `but`): if the conjunction joins two independent
  clauses, split at the conjunction. If it joins two verbs or two objects that share
  one subject, keep the sentence.
- **Subordinating** (`because`, `since`, `although`, `while`, `when`, `if`, `unless`):
  one main clause plus one dependent clause is acceptable, provided the dependent
  clause does not introduce a new subject with its own chain of actions.
- **Relative** (`which`, `that`, `who`): a relative clause that describes the main
  subject is acceptable. A relative clause that introduces a new subject and new
  actions must become its own sentence.

### Worked example — authentication middleware

> **Non-STE:** The authentication middleware validates bearer tokens from the
> authorization header by calling the `validateToken` function in the security module
> which decodes the JWT payload using `HS256` and checks the `exp` claim against the
> current server time before extracting the `sub` and `role` claims and attaching them
> to `request.auth`, and if the token is expired or malformed the middleware returns a
> `401 Unauthorized` response with a JSON error body containing a `message` field and
> an `errorCode` field set to `TOKEN_EXPIRED` or `TOKEN_MALFORMED` respectively, while
> also logging the failure to the audit trail via `AuditLogger.log`.

> **STE:** The authentication middleware validates each incoming request. The
> middleware reads the bearer token from the `Authorization` header. It sends the token
> to the `validateToken` function in the `security` module. The `validateToken` function
> decodes the JWT payload. It uses the `HS256` algorithm from the `jwt-signer` library.
> Then it compares the `exp` claim with the current server time. If the token is not
> expired and not malformed, the function gets the `sub` and `role` claims. It attaches
> these claims to the `request.auth` object.
>
> If the token is expired, the middleware returns a `401 Unauthorized` response. The
> response body is a JSON object:
>
> - The `message` field contains a description of the error.
> - The `errorCode` field is set to `TOKEN_EXPIRED`.
>
> If the token is malformed, the middleware returns a `401 Unauthorized` response. The
> `errorCode` field is set to `TOKEN_MALFORMED`.
>
> The middleware also logs each failure to the audit trail. It calls the
> `AuditLogger.log` static method. This method writes a record to the `audit_events`
> table in the primary database. The write uses an asynchronous pattern that does not
> block the response pipeline.

```typescript
// STE: split the contract into one fact per comment line.
// The authenticate middleware checks each incoming request.
// It reads the bearer token from the Authorization header.
// It sends the token to validateToken in the security module.
// If the token is expired, the middleware returns 401 with errorCode TOKEN_EXPIRED.
// If the token is malformed, the middleware returns 401 with errorCode TOKEN_MALFORMED.
// The middleware logs each failure through AuditLogger.log.
function authenticate(req: Request, res: Response, next: NextFunction): void {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) { return res.status(401).json({ message: "Missing token", errorCode: "TOKEN_MALFORMED" }); }
  const result = validateToken(token);
  if (result.status === "expired") { return res.status(401).json({ message: "Token expired", errorCode: "TOKEN_EXPIRED" }); }
  if (result.status === "malformed") { return res.status(401).json({ message: "Token malformed", errorCode: "TOKEN_MALFORMED" }); }
  req.auth = { sub: result.sub, role: result.role };
  next();
}
```

### By documentation type

| Type | What "one piece of information" means |
|---|---|
| README | One concept per section; one subject per sentence. Purpose, then install, then a basic usage example — each in its own section. |
| API reference | Method and path in one sentence. One sentence per parameter, per response field, per status code. |
| Docstrings / comments | One behavior per sentence. Three behaviors need three sentences. Comments explain one line or one block, never the whole function. |
| Commit messages | One logical change per commit. One sentence for the summary line; one sentence per sub-change in the body. |
| Error messages / logs | One problem per message; one event per log line. Split multi-cause messages into distinct messages with distinct error codes. |
| Changelogs | One change per entry. Do not mix a feature, a fix, and a deprecation in one sentence. |

### Paradigm-specific guidance

- **Object-oriented (Java, C++, C#, Python classes).** Describe one method or one class
  behavior per sentence. For an inheritance chain, describe the base class behavior
  first, then the override, then the side effect — each in its own sentence.
- **Functional (Haskell, Elixir, Clojure, Rust).** Describe one transformation per
  sentence. Break a `|>` pipeline or a `>>=` chain into one sentence per step.
- **Procedural (C, Go, Bash).** Describe one step or one branch per sentence. Do not
  combine an if-else chain, a loop body, and the cleanup code.
- **Declarative (SQL, Terraform, Kubernetes YAML).** Describe one resource, one
  constraint, or one column per sentence. Dependencies are listed one by one.
- **Systems (Rust ownership, C memory).** Describe one ownership rule, one lifetime
  constraint, or one memory operation per sentence. Allocation, ownership transfer,
  and the deallocation guarantee are separate subjects.

```elixir
# STE: document each pipeline step on its own line.
# process_order accepts an Order.
# It applies validate_order to the order.
# It applies calculate_total to the validated order.
# It applies create_invoice to the order with the total.
# It applies send_confirmation to the invoice.
def process_order(order) do
  order
  |> validate_order()
  |> calculate_total()
  |> create_invoice()
  |> send_confirmation()
end
```

```c
// STE: one memory contract rule per line.
// The allocate_buffer function allocates a buffer on the heap.
// It uses malloc for the allocation.
// The function returns a pointer to the buffer.
// The caller becomes the owner of the buffer.
// The caller must free the buffer with free.
// If the allocation fails, the function returns NULL.
// It also sets errno to ENOMEM.
void* allocate_buffer(size_t size, size_t* out_size) {
  void* buf = malloc(size);
  if (!buf) { errno = ENOMEM; return NULL; }
  *out_size = size;
  return buf;
}
```

### Edge cases

- **A framework name that contains several concepts.** Treat
  `UserAuthenticationAndAuthorizationService` as one technical noun. Do not split the
  identifier across sentences. The rule applies to the prose around it: `The
  UserAuthenticationAndAuthorizationService handles user login. It also handles
  permission checks.`
- **Generated documentation.** OpenAPI generators, JSDoc renderers, and Sphinx autodoc
  often emit compound sentences from structured metadata. If you cannot control the
  output, add a plain-language summary above it that obeys Rule 6.1. Generated content
  is exempt unless you edit the source annotations.
- **Control-flow keywords.** `if`, `else`, `while`, and `try`/`catch` describe branching
  with several outcomes. Use one sentence per branch. Describe the `try` block and the
  `catch` block in separate sentences.
- **Brevity contexts (CLI help, error codes).** Use the minimum number of sentences, but
  each one still has one subject. Use fragments only where the display format enforces
  them, as in a one-line usage string.
- **Rewriting existing documentation.** Check whether the compound structure hides a
  dependency. If action B depends on action A, describe A first in its own sentence.

### Grammar note

Working memory holds about four to seven items. A sentence with several subjects, verbs,
and objects forces the reader to hold all of them until the sentence ends. In code
documentation the reader is already processing technical concepts and control flow, so
the cognitive load is higher than in ordinary prose.

In procedures, each imperative step has the same implied subject (`you`), so imperative
steps follow this rule naturally. Still write `Stop the server. Then restart the
server.` — not `Stop and restart the server.`

---

## Rule 6.2 — Use key words and key phrases to give your text a logical structure

**Rule.** Key words are terms that occur several times in a documentation block to link
different concepts. Key phrases are multi-word expressions with the same function. Key
words and key phrases show how information is related and give the documentation a
logical structure. When you use a key word, do not change it. The same terminology keeps
the documentation clear and correct.

Connecting words and connecting phrases work like traffic signs. They tell the reader
whether the information is new, different, or a result of previous information.

### How the connectives signal

| Connective | Signal | Use it when |
|---|---|---|
| `and`, `also` | Addition | The new sentence adds information about the same key word. |
| `but`, `however` | Contrast | The new sentence differs from the expectation just set. |
| `then` | Sequence | The new sentence is the next step involving the key word. |
| `thus`, `therefore`, `as a result` | Consequence | The new sentence follows from the previous one. |
| `at the same time` | Concurrency | Two effects happen together. |
| `for example` | Illustration | The new sentence instantiates the previous claim. |

### Keeping the key word stable

> **Non-STE:** The parser reads the input stream. Invalid tokens are detected by the
> lexer. An error is returned to the caller.

> **STE:** The parser reads the input stream. The parser detects invalid tokens. The
> parser returns an error to the caller.

In the Non-STE version the topic shifts from `parser` to `invalid tokens` to `an error`,
and the reader must reconstruct that all three sentences are about the parser. In the
STE version, `parser` is the topic of every sentence.

**Multi-word key phrases stay whole.** When the key phrase is a multi-word technical
term (`connection pool`, `rate limiter`, `retry policy`), keep the full phrase. Do not
shorten `connection pool` to `pool` halfway through a block.

> **Non-STE:** The connection pool limits concurrent database connections. The pool size
> is configurable. Idle connections are recycled after the timeout.
>
> **STE:** The connection pool limits concurrent database connections. The connection
> pool size is configurable. The connection pool recycles idle connections after the
> timeout.

**Dangling key words.** A dangling key word is a term introduced once and never
repeated. The reader expects it to matter and never meets it again.

```text
# Non-STE
The build system compiles TypeScript and bundles static assets.
The output goes to the dist/ directory.
Deployment uses a Docker container.

# STE (resolved)
The build system compiles TypeScript and bundles static assets.
The build system writes the output to the dist/ directory.
The deploy system copies the dist/ directory into a Docker container.
```

### Cohesive ties

Three tie types are permitted:

1. **Repetition.** The same word appears again: `The middleware validates the request.
   The middleware reads the token.`
2. **Pronoun reference.** `it`, `they`, `this` refer back to the key word. Use pronouns
   sparingly. After two sentences, repeat the full key word to prevent ambiguity.
3. **Approved synonym or hypernym.** `The function returns a Result. The value contains
   the parsed data.` The STE-Code synonym table restricts which substitutions are safe.

### Edge cases

- **A framework name that is also an unapproved word.** Keep the exact identifier as the
  key word. Do not paraphrase a library name to satisfy the vocabulary rules.
- **A code keyword that conflicts with the rule.** Language keywords (`return`, `yield`,
  `import`) stay in code font and keep their exact spelling when used as key words.
- **Generated documentation.** If the generator varies terminology, fix the source
  annotations. If you cannot, add a hand-written summary that uses stable key words.
- **Multi-language repositories.** Choose one cross-language key word and give the
  language-specific names once as a clarification: `The configuration is stored in a map
  (Python: dict, Java: HashMap, Go: map). The map uses string keys.` Do not rotate
  `dict`, `HashMap`, and `map` as if they were three concepts.

### Supporting rules from Section 1

- **Rule 1.11 — One term per concept.** Key words work only if the same term names the
  same concept. Switching synonyms breaks the key word chain.
- **Rule 1.5 — Technical code nouns are allowed.** A class, function, or library name may
  be a key word even when it is not in the approved terminology.
- **Rule 1.8 — Use standard technical nouns.** An invented key word weakens the
  structure because the reader does not recognize it as a key term.
- **Rule 1.9 — Prefer short technical nouns.** A key word such as
  `AbstractAsynchronousDatabaseConnectionManager` is too long to repeat.

---

## Rule 6.3 — Write short sentences. Use a maximum of 25 words in each sentence

**Rule.** Good code documentation uses short sentences for complex topics. Short
sentences give a clear structure and make information easier to understand. In
descriptive code documentation the maximum sentence length is **25 words**, because
descriptive text is more complex than procedural text.

The limit is a ceiling, not a target. Most good sentences are much shorter.

### Worked examples

> **STE:** The authentication middleware validates each incoming request before the
> controller processes it. *(11 words)*

> **Non-STE:** This function provides the ability to run arbitrary software applications
> within a sandboxed execution environment that isolates system resources. *(21 words)*
>
> **STE:** This function lets you run software applications in a sandbox. The sandbox
> isolates system resources. *(9 and 5 words)*
>
> Splitting improves clarity even when the original is already under 25 words.

> **Non-STE:** The configuration loader reads the YAML manifest file from the filesystem
> and parses it into an in-memory representation that other modules can query at runtime
> to determine their operational parameters. *(32 words)*
>
> **STE:** The configuration loader reads the YAML manifest file from the filesystem. It
> parses the file into an in-memory representation. Other modules can query this
> representation at runtime. They use it to find their operational parameters.

> **Non-STE:** The cache invalidation strategy employs a time-to-live mechanism combined
> with a least-recently-used eviction policy to ensure that stale data is removed and
> memory consumption remains within the allocated heap budget. *(34 words)*
>
> **STE:** The cache invalidation strategy uses a time-to-live mechanism. It also uses a
> least-recently-used eviction policy. Together, these mechanisms remove stale data. They
> also keep memory consumption within the allocated heap budget.

```python
# config/loader.py — STE docstring: one behavior per line, each under 25 words.
def load_config(path: Path) -> Config:
    """Read the YAML manifest from the filesystem.

    Parse the file into an in-memory representation.
    Other modules query this representation at runtime.
    They use it to find their operational parameters.
    """
    raw = path.read_text()
    data = yaml.safe_load(raw)
    return Config(data)
```

### Counting rules

- Count words, not characters. A hyphenated technical term (`least-recently-used`,
  `time-to-live`) counts as one word.
- An identifier in code font (`ConnectionPool`, `req.headers.authorization`) counts as
  one word, however long it is.
- A type signature quoted inline counts as one word.
- Do not count the words inside a code block or a table cell.

### By documentation type

- **README.** One sentence for the project purpose, one for the prerequisites, one for
  the install command. A reader must find the install step without parsing a paragraph.
- **API reference.** One short sentence for the path and method. One per parameter. One
  per response field. Developers scan for the one detail they need.
- **Docstrings.** One line per behavior. A summary line, then one line per parameter,
  return value, and raised error.
- **Commit messages.** Keep the summary line short and put each detail on its own body
  line.
- **Error messages.** State one problem in one short sentence. Long error strings are
  truncated by log viewers and terminals.

### Edge cases

- **Long technical terms.** A required identifier may itself be long. It still counts as
  one word. Do not rename an API to satisfy the limit.
- **Compound type signatures.** `Map<String, List<Order>>` is one word. If the signature
  makes the sentence unreadable, move it to a code block and refer to it by name.
- **Legal and license text.** Legal wording is often fixed and cannot be edited. Quote it
  verbatim, then give a short plain-language summary that obeys the limit.
- **Generated documentation.** Long generated sentences are exempt. Fix them at the
  annotation source, or add a compliant summary above them.

### Grammar note

Sentence length is a proxy for clause density. A sentence with one main clause and at
most one dependent clause is normally under 25 words on its own. Prefer coordination that
shares one subject over subordination that stacks clauses. When you must connect two
independent ideas, use a connecting word at the start of the second sentence instead of a
comma splice.

---



## rules-sec7.md

# Level 4 — Section 7: Safety Instructions (Rules 7.1–7.3)

This slice distills **Section 7 (Safety Instructions)** of the STE-Code controlled
standard for people who use LLMs to generate code documentation. Sections 1–6 control
words, sentences, and paragraphs. Section 7 controls the one construct that must never
be misread: the safety instruction.

A safety instruction is any callout that tells a reader an action can harm the system,
the data, or the users. In code documentation it appears in README files, API
reference docs, docstrings, inline comments, commit messages, error messages,
changelogs, release notes, and configuration files.

## The three rules at a glance

| Rule | Requirement | Failure signal |
|---|---|---|
| 7.1 | Use a signal word (`WARNING` / `CAUTION`) that matches the level of risk. | `CAUTION` on a credential leak; `WARNING` on a slow function. |
| 7.2 | Start the body with a clear command or a clear condition. | The callout opens with background prose or with the consequence. |
| 7.3 | Give the risk or possible result. | `DO NOT USE eval().` with no explanation of what happens. |

A complete safety instruction has three parts, always in this order:

```
<SIGNAL WORD>: <COMMAND or CONDITION>. <CONSEQUENCE>. <RISK ESCALATION>.
```

Remove the signal word and the reader cannot triage. Remove the command and the
instruction is not actionable. Remove the consequence and the reader dismisses it.

## Severity model

| Signal word | Use for | Changelog / release-note level |
|---|---|---|
| `WARNING` | Security vulnerability, data loss, system corruption, service unavailability. | `BREAKING` |
| `CAUTION` | Unexpected behavior, performance degradation, incorrect results, build failure. | `DEPRECATED` |
| `NOTE` | Information with no risk. | `NOTE` |

When two levels of risk occur together, use `WARNING`. Use one signal word only — never
`BREAKING: WARNING:`. Mention the breaking nature in the body instead.

---

## Rule 7.1 — Use a signal word that identifies the level of risk

**Rule.** In code documentation, use a signal word (for example, `WARNING` or `CAUTION`)
to immediately show your reader the level of the related risk.

- Risk of security vulnerabilities, data loss, or system corruption → `WARNING`.
- Risk of unexpected behavior, performance degradation, or incorrect results → `CAUTION`.
- Two levels of risk together → `WARNING`.

The signal word is a classification, not emphasis. Do not let it become routine noise:
a document where every callout is a `WARNING` has no signal at all.

### Escalation: the core pattern

> **Non-STE:** CAUTION: ALWAYS VALIDATE INPUT DATA.
>
> **STE:** WARNING: BEFORE YOU PROCESS INPUT DATA, MAKE SURE THAT YOU SANITIZE AND
> VALIDATE THE DATA. UNSANITIZED INPUT CAN CAUSE SECURITY BREACHES AND DATA LOSS.

The original names an abstract obligation and classifies it as `CAUTION`. The true risk
is a security breach and data loss, so the correct signal word is `WARNING`. The STE
version escalates the signal word, gives a command, and names the risk.

The mirror case is over-classification:

> **Non-STE:** WARNING: This function is slow for large inputs.
>
> **STE:** CAUTION: THIS FUNCTION HAS O(N²) TIME COMPLEXITY. FOR INPUTS LARGER THAN
> 10,000 ITEMS, THE FUNCTION CAN TAKE SEVERAL MINUTES TO COMPLETE. USE `fastSort` FOR
> LARGE INPUTS. `fastSort` HAS O(N LOG N) TIME COMPLEXITY.

Performance degradation is a `CAUTION`-level risk. Downgrade, give a threshold, and
give an alternative.

### By documentation type

| Type | Use `WARNING` for | Use `CAUTION` for |
|---|---|---|
| README | Security-critical setup steps. | Configuration that can cause incorrect behavior. |
| API docs | Sensitive data, authentication, destructive endpoints. | Side effects, rate limits. |
| Docstrings / comments | Functions that can cause vulnerabilities or corruption. | Performance pitfalls, non-obvious side effects. |
| Commit messages | Security fixes, data-loss prevention. | Behavior changes downstream consumers must know. |
| Error messages | Detected compromise or corruption conditions. | Detected conditions that give incorrect results. |

Place the signal word at the top of the relevant section. Do not bury it in a paragraph.

**README — `WARNING` (security) and `CAUTION` (configuration):**

> **STE:** WARNING: DO NOT COMMIT THE API KEY TO VERSION CONTROL. AN EXPOSED API KEY
> CAN CAUSE UNAUTHORIZED ACCESS AND DATA LOSS.

> **STE:** CAUTION: BEFORE YOU START THE APPLICATION, CHECK THAT THE PORT NUMBER DOES
> NOT CONFLICT WITH OTHER SERVICES. A PORT CONFLICT CAN CAUSE THE APPLICATION TO FAIL.

**API documentation — destructive endpoint and rate limit:**

> **STE:** WARNING: `DELETE /users/:id` REMOVES THE USER AND ALL RELATED DATA
> PERMANENTLY. THIS OPERATION CANNOT BE UNDONE. VERIFY THE USER ID BEFORE YOU SEND THE
> REQUEST.

> **STE:** CAUTION: THE ENDPOINT ALLOWS A MAXIMUM OF 100 REQUESTS PER MINUTE. IF YOU
> EXCEED THE LIMIT, THE ENDPOINT RETURNS A 429 ERROR. MONITOR THE
> `X-RateLimit-Remaining` HEADER.

**Docstring — `WARNING` for a security-sensitive contract:**

```python
def execute_sql(query: str, params: tuple = ()) -> list:
    """Run a raw SQL query.

    WARNING: THIS FUNCTION EXECUTES THE QUERY DIRECTLY. SANITIZE ALL
    USER INPUT BEFORE YOU PASS IT TO THIS FUNCTION. UNSANITIZED INPUT
    CAN CAUSE SQL INJECTION ATTACKS AND DATA LOSS.

    Parameters:
        query: The raw SQL query string.
        params: The query parameters. The default is an empty tuple.

    Returns:
        A list of result rows.
    """
```

**JSDoc — `CAUTION` for a performance contract:**

```javascript
/**
 * Caches the result of an expensive computation.
 *
 * CAUTION: THE CACHE USES MEMORY PROPORTIONAL TO THE NUMBER OF
 * UNIQUE ARGUMENTS. FOR UNBOUNDED INPUT SETS, USE A CACHE WITH
 * A SIZE LIMIT. AN UNLIMITED CACHE CAN CAUSE MEMORY EXHAUSTION.
 *
 * @param {Function} fn - The function to cache.
 * @returns {Function} A cached version of the function.
 */
```

**Commit messages** may use the signal word as the type prefix, which lets changelog
tools group commits by severity:

> **STE:** WARNING: Prevent SQL injection in the login form. The previous code did not
> sanitize the `username` parameter. This vulnerability could permit unauthorized
> database access.

> **STE:** CAUTION: Change the default timeout from 30 seconds to 10 seconds. Update
> all callers that rely on the previous default. The shorter timeout can cause
> connection failures in high-latency environments.

**Error messages** are read during incidents, so they must be actionable:

> **STE:** WARNING: THE REQUEST SIGNATURE IS NOT VALID. THE REQUEST MAY HAVE BEEN
> TAMPERED WITH. REJECT THE REQUEST. CHECK YOUR SIGNING KEY AND ALGORITHM.

> **STE:** CAUTION: THE `max_connections` VALUE IS GREATER THAN THE `pool_size` VALUE.
> THIS CONFIGURATION CAN CAUSE CONNECTION FAILURES. SET `max_connections` TO A VALUE
> THAT IS NOT MORE THAN `pool_size`.

### By paradigm

| Paradigm | `WARNING` triggers | `CAUTION` triggers |
|---|---|---|
| Object-oriented | A subclass override that breaks a security invariant. | A method that mutates shared state. |
| Functional | An unsafe escape hatch that breaks referential transparency. | A lazy operation that can cause a space leak. |
| Procedural | Buffer overflow, use-after-free, undefined behavior. | Platform-specific behavior, resource limits. |
| Declarative | Data destruction, public exposure of a resource. | Values with subtle effects on behavior. |
| Systems | Undefined behavior, data races, memory corruption. | Performance tradeoffs of unsafe optimizations. |

**Object-oriented — override that must preserve a security invariant (Java):**

> **STE:** WARNING: OVERRIDE THE `validate` METHOD WITH CARE. CALL `super.validate()`
> BEFORE YOU ADD CUSTOM VALIDATION LOGIC. IF YOU SKIP THE BASE VALIDATION, UNTRUSTED
> DATA CAN BYPASS SECURITY CHECKS.

```java
class PaymentRequestValidator extends RequestValidator {
    @Override
    void validate(Request request) {
        // WARNING: CALL super.validate() BEFORE YOU ADD CUSTOM LOGIC.
        super.validate(request);
        PaymentRequest payment = (PaymentRequest) request;
        if (payment.getAmount() <= 0) {
            throw new IllegalArgumentException("Amount must be greater than zero");
        }
    }
}
```

**Object-oriented — mutable shared state (C++):**

> **STE:** CAUTION: THE `invalidateCache` METHOD MODIFIES THE INTERNAL CACHE. THIS
> CHANGE AFFECTS ALL THREADS THAT USE THE CACHE. USE A LOCK BEFORE YOU CALL THIS METHOD.

**Functional — escape hatch and space leak (Haskell):**

> **STE:** WARNING: `unsafePerformIO` BYPASSES THE IO TYPE SYSTEM. THIS FUNCTION HIDES
> SIDE EFFECTS IN PURE CODE. INCORRECT USE CAN CAUSE NONDETERMINISTIC BEHAVIOR AND DATA
> CORRUPTION. USE THIS FUNCTION ONLY WHEN NO SAFE ALTERNATIVE EXISTS.

> **STE:** CAUTION: `foldl` ACCUMULATES UNEVALUATED EXPRESSIONS (THUNKS). A LARGE
> ACCUMULATOR CAN CAUSE A SPACE LEAK AND MEMORY EXHAUSTION. USE `foldl'` FOR STRICT
> ACCUMULATION.

**Procedural — buffer overflow (C) and platform behavior (Go):**

> **STE:** WARNING: `strcpy` DOES NOT CHECK THE SIZE OF THE DESTINATION BUFFER. IF THE
> SOURCE STRING IS LARGER THAN THE DESTINATION BUFFER, THE FUNCTION WRITES PAST THE
> BUFFER BOUNDARY. THIS BUFFER OVERFLOW CAN CAUSE SECURITY VULNERABILITIES AND SYSTEM
> CRASHES. USE `strncpy` WITH A SIZE LIMIT.

> **STE:** CAUTION: THE `filepath` PACKAGE USES THE OPERATING SYSTEM PATH SEPARATOR.
> USE `filepath.Join` OR `filepath.FromSlash` TO BUILD CROSS-PLATFORM PATHS. HARDCODED
> SEPARATORS CAUSE INCORRECT PATHS.

**Declarative — destructive SQL, Terraform recreation, public exposure:**

> **STE:** WARNING: THIS MIGRATION DROPS THE `users` TABLE. ALL USER DATA IS DELETED
> PERMANENTLY. BACK UP THE DATABASE BEFORE YOU RUN THIS MIGRATION. VERIFY THAT YOU RUN
> THE MIGRATION AGAINST THE CORRECT DATABASE.

> **STE:** CAUTION: IF YOU CHANGE THE `subnet_id` ARGUMENT, TERRAFORM DESTROYS THE
> EXISTING EC2 INSTANCE AND CREATES A NEW ONE. THIS RECREATION CAUSES DOWNTIME. THE
> INSTANCE PUBLIC IP ADDRESS CHANGES. PLAN THE CHANGE DURING A MAINTENANCE WINDOW.

> **STE:** WARNING: A SERVICE OF TYPE `LoadBalancer` EXPOSES THE APPLICATION TO THE
> PUBLIC INTERNET. UNAUTHORIZED USERS CAN SEND REQUESTS TO THE APPLICATION. MAKE SURE
> THAT AUTHENTICATION AND NETWORK POLICIES ARE IN PLACE BEFORE YOU APPLY THIS
> CONFIGURATION.

**Systems — undefined behavior (Rust) and an unsafe optimization:**

> **STE:** WARNING: DEREFERENCING A RAW POINTER CAN CAUSE UNDEFINED BEHAVIOR. UNDEFINED
> BEHAVIOR CAN CORRUPT MEMORY, CAUSE SECURITY VULNERABILITIES, AND CRASH THE PROGRAM.
> BEFORE YOU DEREFERENCE A RAW POINTER, CHECK THAT: (1) THE POINTER IS NOT NULL.
> (2) THE POINTER IS CORRECTLY ALIGNED. (3) THE POINTER POINTS TO VALID, INITIALIZED
> MEMORY.

> **STE:** CAUTION: `MaybeUninit` SKIPS INITIALIZATION TO IMPROVE PERFORMANCE. IF YOU
> READ UNINITIALIZED MEMORY, THE PROGRAM BEHAVIOR IS UNDEFINED. MAKE SURE THAT YOU
> INITIALIZE THE VALUE BEFORE YOU READ IT. MEASURE THE PERFORMANCE GAIN BEFORE YOU USE
> THIS TYPE.

### Six classification failures

**1 — Under-classified security risk.**

> **Non-STE:** CAUTION: Store the API key in an environment variable.
>
> **STE:** WARNING: STORE THE API KEY IN AN ENVIRONMENT VARIABLE. DO NOT HARDCODE THE
> API KEY IN THE SOURCE CODE. AN EXPOSED API KEY CAN CAUSE UNAUTHORIZED ACCESS, DATA
> THEFT, AND SERVICE ABUSE. ADD THE `.env` FILE TO `.gitignore`.

**2 — Correct signal word, missing consequence.**

> **Non-STE:** WARNING: Run this migration carefully.
>
> **STE:** WARNING: BEFORE YOU RUN THIS MIGRATION, BACK UP THE `transactions` TABLE.
> THE MIGRATION REMOVES ALL RECORDS OLDER THAN 90 DAYS. THE DATA CANNOT BE RECOVERED
> AFTER THE MIGRATION COMPLETES. VERIFY THE DATE THRESHOLD AGAINST YOUR RETENTION
> POLICY.

**3 — Abstract caution.**

> **Non-STE:** CAUTION: Be mindful of thread safety when using this library.
>
> **STE:** CAUTION: THE `Cache` CLASS IS NOT THREAD-SAFE. IF YOU SHARE A `Cache`
> INSTANCE ACROSS THREADS, RACE CONDITIONS CAN CAUSE INCORRECT CACHE ENTRIES AND
> APPLICATION CRASHES. USE `ConcurrentCache` FOR MULTI-THREADED APPLICATIONS. USE A
> MUTEX FOR MANUAL SYNCHRONIZATION.

**4 — Over-classified performance risk.** See the O(N²) example above. Performance is a
`CAUTION`, so downgrade the signal word, give a threshold, and give an alternative.

**5 — No signal word at all.**

> **Non-STE:** The DEBUG_MODE environment variable controls verbose logging. Setting it
> to true in production will leak sensitive information.
>
> **STE:** WARNING: DO NOT SET `DEBUG_MODE=true` IN A PRODUCTION ENVIRONMENT. DEBUG
> MODE WRITES SENSITIVE DATA TO THE LOG OUTPUT. THIS DATA INCLUDES REQUEST BODIES,
> AUTHENTICATION TOKENS, AND DATABASE QUERIES. AN ATTACKER WITH LOG ACCESS CAN STEAL
> USER CREDENTIALS.

**6 — Mixed levels in one callout.**

> **Non-STE:** CAUTION: The reset method clears the database and disables
> authentication, only use in development.
>
> **STE:** WARNING: THE `reset` METHOD CLEARS THE DATABASE AND DISABLES
> AUTHENTICATION. IF YOU CALL THIS METHOD IN A PRODUCTION ENVIRONMENT, ALL USER DATA IS
> DELETED AND ALL REQUESTS BYPASS AUTHENTICATION. THIS METHOD IS FOR DEVELOPMENT USE
> ONLY. CHECK THE `NODE_ENV` VARIABLE BEFORE YOU CALL THIS METHOD.

### Edge cases

**A framework uses "warning" as a name.** Python's `warnings`, Rust's
`#[allow(warnings)]`, and `console.warn()` are technical code nouns. Put them in
backticks; reserve bare uppercase `WARNING` for the signal word.

> **STE:** CAUTION: THE `warnings` MODULE SUPPRESSES WARNINGS BY DEFAULT. THE OUTPUT
> FROM `warn()` CALLS IS NOT SHOWN. CALL `warnings.simplefilter('always')` TO SHOW ALL
> WARNINGS.

**A third-party library uses a different convention.** Translate `DANGER`, `CRITICAL`,
or `IMPORTANT` into the STE-Code signal word for the actual risk level. Do not
replicate the foreign convention.

**Generated code carries auto-inserted callouts.** Do not edit generated comments — the
generator overwrites them. Add your own signal word in the documentation that wraps the
generated code. If the generator misclassifies a risk, open an issue with that project.

**A breaking change overlaps with a warning.** Use `WARNING` and state the breaking
nature in the body: `WARNING: THE `encrypt` FUNCTION NOW REQUIRES A `key` PARAMETER.
THIS IS A BREAKING CHANGE. UPDATE ALL CALLERS TO PASS A KEY ARGUMENT.`

**Translated documentation.** Translate the signal word with the standard term for each
language and keep the format (uppercase, colon, single space). Maintain a glossary.

| Language | WARNING | CAUTION |
|---|---|---|
| English | WARNING | CAUTION |
| Spanish | ADVERTENCIA | PRECAUCIÓN |
| French | AVERTISSEMENT | ATTENTION |
| German | WARNUNG | VORSICHT |
| Japanese | 警告 | 注意 |

### Grammar notes for Rule 7.1

- **Placement.** The signal word is the first word of the instruction, at the start of
  the line, with nothing before it. `Important: WARNING: …` is wrong.
- **Punctuation.** Signal word, colon, one space, then the instruction.
- **Case.** Uppercase the signal word. Uppercase is part of the signal, not emphasis.
  `Warning:` and `warning:` are both wrong.
- **Structure.** Command or condition → consequence → risk escalation, in that order.
- **Verb form.** Imperative only. Use `DO NOT` for prohibitions. Do not use "should",
  "must", or "needs to". Technical verbs (`sanitize`, `validate`, `encrypt`, `back up`)
  are approved under Rule 1.12 and are used in the imperative.
- **Visual distinction.** In rendered output the signal word must stand out on its own:
  a bold blockquote in Markdown, a `<div>` with a CSS class in HTML, an admonition
  directive (`.. WARNING::`) in reStructuredText. Do not rely on uppercase alone.

**Risk vocabulary.** Name the specific risk. Never write "problems", "issues", or
"trouble".

| `WARNING` consequences | `CAUTION` consequences |
|---|---|
| Security breach | Unexpected behavior |
| Data loss | Performance degradation |
| System corruption | Incorrect results |
| Unauthorized access | Connection failure |
| Credential theft | Memory exhaustion |
| Data leak | Application crash |
| Privilege escalation | Configuration drift |

---

## Rule 7.2 — Start a safety instruction with a clear command or condition

**Rule.** In code documentation, start a safety instruction with a clear and accurate
command or condition. Your reader must know how to prevent security vulnerabilities,
data loss, and system failures. If your reader must know about a condition before they
use a function, method, or API, give this condition first.

The signal word tells the reader *how bad*. The first sentence of the body must tell
the reader *what to do*, within the first few words. The reader must not read through
background information before learning the action.

### Command-first structure

A command-first instruction starts with an imperative verb. The three common forms:

| Form | Pattern | Example |
|---|---|---|
| Prohibition | `DO NOT <action>` | `DO NOT COMMIT THE .env FILE.` |
| Mandatory action | `ALWAYS <action>` | `ALWAYS SANITIZE THE INPUT BEFORE YOU PROCESS IT.` |
| Direct action | `<imperative verb>` | `CHECK`, `MAKE SURE`, `BACK UP`, `SANITIZE`, `VALIDATE`, `VERIFY` |

Use approved verbs — `use`, `check`, `make`, `get`, `set`, `send`, `remove`, `keep`,
`start`, `stop`, `show`, `do` — not `utilize`, `leverage`, `employ`, `commence`,
`terminate`, or `initiate`.

> **Non-STE:** WARNING: STORING API KEYS IN THE SOURCE CODE IS NOT RECOMMENDED.
>
> **STE:** WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. ALWAYS USE ENVIRONMENT
> VARIABLES OR A SECRETS MANAGER TO STORE API KEYS. API KEYS IN SOURCE CODE CAN CAUSE
> UNAUTHORIZED ACCESS AND DATA BREACHES.

The non-STE version describes an attitude ("is not recommended"). The STE version opens
with the command `DO NOT STORE`, gives the required alternative, and names the
consequence.

```python
import os

# WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. ALWAYS USE
# ENVIRONMENT VARIABLES OR A SECRETS MANAGER TO STORE API KEYS.
# API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND
# DATA BREACHES.
def get_api_client() -> "Client":
    api_key = os.environ.get("PAYMENT_API_KEY")
    if api_key is None:
        raise RuntimeError("PAYMENT_API_KEY is not set in the environment")
    return Client(api_key=api_key)
```

> **Non-STE:** CAUTION: THE CODEBASE CONTAINS DEPRECATED FUNCTIONS.
>
> **STE:** CAUTION: DO NOT USE DEPRECATED FUNCTIONS OR METHODS THAT HAVE KNOWN ISSUES.
> USE THE APPROVED REPLACEMENT FUNCTIONS SPECIFIED IN THE MIGRATION GUIDE. DEPRECATED
> FUNCTIONS CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.

The non-STE version only reports the presence of deprecated code. The STE version opens
with the prohibition, names the replacement, and states the consequence.

```python
import warnings

# CAUTION: DO NOT USE DEPRECATED FUNCTIONS OR METHODS THAT HAVE
# KNOWN ISSUES. USE THE APPROVED REPLACEMENT FUNCTIONS SPECIFIED
# IN THE MIGRATION GUIDE. DEPRECATED FUNCTIONS CAN CAUSE UNEXPECTED
# BEHAVIOR AND INCORRECT RESULTS.
def legacy_send_email(address: str, body: str) -> None:
    warnings.warn(
        "legacy_send_email is deprecated; use send_message() instead",
        DeprecationWarning,
        stacklevel=2,
    )
    send_message(address, body)
```

### Condition-first structure

Use a condition first when the risk applies only under a specific state, version, or
configuration. The condition scopes the instruction so readers outside that scope know
it does not apply to them.

> **Non-STE:** PERMANENT DATA LOSS CAN OCCUR.
>
> **STE:** IF YOU DO NOT SET THE CONNECTION TIMEOUT, THE APPLICATION CAN BECOME
> UNAVAILABLE AND PERMANENT DATA LOSS CAN OCCUR.

The non-STE version states only the consequence. The STE version opens with the
condition so the reader learns *when* the risk applies.

```go
// WARNING: IF YOU DO NOT SET THE CONNECTION TIMEOUT, THE APPLICATION
// CAN BECOME UNAVAILABLE AND PERMANENT DATA LOSS CAN OCCUR.
func NewClient(dsn string) (*Client, error) {
    db, err := sql.Open("postgres", dsn)
    if err != nil {
        return nil, err
    }
    db.SetMaxOpenConns(10)
    // Without a timeout the next call can block until the TCP
    // connection is silently dropped, and buffered writes are lost.
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    if err := db.PingContext(ctx); err != nil {
        return nil, err
    }
    return &Client{db: db}, nil
}
```

When both a command and a condition are required, **put the condition first**. The
condition tells the reader when the command applies; the command tells them what to do.

### Six structural failures

**1 — Missing command (description only).**

> **Non-STE:** Storing API keys in plaintext configuration files is a security risk.
>
> **STE:** WARNING: DO NOT STORE API KEYS IN PLAINTEXT CONFIGURATION FILES. STORE API
> KEYS IN ENVIRONMENT VARIABLES OR A SECRETS MANAGER. PLAINTEXT API KEYS IN VERSION
> CONTROL CAN CAUSE UNAUTHORIZED ACCESS AND DATA THEFT.

**2 — Missing condition (consequence only).**

> **Non-STE:** Transactions can fail silently.
>
> **STE:** WARNING: IF YOU DO NOT CHECK THE RETURN VALUE OF `transaction.commit()`, THE
> TRANSACTION CAN FAIL SILENTLY. DATA THAT YOU THINK IS SAVED IS NOT SAVED. THIS SILENT
> DATA LOSS CAN CAUSE APPLICATION INCONSISTENCY. CHECK THE RETURN VALUE AND HANDLE THE
> `RollbackError` CASE.

**3 — Command buried in background information.**

> **Non-STE:** Because environments drift over time and templates diverge, you should
> probably not keep separate configuration templates per environment.
>
> **STE:** WARNING: DO NOT USE DIFFERENT CONFIGURATION TEMPLATES FOR EACH ENVIRONMENT.
> USE THE SAME TEMPLATE FOR ALL ENVIRONMENTS. VERIFY THE CONFIGURATION BEFORE EACH
> DEPLOYMENT. CONFIGURATION DRIFT CAN CAUSE PRODUCTION INCIDENTS AND SERVICE
> UNAVAILABILITY.

**4 — Wrong order (consequence before condition).**

> **Non-STE:** Data is removed permanently if you run the cleanup script without an
> export.
>
> **STE:** WARNING: BEFORE YOU RUN THE CLEANUP SCRIPT, EXPORT THE DATA. IF YOU DO NOT
> EXPORT THE DATA, THE SCRIPT REMOVES THE DATA PERMANENTLY. THE DATA CANNOT BE
> RECOVERED. RUN `export-data --output backup.json` AND VERIFY THE FILE BEFORE YOU RUN
> THE CLEANUP SCRIPT.

**5 — Passive voice instead of a command.**

> **Non-STE:** Input data should be validated before it is processed by the pipeline.
>
> **STE:** CAUTION: VALIDATE THE INPUT DATA BEFORE THE PIPELINE PROCESSES IT. IF THE
> PIPELINE PROCESSES INVALID DATA, THE OUTPUT CAN BE INCORRECT. THE INCORRECT OUTPUT
> CAN PROPAGATE TO DOWNSTREAM SYSTEMS. USE THE `validateSchema` FUNCTION TO CHECK THE
> DATA STRUCTURE AND TYPES.

**6 — Multiple commands without hierarchy.**

> **STE:** WARNING: BEFORE YOU PROCESS THE REQUEST, COMPLETE THESE CHECKS:
> (1) SANITIZE ALL INPUT DATA. (2) USE PARAMETERIZED SQL QUERIES. (3) VALIDATE THE
> RETURN TYPES. (4) VERIFY THE AUTHENTICATION TOKEN. IF YOU SKIP ANY CHECK, A SECURITY
> BREACH OR DATA LOSS CAN OCCUR.

### Edge cases

**A framework method name is also a command word.** Use the plain uppercase word as the
command and backticks for the method reference.

> **STE:** WARNING: CHECK THE RETURN VALUE OF THE `check()` METHOD BEFORE YOU CONTINUE.
> IF `check()` RETURNS `false`, THE AUTHENTICATION IS NOT VALID. DO NOT PROCESS THE
> REQUEST. AN INVALID AUTHENTICATION CAN PERMIT UNAUTHORIZED ACCESS.

**The condition is true only for a subset of users.** Scope it with `IF` instead of
writing a command that is wrong for everyone else.

> **STE:** WARNING: IF YOU USE NODE.JS BEFORE VERSION 18, DO NOT USE THE `fetch` API.
> THE `fetch` API IS NOT AVAILABLE IN NODE.JS BEFORE VERSION 18. YOUR APPLICATION
> CRASHES WITH A `ReferenceError`. USE `node-fetch` OR UPGRADE TO NODE.JS 18 OR LATER.

**Both a command and a condition are required.** Condition first, then command.

```bash
# WARNING: BEFORE YOU RUN THE SCHEMA UPDATE, CONNECT TO THE CORRECT
# DATABASE. RUN THE MIGRATION TOOL WITH THE `--check` FLAG. IF YOU RUN
# THE SCHEMA UPDATE ON THE WRONG DATABASE, THE SCHEMA IS CORRUPTED AND
# THE APPLICATION CANNOT START.
export DATABASE_URL="postgres://app@staging:5432/app"
migrate --check        # fails fast if the connection is wrong
migrate up             # only reaches here on the correct database
```

**The instruction references generated code.** Leave the generated comment alone and add
your own command-first instruction above the generated block.

> **STE:** WARNING: DO NOT EDIT THE `generated/` DIRECTORY MANUALLY. THE GENERATOR
> OVERWRITES YOUR CHANGES ON THE NEXT BUILD. IF YOU CHANGE THE GENERATED CODE, YOUR
> CHANGES ARE LOST. EDIT THE `.proto` SOURCE FILE AND RUN THE GENERATOR AGAIN.

**Translation.** Command words (`DO NOT`, `ALWAYS`, `CHECK`, `MAKE SURE`) and condition
words (`IF`, `BEFORE`, `WHEN`) are translated too, and they stay first after the
translated signal word. The word order rules do not change per language.

| Language | DO NOT | ALWAYS | IF | BEFORE YOU |
|---|---|---|---|---|
| English | DO NOT | ALWAYS | IF | BEFORE YOU |
| Spanish | NO | SIEMPRE | SI | ANTES DE |
| French | NE PAS | TOUJOURS | SI | AVANT DE |
| German | NICHT | IMMER | WENN | BEVOR SIE |
| Japanese | 禁止 | 必ず | 場合 | 前に |

### Grammar notes for Rule 7.2

- **Four imperative forms.** Positive (`CHECK THE RETURN VALUE.`), negative
  (`DO NOT COMMIT THE API KEY.`), emphatic (`ALWAYS SANITIZE THE INPUT.`), and
  sequence (`BEFORE YOU <action>, <command>.`).
- **No modal verbs.** "You should check…" and "The value must be checked…" both weaken
  the instruction. Write `CHECK THE RETURN VALUE BEFORE YOU CONTINUE.`
- **Condition clauses** use `IF`, `BEFORE`, `WHEN`, `UNLESS` and stay in the present
  tense: `IF YOU DO NOT SET THE TIMEOUT, THE APPLICATION HANGS.` — not "IF YOU WILL NOT
  SET…".
- **Length.** The command or condition sentence is 20 words or fewer. Split longer
  instructions into a command sentence plus explanation sentences.
- **Punctuation.** Colon and one space after the signal word; a period at the end of
  each sentence; no semicolons joining command and consequence.
- **Parallel structure.** Multiple commands use the same verb form and a numbered list.
- **"Make sure"** is for verifying existing state (`MAKE SURE THAT THE DATABASE
  CONNECTION IS OPEN BEFORE YOU RUN THE QUERY.`). For an action the reader performs, a
  direct imperative is better (`SANITIZE THE INPUT DATA…`).



## rules-sec8.md

# Level 4 — Punctuation, Word Count & Document Formatting (STE-Code Section 8)

This slice of STE-Code covers the punctuation and word-count rules that apply
to all code documentation: README files, API reference docs, docstrings,
inline comments, commit messages, error messages, configuration comments, and
specification documents. It does NOT apply to source code (where semicolons
and parentheses are language syntax) or to code shown inside code blocks.

Rules in this slice:
- 8.1 — No semicolons
- 8.2 — Hyphens connect directly related words
- 8.3 — Permitted uses of parentheses
- 8.4 — Colon before a vertical list acts as a period
- 8.5 — Parenthetical text counts as one word (and forms its own sentence)
- 8.6 — Elements that count as one word for sentence length
- 8.7 — Hyphenated words count as one word

Use this document to check a draft of code documentation for punctuation and
length compliance. Each rule gives the constraint, the code-domain rationale,
canonical examples, edge cases, and cross-references. The "Reference Catalogue"
at the end lists every pattern an LLM should apply or recognise.

---

## Rule 8.1 — Use all standard English punctuation but NOT the semicolon (;)

**Constraint.** In code documentation you may use every standard English
punctuation mark except the semicolon (;). When two independent clauses would be
joined by a semicolon, write two sentences instead.

**Why.** The semicolon lets a writer pack two complete thoughts into one
sentence, which is hard to parse — especially for non-native English readers.
It also carries a different meaning in most programming languages (statement
terminator in C, C++, Java, JavaScript, Rust, Go), which creates cognitive
interference when the same symbol appears in prose. The fix is always the same:
split into two or more sentences, each with its own subject and verb.

**Where it applies.** README files, API docs, docstrings, inline comments,
commit messages, error messages, configuration comments, spec documents. It does
NOT apply to source code or to code inside code blocks.

**Code-domain examples.**

| Non-STE | STE |
|---------|-----|
| `Call the function to parse the response data; handle any errors that occur.` | `Call the function to parse the response data. Handle any errors that occur.` |
| The cache is invalid after a write operation; you must flush it before the next read. | The cache is invalid after a write operation. You must flush it before the next read. |

```python
def fetch_user(client, user_id):
    """Call the function to parse the response data. Handle any errors that occur.

    Parameters:
        client: The HTTP client.
        user_id: The identifier of the user.

    Returns:
        A user record.
    """
    response = client.get(f"/users/{user_id}")
    data = json.loads(response.text)
    if "error" in data:
        raise UserError(data["error"])
    return data
```

Per documentation type:
- **README:** split a feature from its rationale into two sentences.
- **API docs:** write the primary effect as one sentence, the secondary effect as a second.
- **Docstrings:** use a bullet list for multiple return conditions. Use separate sentences for multiple side effects.
- **Commit messages:** each body sentence states one fact. Split any semicolon you find.
- **Error messages:** "X is not valid. Do Y to fix this."
- **Config comments:** write the purpose as one sentence, the trade-off as a second.

**Edge cases.**
1. Semicolons inside code blocks/fences are language syntax — exempt. Inline backtick code (`const x = 5;`) is also exempt; the prose around it must obey the rule.
2. Auto-generated docs may splice semicolons. This is exempt for machine output. Write your source comments with periods only.
3. Semicolons inside quoted strings (error output, log text) are exempt. Keep the semicolon in the quote. Put the period outside.
4. A semicolon used as a super-comma in a list → replace the list with bullets or a table.
5. Chat and code-review threads are informal and exempt. Commit messages are NOT exempt (permanent history).
6. A semicolon inside a regex or data string is data, not prose — exempt inside the code span.

**Cross-references.** Rule 1.1 (approved words for connecting words), Rule 3.1 (simple sentences), Rule 4.1 (short sentences), Rule 4.4 (connecting words), Rule 8.2 (hyphens, not semicolons, connect words).

---

## Rule 8.2 — Use hyphens (-) to connect words that are directly related

**Constraint.** Use a hyphen to connect two or more words that function as one
concept — usually a compound adjective before a noun. The hyphen signals to the
reader that the words form a single unit and prevents ambiguity about what
modifies what.

**Five code-domain hyphenation categories.**
1. Compound adjectives before a noun: `high-priority task`, `read-only file`, `thread-safe method`, `event-driven architecture`, `type-safe interface`, `end-to-end test`, `server-side rendering`, `just-in-time compilation`, `fire-and-forget pattern`.
2. Two-word fractions/numbers: `seventy-two`, `three-fourths`, `one hundred and twenty-eight`.
3. Uppercase-or-number + noun (shape/config): `L-shaped bracket`, `64-bit register`, `8-byte alignment`, `128-bit value`, `3-prong connector`.
4. Verb whose first part is a noun: `dry-run`, `hot-reload`, `cold-start`, `hard-code`, `soft-delete`, `short-circuit`.
5. Prefix ending in a vowel + root starting with a vowel: `pre-initialized`, `re-entrant`, `de-allocated`, `anti-aliasing`, `re-indexed`.

**Code-domain examples.**

| Non-STE | STE |
|---------|-----|
| `// The high priority task must acquire the write lock` | `// The high-priority task must get the write lock` |
| `@param fd  A read only file descriptor` | `@param fd  A read-only file descriptor` |
| `Expected non negative integer` | `Expected non-negative integer` |

```go
// The thread-safe singleton uses lazy initialization to defer object creation
// until the first access.
class CacheManager { ... }
```

**Paradigm key compounds.**
- OOP: `read-only property`, `thread-safe collection`, `lazy-initialized singleton`, `reference-counted pointer`.
- Functional: `pure-function semantics`, `higher-order function`, `side-effect-free computation`, `persistent-data structure`, `tail-recursive call`.
- Procedural: `null-terminated string`, `zero-initialized struct`, `short-circuit evaluation`, `newline-delimited output`, `statically-linked binary`.
- Declarative: `left-joined table`, `fully-qualified column name`, `cluster-scoped resource`, `base64-encoded value`, `read-committed isolation`.
- Systems: `move-semantics transfer`, `borrow-checked reference`, `memory-mapped I/O`, `copy-on-write page`, `lock-free stack`, `undefined-behavior risk`.

**Edge cases.**
1. Keep hyphens in hyphenated tool names (`create-react-app`). Do not add a second hyphen when you use the name as a modifier.
2. Code keywords in prose: hyphenate as compound adjectives (`type-of operator`), but reproduce the keyword exactly in code spans (`typeof x`).
3. Generated/uncontrolled output: leave it as-is. Add a NOTE in the prose.
4. Established unhyphenated compounds in a codebase (`filename`, `namespace`) may stay if unambiguous and consistent.
5. URL path segments use kebab-case as proper nouns — keep them. Hyphenate prose adjectives normally.

**Grammar notes.**
- Hyphenate in attributive position (before the noun): `thread-safe collection`. Do NOT hyphenate in predicative position (after a linking verb): `the collection is thread safe`.
- Do NOT hyphenate when the first word is an `-ly` adverb: `a fully-qualified name` is wrong; use `a fully qualified name`.
- `self-` compounds always take a hyphen: `self-contained`, `self-signed`, `self-healing`.
- Do not insert hyphens into code identifiers (camelCase stays camelCase in backticks).

**Cross-references.** Rule 1.1 / 1.5 (technical nouns in compounds), Rule 1.9 (shorten long compounds), Rule 1.11 (use one form consistently), Rule 8.1 (punctuation pair), Rule 8.6 / 8.7 (hyphenated = one word).

---

## Rule 8.3 — Use of parentheses

**Constraint.** In code documentation, parentheses are permitted for these
uses (do NOT use square brackets `[ ]` for parentheticals; they are reserved for
optional syntax in code):

1. References to modules, diagrams, or text — `Call the request handler (Figure 3, Module A).`
2. Letters/numbers identifying items — `Disconnect the endpoints (2) and (12) from the load balancer (8).`
3. Work-step numbering in procedures — `(1) Install the dependency package (4).`
4. Abbreviations on first use — `A Command Line Interface (CLI) is ...`
5. Singular/plural at once — `Before you run the test(s), set the environment variable(s).`
6. Explanations of a word or clause — `Increase the timeout slowly (not more than 1000 ms each step).`
7. Alternatives — `Use the left (right) API key for the staging (production) environment.`

**Code-domain examples by type.**
- README: define abbreviations on first use. Reference related docs concisely.
- API docs: show units (`timeout: milliseconds (ms)`), status codes (`404 (Not Found)`), parameter constraints.
- Docstrings: show value ranges in parentheses (`timeout: milliseconds (1 to 30000)`); skip repetition already in the type signature.
- Commit messages: scope and issue refs — `feat(auth): add PKCE support (issue #482)`.
- Error messages: put diagnostic values at the END in parentheses — `Cannot find the configuration file (searched: /etc/myapp/config.yaml).`

**Edge cases.**
1. Framework/library names that are also common words — clarify in parentheses on first use: `Flask (the Python web framework)`.
2. Code keywords that are also punctuation (e.g. Rust `()`): keep the code literal; explain in a separate sentence, not nested.
3. Generated docs auto-insert parentheses — leave them. Apply the rule to human-written descriptions.
4. Never nest parentheses — split or restructure: `Set the cache TTL to 3600 (one hour). For production, set it to 86400 (one day).`
5. CLI `--help` text: use sparingly; prefer the alternative or explanation pattern.

**Grammar notes.** Parentheses are a secondary boundary. The period is primary.
Do NOT use em-dashes for asides (not permitted in STE). The abbreviation pattern
is always "Full Term (ABBR)" — after first use, use only the abbreviation. A
complete-sentence parenthetical should become its own sentence.

**Cross-references.** Rule 1.1 (abbreviation words), Rule 1.3 (approved meanings in explanations), Rule 1.9 (short technical nouns), Rule 5.1 (parenthetical word count), Rule 6.3 (one step per numbered line), Rule 8.2 (parentheses explain. Hyphens join).

---

## Rule 8.4 — Colon (:) in a vertical list acts as a period

**Constraint.** In a vertical list, the colon before the list has the effect of
a period. The introductory text before the colon must obey sentence length:
**20 words max for procedural text, 25 words max for descriptive text.** Each
list item after the colon is a new sentence with its OWN 20/25-word limit.

**Why.** This prevents burying enumerated content in a long clause-heavy
introduction. The introduction should state only what the list contains. The
items carry the detail.

**Code-domain examples.**

| Non-STE | STE |
|---------|-----|
| The config file, which is in the project root, supports these profiles that you can use for deployment: a development profile ..., a staging profile ..., and a production profile ... | The configuration file supports these environment profiles: - Development - Staging - Production. |

API docs, docstrings, commit messages, error messages, and config comments all
follow the same shape: short intro + vertical list. Each item is one thought.

**Edge cases.**
1. Code tokens in backticks inside the intro count as ONE word each (`com.example.service.UserRepository` = 1 word). Prefer ≤15 total words and ≤1 code token.
2. One level of nesting is allowed. The parent item is a short category heading.
3. A list item may contain a fenced code block — the prose part obeys the limit. The block contributes 0 words.
4. Long framework names: move them into the list items. Use a generic intro.
5. Generator-produced lists: obey the rule in your source comments. Accept rendered output.

**Cross-references.** Rule 1.1 (approved words in items), Rule 3.1 (one subject-verb-object per item), Rule 4.1 (length at two points: intro + items), Rule 6.3 (procedural lists), Rule 8.1 (colon replaces semicolon-joined enumerations).

---

## Rule 8.5 — Parentheses and word count

**Constraint.** When you put text in parentheses, it counts as **one word** in
the enclosing sentence. AND the words inside the parentheses form their OWN
separate sentence with its own 20/25-word limit. An identifier or abbreviation
in parentheses (a number, letter, alphanumeric code) also counts as one word.

**Two kinds of parentheticals.**
- **Identifier parentheticals** — `(10)`, `(EACCES)`, `(CI/CD)`, `(v2.1)`, `(PROJ-2847)`. Count as one word; no sentence-length limit (not prose).
- **Explanatory parentheticals** — `(the DEBUG flag is off)`, `(the worker runs every 60 seconds)`. Count as one word in the main sentence AND form a complete separate sentence (subject + verb) that must obey the limit.

**Critical rule.** Do NOT hide safety conditions, required steps, or warnings
in parentheses. If the reader must act on it, it deserves its own sentence or a
labeled block (`BREAKING`, `DEPRECATED`, `NOTE`). In systems docs, never put a
safety precondition in parentheses — use a `# Safety` section.

**Code-domain examples.**

| Non-STE | STE |
|---------|-----|
| Make sure DEBUG is false before you run the deploy in prod (the DEBUG flag must be explicitly disabled for all prod workloads to prevent log leakage). | Make sure that the DEBUG environment variable is set to false (the DEBUG flag is off). |
| Remove the health check flag number ten. | Remove the health check flag (10). |

**Edge cases.**
1. `function()` inside backticks is one atomic word — its parentheses are not Rule 8.5 parentheticals.
2. A URL in parentheses is an identifier (one word). If it has explanatory text after it, that text forms a sentence.
3. Never nest parentheses — restructure or use an em-dash for the inner aside.
4. Framework method names with parentheses (`expect()`): backtick them; one word.
5. Generated parentheticals (type hints, defaults): accept. Obey the rule in your own prose.

**Cross-references.** Rule 1.5 / 1.6 (technical nouns in parentheticals), Rule 3.1 (the parenthetical is a sentence), Rule 3.3 (long parentheticals signal a restructure), Rule 4.1 (limit applies to the parenthetical sentence too), Rule 8.1 (no semicolons inside parentheticals), Rule 8.4 (parentheticals inside list items).

---

## Rule 8.6 — Elements that count as one word

**Constraint.** When counting words for sentence length (20 procedural / 25
descriptive), count EACH of these as ONE word:

1. **Numbers** — `13`, `16`, `twenty-one`. (Do NOT count numbers that identify paragraphs or work steps — they are document numbering.)
2. **Numbers with units** — `10 ms`, `20 MB`, `10 μs`, `3000` + `seconds`.
3. **Abbreviations** — `CI/CD`, `VPN`, `JWT`, `OWASP`, `a.m.` (counts with its number).
4. **Alphanumeric identifiers** — `No. 1`, `E36L7`, `ERR_PG_TIMEOUT_0099`, `cache.miss.count`, `useUserProfile(userId)`.
5. **Quoted text** — anything in `"..."`, `` `...` ``, `<code>...</code>`, or UPPERCASE labels. Includes formulas (`C = (A - B) - 0.063 mm` = 1 word) and backtick-quoted paths/commands.
6. **Titles, headings, UI text, labels** — `Operations Runbook`, `Error Handling and Recovery`, dialog warnings (`"WARNING: This operation permanently deletes all user data."` = 1 word).
7. **Proper nouns** — individuals (`Linus Torvalds`), organizations (`Apache Software Foundation`), geopolitical entities (`United States of America`), and framework/library names (`React`, `AWS Lambda`, `Express`).

**Why this matters.** Correct application shrinks the apparent word count of a
sentence by 3–8 words on average (largest in API docs and READMEs), making it
easier to obey the 20/25 limits.

**Code-domain example.** "Set `http.client.retry.max.attempts` to 5. Set `http.client.retry.backoff.millis` to 1000." — each backtick path is 1 word, each number is 1 word.

**Edge cases.**
1. Framework names with "unapproved" words (`Express`, `Swift`, `React`) are proper nouns (1 word) — do not rewrite them; treat `React` as a noun, not a verb.
2. Code keywords quoted in docs (`class`, `return`) are quoted text (1 word); in your own prose use them as technical nouns/verbs per Rule 1.5/1.12.
3. Generated code/comments count as one word (category 6) when you cannot change them.
4. Quoted text inside quoted text — the outer fence defines the boundary; everything inside is 1 word.
5. Semantic version strings (`1.2.3-alpha.1+build.456`), commit hashes (`a1b2c3d`), image digests (`sha256:abc...`) are alphanumeric identifiers (1 word each). "Version 1.2.3" = 2 words.
6. Numbers that identify document parts (rule numbers in cross-refs, step numbers, issue IDs used as refs) are exempt structural numbering.

**Cross-references.** Rule 1.1 (proper nouns/identifiers exempt from approved-word rule), Rule 1.5 / 1.6 (framework names are technical nouns = proper nouns), Rule 1.14 (keep non-American spelling in proper nouns), Rule 8.7 (hyphenated = one word, a separate case).

---

## Rule 8.7 — Hyphenated words count as one word

**Constraint.** A hyphenated word group counts as ONE word for sentence length,
whether it is a compound adjective before a noun or a long hyphenated technical
noun. The hyphen joins the words into a single unit, so count the unit, not the
individual words inside it.

**Case 1 — Compound adjectives (before a noun, hyphenate):** `read-only file descriptor`, `thread-safe singleton`, `event-driven architecture`, `client-side rendering pipeline`, `end-to-end test suite`, `backward-compatible API`. After a linking verb, write them as separate words and count each: `the singleton is thread safe` = 5 words.

**Case 2 — Long hyphenated technical nouns:** `cutoff-switch power connection` (3 words: `cutoff-switch`/`power`/`connection`), `build-time environment variable` (3: `build-time`/`environment`/`variable`), `client-side rendering pipeline`, `sign-in error message`, `look-up table index`. Only the hyphenated group is one word; the following words are separate.

**Worked count.** "The build-time environment variable must point to the staging cluster." = 10 words (`build-time` is 1). "The thread-safe singleton must cache the read-only file descriptor." = 9 words (both hyphenated terms are 1 each).

**Interaction with other rules.**
- Rule 8.2 (when to hyphenate) + Rule 8.7 (how to count) work together.
- Rule 8.6 covers numbers/units/abbreviations/identifiers; a hyphenated word is a SEPARATE case — do not double-count it as an identifier.
- A hyphen in a spelled-out numeral (`twenty-one`) or range (`pages 10-15`) is covered by Rule 8.6, not 8.7.

**Approved code-domain hyphenated terms (each = one word before a noun).**
`read-only`, `write-only`, `thread-safe`, `event-driven`, `client-side`, `server-side`, `end-to-end`, `backward-compatible`, `low-latency`, `build-time`, `run-time`, `sign-in`, `check-out`, `request-response`.

When such a term follows the noun or a linking verb, write it as separate words and count each word.

**Cross-references.** Rule 8.2 (use hyphens), Rule 8.6 (other one-word elements), Rule 4.1 / 4.2 (sentence-length limits that hyphenation helps you meet).

---

## Reference Catalogue — apply/recognise these patterns in code documentation

**Punctuation allowed:** period (.), question mark (?), exclamation mark (!), comma, colon (:), hyphen (-), parentheses ( ) for the seven listed uses.
**Punctuation banned:** semicolon (;). Em-dashes for asides are not permitted; use parentheses (own sentence) or split into sentences. Square brackets are for code syntax only.

**Sentence-length limits (the master constraint):** 20 words procedural, 25 words descriptive. Count via Rule 8.6 (identifiers/numbers/abbreviations/quoted text/proper nouns = 1 word) and Rule 8.7 (hyphenated groups = 1 word).

**Quick checklist for an LLM reviewing/revising code documentation:**
1. No semicolons in any prose. Split into sentences.
2. Semicolons inside code blocks/fences/backticks — leave them (language syntax).
3. Compound adjectives before a noun get a hyphen; the same words after a verb do not. Never hyphenate `-ly` adverb + adjective. `self-` always hyphenated.
4. Parentheses only for: refs, item IDs, step numbers, abbreviations, singular/plural, explanations, alternatives. Never nest. Never hide safety/required info in them.
5. A parenthetical = 1 word in the sentence AND its own sentence with its own 20/25 limit (identifiers excepted).
6. Vertical list: intro ≤ 20/25 words; each item ≤ 20/25 words. Use a colon, then bullets.
7. Count identifiers, numbers+units, abbreviations, backtick code, proper nouns, and hyphenated groups as ONE word each.

**Cross-slice links.** These punctuation/length rules interact most with:
Rule 1.1 (approved words), Rule 3.1 (simple sentences), Rule 4.1 (short sentences),
Rule 4.4 (connecting words after a semicolon split), Rule 6.3 (procedural lists).
Apply them together — a document can pass general sentence rules yet still fail
Rule 8.1/8.4/8.5 on punctuation and list structure.



## rules-sec9.md

# Level 4 — Section 9: Sentence Construction, Correct Word Use, Phrasal Verbs, Consistency

This sub-document distills **Section 9** of the STE-Code standard for use by
LLMs that generate, review, or rewrite code documentation. It covers the four
"fallback and quality" rules that apply *after* the dictionary (Rule 1.1) has
been consulted:

- **Rule 9.1** — When a word-for-word replacement is not enough, rebuild the sentence.
- **Rule 9.2** — Use every approved word with its approved meaning and part of speech.
- **Rule 9.3** — Do not combine approved words into phrasal verbs.
- **Rule 9.4** — Use one term and one construction for each concept, everywhere.

These rules are the repair and quality layer. Rule 1.1 says *which* words are
allowed; Section 9 says *how* to use them and what to do when a single word
will not fit.

## Quick reference

| Rule | One-line directive | Trigger |
|------|--------------------|---------|
| 9.1 | Rebuild the sentence when no approved word fits by replacement. | Word-for-word swap fails or changes meaning. |
| 9.2 | Every approved word keeps its one approved meaning + part of speech. | A word is used in a meaning/role not in the dictionary. |
| 9.3 | Replace verb+particle pairs with one approved verb. | A phrasal verb (new meaning from two approved words) appears. |
| 9.4 | Same concept = same term, same verb, same structure, everywhere. | You find synonyms or shifting phrasing for one thing. |

## Rule 9.1 — Rebuild the Sentence When a Word-for-Word Replacement Is Not Sufficient

**Source:** ASD-STE100 Issue 9, Rule 9.1 (code-domain adaptation).

### What it says

The dictionary gives approved alternatives for unapproved words. If an
alternative has the **same part of speech** and **does not change the meaning**,
do a word-for-word replacement. If any of these fail, you must write a new
sentence with a different structure that uses only approved words and keeps the
same technical meaning.

A different construction is required when:

1. You must change the grammar to use the approved alternative.
2. A word-for-word swap gives a meaningless or unclear result.
3. The approved alternative changes the meaning.
4. The word to replace is not in the controlled terminology.

### How to rebuild (the decision order)

1. Try a word-for-word replacement with the same part of speech. If it works and keeps the meaning, stop.
2. If it fails, think about *what the sentence is trying to say* and restructure:
   - select different words,
   - use different verb forms (simple present / past / imperative),
   - write shorter sentences,
   - drop information that is not necessary,
   - or get more detail from a developer when the meaning is unclear.

### Worked examples

| Non-STE | STE | Why a rebuild was needed |
|---------|-----|--------------------------|
| A timeout value of 5000 ms is **acceptable** for this endpoint. | A timeout value of 5000 ms is **permitted** for this endpoint. | No rebuild: "acceptable" → approved "permitted", same part of speech, same meaning. |
| The stack trace in the console **must be visible** during the debugging session. | **During the debugging session, make sure that you can see** the stack trace in the console. | Adjective "visible" → verb "see"; restructure around the agent "you". |
| **Loop** the function twice to remove null values from the array. | **Run** the function for two **iterations** to remove null values from the array. | "Loop" not approved; "iterate"/"run" + "iteration" + "two" replace it. |
| Without this change, the behavior **can be uncertain**. | Without this change, **it is possible that** the function **will not behave as expected**. | "Uncertain" not in terminology; word-for-word swap is meaningless, so rebuild. |
| **Just** add a single log statement to the method. | **Only** add a single log statement to the method. (NOT: "Immediately…") | "Just"→"Only"; "Immediately" is the approved alternative but changes the instruction's meaning. |
| The **occurrence** of type errors in the build output is a serious problem. | **Type errors** in the build output are a serious problem. | "Occurrence" not approved; drop the nominalization. |

### Per documentation-type guidance

- **README files** — replace passive with active instructions; move complex explanation to a separate doc; use bullets; drop marketing language.
  - Non-STE: *This library leverages asynchronous I/O to facilitate high-throughput data processing.*
  - STE: *This library uses async I/O. It can process large quantities of data quickly.*
- **API docs** — keep parameter/field names unchanged (Rule 1.5); restructure the description around the approved word; split compound descriptions.
  - Non-STE: *This endpoint facilitates the retrieval of user profiles.*
  - STE: *This endpoint gets user profiles.*
- **Docstrings / inline comments** — keep code symbols; if no replacement fits in the space, replace the sentence with a reference to a longer doc.
  - Non-STE: *"Computes the aggregate of the supplied metrics and persists them."*
  - STE: *"Gets the total of the metrics and saves them."*
- **Commit messages** — use imperative summary ("Add feature"); replace unapproved verbs; keep details in the PR, not the body.
  - Non-STE: *Implemented utilization of the cached connection pool to expedite request handling.*
  - STE: *Use the cached connection pool to make requests faster.*
- **Error messages** — tell the user what happened and what to do; use "cannot" / "do not"; keep code symbols.
  - Non-STE: *The application encountered an unrecoverable exception while attempting to instantiate the connection pool.*
  - STE: *The application cannot start the connection pool. Look at the log for more data.*

### Paradigm-specific patterns

- **OO (Java/C#/C++/Python):** "provides an abstraction that facilitates" → state the concrete purpose. *The `BaseRepository` class lets you use the same data access methods with different databases.*
- **Functional (Haskell/Rust):** type signatures are code (keep); "maps over" → "applies a function to each element"; monad descriptions → "lets you chain operations that can fail".
- **Procedural (C/Go/Bash):** "deallocate" → "free"/"release"; "pipe command A to command B" → "send the output of command A to command B" when "pipe" is prose.
- **Declarative (SQL/Terraform/K8s):** keep field names; "orchestrates the rollout of three replicated Pods" → "makes three copies of the Pod. If a Pod stops, the system starts a new Pod automatically."
- **Systems (Rust/C):** `borrow`/`own`/`move`/`drop` are keywords in code font (keep); in prose replace — "borrow"→"get a reference to", "own"→"has"/"controls".

### Edge cases

- **Framework names that are also common words** (Flask, Express, Vite): technical nouns — keep unchanged, use code font; never use as a verb ("Use Flask with…", not "Flask your application").
- **Code keywords that match approved words** (`use`, `move`, `return`, `break`): code font = keyword (technical noun); prose = approved meaning.
- **Generated code / quoted logs:** keep symbol names and quoted text exactly; your surrounding prose uses approved words.
- **When rebuilding loses precision** (e.g. security audits): split + add a clarifying note, or keep the term in code font with a glossary definition, or (internal audience) keep it as a technical noun with an approved-word definition on first use.

## Rule 9.2 — Use Each Approved Word Correctly

**Source:** ASD-STE100 Issue 9, Rule 9.2 (code-domain adaptation).

### What it says

Each approved word has **one approved meaning** and **one approved part of
speech** (a small set of words are approved as more than one — see below). Use
the word only with that meaning and in that role. Other standard-English
meanings are not approved.

### Core procedure

1. Before using a word, check its entry in the controlled terminology (approved meaning + part of speech).
2. Use the word only in its approved role.
3. If a word is unapproved in the meaning/role you need, find an approved alternative with the same part of speech → word-for-word swap; if none, apply Rule 9.1.

### Common part-of-speech traps

| Word | Approved as | NOT approved as | STE fix |
|------|-------------|-----------------|---------|
| `log` | noun ("the record of events") | verb | "write to the log" (not "log the error") |
| `help` | verb ("to assist") | noun | "help text" / "help information" |
| `damage` | noun ("harm") | verb | "cause damage" / "do damage" |
| `build` | verb (technical, Rule 1.12) **and** noun ("the result") | — | "Build the project" / "The build completed"; be specific, not just "the build" |
| `run` | verb | standalone noun | "Run the tests" / "Do a test run" |
| `set` | verb ("put into state") **and** noun ("a group") | adjective | "Set the timeout" / "a set of options"; not "the set timeout value" |
| `check` | verb ("make sure correct") | standalone noun | "Check before deploy" / "Do a health check" |
| `use` | verb | noun/prep | "Use this method" (not "Using this method…") |
| `return` | verb ("go/get back") | standalone noun | "The function returns a value" / "The return value" (not "the return of the function") |
| `execute` | — | verb (for "run a program") | "run" |
| `create` | — | verb | "make" (SQL `CREATE` keyword stays in code font) |
| `select` | — | verb | "choose" / "get" (SQL `SELECT` keyword stays in code font) |

### Multi-meaning / multi-part-of-speech words

- **flush** — verb ("remove remaining data from a buffer") **and** adjective ("where one surface fully touches another"). *"Flush the output buffer."* vs *"Make sure that the connector is flush with the port."*
- **build, run, set, check** — see table above; when a word is approved in two roles, context (position, determiners) must make the role clear.

### Per documentation-type notes

- **README:** every verb/noun is an approved word in its approved meaning. "leverage"→"use"; "functionality"→"feature"; "capability"→"can".
- **API docs:** HTTP `GET` (code font) ≠ the verb "get". "set the timeout value" (verb) vs "a set of endpoints" (noun). "return value" is allowed (noun adjunct); "the return of the function" is not.
- **Docstrings:** "do" = general action only; use the specific verb for specific actions ("Run the migration", not "Do a migration"). "make" = "create"; not a light verb ("Call the service", not "Make a call").
- **Commit messages:** imperative summary with approved verb ("Add feature", not "Implement feature"). "fix" is a verb; "a fix" (noun) is not — use "correction" or "Correct the bug".
- **Error messages:** use "cannot" (not "unable to"/"failed to"); "must" only when the user must act (else state the state: "The file does not exist"); "if" for conditional actions.

### Paradigm-specific notes

- **OO:** `extends`/`implements`/`override`/`abstract` are keywords in code font (technical nouns); in prose they are unapproved verbs — "inherits from", "uses the interface", "replaces the parent method", "base class".
- **Functional:** `map`/`reduce`/`filter` are function names (technical nouns); in prose use "apply a function to each element", "combine the elements into a single value", "remove elements that do not match". `apply` as a verb is not approved → "use the function on the value".
- **Procedural:** `free`/`open`/`close`/`read` are function names (technical nouns); in prose use them as approved verbs — "free the memory that the pointer points to", "the port is available" (not "open for connections"), "read the data".
- **Declarative:** `CREATE`/`SELECT`/`DROP` stay in code font; in prose "make a table", "get rows", "remove the table". `terraform apply` is a command (technical noun); in prose "use `terraform apply` to make the changes".
- **Systems (Rust):** `move`/`drop` as technical verbs are acceptable when the Rust meaning is clear; `borrow`→"get a reference to"; `own`→"has"/"controls"; "ownership" is a technical noun.

### Edge cases

- **Framework/tool names that are unapproved words** (Express, Flask, FastAPI): technical nouns — keep in code font/capitalization; never use as a verb.
- **Keywords that match approved words** (`use`, `move`, `return`, `break`): code font = keyword; prose = approved meaning. "Do not break the API contract" → "Do not change the API contract" (unless literal physical separation).
- **Generated code:** keep symbol names; describe function with approved words ("The `utilizeConfig()` function uses the configuration…"). Prefer a wrapper with an approved name for public APIs.
- **Quoted error/log text:** keep verbatim; explain with approved prose.

## Rule 9.3 — Do Not Make Phrasal Verbs

**Source:** ASD-STE100 Issue 9, Rule 9.3 (code-domain adaptation).

### What it says

A **phrasal verb** = an approved verb + a particle/preposition whose combined
meaning differs from the individual words ("put out" ≠ "put" + "out"). Do not
combine approved words into such phrases. Replace the phrasal verb with a single
approved verb of the same meaning. Only a small set of phrasal verbs are
specifically approved (see below).

**Test:** remove the preposition. If the meaning stays ≈ the same, it is a
prepositional phrase (allowed). If the meaning changes completely, it is a
phrasal verb (not allowed).
- Allowed: *"The application runs on the server."* ("on the server" = location.)
- Not allowed: *"The application runs on for too long."* ("run on" = continues — phrasal verb.)
- Allowed: *"Write the configuration to the file."* ("to the file" = target.)
- Not allowed: *"The team writes up the test plan."* ("write up" = compose — phrasal verb.)

### Common phrasal verbs → approved verb

| Avoid (phrasal) | Use (single verb) |
|-----------------|-------------------|
| put out (emit) | emit |
| give off | return / release |
| carry out | do |
| set up | configure / install / create |
| run through | execute / complete |
| check out | examine / see |
| go through | read / complete |
| pick up (where stopped) | continue |
| break down (analyze) | divide / separate / analyze |
| go on (proceed) | continue |
| look at | examine / inspect |
| filter out | remove |
| kick in | start |
| clear out | remove |
| hook into / tap into | connect / subscribe to |
| hands off | send / transfer |
| tears down | releases / closes |
| prints out | prints |
| writes up | compose |
| breaks out of | exits |

### Commit-message phrasal verbs

| Avoid | Use |
|-------|-----|
| clean up | remove / delete / tidy |
| fix up | correct / repair |
| speed up | accelerate / make faster |
| cut down | reduce / decrease |
| rip out / strip out | remove |
| wire up | connect |
| flesh out | complete / expand |

### Approved phrasal verbs (restricted meaning — keep as-is)

| Approved phrase | Meaning | Example |
|-----------------|---------|---------|
| log in / log out | start/end an authenticated session | "The user must log in before they can access the dashboard." |
| follow up | take further action after an initial step | "Follow up the installation with the configuration step." |
| back up | make a copy for safekeeping | "Back up the database before you apply the migration." |
| roll back | return to a previous state | "Roll back the deployment if the health check fails." |

NOTE: use "log in/out", not "sign in/out", "log on/off". "back up" (two words) = make a copy only.

### Per documentation-type guidance

- **README:** one approved verb per heading/step. "Set up"→"Configure"/"Install"; "Run through"→"Complete"; "Check out"→"Examine".
- **API docs:** verb matches the operation exactly. "Pulls down"→"Gets"; "Puts in"→"Creates"; "Looks up"→"Finds"; "Takes in"→"Receives"; "Spits out"→"Returns".
- **Docstrings:** edit quickly-written informal phrasal verbs. "Runs through… and picks out"→"Examines… and selects"; "Sets up… and kicks off"→"Configures… and starts".
- **Error messages:** "Could not hook up"→"Could not connect"; "blew up"→"failed"; "out of whack"→"not consistent".
- **Changelogs:** "did away with"→"removed"; "ironed out"→"corrected"; "phased out"→"ended"; "added back"→"restored".

### Paradigm-specific

- **OO:** "tears down"→"releases"/"closes"; "hands off ownership"→"transfers ownership"; "looks up"→"finds"; "wraps up"→"completes".
- **Functional:** "maps over"→"applies a transformation to each element"; "pipes through"→"sends through"; "folds down"→"combines"; "reaches out to"→"sends a request to".
- **Procedural:** "free up"→"release"/"free"; "reach out to"→"send a request to"; "put together"→"make".
- **Declarative:** "brings up"→"creates"; "spins up"→"starts"; "tears down"→"removes"; "joins together"→"joins".
- **Systems:** "hands off ownership"→"transfers ownership"; "holds onto"→"keeps a reference to"; "gives up the lock"→"releases the lock"; "carves out"→"allocates".

### Edge cases

- **Framework/tool name contains a phrasal verb** (`setuptools`, `cleanup`, `rollback`): the name is a noun (keep). Its *behavior description* must follow 9.3 ("`setuptools` configures…", not "sets up…").
- **Keyword is a phrasal-verb component** (`break`, `continue`, `throw`, `catch`): keyword as noun/technical verb is fine ("the `break` statement exits the loop"); "breaks out of" is a phrasal verb → "exits".
- **Two approved words that are NOT a phrasal verb:** location/direction/time prepositional phrases are allowed (see test above).
- **No single verb exists:** apply Rule 9.1 — rewrite. "warms up"→"loads the data"; "flags up"→"reports"/"marks"; "churns through"→"processes".
- **Generated docs:** apply 9.3 to the *source* doc comments so the generated output is compliant.

## Rule 9.4 — Always Use a Consistent Style

**Source:** ASD-STE100 Issue 9, Rule 9.4 (code-domain adaptation).

### What it says

When you choose a term or a construction for a concept, reuse it every time
that concept appears. One name per item, one verb per action, one sentence
structure per instruction type. Different wording for the same thing forces the
reader to ask "is this the same or different?" — that is a documentation failure.

### Three consistency domains (all must hold)

1. **Lexical** — one term per concept. Do not alternate "configuration file" / "settings file" / "config".
2. **Syntactic** — same structure per instruction type. Setup steps, config steps, and verification steps each keep one grammatical template.
3. **Semantic** — same meaning across files/modules/types. If "build" = "compile and link" in the README, it must not mean "compile, link, and package" in the CI docs.

### Per documentation-type guidance

- **README:** one term for the artifact ("library" everywhere, not "library" then "package").
- **API docs:** a field/parameter has exactly one name across all references — match prose to the schema (`createdAt` in schema → "created at", not "creation date"/"timestamp").
- **Docstrings:** use the same term as the function signature. Param `max_retries` → "max retries" in the body, not "maximum attempts"/"retry limit".
- **Commit messages:** one imperative verb per change category. If the convention is `Add`, do not mix in `Introduce`/`Insert`/`Create`.
- **Error messages:** one error code → identical text every time (a reliability property, not style).
- **CLI help:** the `--output` flag description is identical in `--help`, man pages, and error messages.

### Paradigm-specific

- **OO:** inherited/overridden methods reuse the base-class template, adding only subclass behavior. Do not abbreviate class names inconsistently (`UserRepository`, not `UserRepo`/`the user repo`).
- **Functional:** all pure functions use the same anchor phrase ("returns a new list with…"), not "produces a result"/"yields output".
- **Procedural (Go):** all `if err != nil` checks use the same pattern ("Check the return code. If the return code is not 0, stop the program.").
- **Declarative:** one phrase per resource type (`aws_instance` = "a virtual machine in AWS EC2" everywhere). Kubernetes `ConfigMap`/`Pod` are proper nouns — never "config map"/"configmap"/"configuration map".
- **Systems (Rust):** "ownership", "borrow", "lifetime", "move" are terms of art — never substitute synonyms ("moved", not "transferred"/"relinquished control").

### Worked examples

- **Verbs in setup:** Non-STE mixes install/fetch/set up/get running → STE: install / download / set the environment variables / start.
- **Noun across types:** Non-STE: "library" / "auth package" / "authentication module" → STE: "authentication library" everywhere; no "auth" abbreviation.
- **API reference structure:** every endpoint description starts with a third-person singular verb; "retrieves"/"gets" unified to "returns"; the `:id` wording identical across endpoints.
- **Commit convention:** one verb ("Add") for all new features.
- **Error messages:** same failure mode → same text ("Cannot connect to the remote host") so logs are searchable.
- **CLI flags:** each flag uses the template "Enables/Disables [adjective] output".

### Edge cases

- **Framework-mandated terms** (React "props", "hooks"): the framework is the authority — use its term consistently, do not translate to an STE-Code synonym.
- **Generated docs:** fix the *source* docstrings; consistency must be authored, not post-processed. CI should reject commits whose conventional-commit verb is non-standard.
- **Cross-project (monorepo):** per-service docs follow the service glossary; system-level docs define a system glossary that maps each system term to its service-level term.
- **Multiple valid industry names:** pick one, document it in the glossary, never alternate.
- **Version renames:** each version's docs use that version's canonical name; migration guides state the rename explicitly.

### Canonical synonym table (the preferred term per concept)

Pick the preferred term and use it in **every** sentence for that concept.
Variation in technical documentation is a defect, not a virtue.

| Concept | Use | Do NOT use |
|---------|-----|------------|
| use | use | utilize, leverage, employ |
| start | start | initiate, commence, bootstrap |
| show | show | display, render, present |
| make | make | create, generate, produce |
| get | get | retrieve, fetch, obtain |
| set | set | configure, assign, establish |
| check | check | verify, validate, ensure |
| remove | remove | delete, eliminate, purge |
| keep | keep | retain, preserve, maintain |
| send | send | transmit, dispatch, forward |

## LLM usage checklist

When generating or reviewing code documentation, apply Section 9 in this order:

1. **Rule 1.1 first** — is every word in the approved dictionary? If not, find an approved alternative with the same part of speech.
2. **Rule 9.2** — is each approved word used with its one approved meaning and part of speech? (Watch `log`/`help`/`damage` noun-verb splits; `build`/`run`/`set`/`check` dual roles.)
3. **Rule 9.3** — did two approved words combine into a phrasal verb? Replace with one verb (`set up`→`configure`, `put out`→`emit`). Exception: the four approved phrases (log in/out, follow up, back up, roll back).
4. **Rule 9.1** — if no single word fits, rebuild the sentence around a different structure; keep code symbols unchanged (Rule 1.5).
5. **Rule 9.4** — is the same concept always named and verbed the same way, in every file and message? Apply the canonical synonym table.

Keep code symbols, framework names, keywords, and quoted log/error text unchanged
(Rule 1.5). They are technical nouns, not prose, and are exempt from word-level
rules — only your surrounding explanation must comply.

## Cross-references

- **Rule 1.1** (Approved Words) — the dictionary; Section 9 repairs what 1.1 cannot fix by replacement.
- **Rule 1.2 / 1.3** (Part of speech / Approved meanings) — the constraints Rule 9.2 enforces.
- **Rule 1.4** (Approved verb/adjective forms) — single approved verbs avoid non-standard phrasal forms (9.3).
- **Rule 1.5** (Technical code nouns) — keywords, framework/tool names, symbols are exempt from 9.1–9.4; exclude them before applying any rule.
- **Rule 1.7** (No technical nouns as verbs) — reinforced by 9.2/9.3.
- **Rule 1.11** (One term per concept) — the lexical foundation of 9.4.
- **Rule 1.12** (Technical verbs) — `build`/`deploy`/`test`/`lint`/`compile`/`debug`/`parse`/`serialize` are approved; do not replace them with phrasal verbs.
- **Rule 3.1 / 5.1 / 6.1** (Simple tenses / short sentences / active voice) — apply when rebuilding under 9.1.
- **The STE-Code dictionary (A–Z)** — source of truth for approved meaning + part of speech; consult before writing.

*End of Section 9 distillation (Level 4).*



# === tier level5 ===


# STE-Code Level 5 — distilled index

> full standard (all rules + extensions + catalogue + provenance)

## Sub-documents

- 01-principles.md
- 02-synonyms.md
- 03-dictionary.md
- 04-templates.md
- 05-grammar.md
- 06-extensions.md
- 07-catalogue.md
- 08-provenance.md
- rules-sec1-part1.md
- rules-sec1-part2.md
- rules-sec2.md
- rules-sec3.md
- rules-sec4.md
- rules-sec5.md
- rules-sec6.md
- rules-sec7.md
- rules-sec8.md
- rules-sec9.md



## 01-principles.md

# Level 5 — Core Principles (Words: Rules 1.1–1.14)

Level 5 is the full STE-Code standard: every rule, the extension vocabulary, the
reference catalogue, and provenance. This sub-document is the **core principles**
slice — Section 1, which governs *words*. Every other section of STE-Code assumes
these fourteen rules already hold.

Use this file when you generate, review, or lint code documentation with an LLM.

## The three gates

A word is allowed in STE-Code prose only if it passes one of three gates:

1. The word is **approved in the controlled terminology** (STE-Code part 2), or
2. The word is a **code-domain technical noun** (Rule 1.5, 19 categories), or
3. The word is a **code-domain technical verb** (Rule 1.12, 4 categories).

A word that passes no gate must be replaced, or the sentence must be restructured
so that approved words carry the meaning.

## Definitions

- **Controlled terminology** — the STE-Code approved word list. Each entry gives
  one part of speech and one approved meaning, plus the approved verb and
  adjective forms.
- **Code-domain technical noun** — a noun term for a specified concept in
  software development, applicable to a subject field (Rule 1.5).
- **Code-domain technical verb** — a verb term for a specified operation or
  process in software development (Rule 1.12).
- **Project glossary** — the project, company, industry, or subject-field list of
  approved technical nouns and verbs. It is checked before the controlled
  terminology for domain names, and the repository is its source of truth.

## Rule index

| Rule | Statement |
|------|-----------|
| 1.1 | Use words that are approved, code-domain technical nouns, or code-domain technical verbs. |
| 1.2 | Use approved words only as the specified part of speech. |
| 1.3 | Use approved words only with their approved meanings. |
| 1.4 | Use only the approved forms of verbs and adjectives. |
| 1.5 | You can use words you can include in a code-domain technical noun category. |
| 1.6 | Use an unapproved word only when it is a code-domain technical noun or part of one. |
| 1.7 | Do not use code-domain technical nouns as verbs. |
| 1.8 | Use code-domain technical nouns approved in your project, company, industry, or subject field. |
| 1.9 | When you must select a code-domain technical noun, use one that is short and easy to understand. |
| 1.10 | Do not use regional, slang, or jargon words as code-domain technical nouns. |
| 1.11 | Do not use different code-domain technical nouns for the same item. |
| 1.12 | You can use verbs you can include in a code-domain technical verb category. |
| 1.13 | Do not use code-domain technical verbs as nouns. |
| 1.14 | Use American English spelling unless other official directives tell you differently. |

---

## Rule 1.1 — Use approved words, code-domain technical nouns, or code-domain technical verbs

In code documentation, use words that are:

- approved in the controlled terminology,
- code-domain technical nouns, or
- code-domain technical verbs.

The controlled terminology gives the words most frequently used in code
documentation. It also lists words that are **not** approved, with approved
alternatives. Your project glossary or terminology database holds the technical
nouns and technical verbs of your subject field; always check it first.

Worked vocabulary swaps:

| Do not write | Write | Why |
|---|---|---|
| execute the script | run the script | "run" is the approved verb for executing programs |
| generate the artifact | make the artifact | "make" is approved; "generate" is not |
| utilize / leverage the cache | use the cache | inflated verb |
| bootstrap / initiate the service | start the service | "start" is approved |
| configure the runtime | set the runtime behavior | "set" is approved |
| retrieve / fetch the record | get the record | "get" is approved |
| transmit the payload | send the data | "send" is approved |
| validate / verify the input | check the input | "check" is approved |
| unable to connect | cannot connect | "cannot" is approved |
| invalid / malformed data | incorrect data | "correct" is the approved adjective |

Technical terms stay: `UserAuthenticator` is a code-domain technical noun,
`serialize` is a code-domain technical verb, and both are permitted although
neither is in the controlled terminology.

Examples by documentation type:

> **Non-STE (README):** To begin utilizing the build toolchain, you must first
> generate the distributable artifact, then execute the compiled binary to
> bootstrap the local development service.
>
> **STE:** Use the build tool to make the binary. Run the binary to start the
> local service.

> **Non-STE (JSDoc):** Fetches a user record. The duration in milliseconds the
> client shall await a response prior to terminating the connection attempt.
>
> **STE:** Gets a user record. The time in milliseconds that the client waits
> for a response before it stops the connection.

> **Non-STE (CLI error):** Unable to establish connection to the database.
> Please verify your credentials and retry.
>
> **STE:** Cannot connect to the database. Check your credentials and try again.

Paradigm notes:

- **Object-oriented** — prose uses approved verbs (make, get, set, call, send,
  keep). Class, method, and pattern names stay as technical nouns.
- **Functional** — `map`, `fold`, `reduce`, `filter`, `compose`, and `curry` are
  code-domain technical verbs. "Pure function" is a compound technical noun.
- **Procedural** — each step starts with an approved imperative verb. "Allocate"
  is not approved (write "make a buffer"). "Free" and "dereference" are
  code-domain technical verbs.
- **Declarative** — SQL keywords and resource kind names are technical terms.
  "Provision" is not approved (use "make" or "set up"); "orchestrate" is not
  approved (use "control" or "manage").
- **Systems** — "own", "borrow", and "move" are Rust technical verbs. "Dangling
  pointer" and "undefined behavior" are compound technical nouns (category 15).

---

## Rule 1.2 — Use approved words only as the specified part of speech

Each entry in the controlled terminology carries one label: verb (v), noun (n),
adjective (adj), adverb (adv), preposition (prep), conjunction (conj), pronoun
(pron), or article (art). Use the word only in that grammatical role.

- "Query" is an approved **noun**, not a verb. Write "Send a query to the
  database", not "Query the database".
- "Static" is an approved **adjective**, not a verb. Write "Make the variable
  static", not "Static the variable".
- Some words carry more than one label. "Call" is an approved verb and an
  approved noun; the position in the sentence shows the function.

If the word you want is not in the controlled terminology:

1. Find the word in a standard English dictionary.
2. Find the best synonym that is approved in the STE-Code controlled terminology.
3. Use that approved word, or write a different sentence construction.

When you replace a word, make sure that the meaning does not change.

| Violating form | Part-of-speech error | Approved replacement |
|---|---|---|
| Query the database / Cache the result / Queue the job / Log the error | technical noun used as verb | Send a query / Keep the result in the cache / Put the job in the queue / Write the error in the log |
| Docker the app / Git the change / Kubectl the pod | tool name used as verb | Use Docker / Save with Git / Use `kubectl` |
| Secure the endpoint / Empty the buffer / Silent the log | adjective used as verb | Make the endpoint secure / Make the buffer empty / Make the log silent |
| Static the variable / Ready the worker / Live the connection | adjective used as verb | Make the variable static / Make the worker ready / Make the connection live |
| Utilize / Leverage / Employ the service | inflated verb | Use the service |
| Commence the build / Initiate the transfer / Terminate the process | inflated verb | Start the build / Start the transfer / Stop the process |
| Orchestrate the services / Facilitate the sync | unapproved verb | Control the services / Help the sync |

> **Non-STE:** Docker the app and deploy to production. If it fails, rollback.
>
> **STE:** Use Docker to make a container for the application. Deploy the
> container to production. If the deployment fails, roll back to the previous
> version.

---

## Rule 1.3 — Use approved words only with their approved meanings

Each approved word has one specified meaning, often narrower than the standard
English meaning. Do not use an approved word with any other meaning.

- The approved meaning of the verb **follow** is "come after, go after". Use it
  only for sequence: "Do the steps that follow."
- The approved meaning of the verb **obey** is "to do that which the procedures
  or instructions tell you". Use it for compliance: "Obey the instructions."

Four-step check for every approved word you write:

1. **Identify the part of speech** as you used it in the sentence.
2. **Look up the approved meaning** for that part of speech in the controlled
   terminology.
3. **Ask: does my sentence use exactly that meaning?** If not, the word fails —
   even when the word is approved and the sentence reads well.
4. **Replace or restructure** so the approved word carries its approved meaning.

Worked check:

> **Sentence:** The background worker runs every night.
> **Step 1:** "runs" is a verb.
> **Step 2:** Approved meaning of "run" = "execute a program or command".
> **Step 3:** The writer means "operates on a schedule". The meaning does not match.
> **Step 4:** Rewrite: "The background worker operates every night."

---

## Rule 1.4 — Use only the approved forms of verbs and adjectives

The controlled terminology gives each approved verb with its approved forms, and
each approved adjective in the base form with the comparative and superlative
forms where applicable.

Verb entry: `COMPILE (v), COMPILES, COMPILED, COMPILED`

| Infinitive / imperative | Simple present | Simple past | Past participle (as adjective) |
|---|---|---|---|
| (To) Compile / Compile | Compile(s) | Compiled | Compiled |

Forms that are not listed are not permitted: "compilating" and "compilates" are
both incorrect.

Adjective entry: `FAST (adj) (FASTER, FASTEST)` — base form *fast*, comparative
*faster*, superlative *fastest*. Adjectives that make their comparative and
superlative with "more" and "most" have no extra forms in the terminology,
because "more" and "most" are approved words.

Do not use the "-ing" form as a main verb in procedural writing unless the
controlled terminology lists it.

> **Non-STE:** The compiler is compilating the source files every time you save
> the document.
>
> **STE:** The compiler compiles the source files each time you save the document.

> **Non-STE:** This algorithm is more fast than the previous one.
>
> **STE:** This algorithm is faster than the previous one.

> **Non-STE:** After installing the dependencies, you can start compiling the
> project by running the build script.
>
> **STE:** After you install the dependencies, compile the project with the build
> script.

---

## Rule 1.5 — Code-domain technical noun categories

A code-domain technical noun is a noun term for a specified concept in software
development, applicable to a subject field. The controlled terminology cannot
list them all, because each project uses different ones; keep yours in the
project glossary or terminology database.

STE-Code gives the categories to help you select the technical nouns for your
project glossary and to use them correctly. You may use a code-domain technical
noun in procedural and descriptive writing when you can put it in one or more of
these **nineteen** categories. The words shown are examples only, not a complete
list.

| # | Category | Example terms |
|---|---|---|
| 1 | Code components, modules, and libraries | class, controller, helper, hook, middleware, mixin, module, package, plugin, provider, repository, service, utility |
| 2 | Computing devices and their components | CPU, disk, GPU, keyboard, laptop, memory, monitor, mouse, printer, screen, server, smartphone, tablet, terminal |
| 3 | Development tools, environments, and support equipment | CLI, compiler, debugger, Docker, editor, IDE, Git, Jest, linter, loader, Prettier, terminal, test runner, TypeScript, webpack |
| 4 | Data structures, types, and formats | array, boolean, buffer, CSV, enum, hash map, integer, JSON, linked list, object, queue, stack, string, struct, tree, tuple, XML, YAML |
| 5 | Infrastructure, deployment, and platforms | AWS, CI/CD, container, deployment, Heroku, Kubernetes, load balancer, Node.js, pipeline, pod, production, staging, Vercel |
| 6 | Systems, subsystems, and architectural components | API gateway, authentication layer, caching layer, client, database layer, message broker, microservice, proxy, rate limiter, REST API, routing layer, server, WebSocket |
| 7 | Mathematical, algorithmic, and scientific terms | Big O notation, binary search, coefficient, complexity, exponent, hash function, iteration, logarithm, matrix, recursion, regex, sorting algorithm, time complexity, traversal |
| 8 | Interface elements and navigation | button, checkbox, dialog, dropdown, footer, header, menu, modal, navigation bar, radio button, scrollbar, sidebar, tab, text field, toggle, tooltip |
| 9 | Numbers, units of measurement, and time | byte, gigabyte (GB), hertz (Hz), hour (h), kilobyte (KB), megabyte (MB), millisecond (ms), minute, nanosecond (ns), second (s), terabyte (TB) |
| 10 | Quoted text (text you cannot change: error messages, code snippets, UI labels, log output) | `Cannot read properties of undefined`, `ENOENT: no such file or directory`, `Submit` button, `404 Not Found`, `connection refused` |
| 11 | Professional roles, teams, and organizations | administrator, backend developer, contributor, DevOps engineer, frontend developer, Google, maintainer, Microsoft, product owner, QA engineer, reviewer, scrum master, user |
| 12 | Official documents, API references, and standards | API reference, changelog, code of conduct, contributing guide, diagram, figure, Getting Started guide, HTTP specification, note, paragraph, README, release notes, RFC, section, table, warning |
| 13 | Runtime environments and operational conditions | development, environment variable, garbage collection, heap, hot reload, live reload, memory leak, production, sandbox, stack trace, staging, test, thread, timeout, virtual machine |
| 14 | Colors | black, blue, cyan, gray, green, magenta, orange, red, white, yellow |
| 15 | Defects, errors, and fault terminology | assertion failure, bug, crash, deadlock, defect, exception, hang, infinite loop, memory leak, null pointer, race condition, regression, stack overflow, timeout, type error |
| 16 | Computer science, information, and communication technology | AI, algorithm, authentication, authorization, blockchain, containerization, cryptography, database, encoding, encryption, firewall, hashing, internet, machine learning, metadata, neural network, protocol, query, sandbox, schema, token, virtualization |
| 17 | Legal and licensing terms | Apache 2.0, BSD license, compliance, copyright, GPL, license, MIT license, open source, proprietary, terms of service, third-party, trademark, warranty |
| 18 | Database and storage terminology | connection pool, cursor, foreign key, index, migration, NoSQL, ORM, PostgreSQL, primary key, query, Redis, relation, row, schema, seed, SQL, SQLite, stored procedure, table, transaction, view |
| 19 | Network and protocol terminology | DNS, endpoint, HTTP, HTTPS, IP address, localhost, middleware, packet, port, request, response, route, socket, SSH, TCP, TLS, UDP, URL, VPN, WebSocket |

Note on category 14: colors are adjectives, but STE-Code identifies them as
code-domain technical nouns. Comparative and superlative forms of colors (for
example "blacker", "the reddest") are not permitted.

---

## Rule 1.6 — Unapproved words are permitted only inside technical nouns

A word that the controlled terminology marks as not approved fails when you use
it as a general noun or adjective, and passes when it is part of a recognized
code-domain technical noun.

**"Handler"** — not approved; the alternative is "function (n)".

> **Non-STE:** The handler processes each incoming event.
>
> **STE:** The function processes each incoming event.
>
> **STE:** The event handler processes each incoming event. ("Event handler" is a
> code-domain technical noun, category 1.)

**"Main"** — not approved as a general adjective; the alternative is
"primary (adj)".

> **Non-STE:** The main configuration has the latest values.
>
> **STE:** The primary configuration has the latest values.
>
> **STE:** Merge the feature branch into the main branch. ("Main branch" is a
> code-domain technical noun, category 5. Do not write "primary branch".)

**"Base"** — not approved for a surface location; the alternative is "bottom
(n)". "Base" stays inside the technical nouns "base case" (category 7) and "base
class" (category 1).

> **Non-STE:** Copy the files to the base of the build folder.
>
> **STE:** Copy the files to the bottom of the build folder.

---

## Rule 1.7 — Do not use code-domain technical nouns as verbs

Use a code-domain technical noun only as a noun, or as an adjective inside a
different technical noun. Restructure the sentence with an approved verb.

> **Non-STE:** Database the user records before the migration.
>
> **STE:** Store the user records in the database before the migration.

> **Non-STE:** Cache the API responses to improve performance.
>
> **STE:** Store the API responses in the cache to improve performance.

A word can be a technical noun **and** a technical verb when it fits a category
in Rule 1.5 and a category in Rule 1.12. Your project glossary decides:

> **STE (noun):** Write a log entry for each failed request.
>
> **STE (verb):** Log each failed request.

> **See also:** Rule 1.5, Rule 1.12, Rule 1.13.

---

## Rule 1.8 — Use the technical nouns approved in your project or field

If your project, company, industry, or subject field already has an approved
name for a class, module, function, method, variable, component, or process, use
that name. These names live in your project glossary, API documentation, coding
standards, or company documentation. Do not invent your own names for items that
already have established names. The source of truth is the repository.

> **STE:** The dashboard page has a `UserTable` component and a `FilterPanel`
> component.

> **Non-STE:** The account controller manages login and user profile operations.
>
> **STE:** The `AccountController` manages authentication and user profile
> operations.

---

## Rule 1.9 — Select short, easy technical nouns

When no approved technical noun exists in your project, company, industry, or
subject field, select one that is short (not more than three words) and easy to
understand. Do not write a long descriptive phrase when a shorter term is
enough. When the context identifies the item — a code snippet, a line number, a
diagram, an API reference — use the shortest unambiguous term. Add one or two
adjectives only when clarification is necessary.

```javascript
// client.js — line 42
async function fetchUtility(url) {
  const response = await fetch(url);
  return response.json();
}
```

> **Non-STE:** Call the asynchronous JavaScript XML HTTP request wrapper utility
> function (line 42) to get the serialized JSON payload from the remote
> application programming interface endpoint.
>
> **STE:** Call the `fetchUtility` function (line 42) to get the JSON data from
> the API endpoint.

---

## Rule 1.10 — No regional, slang, or jargon words as technical nouns

Some technical words are used only inside confined communities or single
technology ecosystems. They are not easy to understand for readers from a
different background or stack. Code documentation is read by junior developers,
developers from other language communities, and non-native English speakers: a
word that one subculture finds clear can be opaque to every other reader. Always
select well-known words.

| Do not write | Write |
|---|---|
| Remove all the cruft from the legacy module. | Remove all the unnecessary code from the legacy module. |
| The function monkeys with the input data before validation. | The function changes the input data before validation. |
| Bikeshedding delayed the API design by two weeks. | Unnecessary discussion about small details delayed the API design by two weeks. |
| I spent the morning yak shaving before I could write the test. | I spent the morning completing unrelated prerequisite tasks before I could write the test. |
| Replace the foo and bar placeholders with real values. | Replace the example and placeholder values with real values. |

---

## Rule 1.11 — One technical noun per item

Do not use a different code-domain technical noun in another part of your
documentation for the same item. Changing the name of one item between sections
forces the reader to decide whether you mean the same item or a different one.
The source of truth for the name is the code: the class, function, module,
table, resource, environment variable, or configuration key as it is defined in
the repository.

> **Non-STE:**
> 1. Initialize the UserService class to start the session manager.
> 2. Call the authenticate method on the AccountManager to verify a user.
> 3. The UserHandler returns a session token that you send in later requests.
>
> **STE:**
> 1. Initialize the UserService class to start the session manager.
> 2. Call the authenticate method on the UserService to verify a user.
> 3. The UserService returns a session token that you send in later requests.

> **Non-STE:** "/api/login path", "authentication route", "login endpoint" —
> three names for one endpoint.
>
> **STE:** Use "/api/login endpoint" in every sentence, because the OpenAPI file
> defines the path as `/api/login`.

---

## Rule 1.12 — Code-domain technical verb categories

A code-domain technical verb is a verb term that refers to a specified operation
or process in software development and is applicable to a subject field. The
controlled terminology does not include them all; keep yours in the project
glossary or terminology database.

Code-domain technical verbs must obey the same rules as other approved verbs.
Use them in procedural and descriptive texts when you can put them in one or more
of these four categories (examples only, not a complete list):

1. **Development processes**
   - a) Write and modify code: compile, concatenate, import, inject, instantiate,
     lint, minify, marshal, optimize, polyfill, refactor, resolve, shim, stub,
     substitute, tokenize, transpile, trace, vectorize
   - b) Test and verify code: assert, benchmark, debug, fuzz, instrument, mock,
     profile, snapshot, spy, stub, unit-test
   - c) Build and package: bundle, deploy, package, publish, release, tag, version
   - d) Manage dependencies: hoist, install, link, lock, pin, update, upgrade

2. **Computer processes and applications**
   - a) Input and output: click, copy, cut, digitize, enter, paste, press, print,
     scan, swipe, tap, type
   - b) UI and application operations: clear, close, delete, deselect, disable,
     drag, enable, encrypt, erase, filter, hide, highlight, invalidate, maximize,
     minimize, navigate, open, save, scroll, select, show, sort, store, submit,
     toggle, validate, zoom in, zoom out
   - c) System operations: abort, authenticate, authorize, boot, cache,
     communicate, configure, debug, deserialize, download, format, hydrate,
     initialize, install, load, log, manage, mount, process, reboot, render,
     retry, serialize, spawn, synchronize, throttle, update, upgrade, upload

3. **Instructions and information for applicable subject fields**
   - a) Algorithmic, mathematical, data: aggregate, bisect, compute, concatenate,
     convert, count, decode, encode, escape, filter, hash, index, map, merge,
     normalize, parse, pipeline, precompute, recalculate, reduce, tokenize,
     transform, validate, verify
   - b) Database and storage: backup, compact, flush, index, migrate, persist,
     query, replicate, restore, roll back, seed, shard, upsert, vacuum,
     write-ahead
   - c) Network and communication: broadcast, connect, disconnect, establish,
     forward, handshake, intercept, listen, poll, proxy, reject, resolve, route,
     send, stream, timeout, tunnel, unsubscribe, webhook
   - d) Security and authentication: authenticate, authorize, decrypt, decode,
     encode, encrypt, hash, revoke, salt, sanitize, sign, validate, verify

4. **Legal and licensing terms** — only for legal and regulatory texts:
   acknowledge, assign, comply with, conform to, disclose, enforce, explain,
   grant, inform, license, modify, notify, permit, regulate, sign, supersede,
   waive

If there is an approved verb in the controlled terminology that accurately gives
the instruction or information, use the approved verb. Do not use a code-domain
technical verb if you can write the same sentence with approved words.

> **Non-STE:** If you detect a null pointer exception in the parser, fix it before
> the response returns to the client.
>
> **STE:** If you find a null pointer exception in the parser, fix it before the
> response returns to the client.

> **STE:** Read the API key from the configuration file. ("Enter" is a
> code-domain technical verb, category 2 a.)

> **Non-STE:** Run the database migration to version 3, then verify the row
> counts before you open the service.
>
> **STE:** Run the migration of the database schema to version 3, then check the
> row counts before you open the service. (Prefer approved "run" + technical noun
> "migration" over the technical verb "migrate" when precision is not lost.)

Dual-category note: a word may be both a technical verb (Rule 1.12) and a
technical noun (Rule 1.5). For example `deploy` is a technical verb (category 1
c) and a technical noun (category 5); `serialize` is a technical verb and also a
method name (technical noun). Let your project glossary decide the role.

---

## Rule 1.13 — Do not use code-domain technical verbs as nouns

Use code-domain technical verbs only as verbs, not as nouns. If you need a noun,
find an approved noun or a code-domain technical noun with the equivalent meaning.

The most common violation is the **light verb construction**: a weak verb (do,
make, perform, execute, run) paired with a nominalized technical verb.

| Do not write | Write |
|---|---|
| Make a commit of your changes | Commit your changes |
| Do a compile of the source files | Compile the source files |
| Execute a rollback of the migration | Roll back the migration |
| The import of the module takes ten seconds | The import operation for the module takes ten seconds |
| The merge of the feature branch caused a conflict | The merge operation of the feature branch caused a conflict |

Dual-category exception: when a word fits both a technical verb category (Rule
1.12) and a technical noun category (Rule 1.5), you may use it as a noun.

| Word | Technical Verb | Technical Noun |
|------|---------------|---------------|
| build | 1 c) Build and package | 3) Development tools |
| deploy | 1 c) Build and package | 5) Infrastructure, deployment, and platforms |
| test | 1 b) Test and verify code | 3) Development tools |
| commit | 2 c) System operations | 4) Data structures |
| merge | 1 c) Build and package | 4) Data structures |
| release | 1 c) Build and package | 5) Infrastructure, deployment, and platforms |
| patch | 1 a) Write and modify code | 4) Data structures |
| log | 2 c) System operations | 13) Runtime environments |
| import | 1 a) Write and modify code | 4) Data structures |

Article test: if you can put "a / an / the" before the word and the sentence
stays grammatical, the word is acting as a noun. If it is not a dual-category
word, the usage violates Rule 1.13. "The build failed" is correct (dual-category);
"the compile failed" is wrong (compile is only a technical verb).

Quoted tool output (Rule 1.5 category 10) is exempt: a compiler message that says
"compile error" is text you did not write and must not be changed.

> **See also:** Rule 1.5, Rule 1.7, Rule 1.12.

---

## Rule 1.14 — Use American English spelling unless other official directives tell you differently

Use the spelling specified in the STE-Code controlled terminology (American
English). Use a different spelling only if other project specifications, style
guides, contracts, or official directives apply.

If quoted text has British English spelling — an error message, a code comment, a
user interface label, terminal output — do not change it. Keep the quoted text as
it is (Rule 8.6). The surrounding prose must use American English spelling.

Common British → American pairs:

| British | American | Context |
|---------|----------|---------|
| colour | color | UI, terminal, theming |
| behaviour | behavior | feature descriptions, bug reports |
| organise | organize | restructuring, refactoring |
| analyse | analyze | profiling, data processing |
| licence (noun) | license | software license, license key |
| defence | defense | security fixes |
| centre | center | layout, positioning |
| initialise | initialize | object initialization |
| serialise | serialize | object serialization |
| optimise | optimize | performance optimization |
| parametrise | parameterize | parameterized types |
| cancelled | canceled | canceled operations |
| customise | customize | custom behavior |
| minimise | minimize | rollout minimization |
| synchronise | synchronize | state sync |
| traveller | traveler | traveler pattern |

> **Non-STE:** The log file shows the colour of each output line. Initialise the
> variable before you use it in the loop.
>
> **STE:** The log file shows the color of each output line. Initialize the
> variable before you use it in the loop.

> **STE:** The terminal shows the message `Colour profile not recognised`.
> (Quoted terminal output keeps its British spelling; the prose around it uses
> American English.)

> **See also:** Rule 8.6 — Use Quoted Texts Correctly.

---

## Extension adjectives for Section 1

These adjectives are approved extensions to the controlled terminology, added for
the code domain. Use them as the specified part of speech (Rule 1.2).

| Adjective | Definition | STE example |
|-----------|------------|-------------|
| idempotent | Describes an operation that produces the same result when applied more than once, with no extra side effects after the first run. | Make the retry handler idempotent so a second call with the same input does not duplicate the record. |
| immutable | Describes a data structure or value that cannot be changed after it is created, which prevents accidental shared-state bugs. | Keep the request context immutable so concurrent threads cannot overwrite each other's values during a single operation. |
| atomic | Describes an operation that completes fully or not at all, with no partial result visible to other processes. | Wrap the balance update in an atomic transaction so the debit and credit always succeed or fail together. |
| thread-safe | Describes code that functions correctly when accessed by multiple threads at the same time without external locking. | Mark the singleton constructor thread-safe so two threads can call it on first use without creating two instances. |
| asynchronous | Describes a call or task that starts and returns before its work finishes, so the caller can do other work meanwhile. | Make the file upload asynchronous so the user interface stays responsive while the transfer runs in the background. |
| concurrent | Describes tasks that make progress within the same time period, interleaved by the scheduler rather than strictly sequentially. | Run the test suites in concurrent processes so the full check finishes in a fraction of the time. |

The full extension inventory (nouns, verbs, and adjectives) is in
`ste-code/artifacts/level5/06-extensions.md`.

---

## Reference catalogue

These external references inform the STE-Code controlled vocabulary. They are
**not** part of the standard; they are kept in `.agents/reference/` outside
`final/`. They are listed here as a catalogue only.

| Reference | Type | Source |
|---|---|---|
| Microsoft Writing Style Guide | page | https://learn.microsoft.com/en-us/style-guide/welcome/ |
| MicrosoftDocs/microsoft-style-guide (GitHub source) | page | https://github.com/MicrosoftDocs/microsoft-style-guide |
| Google Style Guides | page | https://google.github.io/styleguide/ |
| Kong/apiglossary | page | https://github.com/Kong/apiglossary |
| dwyl/technical-glossary | raw | https://raw.githubusercontent.com/dwyl/technical-glossary/main/README.md |
| jvalentino/glossary | page | https://github.com/jvalentino/glossary |
| GitHub Official Glossary | page | https://docs.github.com/en/get-started/learning-about-github/github-glossary |
| DevOps Style Guide Glossary | page | https://tydukes.github.io/coding-style-guide/glossary/ |
| ryanwi software-terms.dic | raw | https://gist.githubusercontent.com/ryanwi/6135845/raw/software-terms.dic |
| OpenSTE.org | pointer | https://openste.org/ |
| en-wl/wordlist (SCOWL) | page | https://github.com/en-wl/wordlist |
| MichaelWehar 5000-more-common | raw | https://raw.githubusercontent.com/MichaelWehar/Public-Domain-Word-Lists/master/5000-more-common.txt |
| dwyl/english-words | pointer | https://github.com/dwyl/english-words |

The full catalogue, with local mirror paths, is in
`ste-code/artifacts/level5/07-catalogue.md`.

---

## Provenance

Section 1 of STE-Code is adapted from ASD-STE100 Issue 9, Part 1, Section 1
(Words). The adaptation is semantic, not a word swap: each rule keeps its intent
and structure, and the examples and categories are re-expressed for software
documentation. Two structural changes apply to this section:

- The 22 technical noun categories of the source specification become **19**
  code-domain categories (Rule 1.5).
- The technical verb categories become **4** code-domain categories (Rule 1.12).

Per-rule source mapping and the original rule text are in
`ste-code/final/rules/a-sec1-rule1.*.md`, and the tier-wide provenance record is
in `ste-code/artifacts/level5/08-provenance.md`.

---

## Section 1 checklist for LLM generation and review

For each word in the prose you generate:

1. Is the word approved in the controlled terminology? If yes, check the part of
   speech (1.2), the meaning (1.3), and the form (1.4).
2. If it is not approved, is it a code-domain technical noun in one of the 19
   categories (1.5, 1.6)? Use it only as a noun (1.7).
3. If it is not a noun, is it a code-domain technical verb in one of the 4
   categories (1.12)? Use it only as a verb (1.13), and prefer an approved verb
   when one carries the same meaning.
4. Prefer the name already used in the repository or project glossary (1.8), keep
   it short (1.9), avoid slang and jargon (1.10), and use the same name for the
   same item everywhere (1.11).
5. Spell in American English (1.14), but never change quoted text.

If a word passes no gate, replace it or rewrite the sentence.




## 02-synonyms.md

# Level 5 — Code-Domain Technical Noun Categories (Rule 1.5)

> Slice 02 of STE-Code Level 5 (full standard: all rules + extensions + catalogue + provenance).
> Source: ASD-STE100 Issue 9, Rule 1.5 (master.md lines 1698-1878), adapted to the code-documentation domain.
> Companion rules: 1.1 (approved words), 1.6-1.11 (gate mechanics).

## When to use this slice

Use this reference when you must decide whether a word that is NOT in the STE-Code approved dictionary may still appear in code documentation — READMEs, API reference, docstrings, commit messages, ADRs, error messages, and test specs.

**Rule 1.5.** You can use a word that you can include in a code-domain technical noun category.

A code-domain technical noun is a noun term that refers to a specified software concept and is applicable to a given codebase, library, or system. The approved-term dictionary does not list project-specific technical nouns because each codebase, framework, and ecosystem uses different terminology. You can find them in your project glossary, API reference, or architecture decision records (ADRs).

STE-Code gives you the categories below, with examples, to help you:
- Select technical nouns to register in your project glossary.
- Use technical nouns correctly in documentation.

You may use a technical noun in procedural and descriptive code documentation if it fits one or more of the categories below.

**Non-STE vs STE.** "Use the thing to call the function that gets data from the database." → "Use the `fetchUser` method of the `UserRepository` to retrieve a `User` record from the `PostgreSQL` database." (`fetchUser`, `UserRepository`, `User`, `PostgreSQL` are technical nouns — categories 1, 6, 19.)

## How Rule 1.5 fits with the other rules

- **Rule 1.1** requires an approved dictionary word for all common vocabulary. Use an approved word whenever one exists.
- **Rule 1.5** is the complement: it permits a word outside the dictionary when it names a technical concept.
- **Rule 1.6** forbids any non-approved word unless it is a technical noun (classified in a category below) or part of one.
- Together, 1.1 + 1.5 + 1.6 form the gate: a word is allowed if it is approved (1.1) OR a classified code-domain technical noun (1.5); otherwise 1.6 forbids it.

**Glossary registration (required).** Before you use a code-domain technical noun, add it to the project glossary with: the noun term; the STE-Code category (or categories) it belongs to; the approved meaning in the project context; and an example sentence that uses it correctly.

---

## The 19 code-domain technical noun categories

### Category 1 — API and library components
Terms that refer to all API and library components. For example, technical nouns in API reference docs, SDK manifests, or interface definition files.
`endpoint, method, parameter, query parameter, path parameter, request body, response body, header, status code, module, class, interface, type alias, enum, constant, decorator, middleware, route handler, serializer, DTO, model, schema, callback, hook, plugin`

Non-STE: "Call the thing that makes users."
STE: "Call the `POST /api/v1/users` endpoint with a `CreateUserRequest` body to create a `User` resource."

### Category 2 — Applications, services, and subsystems
Terms that refer to all types of applications, services, and their subsystems, and the locations that are part of these units.
`web application, mobile app, desktop client, CLI tool, microservice, monolith, API gateway, load balancer, database server, message broker, cache layer, container, pod, cluster, frontend, backend, admin panel, user dashboard, authentication service, payment service, notification service, search engine, CDN, reverse proxy, serverless function, cron job, worker process`

Non-STE: "The thing that runs the website broke."
STE: "The `nginx` reverse proxy on the `web-01` frontend server stopped responding."

### Category 3 — Development tools and support equipment
Terms that refer to all types of development tools, SDKs, and their components, and locations that are part of these items.
`IDE, code editor, terminal emulator, compiler, interpreter, transpiler, bundler, linter, formatter, debugger, profiler, package manager, version control system, CI runner, test framework, assertion library, mocking library, static analyzer, API client, database client, container runtime, orchestration tool, IaC tool, monitoring dashboard, log aggregator, feature flag service, secrets manager`

Non-STE: "Run the check tool to find problems."
STE: "Run `ESLint` with the `@company/eslint-config` preset to find lint violations."

### Category 4 — Dependencies, packages, and technical debt
Terms that refer to dependencies, packages, and technical debt that can cause regressions or malfunctions.
`dependency, transitive dependency, package, library, framework, runtime, polyfill, shim, vendor bundle, dead code, deprecated API, legacy module, orphaned code, code smell, TODO comment, FIXME comment, zombie import, circular dependency, peer dependency, dev dependency, optional dependency, pinned version, lockfile, SBOM, supply chain artifact, third-party script, ad-hoc patch, monkey-patch, workaround code`

Non-STE: "There's a problem with one of the things we installed."
STE: "The `lodash@4.17.20` transitive dependency introduces a prototype pollution vulnerability (CVE-2020-8203)."

### Category 5 — Hosting, CI/CD, and deployment infrastructure
Terms that refer to the management, structure, and operations of hosting, CI/CD, and deployment infrastructure.
`cloud provider, region, availability zone, data center, Kubernetes cluster, namespace, Docker registry, artifact repository, build pipeline, deployment pipeline, staging environment, production environment, sandbox environment, on-premise server, virtual machine, bare-metal host, edge location, CDN endpoint, storage bucket, message queue, event bus, API gateway endpoint, load balancer target group, auto-scaling group, service mesh, ingress controller`

Non-STE: "Deploy to the cloud place."
STE: "Deploy the `orders-service` container image to the `us-east-1` `production` Kubernetes cluster in namespace `orders`."

### Category 6 — Systems, subsystems, and architectural components
Terms that refer to the structure, operation, composition, and system design of software.
`architecture, design pattern, layered architecture, hexagonal architecture, microservice, event-driven architecture, CQRS, event sourcing, pub/sub, message queue, event bus, database shard, read replica, write-ahead log, connection pool, circuit breaker, retry policy, rate limiter, cache layer, CDN edge, feature flag, A/B test variant, canary deployment, blue-green deployment, rolling update, service registry, configuration provider, secret store, reverse proxy, API gateway route, middleware chain, plugin system, dependency injection container, ORM, migration runner`

Non-STE: "The system uses a pattern to handle failures gracefully."
STE: "The `PaymentGateway` client uses a `CircuitBreaker` pattern — after 5 consecutive failures, it opens and returns cached fallback responses for 30 seconds."

### Category 7 — Mathematical, algorithmic, and scientific terms
Terms that refer to algorithms, data structures, computational concepts, and methodologies.
`algorithm, data structure, Big-O notation, time complexity, space complexity, hash table, binary tree, linked list, graph, trie, bloom filter, LRU cache, consistent hashing, recursion, memoization, dynamic programming, greedy algorithm, backtracking, binary search, quicksort, mergesort, topological sort, Dijkstra, BFS, DFS, A*, Paxos, Raft, two-phase commit, saga pattern, idempotency key, eventual consistency, CAP theorem, ACID, BASE, vector clock, Lamport timestamp, Merkle tree, consistent hashing ring, shard key, partition key, compound index, covering index, query plan, cardinality, selectivity, normalization, denormalization, OLTP, OLAP, ETL, stream processing, batch processing, map-reduce, actor model, CSP, semaphore, mutex, atomic operation, CAS`, `O(n log n)`, `f(x) = x² + 3x - 2`

Non-STE: "The search is fast because it uses a good algorithm."
STE: "The `SearchIndex` uses a `BloomFilter` (`O(k)` lookup) to skip negative lookups before falling back to a `B-Tree` index scan."

### Category 8 — Codebase navigation and project structure
Terms that refer to codebase navigation, project structure, and directory/import hierarchy.
`directory, subdirectory, file path, import path, package root, module root, workspace root, monorepo root, source directory, test directory, build output, entry point, barrel export, index file, re-export, absolute import, relative import, path alias, symlink, Git root, branch, tag, commit, HEAD, upstream, origin, fork, submodule, subtree, vendor directory, node_modules, virtual environment, GOPATH, classpath, namespace, package scope, module scope, public API surface, internal package, private module, exported symbol`

Non-STE: "The file is in the utils folder somewhere."
STE: "The `formatCurrency` helper is in `src/shared/utils/formatting.ts`, re-exported from the barrel file at `src/shared/utils/index.ts`."

### Category 9 — Numbers, units of measurement, and time
Terms that refer to metrics, benchmarks, timing data, and quantitative measurements.
`latency, throughput, response time, p50, p95, p99, p999, ops/sec, req/sec, RPM, RPS, QPS, TPS, bytes, KB, MB, GB, TB, KiB, MiB, ms, µs, ns, s, min, hr, CPU core, thread count, memory usage, heap size, stack size, GC pause, cold start time, warm start time, bootstrap time, build time, deploy time, MTTR, MTBF, uptime, downtime, error rate, success rate, availability (99.9%, 99.99%), RPO, RTO, SLO, SLI, SLA, concurrency, connection count, pool size, batch size, page size, offset, limit, TTL, timeout, interval, poll interval, retry delay, backoff multiplier, rate limit (tokens/sec), quota, sample rate, cardinality`

Non-STE: "The API is pretty fast most of the time."
STE: "The `GET /search` endpoint has a p95 latency of 120 ms and a p99 latency of 350 ms at 5000 RPM."

### Category 10 — Quoted text
Terms that refer to texts that you cannot change in code documentation. For example, quoted error messages, log output, API responses, UI string literals, and command-line output.
`error message, stack trace, log line, HTTP response body, JSON payload, XML response, environment variable value, CLI flag, command option, shell command output, status code text, exception message, assertion message, deprecation warning, compiler diagnostic, linter rule ID, test failure message, benchmark output, profiler report, API route pattern, SQL query string, GraphQL query, regex pattern, glob pattern, cron expression, semantic version string, git commit hash, UUID string, JWT token (example)`, `"Connection refused"`, `"404 Not Found"`, `"TypeError: Cannot read properties of undefined"`, `"--config=./prod.yaml"`, `"npm ERR! code ERESOLVE"`

Non-STE: "If you get an error about the database, restart it."
STE: "If the application logs `\"FATAL: sorry, too many clients already\"` from `PostgreSQL`, restart the `pgbouncer` connection pooler."



## 03-dictionary.md

# Level 5 — Adapted Dictionary A–Z

This sub-document is the **controlled-terminology catalogue** slice of STE-Code level 5 (the full standard). It lists every approved word and every unapproved word with its approved alternative(s), adapted from ASD-STE100 Issue 9, Part 2 (Dictionary, pages 149–434) to the code-documentation domain. Use it as the lookup table when an LLM must decide whether a word is permitted in STE-Code prose, and what to write instead.

> **Source:** Adapted from ASD-STE100 Issue 9, Part 2 — Dictionary, pages 149–434.
> **Domain adaptation:** aerospace → code documentation (API docs, commit messages, README sections, code comments).
> **Preserved:** word alphabetization, STE/non-STE pair format, approved/unapproved status, parts of speech.
> **Replaced:** aerospace examples with code examples.
> **Entries:** 562 (454 approved headwords, 108 unapproved). Word counts in the source header are stale aerospace-format boilerplate; 562 is the true count in this catalogue.

---

## How to read this dictionary

- **UPPERCASE headwords** are approved in STE-Code.
- **lowercase headwords** are not approved; the entry gives the approved alternative(s) to use instead.
- **(v)** = verb, **(n)** = noun, **(adj)** = adjective, **(adv)** = adverb, **(prep)** = preposition, **(conj)** = conjunction, **(pron)** = pronoun, **(art)** = article.
- **(TN)** = code-domain Technical Noun, **(TV)** = code-domain Technical Verb. A (TN) headword is an approved technical noun; a (TV) is an approved technical verb.
- For each entry: the approval status, the approved alternative(s) where relevant, and one representative STE / non-STE code-documentation pair.
- A word not in this list may still be permitted if it is a code-domain technical noun (Rule 1.5, 19 categories) or technical verb (Rule 1.12, 4 categories), or is in your project glossary.

---

# A

### A (art) — approved
- STE: A config file is included in the root directory.
- Non-STE: Config files included in root directory.

### abandon (v) - UNNAPROVED — unapproved
- Use instead: TERMINATE (v), STOP (v). IF THE BUILD FAILS, STOP THE DEPLOYMENT PIPELINE
- STE: If the build fails, stop the deployment pipeline.
- STE: If the values are incorrect, terminate the test run.
- Non-STE: If the build fails, abandon the deployment pipeline.
- Non-STE: If the values are incorrect, abandon the test procedure.

### ability (n) - UNNAPROVED — unapproved
- Use instead: CAN (v). ONE CONFIGURATION CAN HANDLE REQUESTS FOR ALL THE ENDPOINTS
- STE: One configuration can handle requests for all the endpoints.
- Non-STE: One configuration has the ability to handle requests for all the endpoints.

### able (adj) - UNNAPROVED — unapproved
- Use instead: CAN (v). IF YOU CAN RUN THE SCRIPT, DO THE APPLICABLE CHECKS
- STE: If you can run the script, do the applicable checks.
- Non-STE: If you are able to run the script, do the applicable checks.

### abnormal (adj) - UNNAPROVED — unapproved
- Use instead: UNUSUAL (adj), INCORRECT (adj). WATCH FOR UNUSUAL LOG ENTRIES
- STE: Watch for unusual log entries.
- STE: If you find an incorrect value in the output, do a debug run.
- Non-STE: Watch for abnormal log entries.
- Non-STE: If you find an abnormal value in the output, do a debug run.

### abnormality (n) - UNNAPROVED — unapproved
- Use instead: BUG (TN). EXAMINE THE REPORTED STACK TRACE FOR BUGS
- STE: Examine the reported stack trace for bugs.
- Non-STE: Examine the reported stack trace for abnormalities.

### ABOUT (prep) — approved
- STE: For data about the configuration of the module, refer to the README.
- STE: The build takes approximately 5 minutes.
- Non-STE: For data regarding the configuration of the module, refer to the README.
- Non-STE: The build takes about 5 minutes.

### ABOVE (prep) — approved
- STE: Move the cursor above the target line.
- STE: The response time must be more than 200 ms.
- Non-STE: Move the cursor to a position above the target line.
- Non-STE: The response time must be above 200 ms.

### ABRASIVE (adj) - (retained; no STE-code direct equivalent) — approved

### abrupt (adj) - UNNAPROVED — unapproved
- Use instead: SUDDEN (adj), SUDDENLY (adv). THE WATCHDOG PREVENTS SUDDEN SHUTDOWN OF THE SERVICE
- STE: The watchdog prevents sudden shutdown of the service.
- STE: If the process stops suddenly, examine the logs.
- Non-STE: The watchdog prevents abrupt shutdown of the service.
- Non-STE: If the process comes to an abrupt stop, examine the logs.

### absence (n) - UNNAPROVED — unapproved
- Use instead: NONE (pron), NOT (adv), NO (adj). IF NONE OF THE TESTS FAIL, CONTINUE THE DEPLOYMENT
- STE: If none of the tests fail, continue the deployment.
- STE: If the tests are not failing, continue the deployment.
- Non-STE: In the absence of test failures, continue the deployment.
- Non-STE: In the absence of test failures, continue the deployment.

### absent (adj) - UNNAPROVED — unapproved
- Use instead: MISSING (adj), NO (adj). IF ONE OR MORE FILES ARE MISSING, ADD AN ENTRY IN THE CHANGELOG
- STE: If one or more files are missing, add an entry in the changelog.
- Non-STE: If one or more files are absent, add an entry in the changelog.

### absolutely (adv) - UNNAPROVED — unapproved
- Use instead: FULLY (adv). MAKE SURE THAT THE CONNECTION IS FULLY ESTABLISHED
- STE: Make sure that the connection is fully established.
- Non-STE: Make sure that the connection is absolutely established.

### ABSORB (v) — approved
- STE: The buffer absorbs the input data.
- STE: The cache layer absorbs the load from repeated queries.
- Non-STE: The buffer takes up the input data.
- Non-STE: The cache layer mitigates the load from repeated queries.

### absorption (n) - UNNAPROVED — unapproved
- Use instead: ABSORB (v). MEASURE THE TIME THAT IS NECESSARY FOR THE LOG SYSTEM TO ABSORB THE INCOMING EVENTS
- STE: Measure the time that is necessary for the log system to absorb the incoming events.
- Non-STE: Measure the rate of absorption of incoming events by the log system.

### abundant (adj) - UNNAPROVED — unapproved
- Use instead: LARGE (adj). LOG THE ERRORS WITH A LARGE QUANTITY OF CONTEXT DATA
- STE: Log the errors with a large quantity of context data.
- Non-STE: Log the errors with abundant context data.

### abut (v) - UNNAPROVED — unapproved
- Use instead: TOUCH (v). THE WIDGET TOUCHES THE BOUNDARY OF THE CONTAINER
- STE: The widget touches the boundary of the container.
- Non-STE: The widget abuts the boundary of the container.

### accelerate (v) - UNNAPROVED — unapproved
- Use instead: INCREASE (v), FASTER (adj). A LARGER BUFFER SIZE INCREASES THE SPEED OF DATA TRANSFER
- STE: A larger buffer size increases the speed of data transfer.
- STE: To make the build process faster, use parallel compilation.
- Non-STE: A larger buffer size accelerates data transfer.
- Non-STE: To accelerate the build process, use parallel compilation.

### ACCEPT (v) — approved
- STE: Accept the pull request if it passes all checks.
- Non-STE: Merge the pull request if it passes all checks.

### acceptable (adj) - UNNAPROVED — unapproved
- Use instead: PERMITTED (adj), SATISFACTORY (adj), READY (adj). A RESPONSE TIME OF
- STE: A response time of 200 ms is permitted.
- STE: If the condition of the build is not satisfactory, run it again.
- Non-STE: A response time of 200 ms is acceptable.
- Non-STE: If the condition of the build is not acceptable, run it again.

### acceptance (n) - UNNAPROVED — unapproved
- Use instead: ACCEPT (v). BEFORE YOU ACCEPT THE MERGE REQUEST, DO THE SPECIFIED REVIEW CHECKLIST
- STE: Before you accept the merge request, do the specified review checklist.
- Non-STE: Before acceptance of the merge request, do the specified review checklist.

### ACCESS (n) — approved
- STE: Get access to the repository for the authentication module.
- Non-STE: Access the repository for the authentication module.

### accessible (adj) - UNNAPROVED — unapproved
- Use instead: ACCESS (n). SCROLL THE VIEW UNTIL YOU CAN GET ACCESS TO THE FUNCTIONS THAT HAVE PUBLIC ANNOTATIONS
- STE: Scroll the view until you can get access to the functions that have public annotations.
- Non-STE: Scroll the view until the functions with public annotations are accessible.

### ACCIDENT (n) — approved
- STE: To prevent accidents, make sure that the backups are configured.
- Non-STE: To prevent accidents, ensure that backups are in place.

### ACCIDENTAL (adj) — approved
- STE: To prevent accidental deletion of the files, confirm the operation.
- Non-STE: To prevent inadvertent deletion of the files, confirm the operation.

### ACCIDENTALLY (adv) — approved
- STE: If you accidentally press the delete key, restore the file from the recycle bin.
- Non-STE: If you inadvertently press the delete key, restore the file from the recycle bin.

### accommodate (v) - UNNAPROVED — unapproved
- Use instead: LET (v). DIFFERENT CONFIGURATIONS LET YOU HANDLE DIFFERENT TYPES OF INPUT
- STE: Different configurations let you handle different types of input.
- Non-STE: Different configurations accommodate different types of input.

### accomplish (v) - UNNAPROVED — unapproved
- Use instead: DO (v), COMPLETE (v). DO THIS BUILD STEP FIRST
- STE: Do this build step first.
- STE: The pipeline must complete this stage in 5 minutes.
- Non-STE: Accomplish this build step first.
- Non-STE: The pipeline must accomplish this stage in 5 minutes.

### ACCORDING to (prep) - UNNAPROVED — unapproved
- Use instead: REFER (v) TO. TO CONFIGURE THE MODULE, REFER TO THE DEVELOPER
- STE: To configure the module, refer to the developer's guide.
- Non-STE: Configure the module according to the developer's guide.

### ACCOUNT for (v) - UNNAPROVED — unapproved
- Use instead: MAKE SURE (v). MAKE SURE THAT YOU TRACK ALL DEPENDENCIES AND PACKAGES
- STE: Make sure that you track all dependencies and packages.
- Non-STE: All dependencies and packages must be accounted for.

### accumulate (v) - UNNAPROVED — unapproved
- Use instead: COLLECT (v). IF LOGS COLLECT IN THE BUFFER, FLUSH THEM
- STE: If logs collect in the buffer, flush them.
- Non-STE: If logs accumulate in the buffer, flush them.

### accumulation (n) - UNNAPROVED — unapproved
- Use instead: QUANTITY (n), COLLECT (v). REMOVE LARGE QUANTITIES OF OBSOLETE LOGS
- STE: Remove large quantities of obsolete logs.
- STE: If errors collect frequently, examine the connection for issues.
- Non-STE: Remove large accumulations of obsolete logs.
- Non-STE: If accumulation of errors is frequent, examine the connection for issues.

### accuracy (n) - UNNAPROVED — unapproved
- Use instead: PRECISION (n). THE PRECISION OF THE CALCULATION CAN CHANGE
- STE: The precision of the calculation can change.
- Non-STE: The accuracy of the calculation can change.

### ACCURATE (adj) - ACCURATELY (adv) — approved
- STE: The measurement must be accurate.
- STE: Apply the patch accurately on the target branch.
- Non-STE: The measurement must be precise.
- Non-STE: Put the patch accurately on the target branch.

### achieve (v) - UNNAPROVED — unapproved
- Use instead: GET (v). SET THE FLAG TO GET MAXIMUM PERFORMANCE
- STE: Set the flag to get maximum performance.
- Non-STE: Set the flag to achieve maximum performance.

### acquire (v) - UNNAPROVED — unapproved
- Use instead: GET (v). THE MODULE GETS THIS DATA FROM THREE ENDPOINTS
- STE: The module gets this data from three endpoints.
- Non-STE: The module acquires this data from three endpoints.

### acrid (adj) - UNNAPROVED — unapproved
- Use instead: Not applicable. Retained for completeness

### ACROSS (prep) — approved
- STE: Search across all modules for the deprecated function.
- Non-STE: Search all modules for the deprecated function.

### act (v) - UNNAPROVED — unapproved
- Use instead: Use an accurate verb. THE EVENT TRIGGER INVOKES THE HANDLER
- STE: The event trigger invokes the handler.
- Non-STE: The event trigger acts on the handler.

### action (n) - UNNAPROVED — unapproved
- Use instead: STEP (n), PROCEDURE (n), TASK (n). DO THE STEPS THAT FOLLOW
- STE: Do the steps that follow.
- STE: Do not do this procedure in the production environment.
- Non-STE: Do the following actions.
- Non-STE: This action must not be done in the production environment.

### ACTIVATE (v) — approved
- STE: The build pipeline activates the deployment mode.
- STE: Start the container.
- Non-STE: The build pipeline triggers the deployment mode.
- Non-STE: Activate the container.

### ACTIVE (adj) — approved
- STE: Read the config from the active branch.
- Non-STE: Read the config from the current branch.

### activity (n) - UNNAPROVED — unapproved
- Use instead: TASK (n), PROCEDURE (n), WORK (n). A CONTRIBUTOR CAN DO THESE REVIEW TASKS
- STE: A contributor can do these review tasks.
- STE: Do this procedure in the development branch.
- Non-STE: A contributor can do these review activities.
- Non-STE: Do this activity in the development branch.

### actuate (v) - UNNAPROVED — unapproved
- Use instead: START (v), RUN (v), PUSH (v). START THE SERVER
- STE: Start the server.
- STE: Run the script.
- Non-STE: Actuate the server.
- Non-STE: Actuate the script.

### actuation (n) - UNNAPROVED — unapproved
- Use instead: OPERATION (n). MONITOR THE OPERATION OF THE BACKGROUND WORKER
- STE: Monitor the operation of the background worker.
- Non-STE: Monitor the actuation of the background worker.

### ADAPT (v) — approved
- STE: Adapt the connector to the database schema.
- STE: The middleware layer adapts to the protocol of the connected services.
- Non-STE: Adjust the connector to fit the database schema.
- Non-STE: The middleware layer conforms to the protocol of the connected services.

### ADD (v) — approved
- STE: Add 5 lines of configuration to the file.
- Non-STE: Append 5 lines of configuration to the file.

### addition (n) - UNNAPROVED — unapproved
- Use instead: ADD (v). TO GET THE CORRECT BEHAVIOR, ADD SPECIAL FLAGS, AS NECESSARY
- STE: To get the correct behavior, add special flags, as necessary.
- Non-STE: To get the correct behavior through the addition of special flags, as necessary.

### additional (adj) - UNNAPROVED — unapproved
- Use instead: MORE (adj). THIS SECTION GIVES MORE INFORMATION ABOUT DEPLOYMENT
- STE: This section gives more information about deployment.
- Non-STE: This section gives additional information about deployment.

### adequate (adj) - UNNAPROVED — unapproved
- Use instead: SUFFICIENT (adj). MAKE SURE THAT BUFFERS HAVE SUFFICIENT CAPACITY AND THROUGHPUT
- STE: Make sure that buffers have sufficient capacity and throughput.
- Non-STE: Make sure that buffers have adequate capacity and throughput.

### adhere (v) - UNNAPROVED — unapproved
- Use instead: ATTACH (v), OBEY (v). THE PATCH MUST ATTACH CORRECTLY
- STE: The patch must attach correctly.
- STE: Obey the coding standards.
- Non-STE: The patch must adhere correctly.
- Non-STE: Adhere to the coding standards.

### adhesion (n) - UNNAPROVED — unapproved
- Use instead: Not applicable. Retained for completeness

### ADJACENT (adj) - ADJACENT TO (prep) — approved
- STE: Do not modify the adjacent function.
- STE: The config file is located adjacent to the main module.
- Non-STE: Do not modify the function that is next to it.
- Non-STE: The config file is located next to the main module.

### adjoining (adj) - UNNAPROVED — unapproved
- Use instead: ADJACENT (adj). ALIGN THE IMPORTS WITH THE ADJACENT MODULES
- STE: Align the imports with the adjacent modules.
- Non-STE: Align the imports with the adjoining modules.

### ADJUST (v) — approved
- STE: Adjust the timeout to the value given in Table 1.
- STE: The auto-scaler adjusts to sudden changes in load.
- Non-STE: Tune the timeout to the value given in Table 1.
- Non-STE: The auto-scaler adapts to sudden changes in load.

### ADJUSTABLE (adj) - ADJUSTMENT (n) — approved
- STE: The two parameters are adjustable.
- STE: Make sure that the adjustment is in the limits given in Table 1.
- Non-STE: The two parameters can be tuned.
- Non-STE: Make sure that the tuning is in the limits given in Table 1.

### admit (v) - UNNAPROVED — unapproved
- Use instead: LET (v). OPEN THE PORT TO LET TRAFFIC GO INTO THE CONTAINER
- STE: Open the port to let traffic go into the container.
- Non-STE: Open the port to admit traffic into the container.

### adopt (v) - UNNAPROVED — unapproved
- Use instead: USE (v). IF THE BUILD FAILS, USE THIS FALLBACK SCRIPT
- STE: If the build fails, use this fallback script.
- Non-STE: Adopt this fallback script if the build fails.

### advance (n) - UNNAPROVED — unapproved
- Use instead: FORWARD (adj). THE FORWARD MOVEMENT OF THE ITERATOR MUST BE SEQUENTIAL
- STE: The forward movement of the iterator must be sequential.
- Non-STE: The advance of the iterator must be sequential.

### advance (v) - UNNAPROVED — unapproved
- Use instead: SET (v), FORWARD (adv). SET THE POINTER TO THE NEXT NODE
- STE: Set the pointer to the next node.
- STE: Move the cursor forward.
- Non-STE: Advance the pointer to the next node.
- Non-STE: Advance the cursor.

### adverse (adj) - UNNAPROVED — unapproved
- Use instead: BAD (adj). REFER TO SECTION
- STE: Refer to Section 6 for instructions about how to handle bad network conditions.
- Non-STE: Refer to Section 6 for instructions about how to handle adverse network conditions.

### advisable (adj) - UNNAPROVED — unapproved
- Use instead: RECOMMEND (v). THE TECHNICAL LEAD RECOMMENDS THAT YOU REBUILD THE CONTAINERS AT INTERVALS OF TWO WEEKS
- STE: The technical lead recommends that you rebuild the containers at intervals of two weeks.
- Non-STE: It is advisable to rebuild the containers at intervals of two weeks.

### advise (v) - UNNAPROVED — unapproved
- Use instead: TELL (v), RECOMMEND (v). TELL THE REVIEWER THAT THE CHANGES ARE READY
- STE: Tell the reviewer that the changes are ready.
- STE: The security officer recommends the applicable authentication protocol.
- Non-STE: Advise the reviewer that the changes are ready.
- Non-STE: The security officer advises on the applicable authentication protocol.

### affect (v) - UNNAPROVED — unapproved
- Use instead: EFFECT (n). THREAD LOCKS HAVE AN UNWANTED EFFECT ON THE SCHEDULER
- STE: Thread locks have an unwanted effect on the scheduler.
- Non-STE: Thread locks affect the scheduler.

### AFT (adj), AFT (adv) — approved

### AFTER (conj) — approved
- STE: After you deploy the update, do a smoke test.
- Non-STE: Following deployment of the update, do a smoke test.

### AGAIN (adv) — approved
- STE: Run the test again.
- Non-STE: Rerun the test.

# B

### BACK (adj), BACK (adv) — approved
- STE: Revert to the back version.
- STE: Navigate back to the previous page.
- Non-STE: Revert to the previous version.
- Non-STE: Go backwards to the previous page.

### BACK up (v) - UNNAPROVED — unapproved
- Use instead: Not applicable as standalone verb in STE-Code. Use SAVE (v) or COPY (v) for data; REVERSE (v) for motion.
- STE: Save the database before the migration.
- STE: Copy the configuration files.
- Non-STE: Back up the database before the migration.
- Non-STE: Back up the configuration files.

### BAD (adj) — approved
- STE: Refer to Section 6 for instructions about how to handle bad build states.
- Non-STE: Refer to Section 6 for instructions about how to handle unsatisfactory build states.

### BALANCE (n), BALANCE (v) — approved
- STE: Make sure that the load is in balance across all nodes.
- STE: Balance the workload across all workers.
- Non-STE: Make sure that the load is balanced across all nodes.
- Non-STE: Distribute the workload across all workers.

### base (n) - UNNAPROVED — unapproved
- Use instead: Use FOUNDATION (n) for conceptual base, ROOT (n) for positional base
- STE: The foundation of the architecture is the data layer.
- STE: Start from the root of the project.
- Non-STE: The base of the architecture is the data layer.
- Non-STE: Start from the base of the project.

### BE (v) — approved
- STE: If there is an error in the log, restart the service.
- STE: Unhandled exceptions are dangerous.
- Non-STE: If an error exists in the log, restart the service.
- Non-STE: Unhandled exceptions constitute a danger.

### BECAUSE (conj) — approved
- STE: Do not use raw input, because it is a security risk.
- Non-STE: Do not use raw input, since it is a security risk.

### BECOME (v) — approved
- STE: The connection becomes unstable.
- Non-STE: The connection turns unstable.

### BEFORE (conj) — approved
- STE: Before you run the migration, read the release notes.
- Non-STE: Prior to running the migration, read the release notes.

### BEGIN (v) — approved
- STE: Begin the build process.
- Non-STE: Initiate the build process.

### BELOW (prep) — approved
- STE: See the example below the code block.
- Non-STE: See the example beneath the code block.

### BEND (v) — approved

### BETWEEN (prep) — approved
- STE: Put the middleware between the client and the server.
- Non-STE: Insert the middleware between the client and the server.

### BLOCK (n) — approved
- STE: Put a comment block above the function.
- Non-STE: Add documentation above the function.

### BOND (v) — approved

### BOTTOM (n), BOTTOM (adj) — approved
- STE: Scroll to the bottom of the file.
- STE: The bottom layer of the stack is the database.
- Non-STE: Scroll to the end of the file.
- Non-STE: The lowest layer of the stack is the database.

### BRACKET (n) - (TN) — approved
- STE: Use square brackets for array access.
- Non-STE: Use the bracket notation for array access.

### BREAK (v) — approved
- STE: Do not break the public API.
- STE: Break out of the loop when the flag is set.
- Non-STE: Do not cause breaking changes to the public API.
- Non-STE: Exit the loop when the flag is set.

### bring (v) - UNNAPROVED — unapproved
- Use instead: GET (v), MOVE (v). GET THE DEPENDENCIES INTO THE CONTAINER
- STE: Get the dependencies into the container.
- Non-STE: Bring the dependencies into the container.

### broad (adj) - UNNAPROVED — unapproved
- Use instead: WIDE (adj). WIDE TEST COVERAGE
- STE: Wide test coverage.
- Non-STE: Broad test coverage.

### BUG (n) - (TN) — approved
- STE: Use the bug tracker to log defects.
- Non-STE: Use the issue tracker to log defects.

### build (v) - UNNAPROVED — unapproved
- Use instead: COMPILE (v), MAKE (v). COMPILE THE PROJECT
- STE: Compile the project.
- Non-STE: Build the project.

### BURN (v) — approved
- STE: Burn the ISO image to the USB drive.
- Non-STE: Write the ISO image to the USB drive.

### BUT (conj) — approved
- STE: The build passes, but the tests fail.
- Non-STE: The build passes, however the tests fail.

### BY (prep) — approved
- STE: Build the project by the CMake tool.
- STE: Authenticate by OAuth.
- Non-STE: Build the project using CMake.
- Non-STE: Authenticate via OAuth.

### BYTE (n) - (TN) — approved
- STE: The buffer holds 1024 bytes.
- Non-STE: The buffer has a size of 1024 bytes.

# C

### CALCULATE (v) — approved
- STE: Calculate the checksum of the file.
- Non-STE: Compute the checksum of the file.

### call (v) - UNNAPROVED — unapproved
- Use instead: Three meanings: 1. NAME (v). NAME THE FUNCTION "init." 2. INVOKE (TV) - as technical verb. 3. REFER (v) TO.
- STE: Name the function "init."
- STE: Contact the administrator.
- Non-STE: Call the function "init."
- Non-STE: Call the administrator.

### CAN (v) — approved
- STE: A misconfiguration can cause a crash.
- STE: You can run the script after the build is completed.
- Non-STE: A misconfiguration could cause a crash.
- Non-STE: You are able to run the script after the build is completed.

### CANCEL (v) — approved
- STE: Cancel the deployment pipeline.
- Non-STE: Abort the deployment pipeline.

### CANNOT (v) — approved
- STE: You cannot access this endpoint without authentication.
- Non-STE: You are unable to access this endpoint without authentication.

### capable (adj) - UNNAPROVED — unapproved
- Use instead: CAN (v). THE SERVICE CAN RECOVER FROM FAILURES AUTOMATICALLY
- STE: The service can recover from failures automatically.
- Non-STE: The service is capable of recovering from failures automatically.

### care (n) - UNNAPROVED — unapproved
- Use instead: BE CAREFUL, CAUTION (n). BE CAREFUL WHEN YOU CHANGE THE CONFIGURATION
- STE: Be careful when you change the configuration.
- Non-STE: Take care when changing the configuration.

### carry (v) - UNNAPROVED — unapproved
- Use instead: MOVE (v), TRANSMIT (v). MOVE THE DATA TO THE CACHE
- STE: Move the data to the cache.
- Non-STE: Carry the data to the cache.

### CARRY out (v) - UNNAPROVED — unapproved
- Use instead: DO (v). DO THE REVIEW
- STE: Do the review.
- Non-STE: Carry out the review.

### case (n) - UNNAPROVED — unapproved
- Use instead: For conditional: IF (conj). For coding structure: use SWITCH CASE as technical noun.
- STE: If the flag is true, log the event.
- STE: Add a switch case for the error state.
- Non-STE: In case the flag is true, log the event.
- Non-STE: Handle the error case.

### CATCH (v) — approved
- STE: Catch the exception and log it.
- Non-STE: Trap the exception and log it.

### CAUSE (v) — approved
- STE: The null pointer caused the crash.
- Non-STE: The null pointer resulted in the crash.

### CAUTION (n) — approved
- STE: Obey the cautions in this README.
- Non-STE: Follow the cautions in this README.

### CENTER (n) — approved
- STE: Align the text to the center.
- Non-STE: Center the text.

### CHANGE (v), CHANGE (n) — approved
- STE: Change the function signature.
- STE: Record the changes in the changelog.
- Non-STE: Modify the function signature.
- Non-STE: Log the changes in the changelog.

### CHECK (n) — approved
- STE: Do a check of the input values.
- Non-STE: Validate the input values.

### check (v) - UNNAPROVED — unapproved
- Use instead: Not approved as verb; use VERIFY (v) or CHECK (n) with DO.
- STE: Do a check of the values.
- STE: Verify the data integrity.
- Non-STE: Check the values.
- Non-STE: Check the data integrity.

### choose (v) - UNNAPROVED — unapproved
- Use instead: SELECT (v), ALTERNATIVE (adj). SELECT THE CORRECT CONFIGURATION
- STE: Select the correct configuration.
- Non-STE: Choose the correct configuration.

### CLEAN (v), CLEAN (adj) — approved
- STE: Clean the temporary files.
- Non-STE: Delete the temporary files.

### CLEAR (adj) — approved
- STE: A clear code path for the request.
- STE: Clear documentation for the API.
- Non-STE: An unobstructed code path for the request.
- Non-STE: Understandable documentation for the API.

### CLICK (n), CLICK (v) - (TN/TV) — approved
- STE: Click the "Submit" button.
- Non-STE: Press the "Submit" button.

### CLOSE (v) — approved
- STE: Close the file handle.
- Non-STE: Release the file handle.

### CODE (n) - (TN) — approved
- STE: The code is in the `src/` directory.
- Non-STE: The source is in the `src/` directory.

### COLLECT (v) — approved
- STE: Collect the metrics from all nodes.
- Non-STE: Gather the metrics from all nodes.

### COME (v) — approved
- STE: When the service comes online, start the tests.
- Non-STE: When the service starts, start the tests.

### COMMENT (n) - (TN) — approved
- STE: Add a comment to explain the algorithm.
- Non-STE: Document the algorithm in the code.

### COMMIT (v) - (TV) — approved
- STE: Commit the changes to the repository.
- Non-STE: Save the changes to the repository.

### COMPARE (v) — approved
- STE: Compare the hash value with the expected hash.
- Non-STE: Check the hash value against the expected hash.

### COMPATIBLE (adj) — approved
- STE: The library is compatible with version 3.0.
- Non-STE: The library works with version 3.0.

### compile (v) - UNNAPROVED — unapproved
- Use instead: Technical verb (TV) for translating source code. COMPILE THE SOURCE FILES
- STE: Compile the source files.
- Non-STE: Build the source files.

### COMPLETE (v) — approved
- STE: Complete the setup wizard.
- Non-STE: Finish the setup wizard.

### COMPONENT (n) — approved
- STE: The component is imported in the module.
- Non-STE: The component is used in the module.

### COMPRESS (v) — approved
- STE: Compress the log files before archiving.
- Non-STE: Zip the log files before archiving.

### CONDITION (n) — approved
- STE: The condition of the build is satisfactory.
- STE: If the condition is true, continue.
- Non-STE: The build state is good.
- Non-STE: If the conditional evaluates to true, continue.

### CONFIGURATION (n) - (TN) — approved
- STE: The configuration file is in YAML format.
- Non-STE: The config file is in YAML format.

### confirm (v) - UNNAPROVED — unapproved
- Use instead: MAKE SURE (v). MAKE SURE THAT THE BUILD IS SUCCESSFUL
- STE: Make sure that the build is successful.
- Non-STE: Confirm that the build is successful.

### CONNECT (v) — approved
- STE: Connect the client to the server.
- Non-STE: Establish a connection between the client and the server.

### CONTAIN (v) — approved
- STE: The module contains the helper functions.
- Non-STE: The module includes the helper functions.

### CONTACT (v) — approved
- STE: Contact the system administrator.
- Non-STE: Get in touch with the system administrator.

### CONTINUE (v) — approved
- STE: If the build passes, continue the deployment.
- Non-STE: If the build passes, proceed with the deployment.

### CONTROL (n), CONTROL (v) — approved
- STE: The control of the access is role-based.
- STE: Control the workflow with the dashboard.
- Non-STE: Access is role-based.
- Non-STE: Manage the workflow with the dashboard.

### COPY (v) — approved
- STE: Copy the config to the staging environment.
- Non-STE: Duplicate the config to the staging environment.

### CORRECT (adj) — approved
- STE: Make sure that the test results are correct.
- Non-STE: Verify that the test results are correct.

### CORRECTLY (adv) — approved
- STE: Make sure that the package is correctly installed.
- Non-STE: Ensure the package is correctly installed.

### COUNT (v) — approved
- STE: Count the records in the database.
- Non-STE: Get the count of records in the database.

### COVER (n) — approved

### CRASH (v) - (TV) — approved
- STE: If the application crashes, read the logs.
- Non-STE: If the application fails, read the logs.

### CREATE (v) — approved
- STE: Create a new instance of the class.
- Non-STE: Instantiate a new object of the class.

### CUT (v) — approved
- STE: Cut the text and paste it in the new location.
- Non-STE: Move the text to the new location.

# D

### DAMAGE (n) — approved
- STE: The damage to the data is irreversible.
- Non-STE: The data corruption is irreversible.

### danger (n) - UNNAPROVED — unapproved
- Use instead: RISK (n). THIS OPERATION HAS A RISK OF DATA LOSS
- STE: This operation has a risk of data loss.
- Non-STE: There is a danger of data loss with this operation.

### DANGEROUS (adj) — approved
- STE: This command is dangerous.
- Non-STE: This command poses a danger.

### DATA (n) - (TN) — approved
- STE: The data is stored in the cache.
- Non-STE: The information is stored in the cache.

### DEACTIVATE (v) — approved
- STE: Deactivate the background worker.
- Non-STE: Disable the background worker.

### DEBUG (v) - (TV) — approved
- STE: Debug the application with the attached profiler.
- Non-STE: Troubleshoot the application with the attached profiler.

### DECREASE (v) — approved
- STE: Decrease the timeout value.
- Non-STE: Lower the timeout value.

### DEEP (adj) — approved
- STE: Deep directory structure.
- Non-STE: Nested directory structure.

### DEFAULT (n) - (TN) — approved
- STE: The default value is 8080.
- Non-STE: The initial value is 8080.

### DEFECT (n) - (TN) — approved
- STE: Log the defect in the tracking system.
- Non-STE: Log the bug in the tracking system.

### DEFINE (v) — approved
- STE: The header file defines the interface.
- Non-STE: The header file declares the interface.

### delete (v) - UNNAPROVED — unapproved
- Use instead: REMOVE (v). REMOVE THE FILE FROM THE DIRECTORY
- STE: Remove the file from the directory.
- Non-STE: Delete the file from the directory.

### DEPLOY (v) — approved
- STE: Deploy the application to production.
- Non-STE: Release the application to production.

### DEPRECATED (adj) - (TN) — approved
- STE: The deprecated function will be removed in version 4.0.
- Non-STE: The outdated function will be removed in version 4.0.

### DESIGN (n) — approved
- STE: The design of the API follows REST principles.
- Non-STE: The architecture of the API follows REST principles.

### destroy (v) - UNNAPROVED — unapproved
- Use instead: BREAK (v), REMOVE (v). BREAK THE OLD SESSION
- STE: Break the old session.
- Non-STE: Destroy the old session.

### DEVELOP (v) - (TV) — approved
- STE: Develop the feature in a separate branch.
- Non-STE: Build the feature in a separate branch.

### DIFFERENT (adj) — approved
- STE: The two implementations have different performance.
- Non-STE: The two implementations differ in performance.

### DIMENSION (n) — approved
- STE: The array has three dimensions.
- Non-STE: The array is three-dimensional.

### DIRECTORY (n) - (TN) — approved
- STE: The source files are in the `src/` directory.
- Non-STE: The source files are in the `src/` folder.

### DISABLE (v) - (TV) — approved
- STE: Disable the feature flag.
- Non-STE: Turn off the feature flag.

### DISCARD (v) — approved
- STE: Discard the deprecated code.
- Non-STE: Remove the deprecated code.

### DISCONNECT (v) — approved
- STE: Disconnect the socket.
- Non-STE: Close the socket.

### DISPLAY (v), DISPLAY (n) — approved
- STE: The terminal displays the log output.
- Non-STE: The terminal shows the log output.

### DIVIDE (v) — approved
- STE: Divide the tasks among the workers.
- Non-STE: Distribute the tasks among the workers.

### DO (v) — approved
- STE: Do the build step.
- Non-STE: Execute the build step.

### DOCUMENT (v) - (TV) — approved
- STE: Document the public API.
- Non-STE: Write docs for the public API.

### DOWN (adv), DOWN (prep) — approved
- STE: Scroll down the page.
- STE: The server is down.
- Non-STE: Scroll to the lower part of the page.
- Non-STE: The server is not operational.

### DOWNLOAD (v) - (TV) — approved
- STE: Download the package from the registry.
- Non-STE: Get the package from the registry.

### DRAIN (v) — approved
- STE: Drain the connection pool.
- Non-STE: Empty the connection pool.

### DRAW (v) — approved
- STE: Draw the architecture diagram.
- Non-STE: Create the architecture diagram.

### DROP (v) — approved
- STE: Drop the table from the database.
- Non-STE: Delete the table from the database.

### DRY (adj), DRY (v) — approved

# E

### EACH (adj) — approved
- STE: Each module has a README file.
- Non-STE: Every module has a README file.

### EASY (adj) — approved
- STE: The setup is easy.
- Non-STE: The setup is straightforward.

### EDIT (v) - (TV) — approved
- STE: Edit the configuration file with a text editor.
- Non-STE: Modify the configuration file with a text editor.

### EFFECT (n) — approved
- STE: The effect of the change is small.
- Non-STE: The impact of the change is small.

### EJECT (v) — approved
- STE: Eject the volume.
- Non-STE: Unmount the volume.

### ELEMENT (n) — approved
- STE: Each element of the list has an index.
- Non-STE: Each item of the list has an index.

### ELSE (adv) - (TN) — approved
- STE: If the value is null, return 0; else return the value.
- Non-STE: If the value is null, return 0; otherwise return the value.

### EMPTY (adj) — approved
- STE: An empty string.
- Non-STE: A zero-length string.

### ENABLE (v) - (TV) — approved
- STE: Enable the debug mode.
- Non-STE: Turn on the debug mode.

### END (n), END (v) — approved
- STE: The end of the file.
- STE: End the session.
- Non-STE: The final byte of the file.
- Non-STE: Terminate the session.

### ensure (v) - UNNAPROVED — unapproved
- Use instead: MAKE SURE (v). MAKE SURE THAT THE DATABASE IS CONNECTED
- STE: Make sure that the database is connected.
- Non-STE: Ensure that the database is connected.

### enter (v) - UNNAPROVED — unapproved
- Use instead: PUT (v), TYPE (v). TYPE YOUR PASSWORD
- STE: Type your password.
- Non-STE: Enter your password.

### ENVIRONMENT (n) - (TN) — approved
- STE: The staging environment is a copy of production.
- Non-STE: The staging setup is a copy of production.

### EQUAL (adj), EQUAL (v) — approved
- STE: The two hashes are equal.
- STE: The result equals zero.
- Non-STE: The two hashes are the same.
- Non-STE: The result is zero.

### ERASE (v) — approved
- STE: Erase the sensitive data from memory.
- Non-STE: Wipe the sensitive data from memory.

### ERROR (n) - (TN) — approved
- STE: The error occurred at line 42.
- Non-STE: The issue occurred at line 42.

### establish (v) - UNNAPROVED — unapproved
- Use instead: MAKE (v), START (v). MAKE A CONNECTION
- STE: Make a connection.
- Non-STE: Establish a connection.

### EVALUATE (v) - (TV) — approved
- STE: Evaluate the expression at runtime.
- Non-STE: Compute the expression at runtime.

### EVENT (n) - (TN) — approved
- STE: The event triggers the callback.
- Non-STE: The event fires the callback.

### EXAMINE (v) — approved
- STE: Examine the code for security issues.
- Non-STE: Review the code for security issues.

### EXAMPLE (n) — approved
- STE: This is an example of a correct API call.
- Non-STE: This demonstrates a correct API call.

### except (prep) - UNNAPROVED — unapproved
- Use instead: BUT NOT, OTHER THAN. ALL MODULES EXCEPT THE DATABASE ARE AVAILABLE
- STE: All modules except the database module are available.
- Non-STE: All modules other than the database module are available.

### EXECUTE (v) - (TV) — approved
- STE: Execute the script from the terminal.
- Non-STE: Run the script from the terminal.

### EXPAND (v) — approved
- STE: Expand the macro at compile time.
- Non-STE: The macro is substituted at compile time.

### explain (v) - UNNAPROVED — unapproved
- Use instead: DESCRIBE (v), TELL (v). DESCRIBE THE ERROR CONDITION
- STE: Describe the error condition.
- Non-STE: Explain the error condition.

### EXPORT (v) - (TV) — approved
- STE: Export the function from the library.
- Non-STE: Make the function available from the library.

### EXTEND (v) — approved
- STE: Extend the base class to add new methods.
- Non-STE: Subclass the base class to add new methods.

# F

### FAIL (v) — approved
- STE: If the test fails, examine the logs.
- Non-STE: If the test does not pass, examine the logs.

### failure (n) - UNNAPROVED — unapproved
- Use instead: DOES NOT WORK, STOPS. IF THE SERVICE STOPS, RESTART IT
- STE: If the service stops, restart it.
- Non-STE: In case of service failure, restart it.

### FALL (v) — approved

### FALSE (adj) - (TN) — approved
- STE: If the condition is false, skip the block.
- Non-STE: If the condition does not hold, skip the block.

### FAST (adj), FAST (adv) — approved
- STE: Fast response time.
- Non-STE: Low latency.

### FATAL (adj) - (TN) — approved
- STE: A fatal error occurred.
- Non-STE: A critical error occurred.

### FETCH (v) — approved
- STE: Fetch the records from the database.
- Non-STE: Retrieve the records from the database.

### FIELD (n) - (TN) — approved
- STE: The `email` field of the form must be validated.
- Non-STE: The `email` input of the form must be validated.

### FILE (n) - (TN) — approved
- STE: The configuration file is in TOML format.
- Non-STE: The config is in TOML format.

### FILL (v) — approved
- STE: Fill the array with default values.
- Non-STE: Initialize the array with default values.

### FILTER (n), FILTER (v) — approved
- STE: Filter the results by status.
- Non-STE: Select only the results that match the status.

### FIND (v) — approved
- STE: Find the root cause of the error.
- Non-STE: Determine the root cause of the error.

### FINISH (v) — approved
- STE: Finish the setup.
- Non-STE: Complete the setup.

### FIRST (adj), FIRST (adv) — approved
- STE: Define the variable first.
- Non-STE: Initially define the variable.

### fit (v) - UNNAPROVED — unapproved
- Use instead: INSTALL (v), ADD (v). INSTALL THE PACKAGE
- STE: Install the package.
- Non-STE: Fit the package into the project.

### FIX (v) — approved
- STE: Fix the memory leak.
- Non-STE: Resolve the memory leak.

### FLAG (n) - (TN) — approved
- STE: Set the debug flag to true.
- Non-STE: Enable the debug flag.

### FLOW (n), FLOW (v) — approved
- STE: The flow of data through the pipeline.
- STE: The data flows through the channel.
- Non-STE: The data stream through the pipeline.
- Non-STE: The data passes through the channel.

### follow (v) - UNNAPROVED — unapproved
- Use instead: OBEY (v). OBEY THE CODING GUIDELINES
- STE: Obey the coding guidelines.
- Non-STE: Follow the coding guidelines.

### FOR (prep) — approved
- STE: For examples, refer to the README.
- Non-STE: To see examples, refer to the README.

### FORCE (n) — approved
- STE: Force the application to restart.
- Non-STE: Compel the application to restart.

### FORMAT (n) - (TN) — approved
- STE: The file format is JSON.
- Non-STE: The file is in JSON.

### FORWARD (adv) — approved
- STE: Move the pointer forward.
- Non-STE: Advance the pointer.

### FREE (adj) — approved
- STE: The code is free of errors.
- Non-STE: The code has no errors.

### FROM (prep) — approved
- STE: Import the module from the package.
- Non-STE: Import the module out of the package.

### FULL (adj) — approved
- STE: Full test suite.
- Non-STE: Complete test suite.

### FUNCTION (n) — approved
- STE: The function returns a string.
- STE: The function of the middleware is to authenticate requests.
- Non-STE: The method returns a string.
- Non-STE: The role of the middleware is to authenticate requests.

# G

### GET (v) — approved
- STE: Get the data from the API.
- STE: The service gets unstable under load.
- Non-STE: Fetch the data from the API.
- Non-STE: The service becomes unstable under load.

### GIVE (v) — approved
- STE: This section gives the build instructions for the module.
- Non-STE: This section provides the build instructions for the module.

### GO (v) — approved
- STE: Go to the next phase of the pipeline.
- Non-STE: Proceed to the next phase of the pipeline.

### GOOD (adj) — approved
- STE: Good test coverage.
- Non-STE: Satisfactory test coverage.

### GROUP (n), GROUP (v) — approved
- STE: Group the tests by module.
- Non-STE: Organize the tests by module.

# H

### handle (v) - UNNAPROVED — unapproved
- Use instead: PROCESS (v), MANAGE (v). PROCESS THE EXCEPTION
- STE: Process the exception.
- Non-STE: Handle the exception.

### happen (v) - UNNAPROVED — unapproved
- Use instead: OCCUR (v). AN EXCEPTION OCCURRED DURING INITIALIZATION
- STE: An exception occurred during initialization.
- Non-STE: An exception happened during initialization.

### HARD (adj) — approved
- STE: A hard limit on the number of connections.
- Non-STE: A strict limit on the number of connections.

### HAVE (v) — approved
- STE: The class has two methods.
- Non-STE: The class contains two methods.

### HEAD (n) — approved
- STE: The head of the queue.
- Non-STE: The front of the queue.

### HELP (n), HELP (v) — approved
- STE: This README helps you to set up the project.
- Non-STE: This README assists you in setting up the project.

### HIGH (adj) — approved
- STE: High load on the server.
- Non-STE: Heavy load on the server.

### HIT (v) — approved
- STE: Hit the endpoint with a GET request.
- Non-STE: Send a GET request to the endpoint.

### HOLD (v) — approved
- STE: Hold the lock until the operation completes.
- Non-STE: Keep the lock until the operation completes.

### HOOK (n) - (TN) — approved
- STE: Use a pre-commit hook to validate the code.
- Non-STE: Use a pre-commit script to validate the code.

### HOW (adv) — approved
- STE: How to compile the project.
- Non-STE: Instructions to compile the project.

# I

### IDENTIFY (v) — approved
- STE: Identify the source of the memory leak.
- Non-STE: Find the source of the memory leak.

### IF (conj) — approved
- STE: If the status code is 500, retry the request.
- Non-STE: In the event of a 500 status code, retry the request.

### IGNORE (v) — approved
- STE: Ignore the case sensitivity.
- Non-STE: Do not consider the case sensitivity.

### IMMEDIATELY (adv) — approved
- STE: Restart the service immediately.
- Non-STE: Restart the service right away.

### IMPLEMENT (v) - (TV) — approved
- STE: Implement the interface.
- Non-STE: Code the interface.

### IMPORT (v) - (TV) — approved
- STE: Import the module at the top of the file.
- Non-STE: Include the module at the top of the file.

### IMPORTANT (adj) — approved
- STE: Important security note.
- Non-STE: Critical security note.

### IN (prep) — approved
- STE: In the directory `src/lib/`.
- Non-STE: Within the directory `src/lib/`.

### INCLUDE (v) — approved
- STE: The package includes the dependencies.
- Non-STE: The package contains the dependencies.

### INCORRECT (adj) — approved
- STE: Incorrect syntax.
- Non-STE: Wrong syntax.

### INCREASE (v) — approved
- STE: Increase the buffer size.
- Non-STE: Make the buffer larger.

### INDEX (n) - (TN) — approved
- STE: The index of the element is 0.
- Non-STE: The position of the element is 0.

### indicate (v) - UNNAPROVED — unapproved
- Use instead: SHOW (v). THE LOG SHOWS THE ERROR TYPE
- STE: The log shows the error type.
- Non-STE: The log indicates the error type.

### INITIALIZE (v) - (TV) — approved
- STE: Initialize the variable to zero.
- Non-STE: Set the variable to zero initially.

### INPUT (n) - (TN) — approved
- STE: Validate the user input.
- Non-STE: Validate the data entered by the user.

### insert (v) - UNNAPROVED — unapproved
- Use instead: PUT (v), ADD (v). PUT THE RECORD INTO THE DATABASE
- STE: Put the record into the database.
- Non-STE: Insert the record into the database.

### inspect (v) - UNNAPROVED — unapproved
- Use instead: EXAMINE (v), REVIEW (v). REVIEW THE CODE FOR VULNERABILITIES
- STE: Review the code for vulnerabilities.
- Non-STE: Inspect the code for vulnerabilities.

### INSTALL (v) — approved
- STE: Install the package with npm.
- Non-STE: Set up the package with npm.

### INSTRUCTION (n) — approved
- STE: Obey the instructions in the README.
- Non-STE: Follow the instructions in the README.

### INTERFACE (n) - (TN) — approved
- STE: The interface defines three methods.
- Non-STE: The contract defines three methods.

### INVALID (adj) - (TN) — approved
- STE: An invalid token.
- Non-STE: A bad token.

### ISOLATE (v) — approved
- STE: Isolate the component for unit testing.
- Non-STE: Separate the component for unit testing.

### IT (pron) — approved
- STE: The package. It is in the registry.
- Non-STE: The package is in the registry.

# J

### JOIN (v) — approved
- STE: Join the two strings.
- Non-STE: Concatenate the two strings.

# K

### KEEP (v) — approved
- STE: Keep the connection open.
- Non-STE: Maintain the connection.

### KEY (n) - (TN) — approved
- STE: The key for the cache entry is the user ID.
- Non-STE: The identifier for the cache entry is the user ID.

### KILL (v) — approved
- STE: Kill the process with SIGTERM.
- Non-STE: Terminate the process with SIGTERM.

### KNOW (v) — approved
- STE: You must know the API specification.
- Non-STE: You must be familiar with the API specification.

# L

### LARGE (adj) — approved
- STE: A large dataset.
- Non-STE: A big dataset.

### LAST (adj), LAST (adv) — approved
- STE: Execute the teardown last.
- Non-STE: Execute the teardown at the end.

### LAYER (n) - (TN) — approved
- STE: The data access layer handles queries.
- Non-STE: The data tier handles queries.

### LEFT (adj), LEFT (adv) — approved
- STE: Align the text left.
- Non-STE: Align the text to the left.

### LENGTH (n) — approved
- STE: The length of the array is 10.
- Non-STE: The array has 10 elements.

### LESS (adj), LESS (adv), LESS (prep) — approved
- STE: Less memory usage.
- Non-STE: Lower memory usage.

### LET (v) — approved
- STE: Let the process complete before you restart.
- Non-STE: Allow the process to complete before you restart.

### LEVEL (n) — approved
- STE: Set the log level to debug.
- Non-STE: Set the logging severity to debug.

### LIBRARY (n) - (TN) — approved
- STE: Import the standard library.
- Non-STE: Include the standard library.

### LIFT (v) — approved
- STE: Lift the function to a separate module.
- Non-STE: Extract the function to a separate module.

### LIGHT (adj) — approved
- STE: A light process with small memory footprint.
- Non-STE: A lightweight process.

### LIMIT (n), LIMIT (v) — approved
- STE: Limit the number of requests.
- Non-STE: Restrict the number of requests.

### LINE (n) — approved
- STE: The error is at line 42.
- Non-STE: The error is on line 42.

### LINK (n), LINK (v) — approved
- STE: Link the library to the project.
- Non-STE: Connect the library to the project.

### LIST (n), LIST (v) — approved
- STE: List the files in the directory.
- Non-STE: Show the files in the directory.

### LOAD (n), LOAD (v) — approved
- STE: Load the configuration file.
- Non-STE: Read the configuration file.

### locate (v) - UNNAPROVED — unapproved
- Use instead: FIND (v). FIND THE ERROR IN THE LOGS
- STE: Find the error in the logs.
- Non-STE: Locate the error in the logs.

### LOCK (v) — approved
- STE: Lock the mutex.
- Non-STE: Acquire the mutex.

### LOG (n), LOG (v) - (TN/TV) — approved
- STE: Log the error to the file.
- Non-STE: Write the error to the file.

### LONG (adj) — approved
- STE: A long process.
- Non-STE: A time-consuming process.

### LOOK (v) — approved
- STE: Look at the error message.
- Non-STE: Examine the error message.

### LOOP (n) - (TN) — approved
- STE: The for loop iterates 10 times.
- Non-STE: The iteration runs 10 times.

### LOOSE (adj) — approved
- STE: Loose coupling between modules.
- Non-STE: Decoupled modules.

### LOW (adj) — approved
- STE: Low latency.
- Non-STE: Minimal delay.

### LOWER (v) — approved
- STE: Lower the log level.
- Non-STE: Reduce the log level.

# M

### main (adj) - UNNAPROVED — unapproved
- Use instead: PRIMARY (adj). THE PRIMARY CAUSE OF THE CRASH IS A NULL POINTER
- STE: The primary cause of the crash is a null pointer.
- Non-STE: The main cause of the crash is a null pointer.

### MAKE (v) — approved
- STE: Make a copy of the file.
- Non-STE: Create a copy of the file.

### MAKE SURE (v) — approved
- STE: Make sure that the tests pass.
- Non-STE: Ensure that the tests pass.

### MANAGE (v) - (TV) — approved
- STE: The package manager manages dependencies.
- Non-STE: The package manager handles dependencies.

### MANDATORY (adj) — approved
- STE: The API key is mandatory.
- Non-STE: The API key is required.

### MANUAL (adj), MANUAL (n) — approved
- STE: Manual review of the code.
- STE: Read the manual before you start.
- Non-STE: Human review of the code.
- Non-STE: Read the docs before you start.

### MANY (adj) — approved
- STE: Many requests per second.
- Non-STE: Numerous requests per second.

### MAP (v) - (TV) — approved
- STE: Map the array to uppercase.
- Non-STE: Transform each element of the array.

### MARK (n), MARK (v) — approved
- STE: Mark the function as deprecated.
- Non-STE: Flag the function as deprecated.

### MATCH (v) — approved
- STE: The pattern must match the input.
- Non-STE: The pattern must correspond to the input.

### MATERIAL (n) — approved
- STE: Refer to the training material.
- Non-STE: Refer to the training resources.

### MAXIMUM (adj), MAXIMUM (n) — approved
- STE: Maximum connections is 100.
- Non-STE: The limit is 100 connections.

### MEASURE (v) — approved
- STE: Measure the response time.
- Non-STE: Calculate the response time.

### MEMORY (n) - (TN) — approved
- STE: The application uses 256 MB of memory.
- Non-STE: The application uses 256 MB of RAM.

### MERGE (v) - (TV) — approved
- STE: Merge the feature branch into main.
- Non-STE: Combine the feature branch into main.

### MESSAGE (n) — approved
- STE: The error message describes the issue.
- Non-STE: The error text describes the issue.

### METHOD (n) - (TN) — approved
- STE: The method takes two parameters.
- Non-STE: The function takes two parameters.

### MINIMUM (adj), MINIMUM (n) — approved
- STE: The minimum password length is 8.
- Non-STE: The password must be at least 8 characters.

### MINUS (prep) — approved
- STE: The value is total minus overhead.
- Non-STE: The value is total less overhead.

### MISSING (adj) — approved
- STE: A missing dependency.
- Non-STE: A dependency that is not installed.

### MIX (v) — approved
- STE: Do not mix concerns in a single module.
- Non-STE: Do not combine concerns in a single module.

### MODE (n) - (TN) — approved
- STE: The debug mode shows more information.
- Non-STE: Debug builds show more information.

### MODEL (n) - (TN) — approved
- STE: The user model has three fields.
- Non-STE: The user schema has three fields.

### modify (v) - UNNAPROVED — unapproved
- Use instead: CHANGE (v). CHANGE THE FILE PERMISSIONS
- STE: Change the file permissions.
- Non-STE: Modify the file permissions.

### MODULE (n) - (TN) — approved
- STE: Each module has its own namespace.
- Non-STE: Each package has its own namespace.

### MONITOR (v) — approved
- STE: Monitor the server logs.
- Non-STE: Watch the server logs.

### MORE (adj), MORE (adv) — approved
- STE: More memory allocation.
- Non-STE: Additional memory allocation.

### MOST (adj), MOST (adv) — approved
- STE: Most errors occur at startup.
- Non-STE: The majority of errors occur at startup.

### MOVE (v) — approved
- STE: Move the file to the archive.
- Non-STE: Transfer the file to the archive.

### MUCH (adj), MUCH (adv) — approved
- STE: Not much memory usage.
- Non-STE: Low memory usage.

### MUST (v) — approved
- STE: You must validate all inputs.
- Non-STE: You have to validate all inputs.

# N

### NAME (n), NAME (v) — approved
- STE: Name the variable `count`.
- Non-STE: Call the variable `count`.

### NEAR (adj), NEAR (prep) — approved
- STE: Near the end of the file.
- Non-STE: Close to the end of the file.

### NECESSARY (adj) — approved
- STE: It is necessary to restart the service.
- Non-STE: You must restart the service.

### need (v) - UNNAPROVED — unapproved
- Use instead: MUST (v), NECESSARY (adj). YOU MUST INSTALL THE DEPENDENCIES
- STE: You must install the dependencies.
- Non-STE: You need to install the dependencies.

### NEVER (adv) — approved
- STE: Never store passwords in plain text.
- Non-STE: Do not store passwords in plain text under any circumstances.

### NEW (adj) — approved
- STE: A new instance of the class.
- Non-STE: A fresh instance of the class.

### NEXT (adj) — approved
- STE: The next iteration.
- Non-STE: The following iteration.

### NO (adj) — approved
- STE: No errors in the output.
- Non-STE: Zero errors in the output.

### NONE (pron) — approved
- STE: None of the tests fail.
- Non-STE: All tests pass.

### normal (adj) - UNNAPROVED — unapproved
- Use instead: USUAL (adj). THE USUAL BEHAVIOR IS TO RETURN ZERO
- STE: The usual behavior is to return zero.
- Non-STE: The normal behavior is to return zero.

### NOT (adv) — approved
- STE: Do not use deprecated functions.
- Non-STE: Avoid using deprecated functions.

### NOTE (n), NOTE (v) — approved
- STE: Add a note in the code.
- Non-STE: Add a comment in the code.

### NULL (adj) - (TN) — approved
- STE: The pointer is null.
- Non-STE: The pointer is empty.

### NUMBER (n) — approved
- STE: The number of records is 100.
- Non-STE: The count of records is 100.

# O

### OBJECT (n) - (TN) — approved
- STE: Create a new object of the User class.
- Non-STE: Instantiate the User class.

### OBEY (v) — approved
- STE: Obey the coding standards.
- Non-STE: Follow the coding standards.

### OCCUR (v) — approved
- STE: An exception occurred at runtime.
- Non-STE: An exception was thrown at runtime.

### OF (prep) — approved
- STE: The name of the function.
- Non-STE: The function's name.

### OFF (adv), OFF (prep) — approved
- STE: Turn off the feature flag.
- Non-STE: Disable the feature flag.

### ON (adv), ON (prep) — approved
- STE: Turn on the debug mode.
- Non-STE: Enable the debug mode.

### ONLY (adv) — approved
- STE: Only the admin can run this command.
- Non-STE: Solely the admin can run this command.

### OPEN (v), OPEN (adj) — approved
- STE: Open the file for reading.
- STE: An open port on the firewall.
- Non-STE: Read the file.
- Non-STE: A listening port on the firewall.

### OPERATE (v) — approved
- STE: Operate the application through the CLI.
- Non-STE: Run the application through the CLI.

### OPERATION (n) — approved
- STE: The operation of the request is asynchronous.
- Non-STE: The request is processed asynchronously.

### option (n) - UNNAPROVED — unapproved
- Use instead: ALTERNATIVE (n), CAN (v). YOU CAN USE AN ALTERNATIVE CONFIGURATION
- STE: You can use an alternative configuration.
- Non-STE: You have the option to use another configuration.

### OR (conj) — approved
- STE: Use Python or Node.js.
- Non-STE: Use Python; alternatively use Node.js.

### ORDER (n) — approved
- STE: Execute the steps in the given order.
- Non-STE: Execute the steps sequentially.

### OTHER (adj) — approved
- STE: The other endpoint returns JSON.
- Non-STE: The alternative endpoint returns JSON.

### OUTPUT (n) - (TN) — approved
- STE: The output of the command is a list.
- Non-STE: The command prints a list.

### over (prep) - UNNAPROVED — unapproved
- Use instead: MORE THAN, ABOVE. MORE THAN THE THRESHOLD
- STE: More than the threshold.
- Non-STE: Over the threshold.

### OVERRIDE (v) - (TV) — approved
- STE: Override the default behavior in the subclass.
- Non-STE: Replace the default behavior in the subclass.

# P

### PACKAGE (n) - (TN) — approved
- STE: Install the package with pip.
- Non-STE: Install the library with pip.

### PAGE (n) — approved
- STE: The landing page of the application.
- Non-STE: The home screen of the application.

### PARAMETER (n) - (TN) — approved
- STE: The function takes two parameters.
- Non-STE: The function accepts two arguments.

### PART (n) — approved
- STE: A part of the documentation.
- Non-STE: A section of the documentation.

### PASS (v) — approved
- STE: The test passes.
- Non-STE: The test succeeds.

### PASTE (v) — approved
- STE: Paste the text into the editor.
- Non-STE: Insert the copied text into the editor.

### PATH (n) - (TN) — approved
- STE: The path to the config file is `/etc/app/`.
- Non-STE: The location of the config file is `/etc/app/`.

### PATTERN (n) - (TN) — approved
- STE: The regex pattern matches the input.
- Non-STE: The regular expression matches the input.

### perform (v) - UNNAPROVED — unapproved
- Use instead: DO (v). DO THE BUILD
- STE: Do the build.
- Non-STE: Perform the build.

### PERFORMANCE (n) — approved
- STE: The performance of the query is good.
- Non-STE: The query runs fast.

### PERMANENT (adj) — approved
- STE: Write the data to permanent storage.
- Non-STE: Write the data to persistent storage.

### permit (v) - UNNAPROVED — unapproved
- Use instead: LET (v), ALLOW (v). THE API LETS YOU SEND
- STE: The API lets you send 100 requests per minute.
- Non-STE: The API permits 100 requests per minute.

### PERSON (n) — approved
- STE: Only one person can access the account.
- Non-STE: Only a single user can access the account.

### PIPE (n) - (TN) — approved
- STE: Use a pipe to connect the commands.
- Non-STE: Use the pipe operator to connect the commands.

### PLACE (n), PLACE (v) — approved
- STE: Place the hook in the lifecycle at the right position.
- Non-STE: Insert the hook into the lifecycle.

### PLUS (prep) — approved
- STE: The total is the base plus the overhead.
- Non-STE: The total is the sum of the base and overhead.

### POINT (n) — approved
- STE: The entry point of the application is `main()`.
- Non-STE: The application starts at `main()`.

### PORT (n) - (TN) — approved
- STE: The application listens on port 8080.
- Non-STE: The application uses port 8080.

### POSITION (n) — approved
- STE: The position of the element in the array is 0.
- Non-STE: The index of the element in the array is 0.

### POSSIBLE (adj) — approved
- STE: A possible solution is to increase the timeout.
- Non-STE: One solution could be to increase the timeout.

### POWER (n) — approved
- STE: The processing power of the server is sufficient.
- Non-STE: The server has enough CPU.

### PREPARE (v) — approved
- STE: Prepare the environment for deployment.
- Non-STE: Set up the environment for deployment.

### PREVENT (v) — approved
- STE: Use parameterized queries to prevent SQL injection.
- Non-STE: Use parameterized queries to avoid SQL injection.

### PREVIOUS (adj) — approved
- STE: The previous version had a bug.
- Non-STE: The prior version had a bug.

### PRIMARY (adj) — approved
- STE: The primary key of the table is the `id` field.
- Non-STE: The main key of the table is the `id` field.

### PROBLEM (n) — approved
- STE: Identify the root cause of the problem.
- Non-STE: Find what caused the issue.

### PROCEDURE (n) — approved
- STE: Do the deployment procedure.
- Non-STE: Follow the deployment procedure.

### process (n), process (v) - UNNAPROVED — unapproved
- Use instead: A running program. THE PROCESS PID IS
- STE: Process the request synchronously.
- Non-STE: Handle the request synchronously.

### provide (v) - UNNAPROVED — unapproved
- Use instead: GIVE (v), RETURN (v). RETURN THE RESULT
- STE: The function returns the result.
- Non-STE: The function provides the result.

### PULL (v) — approved
- STE: Pull the latest changes from the repository.
- Non-STE: Fetch the latest changes from the repository.

### PUSH (v) — approved
- STE: Push the commit to the remote.
- Non-STE: Upload the commit to the remote.

### PUT (v) — approved
- STE: Put the value in the variable.
- Non-STE: Assign the value to the variable.

# Q

### QUALITY (n) — approved
- STE: Code quality is important.
- Non-STE: The standard of the code is important.

### QUANTITY (n) — approved
- STE: A large quantity of data.
- Non-STE: A lot of data.

### QUERY (n) - (TN) — approved
- STE: The query returns 10 rows.
- Non-STE: The SQL statement returns 10 rows.

### QUICK (adj), QUICKLY (adv) — approved
- STE: Process the request quickly.
- Non-STE: Process the request fast.

# R

### RAISE (v) — approved
- STE: Raise an exception when the value is null.
- Non-STE: Throw an exception when the value is null.

### RANGE (n) — approved
- STE: The port range is 8000-8080.
- Non-STE: The ports go from 8000 to 8080.

### READ (v) — approved
- STE: Read the file from disk.
- Non-STE: Load the file from disk.

### READY (adj) — approved
- STE: The build is ready for deployment.
- Non-STE: The build can be deployed.

### RECEIVE (v) — approved
- STE: Receive the HTTP response.
- Non-STE: Get the HTTP response.

### RECOMMEND (v) — approved
- STE: The style guide recommends this format.
- Non-STE: The style guide suggests this format.

### RECORD (v) — approved
- STE: Record the error in the log.
- Non-STE: Log the error.

### reduce (v) - UNNAPROVED — unapproved
- Use instead: DECREASE (v). DECREASE THE MEMORY USAGE
- STE: Decrease the memory usage.
- Non-STE: Reduce the memory usage.

### REFER (v) — approved
- STE: Refer to the API documentation for details.
- Non-STE: See the API documentation for details.

### REFRESH (v) - (TV) — approved
- STE: Refresh the page to see the changes.
- Non-STE: Reload the page to see the changes.

### REJECT (v) — approved
- STE: Reject the commit if tests fail.
- Non-STE: Deny the commit if tests fail.

### RELEASE (v) — approved
- STE: Release the new version to production.
- STE: Release the memory after use.
- Non-STE: Publish the new version to production.
- Non-STE: Free the memory after use.

### REMAINING (adj) — approved
- STE: Fix the remaining warnings.
- Non-STE: Fix the leftover warnings.

### REMOVE (v) — approved
- STE: Remove the deprecated function.
- Non-STE: Delete the deprecated function.

### REPAIR (v) — approved
- STE: Repair the broken build.
- Non-STE: Fix the broken build.

### REPEAT (v) — approved
- STE: Repeat the operation for each item.
- Non-STE: Loop through the items and do the operation.

### REPLACE (v) — approved
- STE: Replace the old library with the new one.
- Non-STE: Swap the old library for the new one.

### REPORT (n), REPORT (v) - (TN/TV) — approved
- STE: Report the bug in the issue tracker.
- Non-STE: Log the bug in the issue tracker.

### REQUEST (n), REQUEST (v) - (TN/TV) — approved
- STE: The HTTP request returns 200 OK.
- Non-STE: The HTTP call returns 200 OK.

### require (v) - UNNAPROVED — unapproved
- Use instead: MUST (v). YOU MUST INSTALL NODE
- STE: You must install Node.js.
- Non-STE: The project requires Node.js.

### RESOURCE (n) - (TN) — approved
- STE: Free the resources after use.
- Non-STE: Release the resources after use.

### RESPONSE (n) - (TN) — approved
- STE: The response contains the user data.
- Non-STE: The reply contains the user data.

### RESTART (v) — approved
- STE: Restart the service.
- Non-STE: Stop and start the service.

### RESULT (n) — approved
- STE: The result of the query is an empty set.
- Non-STE: The query returns no rows.

### RETRY (v) - (TV) — approved
- STE: Retry the request after 5 seconds.
- Non-STE: Try the request again after 5 seconds.

### RETURN (v) — approved
- STE: The function returns the computed value.
- Non-STE: The function gives back the computed value.

### review (n) - UNNAPROVED — unapproved
- Use instead: EXAMINE (v). EXAMINE THE CODE FOR ISSUES
- STE: Examine the code for issues.
- Non-STE: Review the code for issues.

### RIGHT (adj), RIGHT (adv) — approved
- STE: Align the text right.
- Non-STE: Align the text to the right.

### RISK (n) — approved
- STE: The risk of data loss is small.
- Non-STE: There is little chance of data loss.

### ROOT (n) - (TN) — approved
- STE: The config file is in the root of the project.
- STE: Run the command as root.
- Non-STE: The config file is at the top level of the project.
- Non-STE: Run the command with superuser privileges.

### ROUTE (n) - (TN) — approved
- STE: The route `/users` returns the user list.
- Non-STE: The endpoint `/users` returns the user list.

### RULE (n) — approved
- STE: The validation rule checks the email format.
- Non-STE: The validation checks the email format.

### RUN (v) — approved
- STE: Run the script from the terminal.
- Non-STE: Execute the script from the terminal.

# S

### SAFE (adj), SAFETY (n) — approved
- STE: A safe default value prevents crashes.
- STE: For data safety, encrypt the backup.
- Non-STE: A sensible default value prevents crashes.
- Non-STE: For security, encrypt the backup.

### SAME (adj) — approved
- STE: The two functions return the same result.
- Non-STE: The two functions return identical results.

### SAMPLE (n) — approved
- STE: A code sample is in the `examples/` directory.
- Non-STE: An example is in the `examples/` directory.

### SAVE (v) — approved
- STE: Save the file to disk.
- Non-STE: Write the file to disk.

### SCHEDULE (v) — approved
- STE: Schedule the job to run daily.
- Non-STE: Set the job to run daily.

### SEARCH (v) - (TV) — approved
- STE: Search the logs for error messages.
- Non-STE: Look through the logs for error messages.

### SECTION (n) — approved
- STE: Refer to the Security section of the README.
- Non-STE: See the Security part of the README.

### SEE (v) — approved
- STE: See the documentation for details.
- Non-STE: Refer to the documentation for details.

### SELECT (v) — approved
- STE: Select the database from the list.
- Non-STE: Choose the database from the list.

### SEND (v) — approved
- STE: Send the request to the server.
- Non-STE: Make the request to the server.

### separate (adj) - UNNAPROVED — unapproved
- Use instead: ISOLATED (adj), DIFFERENT (adj), NOT CONNECTED. KEEP THE MODULES ISOLATED
- STE: Keep the modules isolated from each other.
- Non-STE: Keep the modules separate from each other.

### SEQUENCE (n) — approved
- STE: Execute the steps in the given sequence.
- Non-STE: Execute the steps in order.

### SERVER (n) - (TN) — approved
- STE: The server listens on port 443.
- Non-STE: The service listens on port 443.

### SERVICE (n) - (TN) — approved
- STE: The authentication service is down.
- Non-STE: The auth service is not running.

### SET (n), SET (v) — approved
- STE: Set the variable to 10.
- Non-STE: Assign 10 to the variable.

### SHORT (adj) — approved
- STE: A short timeout of 1 second.
- Non-STE: A brief timeout of 1 second.

### SHOW (v) — approved
- STE: The command shows the file contents.
- Non-STE: The command displays the file contents.

### SHUT down (v) - UNNAPROVED — unapproved
- Use instead: STOP (v). STOP THE SERVER
- STE: Stop the server.
- Non-STE: Shut down the server.

### SIGNAL (n) - (TN) — approved
- STE: Send a SIGTERM signal to the process.
- Non-STE: Terminate the process.

### SIMPLE (adj) — approved
- STE: A simple function with one responsibility.
- Non-STE: A straightforward function with one responsibility.

### SINGLE (adj) — approved
- STE: A single instance of the application.
- Non-STE: One instance of the application.

### SIZE (n) — approved
- STE: The size of the file is 2 MB.
- Non-STE: The file is 2 MB.

### SLOW (adj), SLOWLY (adv) — approved
- STE: Slowly increase the timeout value.
- Non-STE: Gradually increase the timeout value.

### SMALL (adj) — approved
- STE: A small amount of memory is allocated.
- Non-STE: A negligible amount of memory is allocated.

### SOCKET (n) - (TN) — approved
- STE: Open a socket on port 3000.
- Non-STE: Create a connection on port 3000.

### SOLUTION (n) — approved
- STE: The solution to the memory leak is to use weak references.
- Non-STE: Fix the memory leak by using weak references.

### SOME (adj), SOME (pron) — approved
- STE: Some tests fail under load.
- Non-STE: A few tests fail under load.

### SOURCE (n) — approved
- STE: Find the source of the bug.
- Non-STE: Locate where the bug originates.

### SPACE (n) — approved
- STE: Make sure that there is sufficient disk space.
- Non-STE: Check that there is enough disk space.

### SPECIAL (adj), SPECIALLY (adv) — approved
- STE: Use the special config for staging.
- Non-STE: Use the staging-specific config.

### SPECIFIED (adj) — approved
- STE: Use the specified port number from the config.
- Non-STE: Use the port number that is given in the config.

### SPEED (n) — approved
- STE: The speed of the query is fast.
- Non-STE: The query is fast.

### STACK (n) - (TN) — approved
- STE: Push the value onto the stack.
- Non-STE: Add the value to the stack.

### stage (n) - UNNAPROVED — unapproved
- Use instead: STEP (n). DURING THIS STEP, DO NOT MERGE THE BRANCH
- STE: During this step, do not merge the branch.
- Non-STE: At this stage, do not merge the branch.

### STANDARD (adj) — approved
- STE: Follow the standard coding conventions.
- Non-STE: Follow the usual coding conventions.

### START (n), START (v) — approved
- STE: Start the application.
- Non-STE: Launch the application.

### state (n) - UNNAPROVED — unapproved
- Use instead: CONDITION (n). EXAMINE THE CONDITION OF THE SYSTEM
- STE: Examine the condition of the system.
- Non-STE: Examine the state of the system.

### STATUS (n) - (TN) — approved
- STE: The status of the service is "healthy."
- Non-STE: The service is healthy.

### STAY (v) — approved
- STE: Make sure that the connection stays open.
- Non-STE: Keep the connection open.

### STEP (n) — approved
- STE: Do steps 1 through 5 in the given order.
- Non-STE: Follow the procedure steps 1-5.

### STOP (v) — approved
- STE: Stop the process.
- STE: When the errors stop, check the logs.
- Non-STE: Kill the process.
- Non-STE: When the errors cease, check the logs.

### store (v) - UNNAPROVED — unapproved
- Use instead: KEEP (v), SAVE (v). KEEP THE CONFIG FILES IN VERSION CONTROL
- STE: Keep the config files in version control.
- Non-STE: Store the config files in version control.

### STREAM (n) - (TN) — approved
- STE: Process the data as a stream.
- Non-STE: Process the data in chunks.

### STRING (n) - (TN) — approved
- STE: The response returns a JSON string.
- Non-STE: The response returns JSON text.

### STRONG (adj) — approved
- STE: Use a strong password.
- Non-STE: Use a secure password.

### STRUCTURE (n) — approved
- STE: The structure of the project follows MVC.
- Non-STE: The project layout follows MVC.

### SUFFICIENT (adj), SUFFICIENTLY (adv) — approved
- STE: Make sure that there is sufficient disk space.
- Non-STE: Make sure that there is enough disk space.

### SUDDEN (adj), SUDDENLY (adv) — approved
- STE: If the service fails suddenly, read the logs.
- Non-STE: If the service fails unexpectedly, read the logs.

### SUPPLY (n), SUPPLY (v) — approved
- STE: Supply the API key as a query parameter.
- Non-STE: Provide the API key as a query parameter.

### SURFACE (n) — approved
- STE: The API surface of the library is small.
- Non-STE: The public interface of the library is small.

### SYSTEM (n) — approved
- STE: The authentication system uses JWT.
- Non-STE: The authentication module uses JWT.

# T

### TABLE (n) — approved
- STE: The `users` table has four columns.
- Non-STE: The `users` database table has four columns.

### TAG (n) - (TN) — approved
- STE: Add a version tag to the commit.
- Non-STE: Mark the commit with a version number.

### take (v) - UNNAPROVED — unapproved
- Use instead: Use more accurate verbs: FETCH (v), CONSUME (v), REQUIRE (v).
- STE: The query consumes 100 ms.
- Non-STE: The query takes 100 ms.

### TASK (n) — approved
- STE: The asynchronous task runs in the background.
- Non-STE: The background job runs asynchronously.

### TELL (v) — approved
- STE: The log file tells you the error location.
- Non-STE: The log file shows you the error location.

### TEMPORARY (adj) — approved
- STE: Create a temporary file for the intermediate data.
- Non-STE: Create a temp file for the intermediate data.

### TERMINATE (v) - (TV) — approved
- STE: Terminate the hung process.
- Non-STE: Kill the hung process.

### TEST (n) — approved
- STE: Run the unit tests before you merge.
- Non-STE: Execute the test suite before merging.

### test (v) - UNNAPROVED — unapproved
- Use instead: TEST (n) with DO. DO A TEST OF THE MODULE
- STE: Do a test of the module.
- Non-STE: Test the module.

### TEXT (n) - (TN) — approved
- STE: The response body contains plain text.
- Non-STE: The response body is a string.

### THAN (conj) — approved
- STE: The new version is faster than the previous version.
- Non-STE: The new version outperforms the previous version.

### THAT (conj), THAT (pron) — approved
- STE: Make sure that the tests pass.
- Non-STE: Ensure the tests pass.

### THE (art) — approved
- STE: The function returns a value.
- Non-STE: Function returns a value.

### THEN (adv) — approved
- STE: Compile the code. Then, run the tests.
- Non-STE: Compile the code and subsequently run the tests.

### THICK (adj) — approved

### THREAD (n) - (TN) — approved
- STE: Run the task in a separate thread.
- Non-STE: Run the task in parallel.

### THROUGH (prep) — approved
- STE: Route the request through the proxy.
- Non-STE: Pass the request via the proxy.

### THROW (v) - (TV) — approved
- STE: The function throws an error on invalid input.
- Non-STE: The function raises an error on invalid input.

### THUS (adv) — approved
- STE: The token expires. Thus, the request fails.
- Non-STE: The token expires; therefore, the request fails.

### TIME (n) — approved
- STE: The response time is 200 ms.
- Non-STE: The latency is 200 ms.

### TIMEOUT (n) - (TN) — approved
- STE: Set the timeout to 30 seconds.
- Non-STE: Configure a 30-second time limit.

### TO (prep) — approved
- STE: Navigate to the settings page.
- Non-STE: Go to the settings page.

### TOKEN (n) - (TN) — approved
- STE: Pass the token in the Authorization header.
- Non-STE: Include the token in the request.

### TOO (adv) — approved
- STE: Too many open connections.
- Non-STE: Excessively many open connections.

### TOP (adj), TOP (n) — approved
- STE: The top of the file contains the imports.
- Non-STE: The beginning of the file contains the imports.

### TOUCH (v) — approved
- STE: Touch the file to update its modification date.
- Non-STE: Update the file timestamp.

### TRACK (v) - (TV) — approved
- STE: Track the changes with git.
- Non-STE: Monitor the changes with git.

### TRAIN (v) - (TV) — approved
- STE: Train the model on the training set.
- Non-STE: Fit the model to the training data.

### TRANSFER (v) — approved
- STE: Transfer the file via SCP.
- Non-STE: Copy the file via SCP.

### TRIGGER (v) - (TV) — approved
- STE: The event triggers the callback.
- Non-STE: The event fires the callback.

### true (adj) - UNNAPROVED — unapproved
- Use instead: A Boolean value. THE CONDITION IS TRUE
- STE: The condition is true.
- Non-STE: The condition evaluates to truth.

### TRY (v) — approved
- STE: Try the request again.
- Non-STE: Retry the request.

### TURN (v) — approved
- STE: Turn on the feature flag.
- Non-STE: Enable the feature flag.

### TYPE (n) - (TN) — approved
- STE: The type of the variable is string.
- Non-STE: The variable is a string.

# U

### under (prep) - UNNAPROVED — unapproved
- Use instead: BELOW (prep), LESS THAN. BELOW THE THRESHOLD
- STE: Below the threshold.
- Non-STE: Under the threshold.

### UNLOCK (v) — approved
- STE: Unlock the mutex.
- Non-STE: Release the mutex.

### UNSTABLE (adj) - (TN) — approved
- STE: The connection is unstable.
- Non-STE: The connection is flaky.

### UNTIL (prep) — approved
- STE: Retry the request until it succeeds.
- Non-STE: Keep retrying the request while it fails.

### UNUSUAL (adj) — approved
- STE: Watch for unusual log entries.
- Non-STE: Watch for unexpected log entries.

### UP (adv), UP (prep) — approved
- STE: Bring the service up.
- Non-STE: Start the service.

### UPDATE (v) - (TV) — approved
- STE: Update the package to the latest version.
- Non-STE: Upgrade the package to the latest version.

### USE (v) — approved
- STE: Use the API to fetch data.
- Non-STE: Utilize the API to fetch data.

### USUAL (adj), USUALLY (adv) — approved
- STE: Usually, the request returns 200 OK.
- Non-STE: Typically, the request returns 200 OK.

# V

### valid (adj) - UNNAPROVED — unapproved
- Use instead: CORRECT (adj). MAKE SURE THAT THE INPUT IS CORRECT
- STE: Make sure that the input is correct.
- Non-STE: Make sure that the input is valid.

### VALIDATE (v) - (TV) — approved
- STE: Validate the user input before processing.
- Non-STE: Check the user input before processing.

### VALUE (n) — approved
- STE: The value of the environment variable is "production".
- Non-STE: The environment variable is set to "production".

### VARIABLE (n) - (TN) — approved
- STE: Declare the variable before use.
- Non-STE: Define the variable before use.

### verify (v) - UNNAPROVED — unapproved
- Use instead: MAKE SURE (v). MAKE SURE THAT THE SIGNATURE IS CORRECT
- STE: Make sure that the signature is correct.
- Non-STE: Verify the signature.

### VERSION (n) - (TN) — approved
- STE: The current version is 3.2.1.
- Non-STE: The release is 3.2.1.

### VERY (adv) — approved
- STE: Increase the value very slowly.
- Non-STE: Increment the value in tiny steps.

### via (prep) - UNNAPROVED — unapproved
- Use instead: THROUGH (prep), BY (prep). AUTHENTICATE THROUGH OAUTH
- STE: Authenticate through OAuth.
- Non-STE: Authenticate via OAuth.

### VIEW (n), VIEW (v) - (TN) — approved
- STE: The log view shows recent entries.
- Non-STE: The log display shows recent entries.

### visible (adj) - UNNAPROVED — unapproved
- Use instead: SEE (v). MAKE SURE THAT YOU CAN SEE THE OUTPUT IN THE TERMINAL
- STE: Make sure that you can see the output in the terminal.
- Non-STE: Make sure that the output is visible in the terminal.

### VISUAL (adj) — approved
- STE: Do a visual inspection of the UI.
- Non-STE: Visually inspect the UI.

### VOLUME (n) — approved
- STE: Mount the volume to the container.
- Non-STE: Attach the storage to the container.

# W

### WAIT (v) — approved
- STE: Wait for the asynchronous task to complete.
- Non-STE: Block until the async task finishes.

### WANT (v) — approved
- STE: Install the package that you want.
- Non-STE: Install the desired package.

### WARNING (n) - (TN) — approved
- STE: The compiler shows a warning for the deprecated function.
- Non-STE: The compiler warns about the deprecated function.

### watch (v) - UNNAPROVED — unapproved
- Use instead: MONITOR (v). MONITOR THE LOG OUTPUT
- STE: Monitor the log output for errors.
- Non-STE: Watch the log output for errors.

### WE (pron) — approved
- STE: We recommend using the latest API.
- Non-STE: The team recommends using the latest API.

### WEAK (adj) — approved
- STE: A weak reference does not prevent garbage collection.
- Non-STE: A soft reference does not prevent garbage collection.

### WEIGHT (n) — approved
- STE: The weight of the config value is 0.5.
- Non-STE: The priority of the config value is 0.5.

### WHEN (conj) — approved
- STE: When the build finishes, deploy the artifact.
- Non-STE: After the build finishes, deploy the artifact.

### WHERE (conj) — approved
- STE: Find the line where the error occurred.
- Non-STE: Find the line at which the error occurred.

### WHILE (conj) — approved
- STE: Log the progress while the script runs.
- Non-STE: Log the progress as the script executes.

### whole (adj) - UNNAPROVED — unapproved
- Use instead: ENTIRE (adj). EXAMINE ALL OF THE CODEBASE
- STE: Examine all of the codebase.
- Non-STE: Examine the whole codebase.

### WIDE (adj) — approved
- STE: Wide test coverage.
- Non-STE: Broad test coverage.

### WILL (v) — approved
- STE: The docs will help you to set up the project.
- Non-STE: The docs are going to help you set up the project.

### WITH (prep) — approved
- STE: Compare the result with the expected value.
- Non-STE: Compare the result against the expected value.

### WITHOUT (prep) — approved
- STE: Run the build without caching.
- Non-STE: Run the build with caching disabled.

### WORK (n) — approved
- STE: Do the work in a dedicated branch.
- Non-STE: Do the task in a dedicated branch.

### WORKER (n) - (TN) — approved
- STE: The worker processes jobs from the queue.
- Non-STE: The background job processor handles the queue.

### WRITE (v) — approved
- STE: Write the result to a file.
- Non-STE: Save the result to a file.

### wrong (adj) - UNNAPROVED — unapproved
- Use instead: INCORRECT (adj). MARK THE VARIABLE TO PREVENT INCORRECT USAGE
- STE: Mark the variable as private to prevent incorrect usage.
- Non-STE: Mark the variable as private to prevent wrong usage.

# Y

### YES (adv) — approved
- STE: Does the test pass? Yes or no?
- Non-STE: Is the test passing? Affirmative or negative?

### yet (conj) - UNNAPROVED — unapproved
- Use instead: BUT (conj). COMPILE THE PROJECT, BUT SKIP THE TESTS
- STE: Compile the project, but skip the tests.
- Non-STE: Compile the project, yet skip the tests.

### yet (adv) - UNNAPROVED — unapproved
- Use instead: AT THIS TIME. DO NOT DEPLOY THE FEATURE AT THIS TIME
- STE: Do not deploy the feature at this time.
- Non-STE: Do not deploy the feature yet.

### YOU (pron) — approved
- STE: You can run the script from the command line.
- Non-STE: The user can run the script from the command line.

### YOUR (adj) — approved
- STE: If you get an error in your terminal, read the logs.
- Non-STE: If an error appears in the terminal, read the logs.

# Z

### ZERO (n) - (TN) — approved
- STE: Initialize the counter to zero.
- Non-STE: Set the counter to 0.

### List of Recurring Errors - Code-Documentation Domain — approved

### Summary Statistics — approved

---

## Reference & scope notes


> **Note:** The source file `ste-code/merged/master.md` (extracted from ASD-STE100 Issue 9, pages 149-434) contains only the Dictionary A-Z entries. The official ASD-STE100 also includes:
> - **Change History** - tracked via the Highlights section (pages 3-28 of the spec)
> - **Change Form** - a template for submitting proposed changes to the standard
> - **Subject-to-Rule Index** - cross-references subjects to governing rules
> - **List of Approved Verbs** - quick-reference table of ~200 approved verbs (included in Dictionary intro, pages 147-148 of master.md)
> - **List of Recurring Errors** - common mistakes writers make (included in Dictionary intro, pages 145-146 of master.md)
>
> These sections were not available in the enriched files used to create `master.md`. The adaptation above covers all Dictionary A-Z entries present in the extraction.

---

## List of Recurring Errors - Code-Documentation Domain

> Adapted from master.md pages 145-146

| Non-STE | STE-Code Alternative |
|---------|---------------------|
| acceptable (adj) | PERMITTED (adj) |
| alternate (adj) | ALTERNATIVE (adj) |
| avoid (v) | PREVENT (v) |
| check (v) | VERIFY (v) or CHECK (n) with DO |
| complete (adj) | COMPLETED (adj) |
| damage (v) | DAMAGE (n) with CAUSE |
| ensure (v) | MAKE SURE (v) |
| fit (v) | INSTALL (v) |
| follow (v) | OBEY (v) |
| further (adj) | MORE (adj) |
| have to (v) | MUST (v) |
| however (adv) | BUT (conj) |
| insert (v) | PUT (v) |
| main (adj) | PRIMARY (adj) |
| may (v) | CAN (v) |
| need (v) | NECESSARY (adj) / MUST (v) |
| perform (v) | DO (v) |
| portion (n) | PART (n) |
| press (v) | PUSH (v) |
| repeat (v) | DO ... AGAIN |
| require (v) | NECESSARY (adj) / MUST (v) |
| shall (v) | MUST (v) |
| should (v) | MUST (v) |
| since (conj) | BECAUSE (conj) |
| test (v) | TEST (n) with DO |
| therefore (adv) | THUS (adv) |
| under (prep) | BELOW (prep) / IN (prep) |
| using (v) | USE (v) / WITH (prep) |

---

## Summary Statistics

- **Approved words adapted:** ~875 (all UPPERCASE entries from original)
- **Unapproved words adapted:** ~1274 (all lowercase entries with approved alternatives)
- **Code-domain technical nouns added (TN):** ~60 (for terms not present in original aerospace STE)
- **Code-domain technical verbs added (TV):** ~40 (for software-specific operations)
- **Total entries in this adaptation:** ~2000+
- **Source:** ste-code/merged/master.md lines 5591-10976
- **Original specification:** ASD-STE100 Issue 9, January 2025, Part 2 - Dictionary, Pages 149-434

---

*End of STE-Code Adapted Dictionary A-Z*



## 04-templates.md

# Level 5 — Document Templates (code review / PR feedback)

Level 5 is the full STE-Code standard: every rule, the extension vocabulary, the
reference catalogue, and provenance. This sub-document is the **document
templates** slice — reusable, code-domain skeletons you can drop into an LLM
prompt when it generates or reviews code documentation: README pages, API
reference entries, docstrings, inline comments, commit messages, error messages,
configuration comments, and pull-request descriptions.

The templates below are distilled from the standard's rules on consistency
(Rule 9.4), safety instructions (Rule 7.2), sentence construction (Rule 9.1),
and the word / grammar rules that govern each genre. They are faithful to the
standard and use code-domain examples only. Use them as fill-in-the-blank
scaffolds; do not invent rules that are not in the standard.

## The three consistency templates (Rule 9.4)

Every genre below obeys the same three consistency rules. Pick one term, one
verb, and one sentence structure per action, and reuse it every time that
action appears.

- **Lexical consistency** — one term per concept. Do not alternate between
  "configuration file," "settings file," and "config" for the same file.
- **Syntactic consistency** — same structure for the same action. All setup
  steps, all configuration steps, and all verification steps share one template.
  The template signals the step type before the reader parses the content.
- **Semantic consistency** — same meaning for the same term across files,
  modules, and documentation types. If "build" means "compile and link" in the
  README, it must not mean "compile, link, and package" in the CI docs.

A reviewer comment that flags a synonym swap is a valid STE-Code finding.

---

## Template 1 — README / procedural doc page (Rules 5.3, 5.4, 8.1, 9.4)

Use imperative sentences for each step. Put a descriptive statement before the
command only when the reader needs context first (Rule 5.4). One sentence per
step. No semicolons (Rule 8.1).

```
## <Section title>

<Optional one-sentence context: why this step exists.>

1. <Imperative verb> <object> to <purpose clause>.
2. <Imperative verb> <object> to <purpose clause>.
3. <Imperative verb> <object>.
```

Worked example (STE):

```
## Configure the server

1. Open the configuration file in a text editor.
2. Change the port number in the configuration file.
3. Save the configuration file and close it.
4. Build the project with the build command.
```

Non-STE (three names for one file, three verbs for one action): "Open the
configuration file… Change the port in the settings file… Save the config…
Compile the project… Make the binary…" — each synonym forces the reader to
pause and ask "is this the same thing?"

## Template 2 — API reference entry (Rules 1.3, 9.1, 9.4)

Name each parameter exactly as it appears in the signature. Use the approved
word for the field's meaning (e.g. "permitted," not "acceptable"). Keep the
description to one short sentence.

```
### `VERB /path` — <Short resource name>

<One sentence: what the endpoint does.>

| Parameter   | Type    | Description                              |
|-------------|---------|------------------------------------------|
| `<name>`    | `<type>`| <One short sentence using the exact name.>|

**Responses**
- `200` — <one sentence>
- `4xx` — <one sentence>
```

Worked example (STE): the parameter `timeout_ms` is described as "A timeout
value of 5000 ms is permitted for this endpoint." (approved word "permitted").
The same field must be called `timeout_ms` in prose, schema, and code — never
"creation date" / "timestamp" / "created time" for one response field.

---

## Template 3 — Function docstring (Rules 1.9, 9.4)

The docstring uses the same term that appears in the signature. A parameter
named `max_retries` is "max_retries" in the body, never "maximum attempts" or
"retry limit." Use the shortest unambiguous term (Rule 1.9).

```
def <name>(<params>) -> <type>:
    """<One sentence: what the function does.>

    Args:
        <param>: <one short sentence, same name as signature>
    Returns:
        <one short sentence>
    """
```

Worked example (STE):

```python
def validate_email_address(value: str) -> bool:
    """Validate an email address against RFC 5322.

    Args:
        value: The string to validate.
    Returns:
        True if the string is a valid address.
    """
```

Do not write the 36-word paraphrase of the regex pattern — the signature and
the standard name the concept.

## Template 4 — Inline comment (Rules 1.9, 8.1, 9.4)

One short sentence. The code or the key name carries the context; the comment
only names the purpose in the shortest form. No semicolons.

```
# <Short phrase: the purpose of the next block>
```

Worked examples (STE):
- Config: `# Maximum number of parallel workers.` (the key `max_workers` and
  value `8` already state the rest — do not copy a 9-word phrase as the comment).
- Test: `# Checks that the fetch utility returns JSON from the API endpoint.`
  (the function name and `assert` line name the subject and expectation).

---

## Template 5 — Commit message (Rules 5.3, 7.1, 7.2, 9.4)

Imperative, one verb per category, consistent across the project. If the
convention is `Add`, do not mix in `Introduce`, `Insert`, or `Create`. If the
convention is `Fix`, do not mix in `Resolve`, `Correct`, or `Patch`.

```
<Type>: <Imperative summary in one sentence, <= 72 chars>

<Optional body: one sentence per point. For safety, start with the
command or condition (Rule 7.2).>
```

Worked examples (STE):
- `Add the configuration parser for the YAML settings file.`
- `Fix the connection leak in the worker pool.`
- Safety body: `WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. ALWAYS USE
  ENVIRONMENT VARIABLES OR A SECRETS MANAGER TO STORE API KEYS. API KEYS IN
  SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.`

If a commit needs many unapproved words, write a shorter message and put the
details in the pull-request description.

---

## Template 6 — Error message (Rules 7.1, 7.2, 9.4)

An error code must produce the same text every time (reliability property, Rule
9.4). Start with a signal word when the message carries risk. The reader
correlates the message with the code by the exact code name.

```
<Optional signal word: WARNING | CAUTION> <Clear command or condition, one sentence.>
```

Worked examples (STE):
- `E_CONNECT_FAIL: Cannot connect to the database. Check the connection string.`
- `WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE.`

Do not let `E_CONNECT_FAIL` say "connection refused" in module A and "cannot
connect to server" in module B — the operator cannot search logs reliably.

## Template 7 — Configuration-file comment (Rules 1.9, 8.1, 9.4)

The key and value state the setting; the comment names only the purpose. One
sentence per option. No semicolons (split purpose and trade-off into two
sentences).

```
# <Purpose of this option, one short phrase.>
<key> = <value>
# <Optional trade-off, one sentence.>
```

Worked example (STE):

```
# Maximum number of parallel workers.
max_workers = 8
# A higher value uses more memory.
```

---

## Template 8 — Pull-request / review description (Rules 5.3, 5.4, 8.1, 9.4)

Write instructions as imperative sentences. Give context before a command only
when the reviewer needs it. One sentence per point; use numbered steps for
multi-step workflows so the reviewer can complete one before reading the next.

```
## Summary
<One or two sentences: what this change does.>

## Changes
1. <Imperative verb> <object>.
2. <Imperative verb> <object>.
3. <Imperative verb> <object>.

## Test plan
1. <Imperative verb> <object> to <purpose>.
2. <Imperative verb> <object>.

## Notes
<Optional context sentence before the action, if the reviewer needs it.>
```

Worked example (STE):

```
## Summary
Add the linter to the pre-commit hook.

## Changes
1. Create a new feature branch from the `main` branch.
2. Make your code changes on the feature branch.
3. Commit your changes with a descriptive message.
4. Push the branch to the remote repository.
5. Open a pull request against `main`.

## Test plan
1. Run the linter before you submit the pull request.
2. Squash your commits into a single change.
```

Non-STE (one 40-word sentence joined by "and"): "Create a new feature branch
from the main branch and make your code changes on that branch and then commit
your changes with a descriptive message and push the branch to the remote
repository and open a pull request against the main branch." — the reader
cannot complete one step before reading the next.

---

## Template 9 — Object-oriented inheritance docstring (Rule 9.4)

When you document a class hierarchy, use the same phrasing for overridden
methods. The base-class docstring sets the template; each subclass reuses it and
adds only the subclass-specific behavior.

```
class <Base>:
    """<Template sentence for the method.>"""

class <Sub>(<Base>):
    """<Same template sentence.> <Subclass-specific behavior.>"""
```

Worked example (STE):

```python
class Connection:
    """Establish a connection to the remote host."""

class TlsConnection(Connection):
    """Establish a connection to the remote host. Use TLS for transport."""
```

Non-STE: base says "Connects to server," subclass says "Opens a socket to the
backend," grandchild says "Initiates TCP handshake with data node" — three
templates for one operation.

---

## Sentence-construction fallback (Rule 9.1)

When a word is not approved and a word-for-word swap is not enough, restructure
the sentence — do not keep the unapproved word. Common approved swaps:

| Do not write        | Write             | Why |
|---------------------|-------------------|-----|
| execute the script  | run the script    | "run" is the approved verb |
| generate the artifact | make the artifact | "make" is approved |
| utilize / leverage  | use               | inflated verb |
| bootstrap / initiate | start            | "start" is approved |
| retrieve / fetch    | get               | "get" is approved |
| transmit            | send              | "send" is approved |
| validate / verify   | check             | "check" is approved |
| unable to           | cannot            | "cannot" is approved |
| acceptable          | permitted         | approved adjective |
| visible             | you can see       | verb replaces adjective |

If the part of speech differs or the meaning would change, write a new sentence
with a different structure that keeps the same technical meaning.

## Reviewer checklist (apply to any genre above)

1. One term per concept (lexical consistency).
2. One verb per action, reused everywhere (lexical + syntactic consistency).
3. Same sentence structure for the same step type (syntactic consistency).
4. Same meaning for the same term across files (semantic consistency).
5. One sentence per step; no semicolons (Rule 8.1).
6. Signature name == docstring name == prose name (Rule 9.4).
7. Safety / error text starts with a command or condition and is identical
   wherever the same code appears (Rules 7.2, 9.4).
8. Only approved words, code-domain technical nouns, or code-domain technical
   verbs (Section 1 gates).



## 05-grammar.md

# Level 5 — Grammar (Rules 2.1–2.3, 3.1–3.7)

Level 5 is the full STE-Code standard. This sub-document is the **grammar** slice:
the rules that govern how words combine into technical nouns (Section 2) and into
sentences (Section 3). These rules are the structural backbone that the vocabulary
rules in Section 1 and the clarity rules in Sections 4–9 assume already hold.

Use this file when you generate, review, or lint code documentation with an LLM and
need to enforce sentence shape — short technical nouns, approved verb forms, active
voice, and no auxiliary-verb constructions.

## What "grammar" covers here

- **Section 2 — Technical nouns:** keep multi-word nouns short (Rule 2.1), write long
  technical nouns in full then shorten them (Rule 2.2), hyphenate related words as one
  unit (Rule 2.3).
- **Section 3 — Sentence structure:** use only the approved verb forms (Rule 3.1),
  only the approved tenses (Rule 3.2), use the past participle as an adjective (Rule 3.3),
  do not build auxiliary-verb constructions (Rule 3.4), use "-ing" forms only as technical
  nouns/modifiers (Rule 3.5), use the active voice (Rule 3.6), and prefer a verb over a
  noun when an approved verb exists (Rule 3.7).

The three-word limit for a noun phrase (Rule 2.1) interacts with hyphenation: a hyphenated
unit counts as one word, so `main-feature-flag` + `rollback-handler` + `trigger` is three
words, not five.

---

## Rule 2.1 — Keep technical nouns short

To keep multi-word technical nouns short, use prepositions (for example "of," "on," "in,"
and "for") and explain the multi-word technical nouns. A technical noun that the code domain
uses — a module name, class name, configuration key, endpoint path, error type, or test
fixture — must stay short so the reader can parse it without effort.

When a phrase names a code component with more than a few words, break the phrase into small
nouns that connect with prepositions. Do not write one long noun that stacks modifiers.

Why this matters:

- A stacked noun such as `authentication_token_expiration_refresh_interval_setting` hides
  which part owns which. A short noun with prepositions shows the tree: the setting belongs
  to the interval, the interval to the expiration, the expiration to the token.
- Short technical nouns match how code is already structured. A config key, class, or JSON
  field is one short concept; prepositions in the sentence show how those concepts relate.
- Follow the Microsoft and Google style guides: use short, plain words. Do not use `utilize`,
  `leverage`, or `employ` when `use` is enough; do not use `commence`, `initiate`, or
  `terminate` when `start` and `stop` are enough.
- Approved code-domain adjectives stay attached to the short noun they modify: `idempotent`,
  `immutable`, `thread-safe`, `atomic`, `nullable`, `deprecated`, `stateless`,
  `backward-compatible`, `asynchronous`, `concurrent`, `deterministic`. Write
  `the idempotent retry policy`, not `idempotentretrypolicy`.

How to apply:

1. Find a noun that stacks two or more modifiers (a "noun chain").
2. Split the chain at the ownership or containment points.
3. Connect the parts with `of`, `on`, `in`, or `for`.
4. If a part is itself a code component, name it with its short technical noun (its class,
   key, or file), not a merged word.
5. In instruction text, use the approved verbs: `set`, `get`, `make`, `show`, `check`,
   `remove`, `send`, `start`, `stop`, `use`, `update`. Do not use `configure` for `set`,
   `retrieve` for `get`, `delete`/`purge` for `remove`, or `display` for `show`.

Worked pairs:

| Do not write | Write |
|---|---|
| Authentication token expiration refresh interval setting | Setting of the refresh interval of the expiration of the authentication token |
| Install the forward service request validator middleware config tags. | Install the config tags on the validator middleware of the request of the forward service. |
| Remove the database migration script output directory lock files. | Remove the lock files that lock the output directory of the migration script of the database. |
| Payment gateway timeout retry exhaustion notification handler | Handler of the notification of the exhaustion of the retry of the timeout of the payment gateway |

See also: Rule 1.5 (what counts as a technical noun), Rule 1.3 (keep verbs and nouns plain),
Rule 2.2 (when a noun must stay long), Rule 2.3 (hyphenate related pairs).

---

## Rule 2.2 — Write long technical nouns in full

When a technical code noun has more than three words, write it in full. Then use one of
these methods to make the technical code noun clear:

- Give a shorter form of the technical code noun.
- Use hyphens (-) between words that you use as one unit.
- Use prepositions (for example "of," "on," "in," "for," and "to") to split a long noun into
  short, separate parts (see Rule 2.1).

A long multi-word code noun can be a long technical noun, or a combination of shorter
technical nouns. Frequently it is not possible to divide technical code nouns into smaller
parts because they are the technical nouns your company, framework, or subject field uses.
Thus, write technical code nouns in their approved form.

**Method 1 — Shorter form.** If a long technical code noun comes from an official code
document (an API specification, a schema, an OpenAPI file, an architecture diagram), write it
in full the first time it occurs. Then, if possible, explain the noun and use a shorter form
or approved abbreviation in the rest of the document.

> Initialize the user session cache invalidation lock handler (the handler that locks the
> cache of the user session; in this procedure, we call it the "invalidation lock handler").
> Run the invalidation lock handler before the shutdown hook releases the cache.

> The Main Form Validation Module (MFVM) is a TypeScript module that includes a Main Export
> Controller Unit (MECU) and a Data Bridge (DB). The Dynamic Config Unit (DECU) sends events
> to operate the MFVM.

If an approved technical code noun has three words or fewer, you do not need an abbreviation.

**Method 2 — Prepositions.** When a long technical code noun is a chain of short nouns (for
example "user authentication token refresh failure retry policy"), put the key noun first,
then attach the modifiers with "of," "on," "in," "for," or "to."

| Do not write | Write |
|---|---|
| Configure the user authentication token refresh failure retry policy before you deploy. | Configure the retry policy for the failure of the refresh of the user authentication token before you deploy. |
| Install the background worker queue overflow alert suppression rule on the staging cluster. | Install the alert suppression rule on the overflow of the background worker queue on the staging cluster. |
| Remove the database connection pool exhaustion recovery timeout configuration parameter. | Remove the configuration parameter that sets the recovery timeout for the exhaustion of the database connection pool. |

**Method 3 — Hyphenate.** When two or more words act as a single modifier before a noun, use
a hyphen to show they are one unit. Do not hyphenate when the first word is an "-ly" adverb
(for example "a publicly documented API" stays open).

| Do not write | Write |
|---|---|
| Set the request response mapping handler to the new schema. | Set the request-response mapping handler to the new schema. |
| Run the build time configuration check after you compile. | Run the build-time configuration check after you compile. |
| Add an end to end test for the payment flow. | Add an end-to-end test for the payment flow. |
| Use the out of band signal to stop the long running job. | Use the out-of-band signal to stop the long-running job. |

Note: hyphenation groups words into one unit but does not make a long technical noun short.
If the hyphenated unit still has more than three words (for example "request-response mapping
handler"), write it in full the first time, then use the shorter form ("mapping handler").

How to apply in code documentation:

1. Find the long technical code noun (more than three words).
2. Write it in full the first time it occurs; keep the exact approved form from the source.
3. Give a shorter form or approved abbreviation in parentheses right after.
4. In the rest of the document, use only the shorter form or abbreviation.
5. If the noun is a chain of short nouns, split it with prepositions (Rule 2.1).
6. If two or more words act as one modifier, hyphenate them.
7. Do not fill a procedure with abbreviations; a short clear noun beats a string of letters.

See also: Rule 2.1 (three-word limit), Rule 1.5 (technical noun categories), Rule 1.3
(use, set, get, make, show, check, remove, send, start, stop).

---

## Rule 2.3 — Use hyphens between words used as one unit

A hyphen is a punctuation mark that connects words or parts of words. Use hyphens between
words to show how related words operate as one unit. This method makes the multi-word code
nouns agree with Rule 2.1. Hyphenated words always count as one word, so a hyphenated code
noun fills only one of the three-word slots that Rule 2.1 allows for a noun phrase.

Do not connect words that are not related, because the hyphen changes the meaning of the
multi-word code noun. If you are not sure, explain the noun in the clearest way, then use a
shorter form, an approved verb such as `get`, `set`, `make`, `start`, or an official approved
abbreviation from your glossary.

If an approved technical code noun includes hyphens — for example `input-output stream`,
`thread-safe queue`, or `backward-compatible API` — do not change it. If it is too long, write
it in full the first time it occurs, then use the shorter-technical-noun method.

Do not use hyphens to make groups of more than three words. Keep the hyphen group to at most
three words; split longer chains with prepositions such as `of`, `on`, or `in`.

Approved hyphenated code examples:

| Example | Note |
|---|---|
| Make sure that the fail-safe shutdown-handler connection is safe. | 3 words: make / sure / connection |
| Inspection of the request rate-limit device. | 3 words: inspection / of / device |
| The thread-safe queue keeps the order of the write operations. | 3 words: queue / keeps / order |
| Remove the backward-compatible API client before you make the change. | 3 words |

When a hyphen joins two related words, the pair counts as one unit. Apply this in procedural
and descriptive code documentation so the reader can parse the noun without re-reading.

| Do not write | Write |
|---|---|
| Move the `main-feature-flag-rollback-handler` trigger to start the test run. | Move the `main-feature-flag` rollback-handler trigger to start the test run. |
| Remove the `data-adapter` assembly (8) from the view body. | Remove the `data adapter` assembly (8) from the view body. |
| The `input output stream` is part of the logging system. | The `input-output stream` is part of the logging system. |

Cautions:

- Do not hyphenate a three-word approved technical noun (`data adapter`, `pipeline validator`);
  adding a hyphen changes the count and confuses the reader.
- Keep a hyphen the official name already has (`input-output stream`); removing it changes
  the term.

See also: Rule 2.1 (the three-word limit hyphenated units help you meet), Rule 1.5
(hyphenated code terms such as `thread-safe queue` and `backward-compatible API`),
Rule 2.2 (pair hyphenated nouns with short approved verbs).

---

## Section 3 — Sentence structure

Section 3 governs how approved words form sentences. The dictionary gives each approved verb
with four forms; Section 3 tells you which forms and tenses you may use, how to keep the
active voice, and how to avoid auxiliary-verb constructions.

### The four approved verb-form categories

1. **Development operations** — build, compile, test, lint, format, commit, push, deploy, rollback
2. **Data operations** — read, write, serialize, deserialize, parse, encode, decode, query, insert, migrate
3. **Application operations** — handle, route, authenticate, authorize, validate, schedule, dispatch, resolve
4. **Communication operations** — send, receive, publish, subscribe, stream, poll, broadcast, connect

The plain everyday verbs also apply: `use`, `start`, `stop`, `show`, `make`, `get`, `set`,
`check`, `do`, `send`, `remove`, `keep`.

---

## Rule 3.1 — Use only the verb forms given in the dictionary

The STE-Code dictionary gives the verb forms you can use for each approved verb. Use only
those forms. Do not use other forms (gerunds, participles used as verbs with auxiliaries, or
inflected forms that are not listed).

Every approved verb appears with four forms, in this order: base form, third-person singular,
simple past, past participle. The simple future is not a separate line; make it with "will"
and the base form.

| Line in the entry | Form | Example with WRITE |
|---|---|---|
| Line 1 | Base form (infinitive and imperative) | WRITE — "Write the log." / "to write the log" |
| Line 2 | Third-person singular, simple present | WRITES — "The logger writes the record." |
| Line 3 | Simple past | WROTE — "The job wrote the record." |
| Line 4 | Past participle (as an adjective) | WRITTEN — "the written log" |

How to apply:

1. Find the verb in the STE-Code dictionary.
2. If the verb is not in the dictionary, use the approved verb instead: `make` (not
   `generate`), `get` (not `retrieve`), `check` (not `verify`), `use` (not `utilize`), `start`
   (not `initiate`), `stop` (not `terminate`), `remove` (not `delete`), `show` (not `render`),
   `do` (not `execute`), `keep` (not `maintain`).
3. If the verb is in the dictionary, use only one of the four listed forms.
4. Do not make a new form from an approved verb. "Parsing," "parseable," and "parser" are not
   verb forms of PARSE; a noun such as "parser" is approved only when the dictionary or a
   technical-noun category gives it.
5. Use the past participle only as an adjective ("the parsed manifest," "the deprecated
   method"). Do not use it with "have," "has," "had," or "get" to make a verb.

| Do not write | Write |
|---|---|
| The linter validates the file and is reporting the errors. | The linter validates the file. It reports the errors to the terminal. |
| The script has written the output to the log. | The script wrote the output to the log. Then the test starts. |
| The service utilizes a token cache and leverages the parser. | The service uses a token cache. The service parses each request. |
| The loader does the parsing and the validating. | The loader parses the manifest. Then the loader validates the schema. |
| The migration had deleted the deprecated column. | The migration removed the deprecated column. Then the migration stopped the open connections. |

See also: Rule 3.2 (approved tenses), Rule 3.3 (past participle as adjective), Rule 3.4
(avoid auxiliary verbs), Rule 3.6 (active voice), Rule 1.1 (word gates), Rule 1.5
(technical noun categories), the STE-Code dictionary (a-dictionary.md).

---

## Rule 3.2 — Use only these verb forms and tenses

Use only these verb forms and tenses of verbs:

- The infinitive form
- The imperative form (command form)
- The simple present tense
- The simple past tense
- The simple future tense
- The past participle form (as an adjective)

Do not use other forms and tenses that are not approved:

- The present perfect (have/has parsed)
- The past perfect (had parsed)
- The present/past progressive (is/was parsing)
- The future progressive (will be parsing)
- The perfect progressive (has been parsing, had been parsing)
- The gerund used as a verb with an auxiliary (is parsing, keeps parsing)

Approved verb-form table (code verbs):

| Infinitive | Imperative + object | Simple present | Simple past | Simple future | Past participle (adj) |
|---|---|---|---|---|---|
| (To) Parse | Parse + object | It parses | It parsed | It will parse | The parsed file |
| (To) Write | Write + object | It writes | It wrote | It will write | The written log |
| (To) Build | Build + object | It builds | It built | It will build | The built artifact |
| (To) Send | Send + object | It sends | It sent | It will send | The sent request |
| (To) Validate | Validate + object | It validates | It validated | It will validate | The validated token |

How to select the correct form:

1. **Infinitive** — after a modal verb or to state a purpose: "Use this flag to parse the file."
2. **Imperative** — for each step of a procedure: "Parse the file. Write the log."
3. **Simple present** — for a general fact, repeated action, or system behavior: "The parser reads the file."
4. **Simple past** — for a complete action: "The build failed."
5. **Simple future** — "will" + base form for a later action: "The job will start at 02:00."
6. **Past participle** — only as an adjective before a noun: "the parsed file," "the deprecated method."

How to correct an unapproved form:

- Present perfect ("has parsed") → simple past ("parsed").
- Past perfect ("had parsed") → simple past in two sentences with "Then".
- Progressive ("is parsing," "was parsing") → simple present or simple past; if two actions
  happen together, write two sentences and add "at the same time".
- Future progressive ("will be parsing") → simple future ("will parse").
- Passive with unapproved auxiliary ("is being parsed") → name the actor and use the active
  voice (Rule 3.6).

| Do not write | Write |
|---|---|
| The linter has found three errors. | The linter found three errors in the source file. |
| The server was processing the request when the timeout occurred. | The server processed the request. Then the timeout occurred. |
| The framework had already initialized the pool. | The framework made the connection pool. Then the query started. |
| The scheduler is deploying the build while the tests are running. | The scheduler sends the build to production. The tests run at the same time. |
| You should be setting the timeout, then you will be restarting. | Set the timeout value. Then start the service again. |

See also: Rule 3.1 (dictionary forms), Rule 3.3 (past participle as adjective), Rule 3.4
(avoid auxiliary verbs), Rule 3.5 ("-ing" only as noun/modifier), Rule 3.6 (active voice),
Rule 1.1 (word gates), the STE-Code dictionary.

---

## Rule 3.3 — Use the past participle form as an adjective

When you use the past participle form as an adjective, it shows the condition of something.
This is not passive voice. Use the past participle form of an approved verb as an adjective:

- Before a noun
- After a verb form of "to be," "to become," or "to stay"

Do not use the past participle form if it is not in the STE-Code dictionary. Approved
adjectives in the dictionary that are the past participle of verbs that are not approved
(for example "permitted," "damaged") have part of speech "(adj)" and are permitted.

How to know it is an adjective and not passive voice:

1. The word gives the **condition** of the thing, not an action an actor does.
2. You can put it directly before the noun: "the parsed file," "the deprecated method,"
   "the closed connection".
3. You can put it after "is," "becomes," or "stays": "the cache is initialized," "the endpoint
   becomes deprecated," "the record stays locked".
4. If the sentence names an actor and an action ("the file was parsed by the loader"), it is
   passive voice — write the active voice instead (Rule 3.6).

Approved code-domain past participles used as adjectives:

| Past participle (adj) | Example noun phrase | Condition it shows |
|---|---|---|
| parsed | the parsed manifest | The parser read the file. |
| serialized | the serialized record | The record is in a transport format. |
| deserialized | the deserialized object | The object is in memory again. |
| initialized | the initialized cache | The cache is ready for use. |
| deprecated | the deprecated method | The method is old. Do not use it. |
| allowed | the allowed memory | The limit the configuration gives. |
| corrupted | the corrupted index | The data is not correct. |
| locked | the locked row | Another transaction holds the row. |
| written | the written log | The log file is on disk. |
| given | the given options | The options the caller sends. |
| built | the built artifact | The build made the artifact. |
| signed | the signed token | The token has a valid signature. |

Cautions:

- Do not make a new past participle from an unapproved verb. Write "the removed branch," not
  "the deleted branch," unless "delete"/"deleted (adj)" is in the dictionary.
- Do not use a past participle as a verb with "have," "has," or "had" (Rule 3.2).
- Do not put more than one past participle before the same noun; split into two short
  sentences if the phrase becomes difficult.
- Prefer the plain word: "started" not "commenced," "used" not "utilized," "stopped" not
  "terminated".

| Do not write | Write |
|---|---|
| The method has been deprecated by the API team. | The method is deprecated in release 4.2. Do not use the deprecated method in new code. |
| The record gets locked, then the transaction is committed. | The transaction writes the locked record. Then the transaction ends. |
| The gateway validates the signed token on each request. | (already active — "signed" is the adjective before "token") |
| The build artifact stays uncompiled until the pipeline has compiled. | The artifact stays unbuilt until the pipeline builds the modified sources. |

See also: Rule 3.1 (dictionary forms), Rule 3.2 (approved tenses), Rule 3.4 (avoid auxiliary
verbs), Rule 3.5 ("-ing" as noun/modifier), Rule 3.6 (active voice), Rule 1.1 (word gates),
the STE-Code dictionary (approved adjectives with "(adj)").

---

## Rule 3.4 — Do not use auxiliary verbs to make complex verb constructions

Do not use the past participle form as a verb together with the auxiliary verb "have." Do not
use auxiliary verbs ("have," "be," "will," "can," "must," "should," "is to be") with a past
participle to build compound tenses or passive voice. These constructions make complex verb
forms that STE-Code does not approve. Write the action with a simple, approved verb form:

- Use the simple past instead of "have/has/had + past participle" (present or past perfect).
- Use the active voice with a clear agent instead of "be + past participle" (passive voice,
  Rule 3.6).
- Use the imperative (command) form for instructions instead of "is to be + past participle."
- Use "you can + base verb" instead of "can be + past participle" when the reader is the agent.
- Use "will + base verb" with a named agent instead of "will be + past participle + by + agent."

When a compound construction is unavoidable for correctness, split it into separate simple
sentences. Rule 3.2 lists the only approved verb forms.

| Do not write | Write |
|---|---|
| The build has compiled the module before the test runs. | The build compiled the module. Then the test runs. |
| The migration is to be run before you deploy. | Before you deploy the service, run the migration. |
| The cache can be cleared. | You can clear the cache. |
| The timeout must be set before the job starts. | Set the timeout before the job starts. |
| The report will be generated by the scheduler. | The scheduler will generate the report. |
| The connection pool has been created before the first query is sent. | The connection pool was created. Then the first query is sent. |
| The configuration file must be validated before the server starts. | Validate the configuration file before the server starts. |
| The user credentials are to be encrypted at rest and the key is rotated. | Encrypt the user credentials at rest. Rotate the key every month. |
| The temporary files had been deleted before the backup started. | The cleanup task deleted the temporary files. Then the backup started. |

See also: Rule 3.2 (approved tenses), Rule 3.3 (past participle as adjective), Rule 3.5
("-ing" as noun/modifier), Rule 3.6 (active voice).

---

## Rule 3.5 — Use the "-ing" form only as a technical noun or modifier

Words with an "-ing" form can be a verb, an adjective, a noun, or a long group of modifiers.
These different functions can cause ambiguity or long complex sentences. Thus, words with an
"-ing" form are usually not permitted as verbs. Use an "-ing" word only as a technical noun
(for example a section title or heading) or as a modifier inside a technical noun.

Approved "-ing" words in STE-Code:

- Nouns: logging, monitoring, routing, servicing
- Adjectives: matching, missing, remaining
- A pronoun: something
- A preposition: during

Why the progressive verb form is not approved: Rule 3.2 lists the only permitted forms and
tenses. The present progressive ("is running," "are deploying," "was processing") is not on
that list, so you must not use "-ing" to describe an action. Replace the progressive with the
simple present or simple past, and break a long continuous clause into short separate
sentences. The "-ing" form also hides auxiliary-verb constructions that Rule 3.4 forbids.

Approved "-ing" technical nouns (titles/headings): Logging, Monitoring, Testing and Fault
Isolation, Handling, Packaging, Shipping, Troubleshooting, Building, Deployment.

Approved "-ing" modifiers (inside a technical noun): logging service, monitoring agent,
routing table, switching relay, caching layer, building pipeline, binding configuration,
streaming endpoint, rendering engine.

Do not pull the "-ing" word out of the technical noun and use it as a verb: "The caching layer
stores the result" is approved; "The layer is caching the result" is not.

| Do not write | Write |
|---|---|
| When you are running this script, obey the safety checks. | When you run this script, obey all the safety checks. |
| The background worker is processing the queue and writing results. | The background worker processes the queue. It writes the results to the cache. |
| Developers committing code without running tests risk breaking the build. | Before you commit code, run the test suite. Make sure the tests pass. |
| The matching algorithm is comparing the remaining items. | The matching algorithm compares the remaining items during the iteration. |
| Something going wrong during the migration can corrupt the database. | If something goes wrong during the migration, the database can stay in a broken state. |

See also: Rule 3.2 (present progressive not approved), Rule 3.4 (auxiliary-verb constructions
forbidden), Rule 1.5 (technical-noun categories that the "-ing" modifier/noun uses depend on).

---

## Rule 3.6 — Use the active voice

Use the active voice in all code documentation. In descriptive writing, the passive voice is
permitted only when the agent (the person, service, or component that does the action) is
unknown.

In the active voice, the subject does the action ("A does B"). In the passive voice, the
subject receives the action ("B is done by A"). To test for passive voice, ask "by whom or by
what?" If the sentence answers, it is passive — convert it to active by using the agent as the
subject.

Four methods to convert passive to active:

- **Method 1** — When "by" identifies the agent, move the agent to the subject position.
- **Method 2** — Change an infinitive verb to an active verb.
- **Method 3** — In procedural writing, change the verb to the imperative (command) form.
- **Method 4** — When the agent is not given, use "you" (reader) or "we" (your organization)
  as the subject.

| Do not write (passive) | Write (active) |
|---|---|
| The API response is parsed by the middleware. | The middleware parses the API response. |
| The database connection is established by the connection pool. | The connection pool establishes the database connection at startup. |
| The dependencies can be installed with this command. | Install the dependencies with this command: npm install |
| The configuration file can be edited with a text editor. | You can edit the configuration file with a text editor. |
| The package can be installed with pip install. | Install the package with this command: pip install . |
| Support for WebSocket connections is provided by this library. | This library supports WebSocket connections. |
| The input string is validated and a boolean is returned by this method. | This method validates the input string and returns a boolean. |
| The authentication bug was fixed. | Fix the authentication bug. |

When the agent is unknown and you cannot identify it, passive is correct:

> Passive (correct): During the network request, the payload was corrupted before the checksum
> was computed. The agent is unknown because the failure occurs only under heavy load.

> Active (incorrect): During the network request, the socket corrupted the payload. — "socket"
> is not the true cause; the active sentence misleads the reader about where to fix the bug.

Use the active voice in each documentation type:

- **README** — procedural sections use the imperative with "you" as the implied agent;
  descriptive sections use the project/library/tool as the subject.
- **API docs** — use the method/function as the subject; for callbacks, use the callback as the
  subject; for return values, use the function as the subject ("This function returns a
  `Promise<User>`", not "A `Promise<User>` is returned").
- **Docstrings/comments** — the summary line uses the imperative; the body uses the function as
  the subject.
- **Commit messages** — imperative mood, inherently active ("Fix the authentication bug", not
  "The authentication bug was fixed").

See also: Rule 3.1 (dictionary forms), Rule 3.2 (approved tenses), Rule 3.3 (past participle as
adjective), Rule 3.4 (avoid auxiliary verbs), Rule 3.5 ("-ing" as noun/modifier).

---

## Rule 3.7 — Use an approved verb to describe an action, not a noun

If there is an approved verb that describes an action, use the approved verb. Verbs describe
actions more clearly than nouns or other parts of speech. The four approved technical-code-verb
categories give you the verbs you can use (see the Section 3 table). If a word is not approved
as a verb in the dictionary, do not use it as a verb — use a different sentence construction
(usually the noun form of the word).

Why verbs, not nouns: a noun names a thing; a verb names the work. "validate the token" tells
the reader to run the check; "validation of the token" makes the reader ask whether to run it,
log it, or skip it. Prefer the plain approved verb — `use`, `start`, `stop`, `show`, `make`,
`get`, `set`, `check`, `do`, `send`, `remove`, `keep` — over wordy substitutes such as
*utilize*, *leverage*, *employ*, *commence*, *terminate*, or *initiate*.

| Do not write | Write |
|---|---|
| The ohmmeter gives an indication of 450 ohms. | The ohmmeter shows 450 ohms. |
| Before the removal of the unit, make sure the power is OFF. | Before you remove the unit, make sure the power is OFF. |
| The profiler gives an indication of 200ms latency. | The profiler shows 200ms latency. |
| Before the initialization of the service, check the config. | Before you initialize the service, check the config. |
| Cache the response. | Do a cache of the response. (cache is a technical noun, not an approved verb) |
| The function gives a result of 500 OK. | The function returns 500 OK. |
| The parser does a verification of the payload. | You validate the payload before you store it. |
| A read of the config, then a write of the config. | Read the config, then write the config. |
| A transmission of the event, then a reception. | Send the event, then receive the event. |

See also: Rule 3.2 (approved verb forms and tenses), Rule 1.5 (noun-form fallback when a word
is not an approved verb), the extension approved verbs — use, start, stop, show, make, get, set,
check, do, send, remove, keep.




## 06-extensions.md

# Level 5 — Extensions

Level 5 is the full STE-Code standard. This sub-document is the **extensions** slice:
the approved code-domain vocabulary that sits on top of the core rules in Sections 1–9.
It has two parts:

1. **Extension adjectives** — single approved words (such as `idempotent`, `immutable`,
   `atomic`) that you may attach to a short technical noun without breaking the word-count
   limits of Section 2.
2. **Domain extension vocabulary** — grouped lists of approved code-domain verbs, nouns,
   and signal words for common domains (build, testing, security, version control, and so
   on), each with the rules it must obey and the weak alternatives it replaces.

Use this file when you generate or review code documentation with an LLM and need a compact,
machine-readable list of the words STE-Code accepts beyond its core dictionary.

## How extensions relate to the rules

Extensions are not a new rule set. Each extension still obeys the core rules:

- **Rule 1.1** (approved words only) — every extension word is on an approved list.
- **Rule 2.1** (short technical nouns) — keep the noun short; the adjective attaches to it.
- **Rule 3.1 / 3.7** (prefer a verb) — domain verbs such as `build`, `test`, `deploy` replace
  noun phrases such as "perform a build of" or "do a deployment of".
- **Rule 7.1 / 7.2 / 7.3** (risk and safety words) — the signal-word group replaces vague
  warnings such as "heads up" or "be careful" with `WARNING`, `CAUTION`, `BREAKING`, `DEPRECATED`.

A hyphenated extension adjective counts as one word under Rule 2.1. Write
`the idempotent retry policy` (three words), not `idempotentretrypolicy`. Keep the hyphen
before the noun: `thread-safe`, `backward-compatible`, `read-only`, `stateless`.

---

## Part 1 — Extension adjectives

These adjectives are approved as single words. Each entry gives the definition and one
STE / Non-STE code-documentation pair so you can see the contrast. The Non-STE line shows
the weak alternative the extension replaces (usually `leverage` / `utilize` / `employ` plus a
nominalized verb).

### idempotent
- **meaning**: An operation that produces the same result when applied more than once, with no extra side effects after the first run.
- **STE**: Make the retry handler idempotent so a second call with the same input does not duplicate the record.
- **Non-STE**: Leverage an idempotent retry handler so a duplicate invocation will not create a redundant record.

### immutable
- **meaning**: A data structure or value that cannot be changed after it is created, which prevents accidental shared-state bugs.
- **STE**: Keep the request context immutable so concurrent threads cannot overwrite each other's values during a single operation.
- **Non-STE**: Utilize an immutable request context so concurrent threads will not overwrite shared values during processing.

### atomic
- **meaning**: An operation that completes fully or not at all, with no partial result visible to other processes.
- **STE**: Wrap the balance update in an atomic transaction so the debit and credit always succeed or fail together.
- **Non-STE**: Employ an atomic transaction to encapsulate the balance update so debit and credit always commit or roll back together.

### thread-safe
- **meaning**: Code that functions correctly when accessed by multiple threads at the same time without external locking.
- **STE**: Mark the singleton constructor thread-safe so two threads can call it on first use without creating two instances.
- **Non-STE**: Leverage a thread-safe singleton constructor so concurrent threads will not instantiate duplicate objects on first access.

### asynchronous
- **meaning**: A call or task that starts and returns before its work finishes, so the caller can do other work meanwhile.
- **STE**: Make the file upload asynchronous so the user interface stays responsive while the transfer runs in the background.
- **Non-STE**: Utilize an asynchronous upload mechanism so the user interface remains responsive while the transfer executes in the background.

### concurrent
- **meaning**: Tasks that make progress within the same time period, interleaved by the scheduler rather than strictly sequentially.
- **STE**: Run the test suites in concurrent processes so the full check finishes in a fraction of the single-threaded time.
- **Non-STE**: Employ concurrent processes to execute the test suites so the whole check terminates faster than a single-threaded run.

### deterministic
- **meaning**: A function whose output depends only on its inputs, with no hidden state or time-based variation between runs.
- **STE**: Keep the hash function deterministic so the same key always maps to the same bucket across restarts.
- **Non-STE**: Leverage a deterministic hash function so an identical key consistently maps to the same bucket after restarts.

### deprecated
- **meaning**: An API or feature that still works but that the maintainers plan to remove, so avoid new use of it.
- **STE**: Mark the old login endpoint deprecated and show a warning that points to the new token-based method.
- **Non-STE**: Flag the legacy login endpoint as deprecated and utilize a warning that redirects callers to the token-based method.

### nullable
- **meaning**: A field or variable that can hold a null value to indicate the absence of a meaningful value.
- **STE**: Make the middle-name field nullable so the profile save does not fail when the value is absent.
- **Non-STE**: Configure the middle-name field as nullable so the profile persistence will not fail when the value is missing.

### serializable
- **meaning**: An object that can be converted to a byte stream and rebuilt elsewhere without losing its data.
- **STE**: Make the session object serializable so the cache layer can store it and restore it on the next request.
- **Non-STE**: Utilize a serializable session object so the cache layer can persist and reconstitute it on the following request.

### stateless
- **meaning**: A service that keeps no client data between requests, which makes horizontal scaling simpler and safer.
- **STE**: Build the authentication proxy stateless so any node can answer a request without shared session memory.
- **Non-STE**: Employ a stateless authentication proxy so every node can service a request without shared session storage.

### backward-compatible
- **meaning**: A change that older clients can still use without modification because the old interface still works.
- **STE**: Keep the API response backward-compatible so existing mobile apps keep working after the schema update.
- **Non-STE**: Leverage a backward-compatible response format so legacy mobile clients remain functional after the schema update.

### read-only
- **meaning**: A resource or mode that permits inspection but forbids any write, update, or delete operation.
- **STE**: Open the database handle read-only during reports so the query tool cannot change production data by mistake.
- **Non-STE**: Utilize a read-only database handle for reports so the query tool cannot mutate production data accidentally.

### recursive
- **meaning**: A function that calls itself with a smaller part of the problem until it reaches a base case.
- **STE**: Write the directory walker recursive so it visits every nested folder without a manual loop stack.
- **Non-STE**: Employ a recursive directory walker so it traverses each nested folder without an explicit loop stack.

### monotonic
- **meaning**: A counter or clock that only increases and never goes backward, which makes ordering safe.
- **STE**: Use a monotonic sequence for the event id so replays never create a lower number than a prior record.
- **Non-STE**: Leverage a monotonic sequence for the event identifier so replays never yield a lower value than prior records.

### transitive
- **meaning**: A permission or relation that flows through a chain, so a grant to a group reaches its members.
- **STE**: Make the role grant transitive so a user in a child team inherits the parent team's read access automatically.
- **Non-STE**: Utilize a transitive role grant so a member of a child team inherits the parent team's read access automatically.

### volatile
- **meaning**: A memory value that another thread or device can change at any time, so the compiler must reload it.
- **STE**: Declare the status flag volatile so the loop reads the hardware register again instead of using a cached copy.
- **Non-STE**: Employ a volatile status flag so the loop reloads the hardware register rather than using a cached copy.

### hierarchical
- **meaning**: Data or permissions arranged in parent-child levels where a child inherits settings from its ancestor.
- **STE**: Store the configuration in a hierarchical map so a child setting overrides only the matching branch of the tree.
- **Non-STE**: Utilize a hierarchical configuration map so a child setting overrides solely the matching branch of the tree.

### normalized
- **meaning**: A database schema arranged to remove redundant data and reduce update anomalies across tables.
- **STE**: Keep the user table normalized so the address lives in one row and every order references it by id.
- **Non-STE**: Utilize a normalized user table so the address resides in one row and each order references it by identifier.

### incremental
- **meaning**: A build or update that processes only the changed parts instead of recomputing the whole result.
- **STE**: Run an incremental compile so the tool rebuilds only the modules whose source changed since the last run.
- **Non-STE**: Employ an incremental compile so the tool reconstructs only the modules whose source changed since the prior run.

---

## Part 2 — Domain extension vocabulary

Each domain below lists the approved code-domain words, the weak alternatives they replace,
the core rules that govern them, and one STE / Non-STE example. Use these as drop-in vocabulary
when documenting the matching domain.

### Build and Package
Operations for compiling, assembling, bundling, and distributing software artifacts.
- **Approved**: build, compile, bundle, package, deploy, publish, release, tag, version, transpile, minify, polyfill, ship
- **Replaces**: make a build of → build; perform compilation → compile; create a bundle → bundle; generate the artifact → build; assemble → build; construct → build; fabricate → build
- **Rules**: Rule 1.12, Rule 1.13, Rule 1.1, Rule 1.7
- **Example**: STE: Build the Docker image. Then deploy the container to the registry. | Non-STE: Perform a build of the Docker image and then do a deployment to the registry.

### Testing and Quality Assurance
Operations for verifying code correctness, measuring performance, and ensuring quality.
- **Approved**: test, assert, mock, stub, spy, benchmark, profile, instrument, debug, unit-test, lint, check
- **Replaces**: validate → check; verify → check; ensure → make sure; run validation → check; perform testing → test; execute tests → run tests; carry out verification → check
- **Rules**: Rule 1.12, Rule 1.1, Rule 1.5, Rule 4.1
- **Example**: STE: Run the test suite. Check that the coverage is above 80 percent. | Non-STE: Execute the test suite and verify that coverage exceeds 80%.

### Dependency Management
Operations for installing, updating, locking, and resolving software dependencies.
- **Approved**: install, update, upgrade, pin, lock, link, hoist, resolve, uninstall, add, remove
- **Replaces**: fetch dependencies → install; retrieve packages → install; pull down → install; bump → update; snag → install; grab → get
- **Rules**: Rule 1.12, Rule 1.1, Rule 1.10, Rule 1.11
- **Example**: STE: Install the dependencies with npm install. Pin the versions in the lock file. | Non-STE: Snag the deps and bump the versions.

### Version Control
Operations for tracking changes, branching, merging, and collaborating on source code.
- **Approved**: commit, branch, merge, rebase, tag, push, pull, clone, fork, checkout, revert, cherry-pick, stash, stage, reset
- **Replaces**: save changes → commit; upload → push; download → pull/clone; combine → merge; split off → branch
- **Rules**: Rule 1.12, Rule 1.7, Rule 1.13, Rule 1.1
- **Example**: STE: Commit the changes. Then push the branch to the remote repository. | Non-STE: Git the changes and then push them up. (Uses Git as a verb, Rule 1.7 violation)

### Security
Operations for authentication, authorization, encryption, and protecting systems from threats.
- **Approved**: authenticate, authorize, encrypt, decrypt, hash, salt, sanitize, validate, sign, revoke, audit, escape
- **Replaces**: secure → encrypt/protect; lock down → restrict; harden → make secure; obfuscate → hide
- **Rules**: Rule 1.12, Rule 7.1, Rule 1.5, Rule 1.1
- **Example**: STE: WARNING: Sanitize all user input before you process it. Unsanitized input can cause SQL injection attacks. | Non-STE: CAUTION: Always clean your inputs.

### Logging and Monitoring
Operations for recording events, measuring system health, and observing runtime behavior.
- **Approved**: log, monitor, trace, instrument, observe, alert, report, record
- **Replaces**: write to log → log; keep track of → monitor; watch → monitor; spy on → observe; output → write/log
- **Rules**: Rule 1.12, Rule 1.1, Rule 1.5, Rule 5.1
- **Example**: STE: Log the error details to the error file. Monitor the CPU usage. | Non-STE: Do a logging of the exception. Keep an eye on the CPU.

### API Design
Concepts for designing, documenting, and consuming application programming interfaces.
- **Approved**: endpoint, route, handler, middleware, controller, request, response, payload, header, status code, rate limit, query parameter, path parameter, body, schema
- **Replaces**: URL path → endpoint; API method → endpoint; args → parameters; params → parameters; data → payload/body; return value → response
- **Rules**: Rule 1.5, Rule 1.11, Rule 1.8, Rule 4.1
- **Example**: STE: The endpoint returns a JSON object. The object contains a user list and a pagination token. | Non-STE: The API method gives you back a JSON with the users and a next-page thing.

### Configuration Management
Operations for setting up, managing, and maintaining system and application configuration.
- **Approved**: configure, set, initialize, bootstrap, provision, override, default, environment variable, config file, dotenv, settings
- **Replaces**: tweak → set/change; dial in → configure; set up → configure/initialize; wire up → configure/connect; spin up → start/initialize
- **Rules**: Rule 1.12, Rule 1.1, Rule 1.10, Rule 5.4
- **Example**: STE: Set the DATABASE_URL environment variable in the .env file. | Non-STE: Tweak the DATABASE_URL knob in the dotenv thing.

### Object-Oriented Design
Concepts and operations specific to object-oriented programming paradigms.
- **Approved**: instantiate, inherit, override, extend, implement, encapsulate, delegate, inject, compose, abstract class, interface, constructor, method, property, polymorphism
- **Replaces**: make an instance → instantiate; new up → instantiate; subclass → extend/inherit; hide → encapsulate; pass → delegate
- **Rules**: Rule 1.12, Rule 1.5, Rule 1.7, Rule 1.13
- **Example**: STE: The UserRepository class extends BaseRepository. It implements the IAuditable interface. Inject the Database dependency through the constructor. | Non-STE: The repo subclasses the base and hides the data. Pass the DB in via the ctor.

### Functional Programming
Concepts and operations specific to functional programming paradigms.
- **Approved**: compose, curry, map, reduce, fold, filter, recurse, memoize, lift, pattern match, pure function, immutable, closure, higher-order function, monad, functor, applicative
- **Replaces**: chain → compose; loop over → map; combine → reduce/fold; cache results → memoize; call itself → recurse
- **Rules**: Rule 1.12, Rule 1.5, Rule 1.1, Rule 1.11
- **Example**: STE: Map the transformation over the list. Then fold the results with the sum function. | Non-STE: Loop over the array applying the transform and then add everything up.

### Systems Programming
Concepts and operations for memory management, ownership, lifetimes, and low-level system access.
- **Approved**: allocate, deallocate, borrow, own, drop, move, pin, acquire, release, dereference, lifetime, ownership, stack, heap, undefined behavior, dangling pointer, segmentation fault, mutex, atomic
- **Replaces**: free → deallocate; malloc → allocate; clean up → deallocate/drop; grab a lock → acquire; let go → release; shooting yourself in the foot → undefined behavior
- **Rules**: Rule 1.12, Rule 1.5, Rule 1.10, Rule 7.1
- **Example**: STE: Allocate a buffer on the heap. Deallocate the buffer before the function returns. The borrow checker prevents dangling pointers. | Non-STE: Malloc a chunk of memory and free it when you are done. Rust's thingy stops you from shooting yourself in the foot.

### Declarative Configuration
Concepts for describing desired system state through configuration files and infrastructure-as-code.
- **Approved**: provision, converge, reconcile, apply, destroy, declare, resource, provider, module, state, plan, namespace, pod, deployment, service
- **Replaces**: spin up → provision/start; tear down → destroy; make → provision; run → apply; set up → provision
- **Rules**: Rule 1.12, Rule 1.5, Rule 1.1, Rule 4.1
- **Example**: STE: The Terraform resource provisions an AWS EC2 instance. Apply the configuration to converge the infrastructure. | Non-STE: Terraform spins up an EC2 box when you run the apply command.

### Risk and Safety Documentation
Signal words and conventions for documenting security risks, breaking changes, and important notes in code.
- **Approved**: WARNING, CAUTION, BREAKING, DEPRECATED, NOTE, FIXME, TODO, HACK, XXX
- **Replaces**: DANGER → WARNING; IMPORTANT → NOTE/WARNING; BE CAREFUL → CAUTION; ATTENTION → NOTE; heads up → NOTE; watch out → CAUTION
- **Rules**: Rule 7.1, Rule 7.2, Rule 7.3, Rule 1.1
- **Example**: STE: WARNING: DO NOT COMMIT THE API KEY. AN EXPOSED KEY CAN CAUSE UNAUTHORIZED ACCESS. | Non-STE: heads up: don't check in the secret key or bad things happen.

### Commit Message Conventions
Standardized terms and formats for writing clear, consistent commit messages.
- **Approved**: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert, add, remove, update, change
- **Replaces**: implemented → feat/add; added → add/feat; fixed → fix; changed → update/change; removed → remove; bumped → update; patched → fix
- **Rules**: Rule 1.1, Rule 4.1, Rule 5.1, Rule 1.11
- **Example**: STE: feat: Add JWT authentication middleware for API routes. | Non-STE: Implemented JWT auth middleware for the API endpoints.

### Continuous Integration and Delivery
Operations and concepts for automated build, test, and deployment pipelines.
- **Approved**: pipeline, workflow, job, stage, runner, artifact, trigger, checkout, cache, matrix, environment, deploy, rollback, approval, gate
- **Replaces**: CI → pipeline/workflow; CD → deployment pipeline; build step → job/stage; CI runner → runner; kick off → trigger/start; fire → trigger
- **Rules**: Rule 1.5, Rule 1.12, Rule 1.8, Rule 5.2
- **Example**: STE: The pipeline has three stages: build, test, and deploy. Trigger the workflow on every push to the main branch. | Non-STE: The CI kicks off when you push to main and runs the build, test, and deploy stuff.

### Database Operations
Operations for querying, migrating, backing up, and managing database systems.
- **Approved**: query, migrate, seed, backup, restore, roll back, replicate, shard, index, vacuum, compact, flush, persist, transaction, schema
- **Replaces**: run a query → query; do a migration → migrate; populate the DB → seed; dump → backup; snapshot → backup; write to disk → persist/flush
- **Rules**: Rule 1.12, Rule 1.13, Rule 1.5, Rule 1.11
- **Example**: STE: Migrate the database schema to version 3. Seed the development database with test data. | Non-STE: Run the migration script to update the DB and populate it with fake data.

### User Interface Documentation
Terms for documenting UI components, interactions, and interface behavior.
- **Approved**: click, type, scroll, select, drag, drop, toggle, zoom in, zoom out, navigate, press, tap, swipe, hover, focus
- **Replaces**: hit → click/press; push → click/press; enter → type; choose → select; flip → toggle; go to → navigate
- **Rules**: Rule 1.12, Rule 1.5, Rule 1.1, Rule 5.2
- **Example**: STE: Click the Submit button. Type your password in the text field. | Non-STE: Hit the submit thing and enter your pwd in the box.



## 07-catalogue.md

# Level 5 — Reference Catalogue (vendor / community)

This document catalogues the **external references** that informed STE-Code's
controlled vocabulary. These references are **NOT part of the standard**. They
are vendor and community sources that the dictionary and rules were checked
against. Use them when you need to resolve a word, a term, or a style question
that the STE-Code rules and dictionary do not settle.

Status note for readers: each entry is either bundled locally as a mirror under
`.agents/reference/` (type `page` or `raw`) or is a live external pointer (type
`pointer`). Local mirrors are stored outside `final/` per project rule, so they
do not ship inside the standard itself — only this catalogue does.

How to use this catalogue:
- Need a style decision (voice, capitalization, sentence length)? → Style guides.
- Need a definition of a code-domain term (API, commit, idempotent)? → Glossaries.
- Need to confirm a word is a real English word / spelled right? → Word lists.
- Need to automate checking in CI? → Linters.
- Need to discover more sources? → Pointer / topic indexes.

## Style guides

These set the **voice and conventions** STE-Code inherits: short sentences,
active voice, plain words, consistent terminology.

| Reference | Type | Source | Use for |
|---|---|---|---|
| Microsoft Writing Style Guide | page | [learn.microsoft.com](https://learn.microsoft.com/en-us/style-guide/welcome/) (mirror: `.agents/reference/microsoft-writing-style-guide.md`) | Voice, capitalization, tone, word choice |
| MicrosoftDocs/microsoft-style-guide (GitHub source) | page | [github.com/MicrosoftDocs/microsoft-style-guide](https://github.com/MicrosoftDocs/microsoft-style-guide) (mirror: `.agents/reference/microsoft-style-guide-github.md`) | Same content as above, source repo |
| Google Style Guides | page | [google.github.io/styleguide](https://google.github.io/styleguide/) (mirror: `.agents/reference/google-style-guides.md`) | Technical writing conventions, API docs, capitalization |
| DevOps Style Guide Glossary | page | [tydukes.github.io/coding-style-guide/glossary](https://tydukes.github.io/coding-style-guide/glossary/) (mirror: `.agents/reference/devops-style-guide-glossary.md`) | DevOps and coding style terms |

## Code-domain glossaries

These supply **definitions of terms used in software and code documentation**.
Prefer them over general dictionaries when a word has a code-specific meaning.

| Reference | Type | Source | Use for |
|---|---|---|---|
| Kong/apiglossary | page | [github.com/Kong/apiglossary](https://github.com/Kong/apiglossary) (mirror: `.agents/reference/kong-apiglossary.md`) | API and REST terminology |
| dwyl/technical-glossary | raw | [raw.githubusercontent.com/dwyl/technical-glossary/main/README.md](https://raw.githubusercontent.com/dwyl/technical-glossary/main/README.md) (mirror: `.agents/reference/dwyl-technical-glossary.txt`) | Broad technical terms |
| jvalentino/glossary | page | [github.com/jvalentino/glossary](https://github.com/jvalentino/glossary) (mirror: `.agents/reference/jvalentino-glossary.md`) | Software engineering terms |
| GitHub Official Glossary | page | [docs.github.com/.../github-glossary](https://docs.github.com/en/get-started/learning-about-github/github-glossary) (mirror: `.agents/reference/github-official-glossary.md`) | Git and GitHub terms (commit, fork, pull request) |

## Word lists (spelling & allowed vocabulary)

These are the **authority for whether a word is a real English word and how it is
spelled**. STE-Code also uses them to seed and verify its approved dictionary.

| Reference | Type | Source | Use for |
|---|---|---|---|
| ryanwi software-terms.dic | raw | [gist.githubusercontent.com/ryanwi/6135845/raw/software-terms.dic](https://gist.githubusercontent.com/ryanwi/6135845/raw/software-terms.dic) (mirror: `.agents/reference/ryanwi-software-terms.txt`) | Software-domain word list |
| en-wl/wordlist (SCOWL) | page | [github.com/en-wl/wordlist](https://github.com/en-wl/wordlist) (mirror: `.agents/reference/en-wl-wordlist.md`) | Spell-check word lists (many sizes/levels) |
| MichaelWehar 5000-more-common | raw | [raw.githubusercontent.com/MichaelWehar/Public-Domain-Word-Lists/master/5000-more-common.txt](https://raw.githubusercontent.com/MichaelWehar/Public-Domain-Word-Lists/master/5000-more-common.txt) (mirror: `.agents/reference/michaelwehar-5000-common.txt`) | Common-word supplement |
| OpenSTE.org | pointer | [openste.org](https://openste.org/) | Reference implementation of Simplified Technical English |
| dwyl/english-words (POINTER) | pointer | [raw.githubusercontent.com/dwyl/english-words/master/words.txt](https://raw.githubusercontent.com/dwyl/english-words/master/words.txt) | Large general English word list |
| freeDictionaryAPI english.txt (POINTER) | pointer | [raw.githubusercontent.com/meetDeveloper/freeDictionaryAPI/master/meta/wordList/english.txt](https://raw.githubusercontent.com/meetDeveloper/freeDictionaryAPI/master/meta/wordList/english.txt) | General English word list |

## Linters (automated checking)

Use these to **enforce STE-Code-like rules in CI** (prose lints, not compiler
errors). They are the basis for the style checks STE-Code recommends.

| Reference | Type | Source | Use for |
|---|---|---|---|
| Vale linter | page | [github.com/errata-ai/vale](https://github.com/errata-ai/vale) (mirror: `.agents/reference/vale.md`) | Pluggable prose linter for docs/CI |
| errata-ai/Microsoft | page | [github.com/errata-ai/Microsoft](https://github.com/errata-ai/Microsoft) (mirror: `.agents/reference/vale-microsoft.md`) | Microsoft style rules for Vale |
| errata-ai/Google | page | [github.com/errata-ai/Google](https://github.com/errata-ai/Google) (mirror: `.agents/reference/vale-google.md`) | Google style rules for Vale |
| errata-ai/write-good | page | [github.com/errata-ai/write-good](https://github.com/errata-ai/write-good) (mirror: `.agents/reference/vale-write-good.md`) | write-good style rules for Vale |

## Discovery pointers (topic indexes)

Starting points for **finding more word lists and glossaries** if the above do
not cover a term.

| Reference | Type | Source | Use for |
|---|---|---|---|
| GitHub topic: word-list | pointer | [github.com/topics/word-list](https://github.com/topics/word-list) | More word-list repositories |
| GitHub topic: glossary-terms | pointer | [github.com/topics/glossary-terms](https://github.com/topics/glossary-terms) | More glossary repositories |
| GitHub topic: technical-writing | pointer | [github.com/topics/technical-writing](https://github.com/topics/technical-writing) | More technical-writing resources |
| GitHub topic: controlled-vocabulary | pointer | [github.com/topics/controlled-vocabulary](https://github.com/topics/controlled-vocabulary) | More controlled-vocabulary resources |



## 08-provenance.md

# Level 5 — Provenance

Level 5 is the full STE-Code standard: every rule, the extension vocabulary, the
reference catalogue, and provenance. This sub-document is the **provenance**
slice. It records where the content of the standard comes from, which pipeline
stage produced each part, and what is inside the standard versus what is only an
external input.

Use this file when you must answer one of these questions:

- Which directory holds the authoritative form of a rule, a dictionary entry, or
  an extension term?
- Which stage created a given file, and from what input?
- Is a word list part of STE-Code, or only a reference that informed it?

## Trust order

When two files disagree, the later stage wins:

`extracted` → `refined` → `grouped` → `adapted` → `enriched (final/rules)` → `final`

`ste-code/final/` is the authoritative form of the standard. Every earlier
directory is kept for traceability, not for reuse in generation.

External references never win. They are inputs to vocabulary work only.

## Pipeline stages

| Stage | Source dir | Role |
|---|---|---|
| A Extraction | `ste-code/extracted/` | Specification PDF to structured pages |
| B Refinement | `ste-code/refined/` | Formatted dictionary and rule markdown |
| C Grouping | `ste-code/grouped/` | Semantic slice and concatenation of pages |
| D Adaptation | `ste-code/adapted/` | Code-domain rule rewrite |
| G Enrichment | `ste-code/final/rules/` | Cross-references and traceability |
| E Extension | `ste-code/extensions/` | Code-domain vocabulary gap-fills |
| References | `.agents/reference/` | Vendor and community vocabulary (catalogued) |

The stages are consolidated into `ste-code/final/` by `assemble_final.py`.

## Stage notes

- **A Extraction** reads the source specification and writes one markdown page
  per specification page. No rewriting occurs at this stage.
- **B Refinement** applies formatting rules only. Dictionary pages become
  tables; rule pages keep the original rule text and its examples.
- **C Grouping** is deterministic. It moves bytes: it slices and concatenates
  refined pages into semantic groups. It does not generate text, so no content
  can be lost or invented here.
- **D Adaptation** re-expresses each rule in the code domain. It keeps the
  original rule statement for traceability and adds a code-domain form and
  code-domain examples.
- **G Enrichment** adds cross-references between rules and the traceability
  links back to the adapted and refined sources.
- **E Extension** adds vocabulary that the code domain needs and the source
  standard does not supply. Extension entries are marked as extensions; they are
  not presented as original rules.

## Inside and outside the standard

| Item | Location | In the standard? |
|---|---|---|
| Rules | `ste-code/final/rules/` | Yes |
| Dictionary and extension vocabulary | `ste-code/extensions/` | Yes |
| Reference catalogue | `ste-code/final/reference-catalogue.md` | Yes, as a catalogue |
| Vendor and community word lists | `.agents/reference/` | No |
| Pipeline tools, state, and logs | `.agents/` | No |

The reference catalogue is part of the standard, but the referenced material is
not. The catalogue records what informed the controlled vocabulary so that a
reader can audit a term without the standard shipping third-party content.

## Reference catalogue (summary)

These external sources inform the STE-Code controlled vocabulary. They are not
part of the standard.

| Reference | Type | Use |
|---|---|---|
| Microsoft Writing Style Guide | page | Plain-language and terminology guidance |
| MicrosoftDocs/microsoft-style-guide | page | Source form of the style guide |
| Google Style Guides | page | Code and documentation conventions |
| Kong/apiglossary | page | API terminology |
| dwyl/technical-glossary | raw | General technical terms |
| jvalentino/glossary | page | General technical terms |
| GitHub Official Glossary | page | Repository and workflow terms |
| DevOps Style Guide Glossary | page | Build, deploy, and operations terms |
| ryanwi software-terms.dic | raw | Software spelling dictionary |
| OpenSTE.org | pointer | Simplified Technical English community work |
| en-wl/wordlist (SCOWL) | page | Word-list coverage checks |
| MichaelWehar 5000-more-common | raw | Common-word frequency checks |
| dwyl/english-words | pointer | Word-list coverage checks |
| freeDictionaryAPI english.txt | pointer | Word-list coverage checks |
| Vale linter | page | Rule enforcement tooling |
| errata-ai/Microsoft | page | Vale rule set |
| errata-ai/Google | page | Vale rule set |
| errata-ai/write-good | page | Vale rule set |
| GitHub topics: word-list, glossary-terms, technical-writing, controlled-vocabulary | pointer | Discovery of further vocabulary sources |

The full catalogue, with the retrieval URL and the local cached file for each
entry, is in `ste-code/final/reference-catalogue.md`.

## Traceability contract

Every rule in `ste-code/final/rules/` can be traced back through the stages:

1. The adapted rule keeps the **original rule statement**, so a reader can
   compare the code-domain form against the source form.
2. The refined page keeps the **source page identifier**, so the adapted rule
   maps to a specific page of the source specification.
3. The extracted page is the raw form of that same page.

If a rule cannot be traced to a refined page, it is an **extension**, not an
adapted rule, and it must be labelled as such.

## Rules for an LLM that uses this file

- Cite `ste-code/final/` when you quote the standard. Do not cite
  `ste-code/extracted/`, `ste-code/refined/`, or `ste-code/grouped/`.
- Do not present an extension term as a rule from the source specification.
- Do not add a word to the controlled vocabulary because it appears in a
  reference in `.agents/reference/`. A reference is evidence, not approval.
- If a term is not in the controlled terminology and not in the extensions, say
  that it is not approved. Do not invent an entry.



## rules-sec1-part1.md

# Level 5 — Section 1 Rules, Part 1 (Words: 1.1–1.4, 1.10–1.14)

Level 5 is the full STE-Code standard. This sub-document is **Section 1, part 1**:
the nine word-level rules that decide *which words you may use, in what form, with
what meaning, and under which name*.

Rules in this part: **1.1, 1.2, 1.3, 1.4, 1.10, 1.11, 1.12, 1.13, 1.14**.
Rules 1.5–1.9 (technical-noun categories) are in Section 1, part 2.

Use this file when an LLM generates, rewrites, or reviews code documentation:
READMEs, API reference, docstrings and inline comments, commit messages, error
messages, and log output.

## How to apply this part

1. **Gate every word** (Rule 1.1): approved word, code-domain technical noun, or
   code-domain technical verb. Nothing else.
2. **Check the part of speech** (Rule 1.2) and the **meaning** (Rule 1.3).
3. **Check the form** (Rule 1.4): only the listed verb and adjective forms.
4. **Check the name** (Rules 1.10, 1.11): no slang or jargon; one name per item.
5. **Check verb use** (Rules 1.12, 1.13): technical verbs only where an approved
   verb is not sufficient, and never as nouns.
6. **Check the spelling** (Rule 1.14): American English, except in quoted text.

| Rule | Statement | One-line test |
|------|-----------|---------------|
| 1.1 | Use approved words, code-domain technical nouns, or code-domain technical verbs. | Does the word pass one of the three gates? |
| 1.2 | Use approved words only as the specified part of speech. | Is the word used as the part of speech it is approved for? |
| 1.3 | Use approved words only with their approved meanings. | Does the sentence use the one approved meaning? |
| 1.4 | Use only the approved forms of verbs and adjectives. | Is the form in the entry (no invented or `-ing` forms)? |
| 1.10 | Do not use regional, slang, or jargon words as code-domain technical nouns. | Would a developer from another community understand it? |
| 1.11 | Do not use different code-domain technical nouns for the same item. | Is this item called the same thing everywhere? |
| 1.12 | You can use verbs you can include in a code-domain technical verb category. | Is an approved verb sufficient instead? |
| 1.13 | Do not use code-domain technical verbs as nouns. | Is the action written as a verb, not as "do a X"? |
| 1.14 | Use American English spelling unless official directives tell you differently. | Is every unquoted word spelled American English? |

---

## Rule 1.1 — Use approved words, technical nouns, or technical verbs

In code documentation, use words that are:

- approved in the controlled terminology (part 2),
- code-domain technical nouns (Rule 1.5), or
- code-domain technical verbs (Rule 1.12).

A **code-domain technical noun** is a noun term for a specified concept in software
development, applicable to a subject field. A **code-domain technical verb** is a
verb term for a specified operation or process in software development.

The controlled terminology also lists words that are **not** approved, with the
approved alternative. Your project glossary or terminology database holds the
technical nouns and verbs; check it first, then this rule.

Rule 1.1 is the gatekeeping rule: every word in every sentence must pass one gate.
Names of tools, files, commands, classes, and endpoints are technical nouns and do
not need approval. The prose around them does.

### Core substitutions

| Do not write | Write |
|--------------|-------|
| execute | run |
| generate, construct | make |
| configure | set |
| retrieve, fetch | get |
| transmit | send |
| delete, purge | remove |
| validate, verify, ensure | check |
| utilize, leverage | use |
| bootstrap, initiate, commence | start |
| terminate | stop |
| perform | do |
| unable to | cannot |
| invalid, malformed | incorrect, not correct |
| duration | time |
| prior to | before |
| implement | add, make |
| optimize (prose) | make faster, make smaller |

### By documentation type

- **README** — procedural sections take approved imperative verbs; descriptive
  sections take approved adjectives and adverbs ("large" not "substantial",
  "usual" not "conventional", "correct" not "valid").
- **API reference** — names are technical nouns; return, parameter, and error prose
  uses approved verbs.
- **Docstrings and comments** — shortest approved word available. `NOTE:` and
  `WARNING:` are approved nouns; `FIXME:` is a code-domain technical noun.
- **Commit messages** — the smallest vocabulary of all: add, fix, remove, update,
  set, make, check, run. "refactor" is allowed as a technical verb (Rule 1.12).
- **Error messages** — read by end users; no jargon, no slang, no abbreviation
  that is not a technical noun.

### Examples

> **Non-STE:** Execute the script to do the task.
>
> **STE:** Run the script to do the task.

> **Non-STE:** To begin utilizing the build toolchain, you must first generate the
> distributable artifact, then execute the compiled binary to bootstrap the local
> development service.
>
> **STE:** Use the build tool to make the binary. Run the binary to start the local
> service.

> **Non-STE (JSDoc):** Fetches a user record. `@param timeout` — The duration the
> client shall await a response prior to terminating the connection attempt.
>
> **STE (JSDoc):** Gets a user record. `@param timeout` — The time that the client
> waits for a response before it stops the connection.

> **Non-STE (Python):** `"""Performs validation on the input data to ensure it
> conforms to the expected schema."""`
>
> **STE (Python):** `"""Checks the input data against the schema. Gives True when
> the data is correct and False when the data is not correct."""`

> **Non-STE (commit):** `feat: implement JWT authentication middleware`
>
> **STE (commit):** `feat: add JWT authentication middleware`

> **Non-STE (CLI):** `Error: Unable to establish connection to the database. Please
> verify your credentials and retry.`
>
> **STE (CLI):** `Error: Cannot connect to the database. Check your credentials and
> try again.`

### Paradigm notes

- **Object-oriented** — class, method, interface, and pattern names are technical
  nouns (Rules 1.5, 1.6). In prose: make (not instantiate), get (not retrieve), set
  (not assign), call, send, keep (not maintain), "is a" / "has a".
- **Functional** — pure, immutable, monad, closure, higher-order function are
  technical nouns. map, fold, reduce, filter, compose, curry are technical verbs
  (Rule 1.12). "Apply" and "pure" carry both an approved sense and a functional
  sense; both are valid.
- **Procedural** — one approved imperative verb per step.
- **Declarative and systems** — keyword names are technical nouns; the surrounding
  instruction uses approved verbs.

### Edge cases

- A framework name that is also a common word (Rails, Spring, Django, Flask) is a
  technical noun when capitalized as a proper noun.
- Code keywords (`goto`, `break`, `continue`, `finally`) keep their code meaning;
  do not use them colloquially.
- Generated documentation (OpenAPI output, JSDoc stubs, godoc) may not follow the
  rule; human-written prose inside it must.
- A technical verb used inside a compound term is part of a technical noun.
- Loanwords and non-English words are not approved unless they are technical nouns.

---

## Rule 1.2 — Use approved words only as the specified part of speech

Each entry in the controlled terminology gives one part of speech. Use the word
only as that part of speech.

- "Query" is an approved **noun**, not a verb. Write "Send a query to the
  database", not "Query the database".
- "Static" is an approved **adjective**, not a verb. Write "Make the variable
  static", not "Static the variable".
- Some words are approved as more than one part of speech. "Call" is an approved
  verb and an approved noun; position in the sentence shows which.

When you replace a word, check that the replacement does not change the meaning.
If it does, restructure the sentence.

If a word is not in the controlled terminology:

1. Find the word in a standard English dictionary.
2. Find the best synonym that is approved in the controlled terminology.
3. Use that approved word, or build a different sentence from approved words.

### Part-of-speech violation table

| Violating form (do not use) | Error | Approved replacement |
|-----------------------------|-------|----------------------|
| Query the database / Cache the result / Queue the job / Log the error / Index the record | Technical noun used as verb | Send a query / Keep the result in the cache / Put the job in the queue / Write the error in the log / Use the index to find the record |
| Docker the app / Git the change / Kubectl the pod / Terraform the VPC | Tool name used as verb | Use Docker / Save with Git / Use `kubectl` / Use Terraform |
| Secure the endpoint / Empty the buffer / Silent the log | Adjective used as verb | Make the endpoint secure / Make the buffer empty / Make the log silent |
| Static the variable / Ready the worker / Live the connection | Adjective used as verb | Make the variable static / Make the worker ready / Make the connection live |
| Utilize the cache / Leverage the library / Employ the service | Unapproved verb (inflated) | Use the cache / Use the library / Use the service |
| Commence the build / Initiate the transfer / Terminate the process | Unapproved verb (inflated) | Start the build / Start the transfer / Stop the process |
| Orchestrate the services / Facilitate the sync | Unapproved verb | Control the services / Help the sync |

"Clear" is approved as both verb and adjective, so "Clear the flag" is allowed.
The **make + adjective** pattern applies to true adjectives such as "secure" and
"empty".

### Examples

> **Non-STE:** Query the database for user records.
>
> **STE:** Send a query to the database for user records.

> **Non-STE (comment):** `# Static the cache size so the value does not change.`
>
> **STE (comment):** `# Make the cache size static so the value does not change.`

> **Non-STE (comment):** `# Terraform the VPC, then Kubectl the pods into the cluster.`
>
> **STE (comment):** `# Use Terraform to make the VPC. Use kubectl to apply the pod configuration to the cluster.`

---

## Rule 1.3 — Use approved words only with their approved meanings

An approved word carries exactly one approved meaning. Using the right word with
the wrong meaning is the most common class of documentation error.

### Procedure

1. Identify the part of speech of the word.
2. Read the approved meaning in the controlled terminology.
3. Compare it to the meaning you intend.
4. If they do not match, use a different approved word or restructure.

### Most-misused approved words

| Approved word | Approved meaning (only this) | Wrong meaning to avoid | Use instead |
|---------------|------------------------------|------------------------|-------------|
| run | execute a program or command | operate, manage, continue | operate, manage, continue |
| return | send a value back from a function to its caller | go back to a state or location | go back |
| call | invoke a function, method, or subroutine | name something | name, refer to as |
| get | fetch or retrieve data from a source | become, understand | become, understand, receive |
| set | put a value into a variable or configuration | become solid, prepare | become solid, prepare |
| make | bring into existence by building or assembling | force, earn | cause, earn |
| send | transmit data to a destination | cause a person to go | cause to go |
| raise | cause an exception or error to occur | increase, lift | increase, lift |
| catch | handle or intercept an exception | capture, become trapped | capture, become trapped |
| pass | give data as an argument to a function | go past, succeed | go past, succeed, give |
| check | examine something to determine correctness or state | stop, restrain | stop, leave |
| break | exit a loop or switch statement immediately | divide, damage, interrupt | split, damage, interrupt |
| continue | skip to the next iteration of a loop | keep doing without interruption | keep |
| fail | an operation did not complete successfully | not pass a test | not pass |
| move | transfer ownership of a value (Rust) | change physical position | go, change position |
| borrow | take a reference without taking ownership | take temporarily | take temporarily |
| follow | come after, go after | act in accordance with | obey |

### Examples

> **Non-STE:** Follow the configuration steps to set up the server.
>
> **STE:** Obey the configuration instructions to set up the server. Then do the
> steps that follow.

> **Non-STE (docstring):** `"""The function will return you to the login screen."""`
>
> **STE (docstring):** `"""The function will go back to the login screen."""`

> **Non-STE:** The background worker runs every night.
>
> **STE:** The background worker operates every night.
> *(The writer means "operates on a schedule", not "executes a program".)*

> **Non-STE (comment):** `# We call this pattern the Repository Pattern.`
>
> **STE (comment):** `# We name this pattern the Repository Pattern.`

> **Non-STE (comment):** `# The middleware serves the cached page and then returns.`
>
> **STE (comment):** `# The middleware gives the cached page to the user and then goes back.`

---

## Rule 1.4 — Use only the approved forms of verbs and adjectives

The controlled terminology gives each approved verb with its approved forms, and
each approved adjective with its comparative and superlative forms where they
apply.

**Verbs** — `COMPILE (v), COMPILES, COMPILED, COMPILED`

| Infinitive / imperative | Simple present | Simple past | Past participle (as adjective) |
|-------------------------|----------------|-------------|--------------------------------|
| (To) Compile / Compile | Compile(s) | Compiled | Compiled |

Forms that are not listed are not allowed: "compilating" and "compilates" are not
forms of "compile".

**Adjectives** — `FAST (adj) (FASTER, FASTEST)`

Base: fast · Comparative: faster · Superlative: fastest.
Adjectives that form the comparative with "more" and "most" have no listed forms,
because "more" and "most" are approved words.

### Form rules by documentation type

- **README** — imperative (base form) for procedures; simple present for
  description. Do not use the `-ing` form as a main verb.
- **API reference** — simple present, third person singular, because the subject is
  the function: "gives", "accepts", "fails". `GIVE (v), GIVES, GAVE, GIVEN`. The
  past participle is an adjective ("the given input"), not a main verb.
- **Docstrings** — imperative for the first line, simple present for the rest. Do
  not mix forms for the same kind of content.
- **Commit messages** — imperative base form only. Not "Added", not "Adding".
- **Error messages and logs** — simple present or simple past of listed forms only.

### Examples

> **Non-STE:** The compiler is compilating the source files every time you save.
>
> **STE:** The compiler compiles the source files each time you save.

> **Non-STE:** This algorithm is more fast than the previous one.
>
> **STE:** This algorithm is faster than the previous one.

> **Non-STE (README):** After installing the dependencies, you can start compiling
> the project by running the build script.
>
> **STE (README):** After you install the dependencies, compile the project with the
> build script.

> **Non-STE (API):** This method is returning a sorted list of users. It is
> accepting an optional filter parameter and is throwing an error when the query is
> failing.
>
> **STE (API):** This method gives a sorted list of users. It accepts an optional
> filter parameter and gives an error when the query fails.

> **Non-STE (commit):** `Fixed memory leak in connection pool and adding timeout configuration`
>
> **STE (commit):** `Fix memory leak in connection pool and add timeout configuration`



## rules-sec1-part2.md

# Level 5 — Section 1 (Part 2): Rules 1.5–1.9 (Code-Domain Technical Nouns)

This slice covers the five STE-Code rules that govern **code-domain technical nouns** —
the domain-specific vocabulary (class names, libraries, protocols, algorithms, defects,
infrastructure terms) that is permitted in documentation even though it is not in the
approved STE-Code dictionary.

Read this slice together with `rules-sec1-part1.md` (Rules 1.1–1.4) and
`rules-sec1-part3.md` (Rules 1.10–1.14).

## Purpose and scope

- Rule 1.5 — which words may appear as code-domain technical nouns (the 19 categories).
- Rule 1.6 — the *gate*: a non-approved word is allowed only as a technical noun.
- Rule 1.7 — a technical noun must never be used as a verb.
- Rule 1.8 — when several names exist, use the standard/approved one.
- Rule 1.9 — when you must choose a technical noun, pick the shortest unambiguous form.

These five rules answer: *"Is this word allowed, and if so how should I write it?"*

## How the five rules interact

```
Word in documentation?
 ├─ approved STE-Code word (Rule 1.1) ──────────────► use it as its part of speech (Rule 1.2)
 └─ not approved
      └─ is it a code-domain technical noun? (Rule 1.5 / 1.6 gate)
           ├─ NO  ───────────────────────────────────► forbidden (replace with approved word)
           └─ YES
                ├─ use the STANDARD name (Rule 1.8)
                ├─ use the SHORTEST form (Rule 1.9)
                ├─ keep it a NOUN (Rule 1.7) ── not a verb
                └─ register it in the project glossary
```

---

# Rule 1.5 — Use Words That You Can Include in a Code-Domain Technical Noun Category

**Statement:** You may use a word that names a precise code-domain concept if it fits one
of the nineteen categories below. Such words are *code-domain technical nouns* and are
allowed even though they are not in the approved STE-Code dictionary.

The dictionary cannot list every technical noun (there are too many, and each project uses
different ones). Register every technical noun you use in your **project glossary** with:
its term, its category, its approved meaning, and an example sentence.

## The nineteen categories

1. **Code components, modules, and libraries** — `class, controller, helper, hook,
   middleware, mixin, module, package, plugin, provider, repository, service, utility`
2. **Computing devices and their components** — `CPU, disk, GPU, keyboard, laptop,
   memory, monitor, mouse, printer, screen, server, smartphone, tablet, terminal`
3. **Development tools, environments, and support equipment** — `CLI, compiler, debugger,
   Docker, editor, IDE, Git, Jest, linter, loader, Prettier, terminal, test runner,
   TypeScript, webpack`
4. **Data structures, types, and formats** — `array, boolean, buffer, CSV, enum, hash map,
   integer, JSON, linked list, object, queue, stack, string, struct, tree, tuple, XML, YAML`
5. **Infrastructure, deployment, and platforms** — `AWS, CI/CD, container, deployment,
   Heroku, Kubernetes, load balancer, Node.js, pipeline, pod, production, staging, Vercel`
6. **Systems, subsystems, and architectural components** — `API gateway, authentication
   layer, caching layer, client, database layer, message broker, microservice, proxy, rate
   limiter, REST API, routing layer, server, WebSocket`
7. **Mathematical, algorithmic, and scientific terms** — `Big O notation, binary search,
   coefficient, complexity, exponent, hash function, iteration, logarithm, matrix,
   recursion, regex, sorting algorithm, time complexity, traversal`
8. **Interface elements and navigation** — `button, checkbox, dialog, dropdown, footer,
   header, menu, modal, navigation bar, radio button, scrollbar, sidebar, tab, text field,
   toggle, tooltip`
9. **Numbers, units of measurement, and time** — `byte, gigabyte (GB), hertz (Hz), hour (h),
   kilobyte (KB), megabyte (MB), millisecond (ms), minute, nanosecond (ns), second (s),
   terabyte (TB)`
10. **Quoted text** — verbatim text that cannot change: error messages, code snippets,
    UI labels, log output. `Cannot read properties of undefined`, `404 Not Found`,
    `connection refused`, `Submit` button
11. **Professional roles, teams, and organizations** — `administrator, backend developer,
    contributor, DevOps engineer, frontend developer, Google, maintainer, Microsoft, product
    owner, QA engineer, reviewer, scrum master, user`
12. **Official documents, API references, and standards** — `API reference, changelog, code
    of conduct, contributing guide, diagram, figure, Getting Started guide, HTTP
    specification, note, paragraph, README, release notes, RFC, section, table, warning`
13. **Runtime environments and operational conditions** — `development, environment
    variable, garbage collection, heap, hot reload, live reload, memory leak, production,
    sandbox, stack trace, staging, test, thread, timeout, virtual machine`
14. **Colors** — `black, blue, cyan, gray, green, magenta, orange, red, white, yellow`.
    Colors are adjectives but are treated as code-domain technical nouns. Comparative/superlative
    forms (`blacker`, `the reddest`) are forbidden.
15. **Defects, errors, and fault terminology** — `assertion failure, bug, crash, deadlock,
    defect, exception, hang, infinite loop, memory leak, null pointer, race condition,
    regression, stack overflow, timeout, type error`
16. **Computer science, information, and communication technology** — `AI, algorithm,
    authentication, authorization, blockchain, containerization, cryptography, database,
    encoding, encryption, firewall, hashing, internet, machine learning, metadata, neural
    network, protocol, query, sandbox, schema, token, virtualization`
17. **Legal and licensing terms** — `Apache 2.0, BSD license, compliance, copyright, GPL,
    license, MIT license, open source, proprietary, terms of service, third-party,
    trademark, warranty`
18. **Database and storage terminology** — `connection pool, cursor, foreign key, index,
    migration, NoSQL, ORM, PostgreSQL, primary key, query, Redis, relation, row, schema,
    seed, SQL, SQLite, stored procedure, table, transaction, view`
19. **Network and protocol terminology** — `DNS, endpoint, HTTP, HTTPS, IP address,
    localhost, middleware, packet, port, request, response, route, socket, SSH, TCP, TLS,
    UDP, URL, VPN, WebSocket`

The lists above are **examples only** — Rule 1.5 does not give a complete list of every
possible code-domain technical noun.

## Relationship to other rules

- **Rule 1.1** (approved words): use an approved word whenever one exists. Use a
  code-domain technical noun only when no approved word names the concept.
- **Rule 1.6** (non-approved words as technical nouns): a non-approved word must belong to
  at least one of these nineteen categories to appear at all.

## Quick application guidance

| Documentation type | Primary categories | Example |
|---|---|---|
| README | 1, 3, 5, 17 | "This package provides a middleware for Express." |
| API documentation | 6, 18, 19 | "The `GET /users/:id` route returns a JSON object with a user struct." |
| Docstrings/comments | 4, 7, 15 | "Traverse the binary search tree in-order and return a sorted array." |
| Commit messages | 1, 15, 18 | "Fix race condition in the connection pool that caused a deadlock on PostgreSQL." |
| Error messages | 13, 15, 19 | "Connection refused: the TCP socket on port 5432 timed out after 30 seconds." |
| Test specs | 1, 4, 15 | "The test calls `parseConfig` with a null pointer and checks for an assertion failure." |

## Edge cases

- **Framework names that are also common words** (`React`, `Go`, `Rust`, `Swift`, `Vue`):
  treat as code-domain technical nouns (category 3 or 5); capitalize to distinguish from
  the English verb ("the Swift language", "the Rust compiler").
- **Code keywords in prose** (`if`, `for`, `class`, `return`): when quoted/backticked they
  are category 10; when used as English words they must follow approved meanings.
- **Abbreviations/acronyms** (`API, JSON, SQL`): allowed; define at first use unless
  universally understood by the audience.
- **Project-internal names** (`PhoenixCache`): allowed only if registered in the glossary.
- **Numbers as named tokens** (`Node.js 18`, `404`, `port 5432`): quoted text or category 9;
  must appear verbatim.

<!-- END-RULE-1.5 -->

---

# Rule 1.6 — Use a Non-Approved Word Only As a Code-Domain Technical Noun

**Statement:** A word that is not approved in the controlled terminology may appear only
when it is a code-domain technical noun, or part of one (Rule 1.5).

This is a **gate** with three tests. An unapproved word may stay only if it clears all three.

## The Technical Noun Gate — three tests

| Test | Question | Pass | Fail |
|---|---|---|---|
| 1 | Is the word unapproved? | approved words skip the gate entirely | — |
| 2 | Is it a technical noun, or part of a compound technical noun (19 categories)? | standalone noun or recognized compound | replace with approved word |
| 3 | Is it used as a noun in the sentence? | noun role | verb/adjective role → replace |

Worked trace — *"The main config loader backups the data through the handler pipeline."*

| Phrase | T1 unapproved? | T2 technical noun? | T3 noun? | Result |
|---|---|---|---|---|
| main config loader | yes | "main" is a general adjective, not a recognized compound | — | "main" → "primary" |
| backups | yes | "backup" as a verb is not a noun | used as verb | "makes an auxiliary copy" |
| handler pipeline | yes | "handler + pipeline" not a recognized compound | fails T2 | "processing pipeline" |

Result: *"The primary config loader makes an auxiliary copy of the data through the
processing pipeline."*

## Key dictionary entries

- **BASE (n) — UNAPPROVED.** Alternatives: BOTTOM (surface/stack), ROOT (filesystem).
  Allowed in compounds: `base case` (cat 7), `base class` (cat 1), `base URL` (cat 8).
- **MAIN (adj) — UNAPPROVED.** Alternative: PRIMARY. Allowed in `main branch` (cat 5),
  `main()` / main function (cat 1, entry point).
- **HANDLER (n) — UNAPPROVED.** Alternative: FUNCTION. Allowed in `event handler`,
  `request handler` (cat 1).
- **BACKUP (n, v) — UNAPPROVED.** Alternatives: AUXILIARY (adj), "makes an auxiliary copy"
  (verb). Allowed in `backup file`, `backup_logs` (cat 18), `/api/v1/backup` (cat 19).
- **BOTTOM, FUNCTION, PRIMARY, AUXILIARY, ROOT** — APPROVED (use these as replacements).

## Compound technical noun checklist

A compound counts as a code-domain technical noun only if ALL are true:
1. The words name one concept the domain recognizes.
2. The compound fits one of the 19 categories.
3. Swapping the unapproved word for its approved alternative changes the recognized name
   and causes confusion.

Criterion: does the compound appear in the framework/language/standard official docs?
Yes → technical noun. No → replace the unapproved words with approved ones.

## Most-used categories for Rule 1.6

1 (code components), 3 (dev tools), 5 (infrastructure), 7 (algorithmic), 8 (directory
hierarchy), 18 (database), 19 (computer science/network).

## Examples

- *"The handler processes each incoming event."* → *"The function processes each incoming
  event."* (standalone "handler" is unapproved).
- *"The event handler processes each incoming event."* → STAYS (compound technical noun, cat 1).
- *"The main configuration has the latest values."* → *"The primary configuration…"*
  ("main" as adjective fails; "main branch" would stay).
- *"Check out the main branch, then copy the files to the base of the build folder."* →
  *"…to the bottom of the build folder."* ("base" as surface word → "bottom").

## Edge cases

- **Framework name used as general verb** — `pandas` stays; "data-frame" verb → "load … into
  a data frame".
- **Code keyword as general noun** — "The `class` of objects…" → "category"; keyword
  `return` stays backticked.
- **Invented compounds** (`handler pipeline`, `backup orchestrator`, `main dispatcher`) —
  not recognized → restructure with approved words.
- **Generated docs** — fix the *source* (docstrings/comments), not the generated output.
- **Brand names** — always technical nouns; descriptive echoes still reviewed.

<!-- END-RULE-1.6 -->

---

# Rule 1.7 — Do Not Use Words That Are Technical Nouns as Verbs

**Statement:** Use a code-domain technical noun only as a noun (or as an adjective inside a
compound technical noun). Do **not** use it as a verb.

The repair pattern: use an approved verb followed by the noun in a prepositional phrase.
*Cache the data* → *Put the data in the cache*. *Database the records* → *Store the records
in the database*. *Queue the jobs* → *Put the jobs in a queue*.

## The dual-category exception

Some words are cataloged in **both** a noun category (Rule 1.5) and a verb category
(Rule 1.12). Then the verb form is allowed **in its approved verb sense** only. Decide in
your glossary which part of speech the word has and obey that decision.

| Word | Noun (Rule 1.5) | Verb (Rule 1.12) |
|---|---|---|
| cache | cat 16: "The cache stores responses." | cat 2c: "Cache the responses." |
| log | cat 18: "Write a log entry." | cat 2c: "Log the error." |
| queue | cat 4: "Add the job to the queue." | cat 3a: "Queue the job." |
| filter | cat 4 / 16 | cat 2b: "Filter the results." |
| sort | cat 7 | cat 2b: "Sort the list by name." |
| map | cat 4 | cat 3a: "Map the function over the list." |

RULE: if a word is cataloged as a noun only → obey Rule 1.7. If both → use the verb form
only when the context matches the verb category. Keep noun and verb uses distinct
(*"Log the error and write the entry to the log file"*, not *"Log the log to the log"*).

## Common noun→verb violations by paradigm

| Paradigm | Noun | Wrong (verb) | Right construction |
|---|---|---|---|
| OOP | interface | "Interface the module with…" | "Add an interface between the module and…" |
| OOP | class / singleton / factory | "Class the model." / "Singleton the logger." | "Make a class for…" / "Make the logger a singleton." |
| Functional | monad / functor | "Monad the value." | "Wrap the value in a monad." |
| Functional | closure / lambda | "Closure the var." | "Capture the var in a closure." |
| Procedural | buffer / pointer / heap | "Buffer the output." | "Write the output to a buffer." |
| Declarative | table / schema / index | "Schema the database." | "Apply a schema to the database." |
| Systems | mutex / semaphore / DMA | "Mutex the state." | "Lock the mutex for the state." |

## Tool, brand, and protocol names

These are always code-domain technical nouns — never verbs.

- *"Docker the application, Git the changes"* → *"Containerize the application, commit the changes."*
- *"Google the error, Slack the results"* → *"Search for the error with Google, send the results with Slack."*
- *"Kubernetes the microservices, Terraform the infra"* → *"Deploy the microservices with Kubernetes, provision the infra with Terraform."*
- *"JSON the response, HTTP it to the client"* → *"Encode the response as JSON, send it through HTTP."*
- *"Microservice the monolith, API the services"* → *"Break the monolith into microservices, add an API for each service."*

## Multi-word technical nouns

Keep the full phrase; do not drop a word to make a verb.

- *"Load balance the requests"* → *"Distribute the requests with a load balancer."*
- *"Rate limit the clients"* → *"Set a rate limit for the clients."*
- *"Feature flag the endpoint"* → *"Put the endpoint behind a feature flag."*
- *"Circuit break the service"* → *"Apply a circuit breaker to the service."*

## Edge cases

- **Framework names that are also English verbs** (`React`, `Go`, `Spring`, `Express`) —
  stay nouns: *"Write the middleware with Express and respond to changes with React."*
- **Code keywords as verbs** (`class`, `import`, `return`, `yield`) — refer to them as
  backticked nouns; use approved verbs for the action. (Note: `return` is itself an approved
  verb; format the keyword as `` `return` `` when naming the construct.)
- **Generated symbol names** (`toJson()`, `UserBuilder`) — exempt; refer to them as nouns
  in prose ("makes a `User` object", "encodes output as JSON").

## Preposition-phrase repair reference

| Noun-verb | Repair | Verb | Prep |
|---|---|---|---|
| Cache the data | Put the data in the cache | put | in |
| Queue the job | Add the job to the queue | add | to |
| Buffer the output | Write the output to a buffer | write | to |
| Socket the connection | Send the connection through a socket | send | through |
| Database the records | Store the records in the database | store | in |
| Docker the app | Package the app in a container | package | in |
| JSON the response | Encode the response as JSON | encode | as |

<!-- END-RULE-1.7 -->

---

# Rule 1.8 — Use Code-Domain Technical Nouns Approved in Your Project, Company, Industry, or Subject Field

**Statement:** When more than one name exists for a code concept, use the name from the most
authoritative source. Do not invent names for items that already have established names in
your codebase or domain. Consistency lets readers find the exact element in the source tree.

## Authority hierarchy (highest first)

1. **Source code** — class names, function names, file names, variable names, type names.
2. **Language specification** — keyword names, standard-library names, built-in types.
3. **Framework/library documentation** — API names, component names, hook names, config keys.
4. **Project glossary** — project-specific terms registered under Rule 1.5.
5. **Industry standard** — design-pattern names, protocol names, algorithm names, architecture names.
6. **Company documentation** — internal system/service/team names.

When the codebase name differs from the industry name, mention both with clear context:
codebase name for traceability, industry name for comprehension. Never mix names from
different levels for the same concept in one document.

## Paradigm reference: avoid → use

| Paradigm | Avoid (invented) | Use (approved) | Authority |
|---|---|---|---|
| OOP | user manager / user handler | `UserRepository` | source code |
| OOP | maker pattern | Factory pattern | pattern literature |
| OOP | data layer / DB interface | `IRepository<T>` | source code |
| Functional | maybe-type / chain functions | `Option` / `None`, pattern matching | language stdlib |
| Functional | higher-order function? (keep) | Higher-order function | math terminology |
| Procedural | heap allocation / data record | `malloc`, `struct`, `pointer` | C spec |
| Procedural | green process | `goroutine` | Go spec |
| Declarative | compute instance | `aws_instance` | Terraform provider docs |
| Declarative | retrieval query | `SELECT` statement | SQL standard |
| Systems | ownership handoff | `move` semantics, `borrow` | Rust reference |
| Systems | thread lock | `Mutex` | stdlib |

## Key principles

- Use exact class/function/type names from the source; do not substitute descriptive phrases
  (*"account controller"* → `AccountController`).
- Use exact protocol/algorithm/framework feature names (*"secure web communication"* →
  `HTTPS`; *"function that manages state and side effects"* → `useEffect`).
- **Define each acronym at first use**, then use only the acronym (*"application programming
  interface (API) … The API returns JSON"*). Alternating full form and acronym implies two
  concepts (violates Rule 1.11).
- Keep the capitalization/spelling of the approved name exactly as in the source
  (`userService`, `findById`, `DATABASE_URL`).
- When a framework renames a standard concept (Django "view", Rails "partial"), use the
  framework's own term in framework-specific docs.
- During a migration, use the **target** name; show the old name only as quoted/DEPRECATED.

## Edge cases

- **Codebase uses a non-standard name** (e.g. `DataStore` for a Repository) — use the
  codebase name; optionally note the industry pattern ("`DataStore` (a Repository
  implementation)").
- **Two industry standards compete** (callback/handler/listener; map/dictionary/object) —
  pick one, register it, use it consistently (Rule 1.11); prefer the ecosystem name.
- **Approved name is an acronym** (API, JSON, JWT) — define at first use unless universal.
- **Framework renames a standard concept** — use framework's term in its own docs.
- **Name changes during refactor** — use the new name; mark the old one DEPRECATED.
- **Same package, different registries** (`python-dotenv` on PyPI vs `dotenv` on npm) — use
  the ecosystem-specific name in installation instructions.

<!-- END-RULE-1.8 -->

---

# Rule 1.9 — When You Must Select a Technical Noun, Use One That Is Short and Easy to Understand

**Statement:** When no code-domain technical noun is approved in your project/industry,
select one that is **short (not more than three words)** and easy to understand. Do not use
long descriptive phrases when a shorter term is sufficient. If the context already
identifies the item, use the shortest unambiguous term; add one or two adjectives only when
needed for disambiguation.

## Core insight: context permits brevity

Context sources that make a short term sufficient: a code reference (line number, function
name, file path), a diagram, a preceding definition, an API spec, or a code snippet that
follows the prose. The code itself carries the detail — the prose only needs to name it.

Examples:
- *"asynchronous JavaScript XML HTTP request wrapper utility function (line 42)"* →
  *"`fetchUtility` function (line 42)"*
- *"user account profile information data transfer object"* → *"`UserProfileDTO`"*
- *"multi-platform containerized microservice orchestration and deployment management layer"*
  → *"the Kubernetes cluster"*
- *"the relational database management system server instance"* → *"the database"*

## Long phrase → short form reference

| Long phrase | Short STE form | Context that permits it |
|---|---|---|
| asynchronous JS XML HTTP request wrapper utility function | fetch utility | line number + snippet |
| serialized JSON payload from the remote API endpoint | JSON data from the API endpoint | field name + type |
| user account profile information data transfer object | `UserProfileDTO` | parameter already named |
| relational database management system server instance | database | port + "primary" |
| mutual exclusion lock primitive with timeout acquisition | mutex | class name in code |
| configuration, settings, and options parameters object | `Config` object | object named `Config` |
| dynamically allocated resizable memory region utility | dynamic array | type declared |

## The three-word limit — rationale and exceptions

The limit (≤3 words) reflects working-memory capacity. Exceptions:
1. **Established technical terms** — "continuous integration pipeline", "abstract syntax
   tree", "public key infrastructure certificate" (standard even if >3 words; do not invent a
   shorter form).
2. **Framework/tool proper names** — "GitHub Actions workflow", "AWS Lambda" (use as given).
3. **Fully qualified type names** — use the short name after first reference
   (`SubComponent` for `com.example.module.SubComponent`).
4. **Shortening causes ambiguity** — keep the longer form; clarity overrides brevity.

## Adjectives: keep only disambiguating ones

- Noise: "the configurable application settings object" (all settings objects are
  configurable), "the secure HTTPS protocol" (HTTPS is secure by definition).
- Disambiguating: "the production application settings object" (prod/staging/dev coexist),
  "the legacy HTTPS endpoint" (old and new coexist).

## Abbreviations and acronyms

- **Universal** (use on first reference, expansion optional): API, JSON, SQL, HTML, HTTP,
  URL, DNS, TCP, TLS, CPU, RAM, SSD.
- **Domain-specific** (expand on first use for a general audience): JWT, CORS, ORM, SPA, SSR.
- **Project-specific** (define on first use in every document; accepted only after defined).
- Do **not** invent new abbreviations to satisfy brevity (Rule 1.8 — use the recognized term).

## Paradigm guidance

- **OOP:** use the class name; state inheritance in a separate sentence
  (*"`UserRepository` extends `BaseRepository<User>`"*), not six stacked modifiers.
- **Functional:** name the *result*, not the whole data-flow chain (*"The fold function. It
  reduces a collection to a single value."*).
- **Procedural:** name the function; let the signature carry types (*"The `fprintf`
  function. It writes formatted output to a file descriptor."*).
- **Declarative:** name the resource type; describe config in bullets/table
  (*"The `HorizontalPodAutoscaler` resource. Set min/max replicas."*).
- **Systems:** use short terms (*reference, borrow, lifetime*); the compiler enforces
  guarantees — describe what the programmer controls, not what the compiler prevents.

## Edge cases

- **Short term less well-known than long** (e.g. `AST`) — expand on first use
  ("abstract syntax tree (AST)"), then use the short form. Test: would a 1-year-experienced
  developer in this domain understand it?
- **Framework name is also a short word** (`React`, `Go`) — use as modifier ("the React
  framework") on first use; do not invent abbreviations like "Rkt".
- **Codebase uses long names internally** (`AbstractUserAuthenticationProviderFactoryBean`)
  — Rule 1.8 wins: use the codebase name as given; use a short prose alias only in surrounding
  text ("the factory bean").
- **Shortening creates a homonym** (`pool` = thread/connection/object) — keep the disambiguating
  modifier ("connection pool", "thread pool") when both appear.
- **Generated docs** — auto-generated portions exempt; human-written summaries/descriptions
  must obey the rule.

---

## Cross-references (Rules 1.5–1.9)

- **Rule 1.1 (Approved Words)** — use approved words for common vocabulary; technical nouns
  supply domain terms.
- **Rule 1.2 (Part of Speech)** — technical nouns are nouns; noun-verbing violates it (Rule 1.7).
- **Rule 1.3 (Approved Meanings)** — a technical noun has its registered meaning only.
- **Rule 1.5 (Technical Noun Categories)** — defines which words qualify (this slice).
- **Rule 1.6 (Non-Approved Words as Technical Nouns)** — the gate; pairs with Rule 1.5.
- **Rule 1.7 (No Noun-Verbing)** — technical nouns stay nouns.
- **Rule 1.8 (Standard Technical Nouns)** — choose the approved name among candidates.
- **Rule 1.9 (Short Technical Nouns)** — choose the shortest unambiguous form.
- **Rule 1.10 (No Slang/Jargon)** — invented names are forbidden; use the standard noun.
- **Rule 1.11 (One Term per Concept)** — use the chosen name consistently everywhere.
- **Rule 1.12 (Technical Verbs)** — permits verb forms in the dual-category exception.
- **Rule 1.13 (No Verb-as-Noun)** — inverse of Rule 1.7 for verbs.
- **Rule 1.14 (American English Spelling)** — follow the spec's spelling for spec-defined names.

<!-- END-SLICE -->




## rules-sec2.md

# Level 5 — Section 2: Technical Nouns (Rules 2.1–2.3)

Source: ASD-STE100 Issue 9, Section 2, adapted for code documentation.
Scope: how to write technical nouns — module names, class names, config keys,
endpoint paths, error types, test fixtures — in API docs, READMEs, commit
messages, runbooks, and code comments.

Section rule set:

| Rule | Title | One-line intent |
|---|---|---|
| 2.1 | Keep technical nouns short | Split noun chains with prepositions (`of`, `on`, `in`, `for`). |
| 2.2 | Write long technical nouns in full | More than three words: write in full on first use, then use a short form or approved abbreviation. |
| 2.3 | Use hyphens between words used as one unit | Hyphenate a related pair; never chain more than three words. |

Shared constraints for the whole section:

- A noun phrase is at most three words. A hyphenated unit counts as one word.
- Use approved verbs: `set`, `get`, `make`, `show`, `check`, `remove`, `send`,
  `start`, `stop`, `use`, `update`. Do not use `configure` for `set`,
  `retrieve` for `get`, `delete`/`purge` for `remove`, `display` for `show`.
- Use short, plain words. Not `utilize`, `leverage`, `employ` — use `use`.
  Not `commence`, `initiate`, `terminate` — use `start` and `stop`.
- Approved code-domain adjectives stay attached to the short noun they modify:
  `idempotent`, `immutable`, `thread-safe`, `atomic`, `nullable`, `deprecated`,
  `stateless`, `backward-compatible`, `asynchronous`, `concurrent`,
  `deterministic`.

---

## Rule 2.1 — Keep Technical Nouns Short

> Source: ASD-STE100 Issue 9, Rule 2.1 · Group 005-rules-sec-2 · Alphabetical key 2

### Rule

To keep multi-word technical nouns short, use prepositions (`of`, `on`, `in`,
`for`) and explain the multi-word technical noun. When a phrase names a code
component with more than a few words, break the phrase into small nouns that
connect with prepositions. Do not write one long noun that stacks modifiers.

### Why it matters in code documentation

- A stacked noun such as `authentication_token_expiration_refresh_interval_setting`
  hides which part owns which. Short nouns with prepositions show the tree.
- Short technical nouns match how code is already structured: a config key, a
  class, or a JSON field is one short concept.
- Long merged nouns are hard to grep, hard to scan, and easy to parse wrongly.

### Procedure

1. Find a noun that stacks two or more modifiers (a "noun chain").
2. Split the chain at the ownership or containment points.
3. Connect the parts with `of`, `on`, `in`, or `for`.
4. If a part is itself a code component, name it with its short technical noun
   (its class, key, or file), not a merged word.
5. In instruction text, use the approved verbs.

### Examples

#### Configuration key — auth token refresh

> **Non-STE:** Authentication token expiration refresh interval setting
>
> **STE:** Setting of the refresh interval of the expiration of the authentication token

```yaml
# STE-Code: short keys, one concept per level
auth:
  token:
    expiration:
      refresh_interval_seconds: 300

# Non-STE: one long key hides the relationship (do not write this)
authentication_token_expiration_refresh_interval_setting: 300
```

```python
def get_refresh_interval(token):
    """Return the setting of the refresh interval of the expiration of the authentication token."""
    return token.expiration.refresh_interval_seconds
```

#### Deployment labels — middleware config

> **Non-STE:** Install the forward service request validator middleware config tags.
>
> **STE:** Install the config tags on the validator middleware of the request of the forward service.

```bash
kubectl label pods \
  -l app=forward-service \
  middleware=validator \
  config=enabled
```

#### Cleanup task — migration lock files

> **Non-STE:** Remove the database migration script output directory lock files.
>
> **STE:** Remove the lock files that lock the output directory of the migration script of the database.

Use the approved verb `remove`, not `delete` or `purge`.

```python
from pathlib import Path

def remove_migration_lock_files(db_name: str) -> int:
    """Remove the lock files that lock the output directory of the migration script of the database."""
    output_dir = Path("migrations") / db_name / "output"
    removed = 0
    for lock in output_dir.glob("*.lock"):
        lock.unlink()
        removed += 1
    return removed
```

```python
def test_remove_migration_lock_files(tmp_path):
    out = tmp_path / "app" / "output"
    out.mkdir(parents=True)
    (out / "write.lock").write_text("")
    count = remove_migration_lock_files("app")
    assert count == 1
    assert not any(out.glob("*.lock"))
```

#### Test setup — cache hook alignment

> **Non-STE:** Adjust to obtain cache invalidation hook alignment with the event emitter.
>
> **STE:** Adjust the cache invalidation hook until it aligns with the event emitter.

```python
import time

def align_cache_hook(hook, emitter, timeout: float = 5.0) -> bool:
    """Adjust the cache invalidation hook until it aligns with the event emitter."""
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        if hook.target is emitter:
            return True
        hook.nudge()
    return False
```

#### API documentation — retry policy

> **Non-STE:** Payment gateway timeout retry exhaustion notification handler.
>
> **STE:** Handler of the notification of the exhaustion of the retry of the timeout of the payment gateway.

```python
class PaymentGatewayTimeoutRetryExhaustionNotificationHandler:
    """Handler of the notification of the exhaustion of the retry of the timeout of the payment gateway."""

    def handle(self, notice) -> None:
        log.error("retry of the timeout of the payment gateway is exhausted")
```

#### Commit message — schema change

> **Non-STE:** User account profile avatar image storage bucket policy update.
>
> **STE:** Update the policy of the storage bucket of the image of the avatar of the profile of the user account.

#### README section — rate limit

> **Non-STE:** The inbound request rate limit window reset schedule controls the burst.
>
> **STE:** The schedule of the reset of the window of the rate limit of the inbound request controls the burst.

#### Code comment — background job

> **Non-STE:** The background worker queue overflow alert suppression rule runs on the staging cluster.
>
> **STE:** The alert suppression rule on the overflow of the background worker queue runs on the staging cluster.

```python
def install_alert_rule(cluster: str) -> None:
    rule = AlertSuppressionRule(on=OverflowOf(WorkerQueue(background=True)))
    deploy(rule, cluster="staging")
```

### See also

- Rule 2.2 — write a long noun in full, then shorten it.
- Rule 2.3 — hyphenate a related pair, but do not chain more than three words.
- Rule 1.5 — what counts as a technical noun in code documentation.
- Rule 1.3 — use approved words with their approved meanings.

---

## Rule 2.2 — Write Long Technical Nouns in Full

> Source: ASD-STE100 Issue 9, Rule 2.2

### Rule

When a technical code noun has more than three words, write it in full. Then use
one of these methods to make it clear:

- Give a shorter form of the technical code noun.
- Use hyphens (`-`) between words that you use as one unit (see Rule 2.3).
- Use prepositions (`of`, `on`, `in`, `for`, `to`) to split the long noun into
  short parts (see Rule 2.1).

A long multi-word code noun can be one long technical noun or a combination of
shorter ones. Often you cannot divide it, because it is the approved term of
your company, framework, or subject field. In that case, write it as it is, in
its approved form.

### Method 1 — Shorter form of technical code nouns

If a long technical code noun comes from an official code document (an API
specification, a schema, an OpenAPI file, or an architecture diagram), write it
in full the first time it occurs. Explain it if possible, then use a shorter
form or an approved abbreviation in the rest of the document.

> **STE:** Before you do this procedure, initialize the user session cache
> invalidation lock handler (the handler that locks the cache of the user
> session, referred to in this procedure as the "invalidation lock handler").

The short form "invalidation lock handler" has three words and obeys Rule 2.1.

```python
def initialize_session_lock(user_id: str) -> None:
    """Initialize the user session cache invalidation lock handler.

    The invalidation lock handler locks the cache of the user session so that
    a background job cannot read stale data while a write is in flight.
    """
    handler = UserSessionCacheInvalidationLockHandler(user_id)
    handler.engage()   # from here, the "invalidation lock handler"
```

Abbreviations defined on first use work the same way:

> **STE:** The Main Form Validation Module (MFVM) is a TypeScript module that
> includes a Main Export Controller Unit (MECU) and a Data Bridge (DB). The
> MFVM operates in the form submission system. Its function is to validate and
> submit the form data from the Main Form Provider (MFP) to the data stores and
> the validation hooks. The Dynamic Config Unit (DECU) sends events to operate
> the MFVM.

```typescript
// Abbreviation defined on first use, then reused
interface FormPayload { fields: Record<string, unknown>; }

class MainFormValidationModule {       // MFVM
  constructor(
    private readonly exportController: MainExportControllerUnit,  // MECU
    private readonly bridge: DataBridge,                          // DB
    private readonly config: DynamicConfigUnit,                   // DECU
  ) {}

  submit(payload: FormPayload): void {
    this.config.onEvent("submit", () => this.exportController.run(payload));
  }
}
```

If an approved technical code noun has three words or fewer, you do not need an
abbreviation. Do not fill a procedure with letter codes.

| Do not write: | WRITE: |
|---|---|
| The primary parts of the controller are: - The DTA (8) - The PVA (15) - The BA (17) - The VB (20). | A. Remove the data transformer assembly (8) from the view body (20). B. Remove the pipeline validator assembly (15) from its seat. C. Remove the buffer assembly (17) from the view body (20). |
| A. Remove the DTA (8) from the VB (20). B. Remove the PVA (15) from its seat. C. Remove the BA (17) from the VB (20). | A. Remove the data transformer assembly (8) from the view body (20). B. Remove the pipeline validator assembly (15) from its seat. C. Remove the buffer assembly (17) from the view body (20). |

```yaml
# STE-Code: name each part in full; do not pack the parts into letter codes
controller:
  data_transformer_assembly:   # (8)  part of the view body
  pipeline_validator_assembly: # (15) sits on its seat
  buffer_assembly:             # (17) part of the view body

# Non-STE (do not write this):
#   parts: [DTA_8, PVA_15, BA_17, VB_20]
```

```python
def disassemble_controller(view_body, validator_seat):
    view_body.remove(data_transformer_assembly)         # (8)
    validator_seat.remove(pipeline_validator_assembly)  # (15)
    view_body.remove(buffer_assembly)                   # (17)
```

### Method 2 — Use prepositions to break up a long noun

When a long technical code noun is a chain of short nouns, make the main noun
the head of the sentence and attach the rest with `of`, `on`, `in`, `for`, or
`to`.

> **Non-STE:** Configure the user authentication token refresh failure retry policy before you deploy the service to production.
>
> **STE:** Set the retry policy for the failure of the refresh of the user authentication token before you deploy the service to production.

> **Non-STE:** Install the background worker queue overflow alert suppression rule on the staging cluster.
>
> **STE:** Install the alert suppression rule on the overflow of the background worker queue on the staging cluster.

> **Non-STE:** Remove the database connection pool exhaustion recovery timeout configuration parameter from the settings file.
>
> **STE:** Remove the configuration parameter that sets the recovery timeout for the exhaustion of the database connection pool from the settings file.

> **Non-STE:** Update the build script to obtain output directory naming consistency with the package convention.
>
> **STE:** Update the build script until the output directory naming is consistent with the package convention.

```python
def set_recovery_timeout(pool, seconds: float) -> None:
    """Set the configuration parameter that sets the recovery timeout
    for the exhaustion of the database connection pool."""
    pool.config["recovery_timeout_seconds"] = seconds
```

### Method 3 — Hyphenate words that you use as one unit

When two or more words act as a single modifier before a noun, hyphenate them:
`request-response`, `read-write`, `build-time`, `out-of-band`, `end-to-end`,
`run-time`. Do not hyphenate when the first word is an adverb ending in `-ly`
("a publicly documented API" stays open).

> **Non-STE:** Set the request response mapping handler to the new schema before the migration.
>
> **STE:** Set the request-response mapping handler to the new schema before the migration.

> **Non-STE:** Run the build time configuration check after you compile the module.
>
> **STE:** Run the build-time configuration check after you compile the module.

> **Non-STE:** Add an end to end test for the payment flow before you merge the change.
>
> **STE:** Add an end-to-end test for the payment flow before you merge the change.

> **Non-STE:** Use the out of band signal to stop the long running job.
>
> **STE:** Use the out-of-band signal to stop the long-running job.

```python
def handle_request_response(handler: "RequestResponseMappingHandler") -> None:
    """Set the request-response mapping handler to the new schema."""
    handler.apply(schema=SCHEMA_V2)

def run_build_time_check() -> None:
    """Run the build-time configuration check after you compile the module."""
    ...
```

Note: hyphenation groups words into one unit but does not make a long technical
noun short. If the hyphenated unit still has more than three words, write it in
full the first time, then use the shorter form.

### Expanded documentation pairs

> **Non-STE:** The USCIlh must run before the shutdown hook releases the cache. If the USCIlh fails, the stale session remains.
>
> **STE:** Initialize the user session cache invalidation lock handler (the handler that locks the cache of the user session; in this procedure, the "invalidation lock handler"). Run the invalidation lock handler before the shutdown hook releases the cache. If the invalidation lock handler fails, the stale session remains.

```python
class UserSessionCacheInvalidationLockHandler:
    def engage(self) -> None: ...
    def release(self) -> None: ...

def shutdown_hook(session_id: str) -> None:
    handler = UserSessionCacheInvalidationLockHandler(session_id)
    handler.engage()          # invalidation lock handler
    if not handler.release():
        raise StaleSessionError(session_id)
```

> **Non-STE:** The MFVM uses the MECU and the DB. The DECU sends events to the MFVM so that the MFVM can get data from the MFP.
>
> **STE:** The Main Form Validation Module (MFVM) is a TypeScript module that includes a Main Export Controller Unit (MECU) and a Data Bridge (DB). The Dynamic Config Unit (DECU) sends events to operate the MFVM, and the MFVM gets form data from the Main Form Provider (MFP).

```typescript
const mfvm = new MainFormValidationModule(     // MFVM
  mecu,  // Main Export Controller Unit
  db,    // Data Bridge
  decu,  // Dynamic Config Unit
);
decu.onEvent("submit", () => mfvm.submit(mfp.getData()));  // MFP = Main Form Provider
```

> **Non-STE:** Call the DTA to configure the MFVM before you run the build, then check the MFVM output for errors.
>
> **STE:** Use the data transformer adapter to set up the main form validation module before you run the build. Then check the output of the main form validation module for errors.

```bash
make configure MODULE=data-transformer-adapter   # data transformer adapter
make build MODULE=main-form-validation-module    # main form validation module
make test   MODULE=main-form-validation-module && echo "output checked for errors"
```

> **Non-STE:** Update the cross service request tracing correlation identifier generator after the schema change.
>
> **STE:** Update the correlation identifier generator for the tracing of the request across services after the schema change. (On first use, write "cross-service request tracing correlation identifier generator" in full, then use "correlation identifier generator.")

```python
def update_correlation_generator(schema: dict) -> None:
    """Update the cross-service request tracing correlation identifier generator.

    After the first use, this component is the correlation identifier generator.
    """
    CorrelationIdentifierGenerator.for_request_tracing().apply(schema)
```

> **Non-STE:** The CI pipeline docker image layer cache warming step now runs in parallel.
>
> **STE:** The cache warming step for the layer of the Docker image of the CI pipeline now runs in parallel. (On first use, write the full name, then use "cache warming step.")

```yaml
jobs:
  warm_cache:   # cache warming step for the layer of the Docker image of the CI pipeline
    runs-on: ubuntu-latest
    strategy:
      matrix:
        layer: [base, deps, build]
    steps:
      - run: ./scripts/warm-cache.sh "${{ matrix.layer }}"
```

> **Non-STE:** Document the legacy database migration rollback failure notification webhook endpoint in the runbook.
>
> **STE:** Document the webhook endpoint for the notification of the failure of the rollback of the legacy database migration in the runbook. (On first use, write the full name, then use "notification webhook endpoint.")

### Procedure

1. Find the long technical code noun (more than three words) in your sentence.
2. Write it in full the first time it occurs. If it comes from an official
   source (API spec, schema, architecture diagram), keep the approved form.
3. Give a shorter form or an approved abbreviation right after the full form,
   in parentheses.
4. In the rest of the document, use only the shorter form or the abbreviation.
5. If the noun is a chain of short nouns, split it with prepositions (Rule 2.1).
6. If two or more words act as one modifier, hyphenate them (Rule 2.3).
7. Do not fill a procedure with abbreviations. A short, clear noun is better
   than a string of letters.

### See also

- Rule 2.1 — keep technical nouns to three words or fewer.
- Rule 2.3 — hyphens between words used as one unit.
- Rule 1.5 — technical noun categories and your company glossary.
- Rule 1.3 — approved words: use, set, get, make, show, check, remove, send, start, stop.

---

## Rule 2.3 — Use Hyphens Between Words Used as One Unit

> Source: ASD-STE100 Issue 9, Rule 2.3

### Rule

A hyphen connects words or parts of words. Use hyphens between words to show
that related words operate as one unit. This makes multi-word code nouns agree
with Rule 2.1: a hyphenated group always counts as one word, so it fills only
one of the three word slots.

Constraints:

- Do not connect words that are not related. The hyphen changes the meaning of
  the multi-word code noun. If you are not sure, explain the noun in the
  clearest way, then use a shorter form, an approved verb (`get`, `set`, `make`,
  `start`), or an official abbreviation from your glossary.
- If an approved technical code noun already includes hyphens — `input-output
  stream`, `thread-safe queue`, `backward-compatible API` — do not change it.
  If it is too long, write it in full the first time, then use the short form.
- Do not hyphenate groups of more than three words. Split longer chains with
  prepositions such as `of`, `on`, or `in`.
- If an approved technical code noun has three words or fewer, hyphens are not
  necessary.

### Examples

| Example | Note |
|---|---|
| Make sure that the fail-safe shutdown-handler connection is safe. | 3 words |
| Inspection of the request rate-limit device. | 3 words |
| The thread-safe queue keeps the order of the write operations. | 3 words |
| Remove the backward-compatible API client before you make the change. | 3 words |

#### Hyphenate the related pair only

> **Non-STE:** Move the `main-feature-flag-rollback-handler` trigger to start the test run. (four words joined as one unit — not correct)
>
> **STE:** Move the `main-feature-flag` rollback-handler trigger to start the test run. (3 units: main-feature-flag / rollback-handler / trigger)

```bash
# The hyphen joins the related pair only
make test trigger=rollback-handler flag=main-feature-flag
```

```python
def move_trigger(main_feature_flag: str, rollback_handler: str) -> None:
    """Move the main-feature-flag rollback-handler trigger to start the test run."""
    trigger = f"{main_feature_flag}:{rollback_handler}"
    start_test_run(trigger)
```

#### Do not hyphenate a three-word approved technical noun

> **Non-STE:** A. Remove the `data-adapter` assembly (8) from the view body (20). B. Remove the `pipeline-validator` assembly (15) from its seat.
>
> **STE:** A. Remove the `data adapter` assembly (8) from the view body (20). B. Remove the `pipeline validator` assembly (15) from its seat.

```python
def remove_assembly(name: str, part_id: int) -> None:
    """Remove the data adapter assembly (part_id) from the view body."""
    detach(name, part_id)
    log(f"removed {name} assembly {part_id}")

remove_assembly("data adapter", 8)
remove_assembly("pipeline validator", 15)
```

#### Keep a hyphen that the official name already has

> **Non-STE:** The `input output stream` is part of the logging system.
>
> **STE:** The `input-output stream` is part of the logging system.

```python
class LoggingSystem:
    def __init__(self, stream: "InputOutputStream") -> None:
        # The input-output stream is part of the logging system.
        self.stream = stream

    def write(self, message: str) -> None:
        self.stream.push(message)
```

```yaml
logging:
  # The input-output stream is part of the logging system.
  input-output-stream:
    buffer-size: 4096
    flush-on-error: true
```

### See also

- Rule 2.1 — the three-word limit that hyphenated units help you meet.
- Rule 2.2 — write a long noun in full, then use the short form.
- Rule 1.5 — where hyphenated code terms such as `thread-safe queue` and
  `backward-compatible API` are defined.
- Rule 1.3 — pair hyphenated nouns with short approved verbs.

---

## Section 2 quick reference for LLM generation

When you generate code documentation, apply these checks to every noun phrase:

1. Count the words in the noun phrase. Hyphenated units count as one word.
   More than three? Apply Rule 2.1 or Rule 2.2.
2. Is it a stacked chain? Split it with `of`, `on`, `in`, `for`, `to`, with the
   head noun first.
3. Is it an official approved term? Keep its exact form, including its hyphens.
   Write it in full on first use, then use the short form or abbreviation.
4. Do two adjacent words act as one modifier? Hyphenate them — but never
   hyphenate more than three words, and never after an `-ly` adverb.
5. Is the verb approved? Use `set`, `get`, `make`, `show`, `check`, `remove`,
   `send`, `start`, `stop`, `use`, `update`.
6. Never merge a noun chain into one identifier-like word in prose
   (`useraccountprofileavatarimagestoragebucketpolicyupdate`). Prose names the
   parts; code identifiers stay short and nested.



## rules-sec3.md

# Level 5 — Section 3: Verbs

Scope: Rules 3.1 to 3.7 of STE-Code. These rules control which verbs you use,
which forms of those verbs are legal, and how you build a sentence around them.
Source: ASD-STE100 Issue 9, Part 1, Section 3, adapted to the code domain.

Section contract, in one block:

```
Approved verbs      -> only the verbs in the STE-Code dictionary
Approved forms      -> base, third-person singular, simple past, past participle
Approved tenses     -> infinitive, imperative, simple present, simple past,
                       simple future ("will" + base)
Past participle     -> adjective only
Forbidden           -> perfect, progressive, perfect progressive, passive with
                       auxiliaries, gerund used as a verb
Voice               -> active; passive only when the agent is unknown
Action words        -> verbs, not nominalizations
```

Rule index:

| Rule | Statement |
|---|---|
| 3.1 | Use only the verb forms that the dictionary gives. |
| 3.2 | Use only these verb forms and tenses of verbs. |
| 3.3 | Use the past participle form as an adjective. |
| 3.4 | Do not use auxiliary verbs to make complex verb constructions. |
| 3.5 | Use the "-ing" form only as a technical noun or as a modifier in one. |
| 3.6 | Use the active voice. |
| 3.7 | Use an approved verb to describe an action, not a noun. |

The four approved verb categories (all rules in this section draw from them):

| Category | Verbs |
|---|---|
| Development operations | build, compile, test, lint, format, commit, push, deploy, rollback |
| Data operations | read, write, serialize, deserialize, parse, encode, decode, query, insert, migrate |
| Application operations | handle, route, authenticate, authorize, validate, schedule, dispatch, resolve |
| Communication operations | send, receive, publish, subscribe, stream, poll, broadcast, connect |

---

## Rule 3.1 — Use only the verb forms that the dictionary gives

Source: ASD-STE100 Issue 9, Rule 3.1 (master.md#sec3-rule3.1).

Every approved verb appears in the STE-Code dictionary with exactly four forms,
in this order. If a form is not on one of those four lines, the form is not
approved.

```
VALIDATE (v)        WRITE (v)
VALIDATES           WRITES
VALIDATED,          WROTE,
VALIDATED           WRITTEN
```

How to read an entry:

| Line | Form | WRITE | Where you use it |
|---|---|---|---|
| 1 | Base form (infinitive and imperative) | WRITE | "Write the log." / "to write the log" |
| 2 | Third-person singular, simple present | WRITES | "The logger writes the record." |
| 3 | Simple past | WROTE | "The job wrote the record." |
| 4 | Past participle (as an adjective) | WRITTEN | "the written log" |

The simple future has no line of its own. You make it with "will" plus the base
form: "will write".

Procedure:

1. Find the verb in the STE-Code dictionary.
2. If the verb is not there, do not use it. Use the approved verb instead:
   make (not generate), get (not retrieve), check (not verify), use (not
   utilize), start (not initiate), stop (not terminate), remove (not delete),
   show (not render), do (not execute), keep (not maintain).
3. If the verb is there, use one of the four listed forms only.
4. Do not derive a new form. "Parsing", "parseable", and "parser" are not verb
   forms of PARSE. A noun such as "parser" is approved only when the dictionary
   or a technical noun category gives it.
5. Use the past participle only as an adjective ("the parsed manifest"). Do not
   pair it with "have", "has", "had", or "get" to make a verb.

Examples:

| Non-STE | STE | Why |
|---|---|---|
| The linter validates the file and is reporting the errors to the terminal. | The linter validates the file. It reports the errors to the terminal. | "is reporting" is not a listed form of REPORT. |
| The script has written the output to the log before the test starts. | The script wrote the output to the log. Then the test starts. | Present perfect is not a listed form. |
| The service utilizes a token cache and leverages the parser for each request. | The service uses a token cache. The service parses each request. | "utilize" and "leverage" are not in the dictionary. |
| The parsing of the manifest is done by the loader, and the validating of the schema comes after. | The loader parses the manifest. Then the loader validates the schema. | Gerunds are not listed forms. Name the actor. |
| The migration had deleted the deprecated column and was terminating the open connections. | The migration removed the deprecated column. Then the migration stopped the open connections. | "delete" and "terminate" are unapproved; past perfect and progressive are unapproved. |
| The client will be receiving the streamed records after the broker has been publishing them for one minute. | The broker publishes the records. The client will receive the streamed records after one minute. | Future progressive and perfect progressive are unapproved. "Streamed" is a participle adjective, so it stays. |
| The given options get validated by the gateway, and the removed entries are gotten from the cache. | The gateway validates the given options. The gateway gets the removed entries from the cache. | "get validated" and "are gotten" are unapproved. "Given" and "removed" are participle adjectives. |

```python
# STE: the loader parses the manifest. Then the loader validates the schema.
manifest = loader.parse(path)      # parse -> parses / parsed / parsed
loader.validate(manifest, schema)  # validate -> validates / validated / validated
```

Note (structural carryover): the four-line dictionary layout is a structural
feature of the source standard. The code-domain version keeps the layout with
code verbs. No mapping is forced.

See also: Rules 3.2, 3.3, 3.4, 1.1, 1.5, and the STE-Code dictionary.

---

## Rule 3.2 — Use only these verb forms and tenses of verbs

Source: ASD-STE100 Issue 9, Rule 3.2 (master.md#sec3-rule3.2).

Approved forms and tenses, and nothing else:

- The infinitive form
- The imperative form (command form)
- The simple present tense
- The simple past tense
- The simple future tense
- The past participle form (as an adjective)

| Infinitive | Imperative | Simple present | Simple past | Simple future | Past participle (adj) |
|---|---|---|---|---|---|
| (to) parse (regular) | Parse + object | you/we/they parse; it parses | you/we/they parsed; it parsed | will parse | the parsed file |
| (to) write (irregular) | Write + object | you/we/they write; it writes | you/we/they wrote; it wrote | will write | the written log |
| (to) build (irregular) | Build + object | you/we/they build; it builds | you/we/they built; it built | will build | the built artifact |
| (to) send (irregular) | Send + object | you/we/they send; it sends | you/we/they sent; it sent | will send | the sent request |
| (to) validate (regular) | Validate + object | you/we/they validate; it validates | you/we/they validated; it validated | will validate | the validated token |

Not approved:

- Present perfect (have/has parsed)
- Past perfect (had parsed)
- Present/past progressive (is/was parsing)
- Future progressive (will be parsing)
- Perfect progressive (has been parsing, had been parsing)
- The gerund used as a verb with an auxiliary (is parsing, keeps parsing)
- All other complex verb constructions

How to select the correct form:

1. Infinitive — after a modal verb or to state a purpose: "Use this flag to parse the file."
2. Imperative — for each step of a procedure: "Parse the file. Write the log."
3. Simple present — a general fact, a repeated action, or system behavior: "The parser reads the file."
4. Simple past — a complete action: "The build failed."
5. Simple future — "will" plus the base form: "The job will start at 02:00."
6. Past participle — as an adjective before a noun only: "the parsed file".

How to correct an unapproved form:

| Unapproved | Fix |
|---|---|
| has parsed (present perfect) | simple past: parsed |
| had parsed (past perfect) | two sentences in the simple past, joined by "Then" |
| is/was parsing (progressive) | simple present or simple past; if two actions overlap, write two sentences and add "at the same time" |
| will be parsing (future progressive) | simple future: will parse |
| is being parsed (passive with auxiliary) | name the actor, use the active voice (Rule 3.6) |

Examples:

| Non-STE | STE | Fix applied |
|---|---|---|
| The linter has found three errors in the source file. | The linter found three errors in the source file. | present perfect -> simple past |
| The server was processing the request when the timeout occurred. | The server processed the request. Then the timeout occurred. | past progressive -> two sentences |
| The framework had already initialized the connection pool before the query started. | The framework made the connection pool. Then the query started. | past perfect -> simple past; "make" replaces "initialize" |
| The scheduler is deploying the build to production while the tests are running. | The scheduler sends the build to production. The tests run at the same time. | progressive -> simple present, twice |
| The cache has been keeping the serialized records since the service started, and the client will be reading them after the restart. | The cache keeps the serialized records. The client will read the records after the restart. | perfect progressive and future progressive removed |
| To be parsing the configuration file, the loader must be having read access to the directory. | To parse the configuration file, the loader must have read access to the directory. | infinitive and base form after the modal |
| You should be setting the timeout value and then you will be restarting the service. | Set the timeout value. Then start the service again. | imperative for each step |
| The payload is being validated by the gateway and the deprecated field gets removed by the migration. | The gateway validates the payload. The migration removes the deprecated field. | passive progressive -> active simple present |
| The written log and the parsed manifest are showing that the build had completed with the given options. | The written log and the parsed manifest show that the build completed with the given options. | participle adjectives kept; progressive and past perfect removed |
| We have been building the release artifact and the CI pipeline will have run the tests by the time you review the pull request. | We built the release artifact. The CI pipeline will run the tests. Then you can review the pull request. | perfect progressive and future perfect removed |
| If the connection drops, the client is retrying the request until the server responds. | If the connection drops, the client retries the request. Then the server responds. | progressive -> simple present |

```yaml
# .github/workflows/ci.yml
# STE: we built the release artifact. The CI pipeline will run the tests.
jobs:
  build:
    steps:
      - run: make release
  test:
    needs: build
    steps:
      - run: make test
```

```python
# STE: the server processed the request. Then the timeout occurred.
try:
    response = server.process(request)   # process -> processes / processed / processed
except TimeoutError:
    log.write("request timeout after 30 s")
```

Note (structural carryover): the six-column table of verb forms is a structural
feature of the source standard, kept here with approved code verbs.

See also: Rules 3.1, 3.3, 3.4, 3.5, 3.6, 1.1, and the STE-Code dictionary.

---

## Rule 3.3 — Use the past participle form as an adjective

Source: ASD-STE100 Issue 9, Rule 3.3 (master.md#sec3-rule3.3).

A past participle used as an adjective shows the condition of something. This is
not passive voice. Use it:

- Before a noun
- After a form of "to be", "to become", or "to stay"

Do not use a past participle that the STE-Code dictionary does not give. Some
approved adjectives are past participles of verbs that are themselves not
approved; the dictionary marks them "(adj)" and you may use them.

How to tell adjective from passive voice:

1. The word gives the condition of the thing, not an action that an actor does.
2. You can put it directly before the noun: "the parsed file", "the deprecated method", "the closed connection".
3. You can put it after "is", "becomes", or "stays": "the cache is initialized", "the endpoint becomes deprecated", "the record stays locked".
4. If the sentence names an actor and an action ("the file was parsed by the loader"), it is passive voice. Write the active voice instead (Rule 3.6).

Approved code-domain participle adjectives:

| Past participle (adj) | Example noun phrase | Condition that it shows |
|---|---|---|
| parsed | the parsed manifest | The parser read the file. |
| serialized | the serialized record | The record is in a transport format. |
| deserialized | the deserialized object | The object is in memory again. |
| initialized | the initialized cache | The cache is ready for use. |
| deprecated | the deprecated method | The method is old. Do not use it. |
| allowed | the allowed memory | The limit that the configuration gives. |
| corrupted | the corrupted index | The data is not correct. |
| locked | the locked row | Another transaction holds the row. |
| written | the written log | The log file is on disk. |
| given | the given options | The options that the caller sends. |
| built | the built artifact | The build made the artifact. |
| signed | the signed token | The token has a valid signature. |

Cautions:

- Do not make a new past participle from an unapproved verb. Write "the removed branch", not "the deleted branch", unless the dictionary gives "delete" or "deleted (adj)".
- Do not use a past participle as a verb with "have", "has", or "had" (Rule 3.2).
- Do not stack more than one past participle before the same noun. If "the parsed and validated payload" becomes difficult, write two short sentences.
- Prefer the plain word: "started" not "commenced", "used" not "utilized" or "leveraged", "stopped" not "terminated".

Correct uses:

- "Inspect all fields of the deserialized object for corruption." ("deserialized" before a noun)
- "When the cache is fully initialized, start the worker threads." ("initialized" after "to be")
- "Do not exceed the allowed memory for the buffer." ("allowed" is an approved adjective)
- "Make sure that the input values are not corrupted." ("corrupted" is an approved adjective)

Corrections:

| Non-STE | STE |
|---|---|
| The parsed file was processed by the loader. | The parsed file is ready for the loader. |
| The method has been deprecated by the API team in release 4.2. | The method is deprecated in release 4.2. Do not use the deprecated method in new code. |
| After the record gets locked, the transaction which was started earlier is being committed. | The transaction writes the locked record. Then the transaction ends. |
| The signed token which had been given to the client is validated by the gateway on each request. | The gateway validates the signed token on each request. |
| When the index becomes corrupted it will have to be being rebuilt by the maintenance job. | When the index becomes corrupted, the maintenance job makes the index again. |
| The build artifact stays uncompiled until the pipeline has compiled the modified sources. | The artifact stays unbuilt until the pipeline builds the modified sources. |
| The user is shown a warning if the uploaded configuration file was found to be malformed. | The CLI shows a warning if the uploaded configuration file is malformed. |
| All of the returned records had already been serialized before the response was sent. | The API sends the serialized records in the response. |
| Make sure that the written log and the given options are not being modified by the plugin. | Make sure that the plugin does not change the written log or the given options. |

```go
// STE: "initialized" comes after "is" and gives the condition of the cache.
if cache.IsInitialized() {
    pool.Start(workerCount)
}
```

```sql
-- STE: the transaction writes the locked record. Then the transaction ends.
BEGIN;
SELECT * FROM orders WHERE id = 42 FOR UPDATE;  -- the locked row
UPDATE orders SET status = 'sent' WHERE id = 42;
COMMIT;
```

Note (structural carryover): the source rule uses hardware conditions to show the
grammar. The code-domain version keeps the grammar and gives software conditions.

See also: Rules 3.1, 3.2, 3.4, 3.5, 3.6, 1.1, and the dictionary adjectives "(adj)".

---

## Rule 3.4 — Do not use auxiliary verbs to make complex verb constructions

Source: ASD-STE100 Issue 9, Rule 3.4 (master.md#sec3-rule3.4).

Do not combine an auxiliary verb ("have", "be", "will", "can", "must", "should",
"is to be") with a past participle to build a compound tense or the passive
voice. These constructions make verb forms that STE-Code does not approve.

Conversion table:

| Construction | Replace with |
|---|---|
| have/has/had + past participle (perfect) | the simple past |
| be + past participle (passive) | the active voice with a named agent (Rule 3.6) |
| is to be + past participle | the imperative (command) form |
| can be + past participle | "you can" + base verb, when the reader is the agent |
| will be + past participle + by + agent | agent + "will" + base verb |

When a compound construction seems unavoidable, split it into separate simple
sentences. Rule 3.2 lists the only approved forms: infinitive, imperative,
simple present, simple past, simple future, and past participle as an adjective.

Examples:

| Non-STE | STE | Fix applied |
|---|---|---|
| The build has compiled the module before the test runs. | The build compiled the module. Then the test runs. | present perfect -> simple past |
| The migration is to be run before you deploy the service. | Before you deploy the service, run the migration. | "is to be" -> imperative |
| The cache can be cleared. | You can clear the cache. | "can be" -> "you can" + base verb |
| The timeout must be set before the job starts. | Set the timeout before the job starts. | "must be" -> imperative |
| The report will be generated by the scheduler. | The scheduler will generate the report. | agent to subject, keep "will" |
| The connection pool has been created before the first query is sent. | The connection pool was created. Then the first query is sent. | present perfect passive -> simple past |
| The configuration file must be validated before the server starts. | Validate the configuration file before the server starts. | imperative for a procedure |
| The user credentials are to be encrypted at rest and the key is rotated monthly. | Encrypt the user credentials at rest. Rotate the key every month. | two imperatives |
| The log entries can be exported to a CSV file by the admin. | The admin can export the log entries to a CSV file. | name the agent, keep the modal |
| An error message will be shown by the validator if the input is empty. | The validator will show an error message if the input is empty. | agent to subject |
| The temporary files had been deleted by the cleanup task before the backup started. | The cleanup task deleted the temporary files. Then the backup started. | past perfect passive -> simple past, sequence with "Then" |

See also: Rules 3.2, 3.3, 3.5, 3.6.

---

## Rule 3.5 — Use the "-ing" form only as a technical noun or as a modifier in a technical noun

Source: ASD-STE100 Issue 9, Rule 3.5 (master.md#sec3-rule3.5).

An "-ing" word can be a verb part, an adjective, a noun, or the head of a long
modifier group. That range causes ambiguity and long sentences. In STE-Code the
"-ing" form is not permitted as a verb.

Approved "-ing" words in STE-Code:

| Part of speech | Words |
|---|---|
| Nouns | logging, monitoring, routing, servicing |
| Adjectives | matching, missing, remaining |
| Pronoun | something |
| Preposition | during |

Why the progressive is not approved: Rule 3.2 permits only the infinitive, the
imperative, the simple present, the simple past, the simple future, and the past
participle as an adjective. The progressive ("is running", "are deploying", "was
processing") is not on that list, and the "-ing" form lives inside it. The
"-ing" form also hides auxiliary-verb constructions that Rule 3.4 forbids: write
"The service starts. Then it logs the request", not "the service is starting and
then it is logging the request".

Approved "-ing" technical nouns (section and document titles):

- Logging
- Monitoring
- Testing and Fault Isolation
- Handling
- Packaging
- Shipping
- Troubleshooting
- Building
- Deployment

Approved "-ing" modifiers inside technical nouns:

- logging service
- monitoring agent
- routing table
- switching relay
- caching layer
- building pipeline
- binding configuration
- streaming endpoint
- rendering engine

Do not pull the "-ing" word out of the technical noun and use it as a verb. "The
caching layer stores the result" is approved. "The layer is caching the result"
is not.

Examples:

| Non-STE | STE | Fix applied |
|---|---|---|
| When you are running this script, obey all the safety checks. | When you run this script, obey all the safety checks. | progressive -> simple present |
| Be careful while the process is starting. | Be careful while the process starts. | progressive -> simple present |
| While the deployment is starting, you must watch the logs and you must not stop the process because stopping it during startup can corrupt the state file. | The deployment starts. While it starts, watch the logs. Do not stop the deployment. If you stop the deployment during startup, the state file can become corrupt. | progressive and gerund clause -> short sentences |
| The background worker is processing the queue and it is writing the results to the cache while the main thread is waiting for the response, causing the request to time out and the user to see an error. | The background worker processes the queue. It writes the results to the cache. The main thread waits for the response. If the main thread waits too long, the request times out and the user sees an error. | three progressives and a cause clause split apart |
| The function is returning the value while the cache is loading the entry, which makes the result incorrect during the first request. | The function returns the value. The cache loads the entry. During the first request, the result is incorrect. | progressive -> simple present |
| The matching algorithm is comparing the remaining items during the iteration and it is removing the missing records from the list. | The matching algorithm compares the remaining items during the iteration. It removes the missing records from the list. | approved adjectives kept; progressive verbs removed |
| Something going wrong during the migration can make the database stay in a broken state. | If something goes wrong during the migration, the database can stay in a broken state. | "something" kept; gerund verb -> simple present |

Long "-ing" subjects become vertical lists:

> **Non-STE:** A script opening a socket without checking the firewall rules and
> sending data to an unknown host, using an unverified certificate without
> reading the security policy, is in danger of causing a breach and thus
> exposing private keys and credentials.
>
> **STE:** Before you open a socket, obey these precautions: (1) Read the
> security policy. (2) Make sure that the firewall rules allow the connection.
> (3) Verify the host certificate. (4) Get the correct credentials to send data
> to the host. If you do not obey these precautions, a breach of private keys
> and credentials can occur.

> **Non-STE:** Developers committing code without running the test suite and
> pushing directly to the main branch, ignoring the review policy, risk breaking
> the build and therefore blocking the release for all team members.
>
> **STE:** Before you commit code, obey these precautions: (1) Run the test
> suite. (2) Make sure that the tests pass. (3) Open a review before you merge to
> the main branch. If you do not obey these precautions, you can break the build
> and block the release for all team members.

See also: Rules 3.2, 3.4, 1.5.



## rules-sec4.md

---

## Rule 4.5 — Use an Article or a Demonstrative Adjective Before a Noun

**Source:** Adapted from ASD-STE100 Issue 9, Rule 4.5.

### Requirement

Articles (**the**, **a**, **an**) and demonstrative adjectives (**this**, **these**) show
the position of nouns and multi-word nouns in the sentence. Use them correctly; do not
omit them to make the text shorter.

- Do not use an article in a general statement or before an abstract concept
  (performance, scalability, error handling, concurrency, backward compatibility).
- In short sentences, use an article before each noun.
- In a long series of items, use the article only before the first noun. Repeat it
  before each item when an adjective applies to only one item (to avoid ambiguity).
- Do not use a definite article before a noun when a code identifier follows it —
  the identifier is a proper noun (function, class, variable, file, environment
  variable, error code, version tag).
- Use a demonstrative adjective (**this**, **these**) to connect a noun to the topic
  of the previous sentence. Always keep the noun after it; do not write "this"/"these" alone.

### Code-domain examples

Article before a noun in a short instruction:

> **Non-STE:** Call callback function. Pass response object to handler and set retry flag.
> **STE:** Call the callback function. Pass the response object to the handler. Then set the retry flag.

API reference sentence:

> **Non-STE:** Method reads configuration file and returns settings object.
> **STE:** The `load` method reads the configuration file and returns the settings object.

No article in a general statement; "the" for a specific item:

> **Non-STE:** The error handling is important for the production applications. A function throws the error when the input is not valid.
> **STE:** Error handling is important for production applications. The function throws an error when input is not valid.

Article only before the first noun in a long series:

> **STE:** Delete the temporary files, log files, cache entries, and lock files before you start the build.

Article before each noun when an adjective applies to only one item:

> **STE:** Register the new event listeners, the timers, the subscriptions, and the cleanup callbacks. (Only the event listeners are new.)

No article before a noun with a code identifier (proper noun):

> **Non-STE:** Call the function `validateInput` before you send the request.
> **STE:** Call function `validateInput` before you send the request.  — or —  Call the `validateInput` function before you send the request.
> **STE:** Configure module `AuthService` in the container.  /  Set variable `LOG_LEVEL` to `debug`.  /  Error `ERR_TIMEOUT_1042` shows in the console log.  /  Install version 3.2.1 of the package.

Demonstrative adjective for sentence linking:

> **Non-STE:** The function returns a configuration object. Configuration object has three fields: host, port, and timeout.
> **STE:** The function returns a configuration object. This object has three fields: `host`, `port`, and `timeout`.

Article use in commit messages and release notes:

> **STE:** Fix the race condition in the scheduler. The worker pool now waits for the queue to become empty.
> **STE:** Adds retry logic to the `HttpClient` class. Removes deprecated method `sendSync`.

Article use in an error message and a test description:

> **STE:** The input is not valid. The `name` field must be a string.
> **STE:** The test checks that the handler returns the status code 404 when the record is not in the database.

### Paradigm-specific guidance

- **Object-Oriented:** use an article to separate a class (type) from an instance (value) — "The `ConnectionPool` class manages a pool of database connections. Each instance keeps a list of open connections." No article directly before a bare identifier: "Call `connect`."
- **Functional:** separate a type constructor from a value — "The `Ok(value)` pattern shows a successful result. A `Result` value is either `Ok` or `Err`." Write concepts (immutability, referential transparency) with no article.
- **Procedural (C, Go, Bash):** separate a pointer from the value at the address — "The function receives a pointer to a buffer. The buffer must hold at least 512 bytes."
- **Declarative (SQL, Terraform, YAML, Kubernetes):** separate a resource type from an instance — "A `Deployment` resource manages a set of pods. The `web` deployment runs three replicas." No article before a named resource: "Apply manifest `web-deployment.yaml`."
- **Systems (Rust, C memory, embedded):** make ownership/lifetime clear — "The pointer must point to an initialized region of memory. A borrow of the value must not outlive the owner."

### Edge cases

- **Identifier vs concept:** `ConnectionPool` alone is a proper noun (no article). "The `ConnectionPool` class" takes "the" (noun is "class"). "Call `initialize`" no article; "The `initialize` function" takes "the".
- **"a" vs "an":** use "an" before a vowel sound (an SQL query, an HTML element, an XML parser, an ID, an API key); "a" before a consonant sound (a URL, a Unix system, a UUID, a JSON payload, a `User` record). Match the usual pronunciation.
- **Headings, titles, table cells, UI labels:** may omit the article; the first sentence below the heading must obey the rule.
- **Product/framework names starting with "The":** `TheMovieDB` is a proper noun; the leading "The" is part of the identifier, not an article.
- **Plural types as a general statement:** "Iterators are lazy in this library" takes no article; "The iterator stops at the end of the sequence" takes "the".
- **Code samples and command lines:** do not add an article inside a code block, command, or log line; the rule applies to prose only.
- **Acronyms:** choose the article for the spoken form — "an API" (ay-pee-eye), not "a API".
- **Uncountable technical nouns:** memory, throughput, latency, state take no indefinite article — "The function allocates memory", not "a memory".

### Grammar notes

- "A" = any instance of a type; "the" = one specific identifiable item; no article = the type or concept as a whole.
- First mention uses "a" ("The method throws a `ValidationError`"); later mentions use "the" ("The `ValidationError` contains a message field").
- Proper-noun exception: a code identifier is a proper noun — no definite article directly before it ("Call `connect`", not "Call the `connect`").
- Demonstrative adjectives keep their noun: "this object", "these headers" — never "this"/"these" alone.
- Multi-word nouns: put the article before the full noun ("the retry policy object"), not inside it.
- Possessive forms replace the article: "its return value" and "the return value of the method" are both correct; not "the its return value".

### Summary checklist

- [ ] Articles and demonstrative adjectives are used correctly and not removed to shorten the text.
- [ ] No article appears before a general statement or an abstract concept.
- [ ] Short sentences use an article before each noun.
- [ ] A long series uses the article only before the first noun, unless an adjective applies to one item only.
- [ ] No definite article appears directly before a code identifier used as a proper noun.
- [ ] "a" and "an" match the spoken sound of the term that follows.
- [ ] Each demonstrative adjective is followed by a noun and refers to one clear topic.

---

## Cross-References

- **Rule 1.1** — Use approved words from the STE-Code dictionary.
- **Rule 1.3** — Use words only with their approved meanings.
- **Rule 1.5** — Technical nouns from an approved category still take an article in prose.
- **Rule 1.6** — Non-approved words are permitted only as technical code nouns.
- **Rule 1.11** — Use one term per concept.
- **Rule 3.1** — Write one topic per sentence (simplify before you connect).
- **Rule 4.1** — One topic per sentence, no abstract text.
- **Rule 4.2** — Do not omit words or use contractions.
- **Rule 4.3** — Vertical lists for complex text.
- **Rule 4.4** — Connecting words and phrases.
- **Rule 4.5** — Articles / demonstrative adjectives before a noun.
- **Rule 5.1** — Active voice in procedural steps.
- **Section 5 (Procedural Writing)** — sentence structure for step-by-step instructions.
- **Section 6 (Descriptive Writing)** — sentence structure for descriptions and explanations.



## rules-sec5.md

# Level 5 — Clarity Rules: Sentences & Instructions (Section 5)

This slice contains STE-Code Section 5, adapted for people who use LLMs to
generate code documentation. It covers five rules about how to write procedural
and descriptive sentences in software docs:

- Rule 5.1 — Short Sentences (Maximum 20 Words)
- Rule 5.2 — One Instruction Per Sentence
- Rule 5.3 — Imperative (Command) Form for Instructions
- Rule 5.4 — Descriptive Statement Before the Command
- Rule 5.5 — Notes Give Information Only, Not Instructions

STE-Code voice: plain, code-domain, command-form instructions. Word-count and
voice rules apply to *procedural text* (steps the reader executes). They do not
apply to code blocks, terminal output, string literals, or identifier names.
Inside backticks, a code token counts as one word regardless of length
(`Result<T, E>` = 1 word, `async fn` = 2 words).

## Rule 5.1 — Short Sentences (Maximum 20 Words)

**Core rule:** Every sentence in code-documentation *procedures* must be 20
words or fewer. Split long procedural sentences into shorter ones. Warnings and
cautions about security, data loss, or stability must also obey the 20-word limit.

**Notes** (supplementary, non-procedural text) may use up to 25 words per
sentence. Code blocks, command output, and string literals inside code fences
are excluded from the count.

### Why
Long sentences in install steps, setup checklists, debugging workflows, and API
usage guides are hard to follow when the reader is typing commands or writing
code while reading.

### Split long sentences with these techniques
1. **At coordinating conjunctions.** Replace "and/but/or" with a period. Start
   the next sentence with a transition: "Then," "After that," "Next."
2. **Extract conditions.** Move an "if X, then Y" clause into its own sentence
   that precedes or follows the main instruction.
3. **Separate action from purpose.** Put the instruction in one sentence, the
   reason/result in the next.
4. **Use lists.** Convert an enumerating sentence into bulleted/numbered items.
   List items are fragments, not sentences, but keep them short.

**Allowed (8 words):** Run the tests and check the output.
**Not allowed (28):** Run the full test suite with coverage enabled and check
the report for untested paths that might indicate gaps in the test plan.
**Allowed:** Run the full test suite with coverage enabled. Then, check the
report for untested code paths.

### Counting rules
- A sentence ends at `.`, `?`, or `!`. A comma does not end a sentence.
- Hyphenated compounds count as one word ("command-line" = 1).
- Numbers, symbols, parentheticals each count as one word: "(2)" = 1, "HTTP/2" = 1.
- Code tokens in backticks count as one word each. Generics/type params stay
  opaque: `pub async fn fetch_user(id: UserId) -> Result<User, Error>` is one word.

### Edge cases
- **Long proper nouns** (e.g. "Amazon Web Services Elastic Kubernetes Service"):
  use the shortest accepted form on first use, define an abbreviation, then use
  the abbreviation. The abbreviation counts as one word.
- **Generated docs** (Javadoc, Sphinx, rustdoc, TypeDoc): apply the limit to the
  *source docstrings/comments* the generator reads. Fix the source, not the output.
  If the source is third-party/legacy, apply the 25-word descriptive limit and
  document the exception in a style guide.
- **Legal text** (license headers, disclaimers): not procedural. Put it in a
  separate NOTE or "Legal" section, not inside a procedure.
- **Multi-line code mid-sentence:** the code block is excluded. The introducing
  and following sentences must each obey the limit independently.

### Worked example
```bash
# Non-STE (27 words): Set the environment variable HTTP_TIMEOUT to the value
# 30000 which represents the maximum number of milliseconds that the client
# will wait for a response from the upstream server.
# STE:
export HTTP_TIMEOUT=30000
# This value is the maximum wait time in milliseconds for a response.
```

### Cross-references
Rule 1.1 (approved words), Rule 1.2 (part of speech), Rule 1.4 (verb forms),
Rule 1.5 (technical nouns), Rule 1.7 (no technical-noun-as-verb), Rule 1.9
(short technical nouns), Rule 1.12 (technical verbs), Rule 5.2 (active voice),
Rule 5.3 (imperative), Rule 5.5 (notes), Rule 5.7 (lists), Section 8 (word count).

## Rule 5.2 — One Instruction Per Sentence

**Core rule:** Write exactly one instruction in each sentence. Use numbered or
bulleted lists to show step sequence. There is no limit on the number of steps
in a procedure.

**Exceptions — two instructions in one sentence are allowed only when:**
- both actions occur at the same time and cannot be separated (e.g. "Hold the
  Shift key and click Reload"), or
- a result or measurement follows the action immediately and splitting it would
  break the logical flow (e.g. "Measure the leakage. The leakage must not exceed
  0.5 cc/minute").

### Why
A sentence with multiple instructions lets the reader miss or skip an action,
causing config, deploy, or debug errors.

### Apply across doc types
- **README / quick-start:** each numbered step = one instruction.
- **API docs:** one sentence per endpoint operation, per parameter, per return
  field, per error code.
- **Docstrings:** first line = one-sentence summary. Body: one sentence per
  parameter, return value, raised exception, side effect, precondition.
- **Commit subject:** one imperative sentence describing one change. Multiple
  unrelated changes → split the commit (or use body bullets).
- **Error messages:** state exactly one problem; one recovery instruction if
  applicable. Do not combine failure paths with "or/and/also".

**Non-STE (5 instructions):** Open the config file and locate the database
section and change the connection string to staging and save the file and close
the editor.
**STE:** (1) Open `config/database.toml`. (2) Find the `[database]` section.
(3) Set `connection_string = "postgres://staging-db:5432/app"`. (4) Save the
file. (5) Close the editor.

### Grammar (single predicate)
Each imperative sentence has exactly one main verb in imperative mood.
- Correct: `Install the package.` (one predicate)
- Incorrect: `Install the package and configure the settings.` (two predicates)

**Compound objects are fine** (one verb, many objects):
`Remove the log files, cache files, and temporary directories.` — one instruction.
`Remove the log files and restart the server.` — two instructions (split).

**"-ing" forms as main verbs hide instructions:** "After installing, configuring,
and setting up, run the app" smuggles three instructions. Number them.

**Preconditions are instructions:** "Before you run the tests, set TEST_MODE" →
`(1) Set TEST_MODE to true. (2) Run the tests.`

### Edge cases
- **Framework CLI commands** (`docker compose up`, `kubectl apply`,
  `terraform destroy`) are one technical noun phrase. Do not split into
  "run docker. then compose." Use backticks.
- **Error messages with cascading symptoms:** state the *root cause* (one
  sentence); list consequences in a separate descriptive sentence.
- **Generated docs:** prefer annotation styles (JSDoc `@param` per item) that
  yield one sentence per item.
- **Test assertions:** one description/message per assertion.
- **Progress logs:** each log line reports one completed action/result.

### Cross-references
Rule 5.1 (short sentences), Rule 5.3 (imperative), Rule 1.1 (approved words),
Rule 1.12 (technical verbs), Rule 1.13 (no technical-verb-as-noun), Rule 5.5
(notes), STE-Code Dictionary (approved action verbs).

## Rule 5.3 — Imperative (Command) Form for Instructions

**Core rule:** Write every procedural instruction in the imperative (command)
form. Start each instruction with an imperative verb. The implied subject is
always the reader ("you"), which removes ambiguity about who acts.

**Imperative verbs common in code docs:** run, set, open, save, install,
configure, restart, execute, copy, delete, create, add, enter, select, click,
type, check, use, start, stop, send, show, get, make, remove, build.

**Do NOT use:**
- passive voice ("is executed", "are to be removed"),
- gerunds as commands ("Building the image..."),
- modal verbs (can, could, should, may, might) for instructions,
- "must" before the imperative in a *standard* instruction.

**Reserve "must"** for WARNING/CAUTION blocks about security, data loss, or
safety-critical conditions.

### What kind of text is imperative vs descriptive?
| Text type | Form |
|-----------|------|
| Install/setup/quick-start steps | Imperative |
| API "getting started"/auth walkthrough | Imperative |
| Endpoint *descriptions* (system behavior) | Descriptive ("Returns a list") |
| Docstring body (what code does) | Descriptive |
| Commit **subject line** | Imperative ("Fix the race condition") |
| Commit body (rationale) | Descriptive allowed |
| Error message — recovery instruction | Imperative (after the description) |
| Makefile/shell-script usage headers | Imperative |

### Examples
- Non-STE: The unit tests can be executed with `npm test`.
  STE: Run the unit tests with `npm test`.
- Non-STE: The configuration file should be validated before the app starts.
  STE: Check the configuration file against the schema before you start the app.
- Non-STE: It is recommended that you create a backup before the migration.
  STE: Create a backup of the database before you run the migration.
- Non-STE: The SSL certificate must be renewed and then the server must restart.
  STE: Renew the SSL certificate. Then, restart the web server to apply changes.
- WARNING (allowed "must"): IF YOU MUST STORE CREDENTIALS, ALWAYS USE AN
  ENCRYPTED SECRETS MANAGER. PLAIN-TEXT CREDENTIALS CAN CAUSE BREACHES.

### Grammar
- **Subject omission:** imperative drops "you" → reader knows the instruction is
  for them. Passive hides the agent ("The file is saved" = who?).
- **Modal elimination:** "can/should" let the reader read an action as optional.
  Imperative leaves no room for that.
- **Tense consistency:** base verb form, no inflection — simpler to translate and
  parse.
- **Coordinates with Rule 5.4:** a descriptive context sentence may precede the
  imperative command. Keep the two roles in separate sentences.
  `The Docker daemon must be running. Build the image with \`docker build\`.`

### Paradigm notes
- **OOP:** imperative for setup/config; descriptive for invariants/inheritance.
- **Functional:** imperative for build/REPL/setup; descriptive for what a
  function transforms.
- **Procedural (C/Go/Bash):** imperative dominates (build, compile, link, run).
- **Declarative (SQL/Terraform/K8s):** the spec is descriptive; the *tooling
  that applies it* (CLI, pipelines) is imperative.
- **Systems (Rust/C):** descriptive for invariants; imperative for "how to
  comply" (free memory, satisfy borrow checker).

### Edge cases
- **Framework name = verb** (React, Spring, Go, Make, Build): never start a
  sentence with the framework name as if it were a command. Prefix with an
  article or reword: "Use React to build the UI." Avoid "React to state changes."
- **Generated/tool output** (`--help`, changelogs, OpenAPI pages): fix the
  *template/source*, not the output. CLI help: `help="Write the output to this file"`.
- **Language keywords that are modals** (`try`, `await`, `yield`): use backticks;
  don't start an imperative sentence with the bare keyword. "Use `await` on the
  promise before you access the result."
- **Release notes:** imperative for upgrade/migration steps; past/perfect tense
  for feature/bug descriptions.
- **Interactive tutorials:** label instructional blocks ("Run this command") and
  system-response blocks ("You will see…") separately.

### Cross-references
Rule 1.1 (approved words), Rule 1.2 (part of speech), Rule 1.4 (verb forms),
Rule 1.7 (no technical-noun-as-verb), Rule 5.4 (descriptive before command),
Rule 7.1 (risk signal words), Rule 7.2 (safety instruction start), STE-Code
Dictionary (approved verbs: use > utilize, start > initiate, check > verify,
set > configure).

## Rule 5.4 — Descriptive Statement Before the Command

**Core rule:** When a step has a condition the reader must know first, write the
condition as a descriptive statement at the start of the sentence, follow it with
a **comma**, then give the imperative command. The comma is mandatory — it marks
where the condition ends and the instruction begins.

**Pattern:** `[condition clause] , [imperative verb] [object]`

- Non-STE: Run the migration after you set `DATABASE_URL` and confirmed the
  server accepts connections.
- STE: After you set the `DATABASE_URL` environment variable, run the migration
  script.

### Why the comma matters
Comma placement changes which verb an adverb modifies:
- `If the service does not start, automatically restart it.` (the restart is automatic)
- `If the service does not start automatically, restart it.` (you restart it manually)

In code, condition clauses often contain punctuation (backticks, dots,
parentheses). The comma after the clause is the only reliable boundary marker.

### Apply across doc types
- **README:** one condition-command pair per step. Don't bury the condition after
  the command.
- **API:** state the trigger/error condition before describing the response.
- **Docstrings:** precondition-before-behavior. "If the file does not exist, this
  function raises `FileNotFoundError`."
- **Commit:** context-before-action. "When the connection pool reaches capacity,
  add a mutex lock around pool access."
- **Error messages:** problem-before-resolution. "The config has invalid YAML on
  line 42. Fix the syntax error, then run the app again."

### Dependent clause types (condition first, comma, command)
1. **Time** (before, after, when, while, until): `Before you deploy, run the tests.`
2. **Conditional** (if, unless): `If the build fails, check the error log.`
3. **Reason** (because): prefer splitting — "The port is in use. Use a different port."
4. **Purpose** (to, in order to): `To see running containers, run \`docker ps\`.`
5. **Concessive** (although): `Although the server starts, check the health endpoint.`

Never reverse the order (command first, condition second) — the reader would act
before learning the condition.

### Multiple conditions in one step
- **A — separate sentences:** "Make sure the server is running. After it accepts
  connections, run the migration."
- **B — compound with 'and':** "If the server is running and the backup is
  complete, run the migration."
- **C — sequential pairs (preferred):** "Before you run the migration, make sure
  the server is running. After the server accepts connections, run the migration."

### Paradigm notes
- **OOP:** state preconditions before method-call/constructor instructions.
- **Functional:** state input guard/pattern before describing the transformation.
- **Procedural (C/Go/Bash):** state system-state condition before the action.
- **Declarative:** applies to the *operational wrapper* (how to apply/destroy),
  not the declarative spec itself.
- **Systems (Rust/C):** state safety condition before the operation; use WARNING/
  BREAKING when the consequence is severe.

### Edge cases
- **Framework name = common word** (Next.js, Express): still a technical noun;
  comma rule applies to the condition clause containing it.
- **Code keyword inside condition:** comma after the closing backtick. "When
  `response.status === 429`, wait for the `Retry-After` duration. Then, retry."
- **Condition clause has its own commas** (a list): restructure into a separate
  descriptive sentence + a simple condition clause, or use Strategy C. Don't pile
  commas.
- **Condition implied by tool output:** state the observable output as the
  condition. "If the terminal shows 'Connection refused', start the database."
- **Generated docs:** relaxed for output, but source docstrings/comments must
  follow the rule. For templates, place the condition placeholder first.

### Cross-references
Rule 1.1 (approved words), Rule 1.4 (verb forms), Rule 1.5 (technical nouns),
Rule 5.3 (imperative verb form), Rule 5.5 (notes), Rule 7.2 (safety instruction
start). Dictionary synonyms: verify → check, obtain → get, terminate → stop.

## Rule 5.5 — Notes Give Information Only, Not Instructions

**Core rule:** A NOTE gives descriptive information only. It must not contain
instructions, commands, step-by-step actions, requirements, limits, tolerances,
or expected results of a work step. A note must not use the imperative form.

Each sentence in a note may be up to 25 words. A note can have one or more
sentences.

### The "remove the notes" test
To check correct note usage: read the procedure *without* the notes. If the
reader can complete the procedure correctly, the notes are used correctly. If
important information is only in a note, move it into a numbered work step and
repeat the test.

### Move note content out when…
- it tells the reader to run a command → make it a numbered work step.
- it states a limit/tolerance/result → put it directly in the work step after the
  related action.
- it carries safety-critical info (data loss, security, system damage) → convert
  to a WARNING or CAUTION safety instruction. A note is never a substitute for a
  safety instruction.

**Non-STE:** NOTE: When you update dependencies, run `npm audit fix` to resolve
vulnerabilities. If you skip this, you may have security issues.
**STE:** (5) Run the command `npm audit fix` to resolve known vulnerabilities.

**Non-STE:** NOTE: Do not run the migration on production without a backup.
**STE:** WARNING: DO NOT RUN THE MIGRATION ON THE PRODUCTION DATABASE WITHOUT A
FULL BACKUP. RUNNING IT WITHOUT A BACKUP CAN CAUSE IRREVERSIBLE DATA LOSS.

### Apply across doc types
- **README:** notes give project context (why a dependency exists). Not install steps.
- **API docs:** notes explain behavior/side effects/constraints. "Call the
  /refresh endpoint first" is an instruction — move it to the endpoint description.
- **Docstrings:** describe behavior/constraints. "Call `initialize()` first" is a
  requirement — write it as a descriptive constraint in the function spec.
- **Commit body:** explain *why* a change was made. Not "run the migration" (that
  belongs in release notes / upgrade guide).
- **Error messages:** the fix guidance is part of the error text (descriptive +
  imperative), not a separate note the reader might skip.

### Paradigm notes
- **OOP:** note explains disposed-state constraint, not "call dispose() first."
- **Functional:** note states purity/performance, not "memoize it."
- **Procedural:** note states resource-leak behavior, not "close the fd."
- **Declarative:** note describes attribute behavior, not "always set this."
- **Systems:** note describes borrow/compiler behavior, not "don't mutate."

### Grammar of notes
- **Descriptive mood only.** Subject performs/experiences the action (system,
  code, environment). "The cache expires after 300 seconds." NOT "Run the build."
- **Modals:** "can/may/will" are fine when describing system behavior. "must" in
  a note is a red flag — it usually signals a requirement that belongs in a work
  step or WARNING.
- **Articles:** do not omit "the/a/an" in notes.
- **Technical nouns** (function/class/command names) follow Rule 1.5 — exempt from
  the dictionary, but surrounding words must use approved vocabulary.

### Edge cases
- **Framework name = verb** (React, Express): still a technical noun in a note;
  not an instruction. "The `React` component tree re-renders when state changes."
- **Generated docs:** fix the *source comment*, not the generator output.
- **Interactive tutorials:** exploratory "try this" notes are acceptable only in
  non-shipping tutorial material, never in reference/README/API docs.
- **Command referenced, not commanded:** "The `terraform plan` command shows the
  changes" is a note. "Run `terraform plan`" is an instruction — not a note.
- **Conditional in a note:** "if" alone doesn't make it an instruction. Test: does
  the clause describe system behavior (note) or tell the reader to do something
  (a step)? "The server returns 503 if upstream is slow" = note. "If you get 503,
  check /health" = step.

### Cross-references
Rule 1.1 (approved words), Rule 1.5 (technical nouns), Rule 1.7 (no
technical-noun-as-verb), Rule 5.3 (imperative vs descriptive), Rule 5.4
(descriptive-before-command — a note must not follow this pattern), Rule 5.6
(separate steps for separate actions), Rule 7.1 (risk signal words), Rule 9.1
(descriptive writing).

## Quick checklist for LLM code-doc generation

When generating install steps, API guides, READMEs, docstrings, commit messages,
or error text, apply Section 5 in this order:

1. **5.3 — Use imperative verbs** for every instruction. Drop passive voice,
   gerunds, and modals (can/should/may). Reserve "must" for WARNING/CAUTION.
2. **5.2 — One instruction per sentence.** Number steps. Split compound
   instructions. Don't put preconditions, results, or "and"-chained actions in one
   sentence unless they are simultaneous or an immediate result.
3. **5.1 — Keep each procedural sentence ≤ 20 words** (notes ≤ 25). Exclude code
   blocks and count backtick tokens as one word each. Split long sentences at
   conjunctions/conditions or into lists.
4. **5.4 — Put the condition before the command**, with a comma.
   `After you set DATABASE_URL, run the migration.` Never reverse the order.
5. **5.5 — Keep NOTES descriptive only.** No imperatives, no commands, no limits.
   If a note tells the reader to act, make it a work step (or a WARNING). A note
   sentence may be up to 25 words.

Defaults that are NOT instructions: code blocks, terminal output, string literals,
identifier names, and the words around a backticked technical noun.



## rules-sec6.md

# Level 5 — Section 6: Sentence and Paragraph Structure (Rules 6.1–6.6)

This slice of the STE-Code standard governs how to organize sentences and
paragraphs in code documentation. It is part of the full standard (all rules +
extensions + dictionary + provenance) at Level 5.

## What this section is for

When an LLM generates code documentation (README, API docs, docstrings, inline
comments, commit messages, error messages, changelogs, config comments), apply
these six rules so the output is easy to read on the first pass:

- **Rule 6.1** — Give information gradually; one subject per sentence.
- **Rule 6.2** — Use key words and key phrases to give the text a logical structure.
- **Rule 6.3** — Write short sentences (max 25 words each).
- **Rule 6.4** — Use paragraphs to group related information (topic sentence first).
- **Rule 6.5** — Each paragraph has only one topic.
- **Rule 6.6** — No paragraph has more than six sentences.

The rules build on each other: 6.1 splits compound sentences → 6.2 links the
short sentences with repeated key words → 6.3 keeps each sentence short → 6.4
groups related sentences into paragraphs → 6.5 keeps each paragraph on one
topic → 6.6 caps paragraph length.

## Shared code-domain vocabulary

Across all six rules, prefer plain approved verbs and avoid unapproved synonyms:

- `make` (not "create"/"generate"), `start` (not "initiate"), `stop` (not
  "terminate"), `get` (not "retrieve"/"fetch"), `send` (not "transmit"),
  `show` (not "display"/"render"), `set` (not "configure"/"assign"),
  `check` (not "verify"/"ensure"), `use` (not "utilize"/"leverage").
- Approved connecting words: `and`, `but`, `then`, `thus`, `also`, `however`,
  `therefore`, `for example`, `as a result`, `at the same time`. Place them
  near the start of a sentence so the reader sees the signal first.
- Technical code nouns (class names, function names, library names, framework
  names) are allowed even when not in the approved dictionary (Rule 1.5). Do
  not use a technical noun as a verb.

---

## Rule 6.1 — Give Information Gradually

Adapted from ASD-STE100 Issue 9, Rule 6.1.

**Core rule.** In code documentation, give the reader one piece of information
at a time. Each sentence contains only one subject performing one action. Do
not combine multiple actions, multiple conditions, or multiple subjects in one
sentence. Applies to every form of documentation: README, API reference,
docstrings, inline comments, commit messages, error messages, log entries,
changelogs, config files.

**Why.** Human working memory holds ~4–7 items. A sentence with multiple
subjects and verbs forces the reader to hold all of them until the sentence
ends, raising cognitive load — especially when the reader is also parsing code.

**Single-subject constraint (grammar).**
- One subject + two verbs sharing that subject is OK: "The function validates
  the input and returns a result." (one subject "function").
- Two subjects is NOT OK: "The function validates the input and the middleware
  logs the result." → split: "The function validates the input. The middleware
  logs the result."

**Splitting rules.**
- Coordinating conjunction (`and`/`or`/`but`) joining two clauses, each with
  its own subject — split at the conjunction.
- Subordinating conjunction (`because`/`since`/`while`/`if`) — one main clause
  + one dependent clause is OK, unless the dependent clause introduces a new
  subject with its own chain of actions (then move it to its own sentence).
- Relative clause (`which`/`that`/`who`) describing the main subject is OK; one
  that introduces a new subject + new actions must be split.

**Code-domain example (auth middleware).**

Non-STE (one dense sentence, ~90 words):
> The authentication middleware validates bearer tokens from the authorization
> header by calling the `validateToken` function in the security module which
> decodes the JWT payload using the `HS256` algorithm from the `jwt-signer`
> library and checks the `exp` claim against the current server time before
> extracting the `sub` and `role` claims and attaching them as properties on
> the `request.auth` object, and if the token is expired or malformed the
> middleware returns a `401 Unauthorized` response with a JSON error body ...

STE (one subject per sentence):
> The authentication middleware validates each incoming request. The middleware
> reads the bearer token from the `Authorization` header. It sends the token to
> the `validateToken` function in the `security` module. The `validateToken`
> function decodes the JWT payload. It uses the `HS256` algorithm from the
> `jwt-signer` library. Then it compares the `exp` claim with the current
> server time. If the token is not expired and not malformed, the function gets
> the `sub` and `role` claims. It attaches these claims as properties on the
> `request.auth` object. If the token is expired, the middleware returns a
> `401 Unauthorized` response. The response body is a JSON object: the
> `message` field contains a description of the error; the `errorCode` field is
> set to `TOKEN_EXPIRED`. If the token is malformed, the middleware returns a
> `401 Unauthorized` response. The `errorCode` field in the response is set to
> `TOKEN_MALFORMED`. The middleware also logs each failure to the audit trail.
> It calls the `AuditLogger.log` static method. This method writes a record to
> the `audit_events` table in the primary database. The write uses an
> asynchronous pattern that does not block the response pipeline.

**Per-context guidance.**
- README: one concept per sentence. State the purpose, then the install
  command, then a usage example — each in its own sentence.
- API docs: one sentence for method+path, one per parameter, one per response
  field or status code. A reader who looks up one parameter must not read a
  paragraph about ten unrelated things.
- Docstrings/comments: one behavior per sentence. Each parameter and each
  return condition gets its own sentence.
- Commit messages: one logical change per sentence; use a summary line + bullet
  body, not "Add X, fix Y, update Z, refactor W" as one sentence.
- Error/log messages: one problem per message with a distinct error code; one
  event per log line.
- Changelogs: one change per entry; separate feature / fix / deprecation.

**Paradigm-specific.** Object-oriented: one method/behavior per sentence;
describe the override chain step by step. Functional: one transformation per
sentence; do not describe an entire `>>=` or pipe chain in one sentence.
Procedural: one step/branch per sentence — if/else and loop bodies stay separate
sentences. Declarative: one resource/constraint/column per sentence. Systems:
one ownership rule / lifetime constraint / memory operation per sentence.

**Edge cases.**
- A framework name combining multiple actions (e.g.
  `UserAuthenticationAndAuthorizationService`) is one technical noun — do not
  split it; keep the single-subject rule for the surrounding prose.
- Tool-generated docs (OpenAPI/JSDoc/Sphinx) may emit compound sentences. If
  you cannot change the output, add a one-subject-per-sentence summary above the
  generated block.
- Control-flow keywords (`if`/`else`/`while`/`try-catch`) naturally have
  multiple subjects — use one sentence per branch.
- CLI `--help`/error codes have limited space: still one subject per sentence;
  use fragments only when the display format enforces them.
- When rewriting existing compound docs, check for hidden logical dependency:
  if B depends on A, describe A first, then B.

**See also.** Rule 6.2, 6.3, 6.4, 6.5; Rule 1.1 (approved words); Rule 1.11
(one term per concept).

---

## Rule 6.2 — Use Key Words and Key Phrases to Give Your Text a Logical Structure

Adapted from ASD-STE100 Issue 9, Rule 6.2.

**Core rule.** Use key words (terms repeated across a documentation block) and
key phrases (multi-word expressions) to connect related ideas across sentences.
Key words are the threads that bind a block into one coherent unit. Do not change
the key word within a block — the same term must carry the same meaning
everywhere (links to Rule 1.11). Place approved connecting words near the start
of a sentence so the reader sees the signal before the content.

**Approved connecting words/phrases.** `and`, `but`, `then`, `thus`, `also`,
`however`, `therefore`, `for example`, `as a result`, `at the same time`. Do NOT
use `moreover`, `furthermore`, `nevertheless`, `subsequently`, or
`utilize`/`leverage` as connectors.

**How key words work (example chain).** Across the auth-middleware block:
> Sentence 1: The authentication middleware validates each incoming request.
> Sentence 2: The middleware reads the bearer token from the `Authorization` header. (repeats "middleware")
> Sentence 3: It sends the token to the `validateToken` function in the `security` module. (repeats "token")
> Sentence 4: The `validateToken` function decodes the JWT payload. (repeats "`validateToken` function")
> Sentence 9: The response body is a JSON object. (repeats "response")

Three groups form by key word: (1) token validation, (2) error responses +
`errorCode`, (3) audit trail. The reader follows the chain sentence to sentence
without manual reconstruction.

**Key word by documentation type.**
- README: repeat the project/library name and core concept ("middleware",
  "pipeline", "plugin") as the key word across sections. Do not switch to "the
  library"/"this tool".
- API docs: function names, parameter names, return-type names are the key
  words. Each sentence names the function or a pronoun referring to it.
- Docstrings: the function/class name is the key word; use parameter names and
  pronouns, not synonyms like "transmit"/"data"/"queue".
- Commit messages: the component name + action verb + affected module are the
  key words; do not switch to "pool"/"conn pool"/"connection manager".
- Error messages: the operation name + resource name are the key words; do not
  switch to "document"/"path".
- Cross-type consistency: the same key word means the same thing in README, API
  docs, docstrings, and commits (part of Rule 1.11).

**Paradigm-specific key words.**
- OOP: class names, method names, property names. For a builder/method chain,
  repeat the return type (e.g. "Stream") to show the flow.
- Functional: type names, function names, data constructors; the value flowing
  through transformations is the key word (e.g. "Result", the "changeset").
- Procedural: variable names, struct fields, error codes (e.g. "buffer").
- Declarative: resource names, column names, attribute names (e.g.
  "aws_instance").
- Systems: ownership terms, lifetime names, pointer names (e.g. "buffer",
  "borrow").

**Edge cases.**
- A framework name that is an unapproved word (e.g. a library named "Leverage")
  is a technical code noun — keep it as the key word; do not replace with a
  synonym.
- A short language keyword that carries little meaning (Go `go`, Rust `mut`) is
  not a good key word — use a descriptive key phrase that includes it (e.g.
  "goroutine").
- Generated code with verbose type names (e.g. `UserServiceClientImpl`) is the
  key word even though long — do not shorten to "client"/"stub"/"it".
- Multi-language repos: pick one key word for a cross-language concept (e.g.
  "map" for Python `dict` / Java `HashMap` / Go `map`) and note the
  language-specific names once.
- Multi-word key phrases ("connection pool", "rate limiter", "retry policy")
  stay intact — do not break them apart mid-document.

**Grammar notes.** Key-word repetition is lexical cohesion. Three cohesive ties:
(1) Repetition ("The middleware validates the request. The middleware reads the
token."); (2) Pronoun reference ("It reads the token.") — use sparingly, repeat
the full key word after two sentences; (3) Approved synonym/hypernym. Topic is
the subject of each sentence (topic-comment structure): keep the same key word in
subject position. A "dangling key word" (introduced once, never repeated) breaks
the structure. Use connecting words at the start of sentences, not buried.

**See also.** Rule 6.1, 6.3, 6.4, 6.5; Rule 1.5 (technical code nouns), Rule
1.8 (standard technical nouns), Rule 1.9 (short technical nouns), Rule 1.11 (one
term per concept).

---

## Rule 6.3 — Write Short Sentences. Maximum 25 Words per Sentence.

Adapted from ASD-STE100 Issue 9, Rule 6.3.

**Core rule.** In descriptive code documentation, the maximum sentence length is
25 words. Short sentences give clear structure and make information easier to
understand. This is a hard ceiling for descriptive text; procedures (imperative
steps) are naturally shorter.

**Why the limit.** A 25-word sentence can hold at most ~2 clauses with
connecting words — matching working-memory capacity. Most English clauses are
6–12 words, so the limit indirectly bounds clause density. Splitting one complex
sentence into several short ones improves clarity even when the original is under
25 words.

**Examples (code-domain).**
- Non-STE (32 w): "The configuration loader reads the YAML manifest file from
  the filesystem and parses it into an in-memory representation that other
  modules can query at runtime to determine their operational parameters."
  → STE: "The configuration loader reads the YAML manifest file from the
  filesystem. It parses the file into an in-memory representation. Other modules
  can query this representation at runtime. They use it to find their
  operational parameters." (20/8/7/8)
- Non-STE (34 w): "The cache invalidation strategy employs a time-to-live
  mechanism combined with a least-recently-used eviction policy to ensure that
  stale data is removed and memory consumption remains within the allocated heap
  budget."
  → STE: "The cache invalidation strategy uses a time-to-live mechanism. It also
  uses a least-recently-used eviction policy. Together, these mechanisms remove
  stale data. They also keep memory consumption within the allocated heap
  budget." (16/10/7/10)
- Non-STE (21 w): "This function provides the ability to run arbitrary software
  applications within a sandboxed execution environment that isolates system
  resources."
  → STE: "This function lets you run software applications in a sandbox. The
  sandbox isolates system resources." (8/5)

**Per-context guidance.**
- README: one sentence for the project, one for prerequisites, one for install.
- API docs: one short sentence each for path+method, each parameter, each
  response field, each error code.
- Docstrings: one sentence for purpose, one per parameter, one for return, one
  per exception — all under 25 words.
- Commit messages: subject line ≤72 chars; one short sentence per logical
  change in the body.
- Error messages: two short sentences — the problem, then the action. Log
  aggregation tools parse by line, so one sentence per line helps filtering.

**Paradigm-specific.**
- OOP: split inheritance + behavior into separate sentences ("The
  `AuthenticatedController` class extends `BaseController`. It implements the
  `Auditable` and `Loggable` interfaces.").
- Functional: split composition from error behavior.
- Procedural: each step = one sentence; for safety-critical code, split
  allocation from copy from return.
- Declarative: document each resource argument in its own sentence.
- Systems (Rust ownership, C memory): short sentences are safety-critical; split
  borrowing/lifetime explanation into discrete sentences.

**Edge cases.**
- Long technical terms ("single sign-on", "Hypertext Transfer Protocol Secure")
  count as one unit; if one still pushes over 25 words, introduce an acronym
  (SSO) after first mention to cut later counts.
- Verbose language keywords (`synchronized`, `__attribute__((constructor))`) count
  as one word — keep the rest of the sentence short.
- Compound type signatures (TypeScript/Rust generics) often exceed 25 words: one
  sentence for the type shape, one for constraints, one for behavior.
- Legal/license text (MIT, Apache, GPL, copyright) is exempt; the surrounding
  explanation still obeys the limit.
- Generated documentation (JSDoc/Sphinx/`go doc`) may exceed the limit — fix the
  source docstrings, not the generated output.

**Counting rules.** Hyphenated compounds count as one word ("least-recently-used"
= 1). Acronyms count as one word ("JSON" = 1). Code tokens count as one word
(`Result<Vec<T>>` = 1). Do not count parenthetical word counts in examples.

**Grammar notes.** Prefer coordination with separate sentences over heavy
subordination (e.g. "The `parse` function throws a `SyntaxError`. This error
occurs when the input string contains invalid JSON." rather than a 27-word
sentence with three levels of subordination). Code docs use implicit connectives
(order implies flow) rather than academic "therefore"/"furthermore".

**See also.** Rule 6.1, 6.2, 6.4, 6.5; Rule 1.1 (approved words); Rule 1.10 (no
slang/jargon).

---

## Rule 6.4 — Use Paragraphs to Show Related Information

Adapted from ASD-STE100 Issue 9, Rule 6.4.

**Core rule.** In code documentation, a paragraph starts with a topic sentence
that tells the developer the topic of that paragraph. The sentences that follow
explain it or add related information. A new paragraph signals a new topic or
different information. This applies to procedures (numbered steps) and
descriptive writing alike.

**Why.** Paragraphs group related sentences and give the text a logical
sequence. A paragraph that mixes unrelated topics (install steps + config
options + usage) is not compliant. Use section headings for major topics and
paragraph breaks for sub-topics.

**Examples (data pipeline split into topic-sentence-led paragraphs).**

Non-STE (one dense paragraph, mixed stages + error handling):
> The data pipeline processes incoming events through a sequence of stages. Each
> stage transforms the event payload and passes it to the next stage. The first
> stage is validation ... The second stage is enrichment ... The third stage is
> transformation ... The final stage is persistence ... Error handling is
> implemented at each stage ... If a stage fails, the pipeline logs the error and
> routes the event to the dead-letter queue ...

STE (each stage = its own paragraph with a topic sentence):
> **1. Data Pipeline Overview** — The data pipeline processes incoming events
> through a sequence of stages. Each stage transforms the event payload and
> passes it to the next stage. Error handling is implemented at each stage ...
> **2. Validation Stage** — The first stage is validation. This stage checks the
> event schema. It rejects events that are malformed.
> **3. Enrichment Stage** — The second stage is enrichment. This stage adds
> metadata to the event: Timestamps; Source identifiers; Geolocation data.
> **4. Transformation Stage** — The third stage is transformation. This stage
> converts the event into the target format. Downstream consumers use this
> format.
> **5. Persistence Stage** — The final stage is persistence. This stage writes
> the transformed event to the data store and to the event log for audit.

**Per-context guidance.**
- README: each section starts with a topic sentence. Separate Installation,
  Configuration, Dependencies, Usage into their own paragraphs.
- API docs: endpoint description = topic sentence first; give authentication its
  own paragraph (before endpoint details); separate request schema, response
  schema, and error descriptions with clear topic sentences.
- Docstrings/inline comments: start with a one-line topic sentence, then a blank
  line, then more paragraphs (parameters / returns / raises / side effects /
  usage). Each inline comment is a one-sentence paragraph stating the topic of
  the following code.
- Commit messages: the first line is the topic sentence; the body uses paragraphs
  to group the problem, the changes, and the monitoring separately.
- Error messages: a single sentence states the topic (what failed + why); a
  multi-line error uses paragraphs to separate the error description, the
  diagnostic checks, and the stack trace.

**Paradigm-specific.**
- OOP: separate class purpose, constructor details, public API, and internal
  design into paragraph groups; one paragraph per method description.
- Functional: separate the type signature explanation, the behavior, the
  purity/algebraic properties, and the internal composition.
- Procedural: separate initialization, main loop, and cleanup phases.
- Declarative: give each resource its own paragraph group (identity, spec,
  dependencies).
- Systems: separate the ownership model, lifetime annotations, and unsafe-code
  justifications.

**Edge cases.**
- Framework name = approved word (e.g. "Make" the build tool vs "make" the verb):
  capitalize the tool, use a topic sentence to establish meaning.
- Code keywords (`break`, `continue`, `return`, `yield`) are technical nouns
  (Rule 1.5), not verbs — set them in backticks and start the paragraph with a
  topic sentence naming the keyword.
- A long code block must sit in its own paragraph; start the preceding paragraph
  with a topic sentence that names what the code does, end it, insert the block,
  then start a new paragraph to explain important parts.
- Auto-generated docs (JSDoc/Sphinx/`go doc`): insert a blank comment line
  between topics so the tool emits separate paragraphs.
- Mixed-author documents: apply structural linting; flag paragraphs >5 sentences
  or lacking a topic sentence (a Vale `existence` rule works).

**Grammar notes.** The topic sentence is a declarative simple-present sentence
that names the topic in subject position with an approved verb — never start a
paragraph with a subordinate clause ("Because...", "When...", "If..."). A
paragraph of five sentences cannot exceed 125 words (due to Rule 6.3). Ideal
length: docstrings 1–3 sentences per topic, README 3–5, API endpoint 4–6, error
messages 1. Place a paragraph break before a new concept, a code example, a
warning, a list, or a change in abstraction level. Do NOT break between a topic
sentence and its supporting sentences.

**See also.** Rule 6.1, 6.2, 6.3, 6.5; Rule 1.1, 1.5, 1.11; Rule 7.1 (use lists
for three or more items).

---

## Rule 6.5 — Make Sure That Each Paragraph Has Only One Topic

Adapted from ASD-STE100 Issue 9, Rule 6.5.

**Core rule.** Each paragraph in descriptive code documentation has only one
topic. The topic sentence is the first and most important sentence; it gives new
information and makes a logical connection to previous information (via a key
word and/or connecting word). If you write down the topic sentences of a
document, you get a good outline of its content.

**Why.** The topic sentence lets the developer find applicable information
quickly. When a paragraph drifts to a second topic, the reader loses the thread.
Rule 6.4 tells you to use paragraphs; Rule 6.5 tells you each paragraph gets one
topic.

**Example (auth middleware — one function, three topics).**

Non-STE (five topics in one sentence):
> The authentication middleware validates each request and the logging system
> records all validation failures to the audit trail while the response pipeline
> returns JSON error bodies with error codes and the database connection pool
> maintains idle connections for reuse and the configuration module reloads
> settings when the manifest file changes on disk.

STE (three single-topic paragraphs; topic sentences form an outline):
> The authentication middleware validates each incoming request. The middleware
> reads the bearer token from the `Authorization` header. It sends the token to
> the `validateToken` function ... Then it compares the `exp` claim ...
> If the token is expired, the middleware returns a `401 Unauthorized` response.
> The response body is a JSON object ... If the token is malformed, the middleware
> returns a `401 Unauthorized` response ...
> The middleware also logs each failure to the audit trail. It calls the
> `AuditLogger.log` static method ...

Outline from topic sentences: "The authentication middleware validates each
incoming request." / "If the token is expired, the middleware returns a `401
Unauthorized` response." / "The middleware also logs each failure to the audit
trail."

**Per-context guidance.** The "topic" definition changes with format, but one
topic per paragraph is constant.
- README: "What it does", "How to install", "How to configure", "How to
  contribute" are separate paragraphs.
- API docs: one paragraph for endpoint purpose, one for request format, one per
  response status group (success / client error / server error), one for auth.
- Docstrings: the topic is the function's contract (inputs, outputs, behavior) —
  do not explain why the function exists, side effects of other functions, or
  list callers.
- Commit messages: one commit = one topic; split unrelated changes into separate
  commits.
- Error messages: a one-topic paragraph — what went wrong, why, how to fix; put
  stack traces in a log, not the message.

**Paradigm-specific.**
- OOP: one paragraph per concern — class purpose, constructor, public interface,
  inheritance/interface, thread-safety. Method implementation detail belongs in
  the method docstring.
- Functional: one paragraph for input shape, transformation logic, output shape,
  edge cases; document each pipeline stage in its own paragraph.
- Procedural: one paragraph per phase — init, main loop, cleanup, error handling.
- Declarative: one paragraph per table/view, per Terraform resource, per K8s
  object (Deployment and its Service are separate topics even if related).
- Systems: one paragraph per ownership relationship or memory lifecycle
  (allocation, transfer, deallocation, unsafe invariants).

**Edge cases.**
- Framework name = unapproved word (e.g. "Execute" library): it is a technical
  noun, allowed; but do not use it as a verb in the same paragraph ("Use the
  `Execute` library to run background jobs.", not "Execute background jobs with
  the `Execute` library.").
- Large multi-topic legacy functions: use the docstring as a bullet-point topic
  index; give each responsibility its own paragraph in module-level docs.
- Generated API docs: each individual docstring must still follow the one-topic
  rule because the tool only combines them.
- Cross-cutting concerns (security, performance, accessibility): give them their
  own document/section with a one-paragraph summary + link per module.
- Error-code reference tables: the table is one container; each description cell
  is a mini-paragraph describing only one error condition.

**Grammar notes.** Always use deductive paragraphs (topic sentence first) — a
topic sentence at the end is invisible to a scanning reader. Repeat the key word
(or approved synonym) from the topic sentence in supporting sentences; a new
unconnected key word means drift. Use connecting words in the topic sentence:
"Also" (same topic, new angle), "However" (contrast), "For example" (instance),
"Therefore" (result). A paragraph is 3–7 sentences; a 10+ sentence paragraph
almost always has multiple topics. Separate paragraphs with a blank line (not
indentation-only).

**See also.** Rule 6.1, 6.2, 6.3, 6.4; Rule 1.11 (one term per concept); Rule
3.6 (approved verb forms); Rule 5.1 (imperative instructions); Rule 6.6 (≤6
sentences per paragraph).

---

## Rule 6.6 — Make Sure That No Paragraph Has More Than Six Sentences

Adapted from ASD-STE100 Issue 9, Rule 6.6.

**Core rule.** In code documentation, no paragraph has more than six sentences.
Paragraphs divide a block into logical units and keep the reader's attention. If
a paragraph has more than six sentences, divide it into two smaller paragraphs.
The six-sentence limit is a practical ceiling, not a target — most good
paragraphs use two to four sentences.

**Relationship to 6.4 and 6.5.** Rule 6.4 says use paragraphs; Rule 6.5 says
each paragraph has one topic; Rule 6.6 says don't let a paragraph grow past six
sentences. The three together produce short, single-topic paragraphs.

**When to split a paragraph.**
- It has more than six sentences.
- It covers two or more topics (Rule 6.5).
- A sentence introduces a new key word the earlier sentences don't use (Rule 6.2).
When splitting, group sentences that share a key word in the first paragraph;
start the new paragraph with a topic sentence that names the new key word.

**Code-domain examples.**
- ConnectionPool docstring: the Non-STE version packs four components (socket
  connections, reaper thread, bounded queue, metrics collector) into one 5-sentence
  paragraph; the STE version uses one outline paragraph + four short paragraphs,
  each under six sentences.
- POST /orders handler: the Non-STE version crams the whole lifecycle into one
  one-paragraph sentence; the STE version uses four paragraphs (parse, authorize,
  act, fail), each two to four sentences.
- AuthModule: five responsibilities in one paragraph → six paragraphs, each under
  six sentences, one topic per paragraph.
- Migration `upgrade()`: seven changes in one sentence/paragraph → six short
  paragraphs.
- Changelog v3.1.0: five unrelated changes in one paragraph → one short paragraph
  per change type; mark the API removal with DEPRECATED.

**Per-context guidance.**
- README: keep each feature description to a short paragraph; split
  install/configure/verify into separate paragraphs.
- API docs: keep each endpoint description short — purpose, request, response,
  errors each in its own paragraph under six sentences.
- Docstrings: keep the summary paragraph short; one short paragraph per concern
  (params, returns, raises); move a long parameter list to a bulleted list.
- Error/log diagnostics: a multi-line diagnostic block stays to six lines or
  fewer, or splits into a cause paragraph and a recovery paragraph.

**Paradigm-specific.** OOP: one responsibility per paragraph (e.g. each phase of
the order lifecycle). Functional: one pipeline stage per paragraph. Procedural:
one phase per paragraph (build/rollout/verify/fail). Declarative: one
resource/block per paragraph. Systems: one ownership rule per paragraph (memory
contracts are easy to bury in a long one).

**Edge cases.**
- A topic that needs >6 sentences: keep each paragraph under six sentences and
  continue the same topic in a second paragraph, starting it with "Also," or "In
  addition," (e.g. the garbage-collector description spans two paragraphs).
- A bulleted/numbered list is ONE paragraph regardless of item count. Rule 6.6
  limits the surrounding prose sentences, not the number of list items. Keep the
  intro sentence short; don't add a long closing sentence restating every item.
- Generated docs that emit one long paragraph per symbol: if you can't change the
  generator, add a short human-written summary above the block; the generated
  block is exempt only if you don't edit its source annotations.
- A short paragraph can still violate 6.5 by mixing two topics (e.g. three
  sentences covering both "cache" and "queue") — Rule 6.6 (sentence count) and
  6.5 (topic count) are independent; split even if under the limit.

**Grammar notes.** The six-sentence limit comes from reading psychology: the
topic fades from working memory after ~6 sentences, causing re-reading. Rule 6.6
counts sentences, not words — a paragraph can have six long or six short
sentences and still pass, but six 25-word sentences is at the edge of
readability; prefer 2–4 sentences. Lists/tables inside a paragraph don't add to
the surrounding prose sentence count. In procedural writing each step is its own
paragraph by convention, so 6.6 rarely applies — except when a step has a long
note/rationale (keep it under six sentences or move it to a note paragraph).

**See also.** Rule 6.4, 6.5, 6.1, 6.2, 6.3.

---

## Quick reference for LLM documentation generation

Apply this checklist to any code documentation you produce:

1. **6.1 Gradual** — one subject per sentence; split compound sentences at
   coordinating/subordinating conjunctions and relative clauses.
2. **6.2 Key words** — repeat the same technical noun/term as the key word
   across sentences; use approved connectors (`and`, `but`, `then`, `thus`,
   `also`, `however`, `therefore`, `for example`) at sentence start.
3. **6.3 Short** — every descriptive sentence ≤ 25 words (hyphenated terms,
   acronyms, and code tokens each count as one word).
4. **6.4 Paragraphs** — start each paragraph with a topic sentence; group
   related sentences; separate Installation/Config/Usage/API/etc.
5. **6.5 One topic** — each paragraph covers exactly one topic; topic sentences
   alone should outline the document.
6. **6.6 ≤6 sentences** — no paragraph exceeds six sentences; prefer 2–4; a list
   is one paragraph.

Cross-links within the standard: Section 1 (Vocabulary: approved words, technical
nouns, one term per concept), Section 3 (Verb forms), Section 5 (Imperative
instructions), Section 7 (Lists for three or more items). These six rules form
the sentence-and-paragraph backbone of STE-Code; they are necessary but not
sufficient — pair them with the vocabulary and writing-style rules for full
compliance.



## rules-sec7.md

<!-- a-sec7-rule7.1.md -->

# Rule 7.1 — Use an Applicable Word (for Example, "Warning" or "Caution") to Identify the Level of Risk

> **Source:** Adapted from ASD-STE100 Issue 9, Rule 7.1

> **Source:** [master.md#sec7-rule7.1](ste-code/grouped/)

## Original Rule

**Rule 7.1** Use a word (for example, "warning" or "caution") or, when applicable, a symbol, to immediately show your reader the level of the related risk.

- If there is a risk of injury or death, use a "warning."
- If there is a risk of damage to machines, tools, or equipment, use a "caution."
- If there are the two levels of risk together, use a "warning."

In the non-STE example that follows, the safety instruction is a caution. But if you know about oxygen systems, you also know that oxygen mixed with other materials can cause explosions. Because there is a risk of injury or death here, you must identify this safety instruction as a warning.

Compare the wording in the two safety instructions. The non-STE safety instruction is an abstract sentence and only makes a general statement. The warning in STE gives clear and correct information about how to decrease the risk of explosion. The warning contains the words "explosion," "injury," and "death" to make the reader clearly understand how important this safety instruction is.

**Spec example:**

> **Non-STE:** CAUTION: EXTREME CLEANLINESS OF OXYGEN TUBES IS IMPERATIVE.
>
> **STE:** WARNING: BEFORE YOU FILL THE LIQUID OXYGEN SYSTEM, PUT ON A FACE MASK AND PROTECTIVE CLOTHING. LIQUID OXYGEN CAN CAUSE IRRITATION OF THE RESPIRATORY TRACT AND EYE IRRITATION.

## STE-Code Adaptation

**Rule 7.1** In code documentation, use a signal word (for example, "WARNING" or "CAUTION") to immediately show your reader the level of the related risk.

- If there is a risk of security vulnerabilities, data loss, or system corruption, use a "WARNING."
- If there is a risk of unexpected behavior, performance degradation, or incorrect results, use a "CAUTION."
- If there are the two levels of risk together, use a "WARNING."

Severity mapping: This rule teaches the WARNING and CAUTION safety signal words for code documentation. For release-note and changelog severity, map the same levels as follows: WARNING to BREAKING, CAUTION to DEPRECATED, NOTE to NOTE.

In the non-STE example that follows, the safety instruction is a caution. But if you know about data validation in software systems, you also know that unvalidated input can cause security breaches and data loss. Because there is a risk of security vulnerabilities and data loss here, you must identify this safety instruction as a warning.

Compare the wording in the two code-documentation safety instructions. The non-STE safety instruction is an abstract statement and only makes a general claim. The warning in STE-Code gives clear and correct information about how to decrease the risk of security breaches. The warning contains the words "security breach" and "data loss" to make the reader clearly understand how important this safety instruction is.

### Examples

> *Adapted from spec pair:* Non-STE: `CAUTION: EXTREME CLEANLINESS OF OXYGEN TUBES IS IMPERATIVE.`  |  STE: `WARNING: BEFORE YOU FILL THE LIQUID OXYGEN SYSTEM, PUT ON A FACE MASK AND PROTECTIVE CLOTHING. LIQUID OXYGEN CAN CAUSE IRRITATION OF THE RESPIRATORY TRACT AND EYE IRRITATION.` (ASD-STE100 Issue 9, Rule 7.1, page 99 — escalated from CAUTION to WARNING because the true risk is injury or death.)

> **Non-STE:** CAUTION: ALWAYS VALIDATE INPUT DATA.
>
> **STE:** WARNING: BEFORE YOU PROCESS INPUT DATA, MAKE SURE THAT YOU SANITIZE AND VALIDATE THE DATA. UNSANITIZED INPUT CAN CAUSE SECURITY BREACHES AND DATA LOSS.
>
> *Adapted from the spec pair shown in the Original Rule above: an abstract caution about cleanliness is escalated to a specific warning when the true risk level (injury or death) is higher. The code-domain pair below applies the same escalation. A vague caution about input becomes a warning that names the security breach and data loss risk.*

> **Non-STE:** CAUTION: THE CONFIGURATION FILE MAY CONTAIN OUTDATED SETTINGS.
>
> **STE:** CAUTION: BEFORE YOU DEPLOY THE APPLICATION, COMPARE THE CONFIGURATION FILE AGAINST THE REFERENCE CONFIGURATION. OUTDATED SETTINGS CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.
>
> *Code-domain CAUTION example — risk of unexpected behavior and incorrect results, not security or data loss.*

> **See also:** Rule 5.3 — Imperative (Command) Form for Instructions; Rule 7.2 — Start a Safety Instruction with a Clear and Accurate Command or Condition

---

## Code-Domain Explanation

This rule applies to all code documentation types. Each type has a different level of exposure to security risks, data loss, and unexpected behavior. Use the correct signal word for the risk level. Do not let the signal word become routine noise.

### README Files

README files are the first document a user reads. Use WARNING for security-critical setup steps. Use CAUTION for configuration steps that can cause incorrect behavior. Place signal words at the top of the relevant section. Do not bury them in a paragraph.

**WARNING in a README setup section:**

> **Non-STE:** Note: you should be careful with the API key and not commit it to version control.
>
> **STE:** WARNING: DO NOT COMMIT THE API KEY TO VERSION CONTROL. AN EXPOSED API KEY CAN CAUSE UNAUTHORIZED ACCESS AND DATA LOSS.
>
> *Principles applied: P1, P2 — "warning" for security risk, imperative command, specific consequence*

**CAUTION in a README configuration section:**

> **Non-STE:** Make sure the port number does not conflict with other services or the app won't start.
>
> **STE:** CAUTION: BEFORE YOU START THE APPLICATION, CHECK THAT THE PORT NUMBER DOES NOT CONFLICT WITH OTHER SERVICES. A PORT CONFLICT CAN CAUSE THE APPLICATION TO FAIL.
>
> *Principles applied: P9, P11 — clear signal word, specific condition, specific consequence*

### API Documentation

API documentation describes functions that external callers use. Use WARNING for endpoints that handle sensitive data, authentication, or destructive operations. Use CAUTION for endpoints that have side effects or rate limits.

**WARNING for a destructive API endpoint:**

> **Non-STE:** DELETE /users/:id removes the user and all associated data, this cannot be undone.
>
> **STE:** WARNING: DELETE /users/:id REMOVES THE USER AND ALL RELATED DATA PERMANENTLY. THIS OPERATION CANNOT BE UNDONE. VERIFY THE USER ID BEFORE YOU SEND THE REQUEST.
>
> *Principles applied: P1, P5 — warning for irreversible data loss, technical noun preserved in backticks, specific pre-action instruction*

**CAUTION for a rate-limited endpoint:**

> **Non-STE:** This endpoint allows 100 requests per minute, exceeding this will return 429 errors.
>
> **STE:** CAUTION: THE ENDPOINT ALLOWS A MAXIMUM OF 100 REQUESTS PER MINUTE. IF YOU EXCEED THE LIMIT, THE ENDPOINT RETURNS A 429 ERROR. MONITOR THE `X-RateLimit-Remaining` HEADER.
>
> *Principles applied: P1, P12 — caution for incorrect results (429 errors), technical verb "monitor" is allowed*

### Docstrings and Inline Comments

Docstrings describe function contracts. Use WARNING in docstrings when a function can cause security vulnerabilities or data corruption if used incorrectly. Use CAUTION when a function has performance pitfalls or non-obvious side effects.

**WARNING in a Python docstring:**

```python
def execute_sql(query: str, params: tuple = ()) -> list:
    """Run a raw SQL query.

    WARNING: THIS FUNCTION EXECUTES THE QUERY DIRECTLY. SANITIZE ALL
    USER INPUT BEFORE YOU PASS IT TO THIS FUNCTION. UNSANITIZED INPUT
    CAN CAUSE SQL INJECTION ATTACKS AND DATA LOSS.

    Parameters:
        query: The raw SQL query string.
        params: The query parameters. The default is an empty tuple.

    Returns:
        A list of result rows.
    """
```

*Principles applied: P1, P7 — warning for security risk, "sanitize" used as a verb, specific consequence named*

**CAUTION in a JavaScript JSDoc comment:**

```javascript
/**
 * Caches the result of an expensive computation.
 *
 * CAUTION: THE CACHE USES MEMORY PROPORTIONAL TO THE NUMBER OF
 * UNIQUE ARGUMENTS. FOR UNBOUNDED INPUT SETS, USE A CACHE WITH
 * A SIZE LIMIT. AN UNLIMITED CACHE CAN CAUSE MEMORY EXHAUSTION.
 *
 * @param {Function} fn - The function to cache.
 * @returns {Function} A cached version of the function.
 */
function memoize(fn) {
  const cache = new Map();
  return function (...args) {
    const key = JSON.stringify(args);
    if (cache.has(key)) {
      return cache.get(key);
    }
    const result = fn.apply(this, args);
    cache.set(key, result);
    return result;
  };
}
```

*Principles applied: P1, P13 — caution for performance degradation (memory exhaustion), "cache" used as noun not verb*

### Commit Messages

Commit messages can use WARNING or CAUTION as the commit type prefix. Use `WARNING:` for commits that fix security vulnerabilities or prevent data loss. Use `CAUTION:` for commits that change behavior in a way that downstream consumers must know about. This convention helps automated changelog tools group commits by severity.

> **Non-STE:** fix: patch SQL injection in login form
>
> **STE:** WARNING: Prevent SQL injection in the login form. The previous code did not sanitize the `username` parameter. This vulnerability could permit unauthorized database access.
>
> *Principles applied: P1, P14 — warning for security breach risk, American English spelling*

> **Non-STE:** change: update default timeout from 30s to 10s
>
> **STE:** CAUTION: Change the default timeout from 30 seconds to 10 seconds. Update all callers that rely on the previous default. The shorter timeout can cause connection failures in high-latency environments.
>
> *Principles applied: P1 — caution for unexpected behavior, specific instruction for callers*

### Error Messages

Error messages are read during incidents. Use WARNING in error messages when the system detects a condition that can lead to security compromise or data corruption. Use CAUTION when the system detects a condition that can lead to incorrect results. Error messages must be actionable.

**WARNING in an error message:**

> **Non-STE:** Error: invalid signature
>
> **STE:** WARNING: THE REQUEST SIGNATURE IS NOT VALID. THE REQUEST MAY HAVE BEEN TAMPERED WITH. REJECT THE REQUEST. CHECK YOUR SIGNING KEY AND ALGORITHM.
>
> *Principles applied: P1, P9 — warning for security risk, short clear sentences, actionable instruction*

**CAUTION in an error message:**

> **Non-STE:** The configuration value for max_connections must be less than database pool size.
>
> **STE:** CAUTION: THE `max_connections` VALUE IS GREATER THAN THE `pool_size` VALUE. THIS CONFIGURATION CAN CAUSE CONNECTION FAILURES. SET `max_connections` TO A VALUE THAT IS NOT MORE THAN `pool_size`.
>
> *Principles applied: P1, P11 — caution for incorrect results, one term per concept, actionable correction*

---

## Paradigm-Specific Guidance

### Object-Oriented (Java, C++, C#, Python Classes)

Object-oriented documentation describes class contracts, inheritance hierarchies, and mutable state. Use WARNING when a subclass override can break a security invariant. Use CAUTION when a method mutates shared state.

**WARNING for a security-sensitive override (Java):**

> **Non-STE:** Subclasses should be careful to call super.validate() before performing custom validation.
>
> **STE:** WARNING: OVERRIDE THE `validate` METHOD WITH CARE. CALL `super.validate()` BEFORE YOU ADD CUSTOM VALIDATION LOGIC. IF YOU SKIP THE BASE VALIDATION, UNTRUSTED DATA CAN BYPASS SECURITY CHECKS.
>
> *Principles applied: P1, P7 — warning for security risk, "call" used as imperative verb, specific consequence*

```java
abstract class RequestValidator {
    /** Base security checks that apply to all request types. */
    void validate(Request request) {
        if (request.getUser() == null) {
            throw new SecurityException("Missing user context");
        }
        if (!request.isAuthenticated()) {
            throw new SecurityException("Request is not authenticated");
        }
    }
}

class PaymentRequestValidator extends RequestValidator {
    @Override
    void validate(Request request) {
        // WARNING: CALL super.validate() BEFORE YOU ADD CUSTOM LOGIC.
        super.validate();
        PaymentRequest payment = (PaymentRequest) request;
        if (payment.getAmount() <= 0) {
            throw new IllegalArgumentException("Amount must be greater than zero");
        }
    }
}
```

*The `PaymentRequestValidator.validate` method shows the correct override: it calls `super.validate()` first, so the base security checks (user context and authentication) still run. If a developer removes that call, an untrusted request can bypass the checks and reach the payment logic.*

**CAUTION for mutable shared state (C++):**

> **Non-STE:** Note that this method modifies the internal cache which may affect other threads.
>
> **STE:** CAUTION: THE `invalidateCache` METHOD MODIFIES THE INTERNAL CACHE. THIS CHANGE AFFECTS ALL THREADS THAT USE THE CACHE. USE A LOCK BEFORE YOU CALL THIS METHOD.
>
> *Principles applied: P1, P5 — caution for unexpected behavior in concurrent contexts, technical noun "thread" allowed, specific guard instruction*

### Functional (Haskell, Elixir, Clojure, Rust)

Functional documentation describes pure functions, effect types, and immutable data. Use WARNING when an unsafe escape hatch breaks referential transparency. Use CAUTION when a lazy operation can cause space leaks.

**WARNING for unsafe escape hatches (Haskell):**

> **Non-STE:** Use unsafePerformIO with caution as it breaks purity.
>
> **STE:** WARNING: `unsafePerformIO` BYPASSES THE IO TYPE SYSTEM. THIS FUNCTION HIDES SIDE EFFECTS IN PURE CODE. INCORRECT USE CAN CAUSE NONDETERMINISTIC BEHAVIOR AND DATA CORRUPTION. USE THIS FUNCTION ONLY WHEN NO SAFE ALTERNATIVE EXISTS.
>
> *Principles applied: P1, P8 — warning for data corruption risk, standard technical noun preserved, clear prohibition*

**CAUTION for space leaks (Haskell):**

> **Non-STE:** foldl is strict, but if you accumulate large thunks you might run out of memory.
>
> **STE:** CAUTION: `foldl` ACCUMULATES UNEVALUATED EXPRESSIONS (THUNKS). A LARGE ACCUMULATOR CAN CAUSE A SPACE LEAK AND MEMORY EXHAUSTION. USE `foldl'` FOR STRICT ACCUMULATION.
>
> *Principles applied: P1, P9 — caution for performance degradation, alternative provided, short clear sentences*

### Procedural (C, Go, Bash)

Procedural documentation describes memory management, buffer handling, and system calls. Use WARNING for buffer overflows, use-after-free, and undefined behavior. Use CAUTION for platform-specific behavior or resource limits.

**WARNING for buffer overflow (C):**

> **Non-STE:** Make sure the destination buffer is at least as large as the source string when using strcpy.
>
> **STE:** WARNING: `strcpy` DOES NOT CHECK THE SIZE OF THE DESTINATION BUFFER. IF THE SOURCE STRING IS LARGER THAN THE DESTINATION BUFFER, THE FUNCTION WRITES PAST THE BUFFER BOUNDARY. THIS BUFFER OVERFLOW CAN CAUSE SECURITY VULNERABILITIES AND SYSTEM CRASHES. USE `strncpy` WITH A SIZE LIMIT.
>
> *Principles applied: P1, P8 — warning for security risk and system corruption, standard technical noun, alternative provided*

**CAUTION for platform-specific behavior (Go):**

> **Non-STE:** On Windows, filepath separator is backslash, be careful with cross-platform paths.
>
> **STE:** CAUTION: THE `filepath` PACKAGE USES THE OPERATING SYSTEM PATH SEPARATOR. ON WINDOWS, THE SEPARATOR IS `\\`. ON UNIX, THE SEPARATOR IS `/`. USE `filepath.Join` OR `filepath.FromSlash` TO BUILD CROSS-PLATFORM PATHS. HARDCODED SEPARATORS CAUSE INCORRECT PATHS.
>
> *Principles applied: P1, P11 — caution for incorrect results, one term per concept, specific code examples*

### Declarative (SQL, Terraform, Kubernetes YAML)

Declarative documentation describes desired state, resource specifications, and destructive operations. Use WARNING for operations that destroy data or expose resources publicly. Use CAUTION for configuration values that have subtle effects on behavior.

**WARNING for destructive SQL operations:**

> **Non-STE:** Caution: this migration drops the users table.
>
> **STE:** WARNING: THIS MIGRATION DROPS THE `users` TABLE. ALL USER DATA IS DELETED PERMANENTLY. BACK UP THE DATABASE BEFORE YOU RUN THIS MIGRATION. VERIFY THAT YOU RUN THE MIGRATION AGAINST THE CORRECT DATABASE.
>
> *Principles applied: P1, P5 — warning for irreversible data loss, technical noun in backticks, multiple pre-action checks*

**CAUTION for Terraform resource recreation:**

> **Non-STE:** Changing the subnet_id will cause the EC2 instance to be recreated, which may cause downtime.
>
> **STE:** CAUTION: IF YOU CHANGE THE `subnet_id` ARGUMENT, TERRAFORM DESTROYS THE EXISTING EC2 INSTANCE AND CREATES A NEW ONE. THIS RECREATION CAUSES DOWNTIME. THE INSTANCE PUBLIC IP ADDRESS CHANGES. PLAN THE CHANGE DURING A MAINTENANCE WINDOW.
>
> *Principles applied: P1, P12 — caution for unexpected behavior and downtime, "plan" used as approved verb, specific consequences listed*

**WARNING for public Kubernetes exposure:**

> **Non-STE:** Be careful with LoadBalancer type services as they expose your app to the internet.
>
> **STE:** WARNING: A SERVICE OF TYPE `LoadBalancer` EXPOSES THE APPLICATION TO THE PUBLIC INTERNET. UNAUTHORIZED USERS CAN SEND REQUESTS TO THE APPLICATION. MAKE SURE THAT AUTHENTICATION AND NETWORK POLICIES ARE IN PLACE BEFORE YOU APPLY THIS CONFIGURATION.
>
> *Principles applied: P1, P7 — warning for security risk, "apply" used as imperative verb, specific pre-condition check*

### Systems (Rust Ownership, C Memory)

Systems documentation describes ownership, unsafe blocks, and memory layout. Use WARNING for undefined behavior, data races, and memory corruption. Use CAUTION for performance characteristics of unsafe optimizations.

**WARNING for undefined behavior (Rust):**

> **Non-STE:** Dereferencing a raw pointer is unsafe and may cause undefined behavior if the pointer is invalid.
>
> **STE:** WARNING: DEREFERENCING A RAW POINTER CAN CAUSE UNDEFINED BEHAVIOR. UNDEFINED BEHAVIOR CAN CORRUPT MEMORY, CAUSE SECURITY VULNERABILITIES, AND CRASH THE PROGRAM. BEFORE YOU DEREFERENCE A RAW POINTER, CHECK THAT: (1) THE POINTER IS NOT NULL. (2) THE POINTER IS CORRECTLY ALIGNED. (3) THE POINTER POINTS TO VALID, INITIALIZED MEMORY.
>
> *Principles applied: P1, P4 — warning for system corruption and security, vertical list for preconditions, explicit checklist*

**CAUTION for unsafe optimization tradeoffs:**

> **Non-STE:** Using MaybeUninit can improve performance but be careful about initialization.
>
> **STE:** CAUTION: `MaybeUninit` SKIPS INITIALIZATION TO IMPROVE PERFORMANCE. IF YOU READ UNINITIALIZED MEMORY, THE PROGRAM BEHAVIOR IS UNDEFINED. MAKE SURE THAT YOU INITIALIZE THE VALUE BEFORE YOU READ IT. MEASURE THE PERFORMANCE GAIN BEFORE YOU USE THIS TYPE.
>
> *Principles applied: P1, P9 — caution for incorrect results (undefined behavior is also a WARNING-level risk, but the primary risk here is the subtlety of the contract), specific guard instruction*

---

## Extended Examples

### Example 1 — Misclassified Risk Level in API Key Documentation

> **Non-STE:** CAUTION: Store the API key in an environment variable.
>
> **STE:** WARNING: STORE THE API KEY IN AN ENVIRONMENT VARIABLE. DO NOT HARDCODE THE API KEY IN THE SOURCE CODE. AN EXPOSED API KEY CAN CAUSE UNAUTHORIZED ACCESS, DATA THEFT, AND SERVICE ABUSE. ADD THE `.env` FILE TO `.gitignore`.
>
> *Principles applied: P1 — the original used CAUTION for a security risk (exposed credentials). Escalated to WARNING. Specific consequences named. Actionable prevention steps.*

### Example 2 — Missing Consequence in Database Migration Documentation

> **Non-STE:** WARNING: Run this migration carefully.
>
> **STE:** WARNING: BEFORE YOU RUN THIS MIGRATION, BACK UP THE `transactions` TABLE. THE MIGRATION REMOVES ALL RECORDS OLDER THAN 90 DAYS. THE DATA CANNOT BE RECOVERED AFTER THE MIGRATION COMPLETES. VERIFY THE DATE THRESHOLD AGAINST YOUR RETENTION POLICY.
>
> *Principles applied: P1, P9 — the original warning has no specific consequence and no actionable instruction. The STE version names the consequence (irrecoverable data loss), gives a pre-action check, and links to a policy reference.*

### Example 3 — Abstract Caution in a Library README

> **Non-STE:** CAUTION: Be mindful of thread safety when using this library.
>
> **STE:** CAUTION: THE `Cache` CLASS IS NOT THREAD-SAFE. IF YOU SHARE A `Cache` INSTANCE ACROSS THREADS, RACE CONDITIONS CAN CAUSE INCORRECT CACHE ENTRIES AND APPLICATION CRASHES. USE `ConcurrentCache` FOR MULTI-THREADED APPLICATIONS. USE A MUTEX FOR MANUAL SYNCHRONIZATION.
>
> *Principles applied: P1, P8 — the original caution is abstract and does not give a specific risk or a fix. The STE version names the class, explains the risk, and gives two alternatives.*

### Example 4 — Wrong Signal Word for Performance Degradation

> **Non-STE:** WARNING: This function is slow for large inputs.
>
> **STE:** CAUTION: THIS FUNCTION HAS O(N²) TIME COMPLEXITY. FOR INPUTS LARGER THAN 10,000 ITEMS, THE FUNCTION CAN TAKE SEVERAL MINUTES TO COMPLETE. USE `fastSort` FOR LARGE INPUTS. `fastSort` HAS O(N LOG N) TIME COMPLEXITY.
>
> *Principles applied: P1, P9 — performance degradation is a CAUTION-level risk, not a WARNING. The original used WARNING incorrectly. The STE version downgrades to CAUTION, explains the complexity, gives a threshold, and provides an alternative.*

### Example 5 — Missing Signal Word in Environment Variable Documentation

> **Non-STE:** The DEBUG_MODE environment variable controls verbose logging. Setting it to true in production will leak sensitive information.
>
> **STE:** WARNING: DO NOT SET `DEBUG_MODE=true` IN A PRODUCTION ENVIRONMENT. DEBUG MODE WRITES SENSITIVE DATA TO THE LOG OUTPUT. THIS DATA INCLUDES REQUEST BODIES, AUTHENTICATION TOKENS, AND DATABASE QUERIES. AN ATTACKER WITH LOG ACCESS CAN STEAL USER CREDENTIALS.
>
> *Principles applied: P1 — the original has no signal word at all. The risk (data leak, credential theft) is a security vulnerability. A WARNING is required. The STE version adds the signal word, explains the data at risk, and names the attacker threat.*

### Example 6 — Mixed Risk Levels in a Single Callout

> **Non-STE:** CAUTION: The reset method clears the database and disables authentication, only use in development.
>
> **STE:** WARNING: THE `reset` METHOD CLEARS THE DATABASE AND DISABLES AUTHENTICATION. IF YOU CALL THIS METHOD IN A PRODUCTION ENVIRONMENT, ALL USER DATA IS DELETED AND ALL REQUESTS BYPASS AUTHENTICATION. THIS METHOD IS FOR DEVELOPMENT USE ONLY. CHECK THE `NODE_ENV` VARIABLE BEFORE YOU CALL THIS METHOD.
>
> *Principles applied: P1 — the original has two risks together: data loss (WARNING level) and disabled auth (WARNING level). When two WARNING-level risks exist together, use WARNING. The original used CAUTION incorrectly. The STE version escalates to WARNING, names both consequences, and adds an environment check.*

---

## Edge Cases

### Edge Case 1 — When a Framework or Language Feature Uses "Warning" as a Name

Some programming languages and frameworks use "Warning" as a type or module name (for example, Python's `warnings` module, Rust's `#[allow(warnings)]`, JavaScript's `console.warn()`). When the word "Warning" appears as a technical code noun, put it in backticks. When it appears as a risk signal word, use uppercase WARNING without backticks.

> **Non-STE:** Warning: the warnings module suppresses warnings by default.
>
> **STE:** CAUTION: THE `warnings` MODULE SUPPRESSES WARNINGS BY DEFAULT. THE OUTPUT FROM `warn()` CALLS IS NOT SHOWN. CALL `warnings.simplefilter('always')` TO SHOW ALL WARNINGS.
>
> *The risk is unexpected behavior (suppressed output), so CAUTION is the correct signal word. The `warnings` module name is in backticks. The signal word WARNING is not used here because that would conflict with the module name and cause confusion.*

### Edge Case 2 — When a Third-Party Library Uses a Different Risk Convention

Third-party libraries may use their own signal word conventions (for example, `DANGER`, `CRITICAL`, `IMPORTANT`, `NOTE`). When you document a third-party API in your project, translate their convention to STE-Code signal words. Do not replicate the third-party convention directly.

> **Third-party convention:** DANGER: This operation is irreversible.
>
> **STE-Code translation:** WARNING: THIS OPERATION IS IRREVERSIBLE. THE DATA CANNOT BE RECOVERED AFTER THE OPERATION COMPLETES. BACK UP THE DATA BEFORE YOU START.
>
> *The third party uses DANGER. STE-Code uses WARNING for irreversible data loss. Translate the signal word and add the specific consequence and pre-action instruction.*

### Edge Case 3 — Generated Code with Auto-Inserted Warnings

Generated code (from tools such as `protoc`, `graphql-codegen`, or OpenAPI generators) may insert WARNING or CAUTION comments automatically. These generated comments are not under your control. For generated code:

- Do not modify the generated comments. The generator may overwrite your changes.
- Add your own STE-Code WARNING or CAUTION in the documentation that wraps the generated code.
- If the generated warning misclassifies the risk level, open an issue with the generator project.

> **Generated (leave as-is):** // CAUTION: This method is deprecated.
>
> **Your wrapper documentation:** WARNING: THE `legacy/client.go` FILE CONTAINS DEPRECATED METHODS. DEPRECATED METHODS MAY BE REMOVED IN A FUTURE VERSION. THE REMOVAL OF THESE METHODS CAN BREAK YOUR APPLICATION. MIGRATE TO THE `v2/client.go` API.
>
> *The generated comment remains. Your documentation adds the correct signal word (WARNING, because removal of used methods is a BREAKING risk).*

### Edge Case 4 — When a BREAKING Change Overlaps with a WARNING

BREAKING changes and WARNING-level risks often occur together. When a breaking change also introduces a security risk or data loss risk, use WARNING and mention the breaking nature in the body. Do not use two signal words.

> **Non-STE:** BREAKING: WARNING: The encrypt function now requires a key parameter.
>
> **STE:** WARNING: THE `encrypt` FUNCTION NOW REQUIRES A `key` PARAMETER. THIS IS A BREAKING CHANGE. UPDATE ALL CALLERS TO PASS A KEY ARGUMENT. IF YOU DO NOT PASS A KEY, THE FUNCTION THROWS AN ERROR AND THE DATA IS NOT ENCRYPTED.
>
> *WARNING is used because unencrypted data is a security risk. The breaking nature is mentioned in the body, not as a competing signal word. The consequence of ignoring the warning is stated explicitly.*

### Edge Case 5 — Internationalization of Warning and Caution Strings

When your documentation is translated to other languages, the signal words WARNING and CAUTION must also be translated. Use the standard translation for these words in each target language. Do not invent new signal words per language. Maintain a glossary of translated signal words.

The signal word must remain visually distinct. Use the same formatting rules across all languages:

- Uppercase letters for the signal word.
- A colon (:) after the signal word.
- A space before the instruction text.

**STE-Code signal word glossary (example):**

| Language | WARNING | CAUTION |
|----------|---------|---------|
| English | WARNING | CAUTION |
| Spanish | ADVERTENCIA | PRECAUCIÓN |
| French | AVERTISSEMENT | ATTENTION |
| German | WARNUNG | VORSICHT |
| Japanese | 警告 | 注意 |

*For each new language, add the translation to the glossary. Use the same signal word consistently across all documentation in that language.*

---

## Cross-References

- **Rule 1.1** — Use approved words from the STE-Code dictionary. "Warning" and "caution" are approved signal words. Do not invent new signal words.
- **Rule 1.4** — Use only approved verb forms and adjective forms. A safety instruction must start with an approved verb (for example, "check," "make sure," "do not").
- **Rule 1.6** — Non-approved words are not permitted. Do not use non-approved words inside a WARNING or CAUTION instruction.
- **Rule 1.10** — No slang, jargon, or regional terms. Use standard signal words. Do not use slang signal words (for example, "heads up," "watch out").
- **Rule 1.11** — One term per concept. Use WARNING and CAUTION consistently across all documentation. Do not mix signal word conventions from different sources.
- **Rule 4.1** — Write short and clear sentences. Each WARNING or CAUTION instruction must be a short, clear imperative sentence.
- **Rule 4.2** — Use the active voice. Safety instructions must use the active voice to give clear commands.
- **Rule 5.3** — Use the imperative (command) form for instructions. A WARNING or CAUTION is a safety instruction. The body must use the imperative mood.
- **Rule 5.4** — Write each step as a command. Each action inside a WARNING or CAUTION is a step. Write each step as a command.
- **Rule 7.2** — Start a safety instruction with a clear and accurate command or condition. The sentence that follows the signal word must give a clear command or state a clear condition.
- **Rule 7.3** — Give a clear consequence in the safety instruction. The consequence must use the words that name the risk level (for example, "security breach," "data loss," "unexpected behavior").
- **Section 1 (Vocabulary)** — All words used in WARNING and CAUTION instructions must come from the approved vocabulary unless they are technical code nouns.
- **Section 5 (Procedural Writing)** — WARNING and CAUTION instructions are procedural. Follow all procedural writing rules.

---

## Grammar Notes

### Signal Word Placement

The signal word (WARNING or CAUTION) must be the first word of the safety instruction. Put the signal word at the start of the line. Do not indent the signal word. Do not put text before the signal word.

> **Correct placement:** WARNING: DO NOT SHARE THE PRIVATE KEY.
>
> **Incorrect placement:** Important: WARNING: DO NOT SHARE THE PRIVATE KEY.

The signal word is followed by a colon (:) and a single space. The instruction text starts after the space. The colon is part of the signal word format, not part of the instruction sentence.

### Uppercase Convention

Write the signal word in uppercase letters. This convention makes the signal word visually distinct from the body text. The uppercase is part of the signal, not emphasis. Do not write the signal word in lowercase or title case.

> **Correct:** WARNING: The operation is destructive.
> **Incorrect:** Warning: The operation is destructive.
> **Incorrect:** warning: The operation is destructive.

The instruction text after the signal word can use standard sentence case. The first word of the instruction is uppercase (as the start of a sentence). The rest of the instruction uses standard capitalization.

### Sentence Structure After the Signal Word

The sentence that follows the signal word must include three parts:

1. **A clear command or condition** — What the reader must do or must check.
2. **A clear consequence** — What happens if the reader ignores the instruction.
3. **A clear risk escalation** — How the consequence maps to the risk level (security, data loss, unexpected behavior).

These three parts can be in one sentence or across multiple sentences. The parts must appear in this order. The reader must understand the risk before acting.

> **Structure:** WARNING: [COMMAND/CONDITION]. [CONSEQUENCE]. [RISK ESCALATION].
>
> **Example:** WARNING: DO NOT COMMIT THE API KEY TO VERSION CONTROL. AN EXPOSED API KEY CAN CAUSE UNAUTHORIZED ACCESS AND DATA LOSS. ADD THE `.env` FILE TO `.gitignore`.

### Verb Form in WARNING and CAUTION Instructions

Use the imperative mood for the command part of the instruction. Use "do not" for prohibitions. Do not use "should," "must," or "needs to."

> **Correct (imperative):** CHECK THE INPUT DATA BEFORE YOU PROCESS IT.
> **Correct (prohibition):** DO NOT USE THIS FUNCTION IN PRODUCTION.
> **Incorrect:** You should check the input data before processing.
> **Incorrect:** The input data must be checked before processing.

For technical verbs that have specific meanings in the code domain (for example, "sanitize," "validate," "encrypt," "back up"), use them as verbs in the imperative mood. These are approved technical verbs under Rule 1.12.

### Risk Escalation Vocabulary

Use these approved nouns to describe the risk consequence in WARNING instructions:

- Security breach
- Data loss
- System corruption
- Unauthorized access
- Credential theft
- Data leak
- Privilege escalation

Use these approved nouns to describe the risk consequence in CAUTION instructions:

- Unexpected behavior
- Performance degradation
- Incorrect results
- Connection failure
- Memory exhaustion
- Application crash
- Configuration drift

Do not use vague nouns such as "problems," "issues," or "trouble." Name the specific risk.

### Visual Distinction

In rendered documentation (HTML, PDF, Markdown), the signal word must be visually distinct. Use bold formatting, color, or a border to make the signal word stand out. Do not rely only on the uppercase text. Some readers scan visually. The formatting must catch the eye before the text is read.

```
> **WARNING:** Do not expose the private key. An exposed key can cause unauthorized access.
```

*In Markdown, use a blockquote with bold formatting for the signal word. In HTML, use a `<div>` with a CSS class. In reStructuredText, use an admonition directive (`.. WARNING::`). Choose the format that your documentation generator supports.*

---

## Summary Checklist

Before you publish code documentation that contains WARNING or CAUTION instructions, check each safety instruction:

- [ ] The signal word (WARNING or CAUTION) is correct for the risk level.
- [ ] Security, data loss, or system corruption risks use WARNING.
- [ ] Unexpected behavior, performance, or incorrect result risks use CAUTION.
- [ ] Mixed risk levels with one WARNING-level risk use WARNING.
- [ ] The signal word is the first word of the instruction.
- [ ] The signal word is in uppercase.
- [ ] The signal word is followed by a colon and a space.
- [ ] The instruction gives a clear command or condition.
- [ ] The instruction gives a clear consequence.
- [ ] The consequence names the specific risk (not "problems" or "issues").
- [ ] The instruction uses the imperative mood (not "you should").
- [ ] The instruction is not abstract. It gives concrete actions.
- [ ] Technical code nouns are in backticks.
- [ ] No non-approved words are used in the instruction.
- [ ] No competing signal words from third-party conventions are mixed in.
- [ ] The signal word is visually distinct from body text.

---

<!-- a-sec7-rule7.2.md -->

# Rule 7.2 — Start a Safety Instruction with a Clear and Accurate Command or Condition

> **Source:** Adapted from ASD-STE100 Issue 9, Rule 7.2

> **Source:** [master.md#sec7-rule7.2](ste-code/grouped/)

## Original Rule

**Rule 7.2** Start a safety instruction with a clear and accurate command or condition. Your reader must know how to prevent accidents and keep a high level of safety.

If your reader must know about a condition before the start of a procedure or work step, give this condition first.

**Spec examples:**

(Refer to the underlined command.)

> **WARNING:** DO NOT SWALLOW THE SOLVENT. ALWAYS MAKE SURE THAT YOU KNOW THE SAFETY PRECAUTIONS AND FIRST AID INSTRUCTIONS FOR SOLVENTS. SOLVENTS ARE POISONOUS AND CAN CAUSE INJURY OR DEATH.

> **CAUTION:** DO NOT USE BLEACH OR CLEANSERS THAT CONTAIN CHLORINE TO CLEAN THE UNIT. THESE CLEANING AGENTS CAN CAUSE CORROSION.

(Refer to the underlined condition.)

> IF THEY FALL, PERMANENT DAMAGE TO THE PARTS CAN OCCUR.

## STE-Code Adaptation

**Rule 7.2** In code documentation, start a safety instruction with a clear and accurate command or condition. Your reader must know how to prevent security vulnerabilities, data loss, and system failures.

If your reader must know about a condition before they use a function, method, or API, give this condition first.

Severity mapping: The command or condition in a safety instruction carries the severity from Rule 7.1. In release notes and changelogs, the same levels map as follows: WARNING to BREAKING, CAUTION to DEPRECATED, NOTE to NOTE.

### Examples

> *Adapted from spec pair:* Non-STE: `STORING API KEYS IN THE SOURCE CODE IS NOT RECOMMENDED.`  |  STE: `DO NOT STORE API KEYS IN THE SOURCE CODE. ALWAYS USE ENVIRONMENT VARIABLES OR A SECRETS MANAGER TO STORE API KEYS. API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.` (ASD-STE100 Issue 9, Rule 7.2, page 99–100 — the safety instruction starts with a clear command, not a description of the risk.)

> **Non-STE:** WARNING: STORING API KEYS IN THE SOURCE CODE IS NOT RECOMMENDED.

> **STE:** WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. ALWAYS USE ENVIRONMENT VARIABLES OR A SECRETS MANAGER TO STORE API KEYS. API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.

> *Adapted from spec pair: "WARNING: DO NOT SWALLOW THE SOLVENT. ALWAYS MAKE SURE THAT YOU KNOW THE SAFETY PRECAUTIONS AND FIRST AID INSTRUCTIONS FOR SOLVENTS. SOLVENTS ARE POISONOUS AND CAN CAUSE INJURY OR DEATH." — the safety instruction starts with a clear command ("DO NOT STORE") and explains the risk.*

Full runnable form — a Python module that reads credentials from the environment:

```python
import os

# WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. ALWAYS USE
# ENVIRONMENT VARIABLES OR A SECRETS MANAGER TO STORE API KEYS.
# API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND
# DATA BREACHES.
def get_api_client() -> "Client":
    api_key = os.environ.get("PAYMENT_API_KEY")
    if api_key is None:
        raise RuntimeError("PAYMENT_API_KEY is not set in the environment")
    return Client(api_key=api_key)
```

The non-STE version describes an attitude ("is not recommended"). The STE version starts with the command "DO NOT STORE", gives the required alternative, and names the consequence (data breaches).

> **Non-STE:** CAUTION: THE CODEBASE CONTAINS DEPRECATED FUNCTIONS.

> **STE:** CAUTION: DO NOT USE DEPRECATED FUNCTIONS OR METHODS THAT HAVE KNOWN ISSUES. USE THE APPROVED REPLACEMENT FUNCTIONS SPECIFIED IN THE MIGRATION GUIDE. DEPRECATED FUNCTIONS CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.

> *Adapted from spec pair: "CAUTION: DO NOT USE BLEACH OR CLEANSERS THAT CONTAIN CHLORINE TO CLEAN THE UNIT. THESE CLEANING AGENTS CAN CAUSE CORROSION." — the safety instruction starts with a clear command ("DO NOT USE") and explains the risk.*

Full runnable form — a Python deprecation shim that warns and points to the replacement:

```python
import warnings

# CAUTION: DO NOT USE DEPRECATED FUNCTIONS OR METHODS THAT HAVE
# KNOWN ISSUES. USE THE APPROVED REPLACEMENT FUNCTIONS SPECIFIED
# IN THE MIGRATION GUIDE. DEPRECATED FUNCTIONS CAN CAUSE UNEXPECTED
# BEHAVIOR AND INCORRECT RESULTS.
def legacy_send_email(address: str, body: str) -> None:
    warnings.warn(
        "legacy_send_email is deprecated; use send_message() instead",
        DeprecationWarning,
        stacklevel=2,
    )
    send_message(address, body)
```

The non-STE version only reports the presence of deprecated code. The STE version starts with the prohibition "DO NOT USE", names the replacement, and states the consequence (incorrect results).

> **Non-STE:** PERMANENT DATA LOSS CAN OCCUR.

> **STE:** IF YOU DO NOT SET THE CONNECTION TIMEOUT, THE APPLICATION CAN BECOME UNAVAILABLE AND PERMANENT DATA LOSS CAN OCCUR.

> *Adapted from spec pair: "IF THEY FALL, PERMANENT DAMAGE TO THE PARTS CAN OCCUR." — the safety instruction starts with a clear condition ("IF YOU DO NOT SET...") before stating the risk.*

Full runnable form — a Go database client that requires a timeout:

```go
// WARNING: IF YOU DO NOT SET THE CONNECTION TIMEOUT, THE APPLICATION
// CAN BECOME UNAVAILABLE AND PERMANENT DATA LOSS CAN OCCUR.
func NewClient(dsn string) (*Client, error) {
    db, err := sql.Open("postgres", dsn)
    if err != nil {
        return nil, err
    }
    // A zero value means "wait forever"; set a bound.
    db.SetConnMaxLifetime(0)
    db.SetMaxOpenConns(10)
    // Without a timeout the next call can block until the TCP
    // connection is silently dropped, and buffered writes are lost.
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    if err := db.PingContext(ctx); err != nil {
        return nil, err
    }
    return &Client{db: db}, nil
}
```

The non-STE version states only the consequence. The STE version starts with the condition "IF YOU DO NOT SET THE CONNECTION TIMEOUT" so the reader learns when the risk applies.

> **See also:** Rule 5.3 — Imperative (Command) Form for Instructions; Rule 5.4 — Descriptive Statement Before the Command; Rule 7.1 — Use an Applicable Word to Identify the Level of Risk

---

## Code-Domain Explanation

This rule defines the structure of every safety instruction in code documentation. A safety instruction has two parts: a signal word (WARNING or CAUTION, per Rule 7.1) and a body. The body must start with either a clear command or a clear condition. The reader must understand what action to take (or not take) within the first few words.

A safety instruction is complete only when it has all three of these parts:

1. **Signal word** — WARNING or CAUTION (Rule 7.1).
2. **Command or condition** — the first sentence after the colon. This tells the reader what to do, what not to do, or under what condition the risk applies.
3. **Consequence** — the explanation that shows the risk (Rule 7.3). This is what makes the command or condition "accurate": the reader understands why the instruction matters.

If you write the consequence but not the command, the instruction is not actionable. If you write the command but not the consequence, the reader does not know why the command matters. Both the command or condition and the consequence are required.

### Command-First Structure

A command-first safety instruction starts with an imperative verb. The most common command forms in code documentation are:

- **DO NOT [action]** — Prohibit a dangerous action. Example: "DO NOT COMMIT THE `.env` FILE."
- **ALWAYS [action]** — Require a mandatory action. Example: "ALWAYS SANITIZE THE INPUT BEFORE YOU PROCESS IT."
- **[imperative verb]** — Direct the reader to take a specific action (for example, "CHECK," "MAKE SURE," "BACK UP," "SANITIZE," "VALIDATE," "VERIFY").

The command must appear immediately after the signal word and colon. The reader must not read through background information before learning what to do. Use approved verbs: prefer "use," "check," "make," "get," "set," "send," "remove," "keep," "start," "stop," "show," "do" over "utilize," "leverage," "employ," "commence," "terminate," "initiate."

**Command-first WARNING — README file:**

> **Non-STE:** WARNING: It is important to consider that hardcoding database credentials in the configuration file can lead to serious security issues if the file is committed to version control.

> **STE:** WARNING: DO NOT HARDCODE DATABASE CREDENTIALS IN THE CONFIGURATION FILE. STORE CREDENTIALS IN A SECRETS MANAGER OR ENVIRONMENT VARIABLES. HARDCODED CREDENTIALS IN VERSION CONTROL CAN CAUSE UNAUTHORIZED DATABASE ACCESS.

> *Principles applied: P1, P9 — the command "DO NOT HARDCODE" starts the instruction. The reader knows the prohibition in the first three words.*

Full runnable form — a `.env.example` and a load step:

```bash
# .env.example  (copy to .env and fill in real values)
# WARNING: DO NOT HARDCODE DATABASE CREDENTIALS IN THE CONFIGURATION
# FILE. STORE CREDENTIALS IN A SECRETS MANAGER OR ENVIRONMENT VARIABLES.
# HARDCODED CREDENTIALS IN VERSION CONTROL CAN CAUSE UNAUTHORIZED
# DATABASE ACCESS.
DATABASE_URL=postgres://user:password@localhost:5432/app
```

```python
import os
# Reads DATABASE_URL from the environment, never from a committed file.
db = connect(os.environ["DATABASE_URL"])
```

**Command-first CAUTION — API documentation:**

> **Non-STE:** CAUTION: The `/search` endpoint returns results from a cache that is updated every 5 minutes, so recent changes may not be reflected immediately.

> **STE:** CAUTION: BEFORE YOU USE THE `/search` ENDPOINT, READ THE CACHE STALENESS NOTE. THE CACHE IS UPDATED EVERY 5 MINUTES. RECENT CHANGES ARE NOT VISIBLE UNTIL THE NEXT CACHE UPDATE. DO NOT USE THIS ENDPOINT FOR REAL-TIME DATA.

> *Principles applied: P1, P2 — the condition "BEFORE YOU USE" starts the instruction. The reader knows the prerequisite before the explanation.*

Full runnable form — an OpenAPI operation object:

```yaml
/search:
  get:
    summary: Search the catalog
    # CAUTION: BEFORE YOU USE THE `/search` ENDPOINT, READ THE CACHE
    # STALENESS NOTE. THE CACHE IS UPDATED EVERY 5 MINUTES. RECENT
    # CHANGES ARE NOT VISIBLE UNTIL THE NEXT CACHE UPDATE. DO NOT USE
    # THIS ENDPOINT FOR REAL-TIME DATA.
    description: >
      Results come from a cache that refreshes on a 5-minute interval.
      Do not poll this endpoint for live status; subscribe to the
      webhook stream instead.
    responses:
      '200':
        description: Cached search results
```

### Condition-First Structure

A condition-first safety instruction starts with a subordinate clause that describes the prerequisite the reader must know. The most common condition forms are:

- **IF [condition]...** — State the unsafe condition before the consequence. Example: "IF YOU DISABLE TLS, THE TRAFFIC IS IN CLEAR TEXT."
- **BEFORE YOU [action]...** — Require a pre-action check. Example: "BEFORE YOU RUN THE MIGRATION, BACK UP THE DATABASE."
- **WHEN [condition]...** — Describe a scenario that triggers the risk. Example: "WHEN THE QUEUE IS FULL, THE PUBLISH CALL BLOCKS."

The condition must come first. The consequence comes second. The reader must understand the context before learning the result. Use the active voice in the condition: "IF YOU DO NOT SET..." not "IF THE TIMEOUT IS NOT SET..."

**Condition-first WARNING — docstring:**

> **Non-STE:** WARNING: The database connection may not be initialized if you call this function before `connect()` has completed.

> **STE:** WARNING: IF YOU CALL THIS FUNCTION BEFORE `connect()` COMPLETES, THE DATABASE CONNECTION IS NOT INITIALIZED. THE FUNCTION RETURNS `null` AND YOUR APPLICATION CAN CRASH. CALL `connect()` AND WAIT FOR THE PROMISE BEFORE YOU USE THIS FUNCTION.

> *Principles applied: P1, P10 — the condition "IF YOU CALL THIS FUNCTION BEFORE" starts the instruction. The reader learns the prerequisite scenario first. The consequence follows.*

Full runnable form — a JavaScript class with an explicit precondition:

```javascript
class Repository {
  /**
   * WARNING: IF YOU CALL THIS FUNCTION BEFORE `connect()` COMPLETES,
   * THE DATABASE CONNECTION IS NOT INITIALIZED. THE FUNCTION RETURNS
   * `null` AND YOUR APPLICATION CAN CRASH. CALL `connect()` AND WAIT
   * FOR THE PROMISE BEFORE YOU USE THIS FUNCTION.
   *
   * @param {number} id
   * @returns {Promise<Row|null>}
   */
  async getById(id) {
    if (!this.db) return null; // connection not ready
    return this.db.query("SELECT * FROM rows WHERE id = $1", [id]);
  }

  async connect() {
    this.db = await createPool();
  }
}
```

**Condition-first CAUTION — commit message:**

> **Non-STE:** CAUTION: The CI pipeline will fail if the `NODE_ENV` variable is not set to `production` during the release build.

> **STE:** CAUTION: WHEN YOU RUN THE RELEASE BUILD, SET `NODE_ENV=production`. IF YOU DO NOT SET THIS VARIABLE, THE CI PIPELINE FAILS. THE DEPLOYMENT STOPS UNTIL THE VARIABLE IS SET.

> *Principles applied: P1, P12 — the condition "WHEN YOU RUN THE RELEASE BUILD" starts the instruction. The command follows. The consequence is explained.*

Full runnable form — a commit body that changelog tools can parse:

```text
CAUTION: Change the build to require NODE_ENV in the release job.

WHEN YOU RUN THE RELEASE BUILD, SET NODE_ENV=production. IF YOU DO
NOT SET THIS VARIABLE, THE CI PIPELINE FAILS. THE DEPLOYMENT STOPS
UNTIL THE VARIABLE IS SET.

- Add NODE_ENV=production to .github/workflows/release.yml
- Add a guard that fails fast when the variable is missing
```

### Documentation Type Differences

**README files:** Safety instructions in README files are read before the user sets up the project. Use command-first for prohibitions (for example, "DO NOT COMMIT"). Use condition-first for prerequisites (for example, "BEFORE YOU RUN THE BUILD").

**API documentation:** Safety instructions in API docs are read by external consumers. Use command-first for destructive operations. Use condition-first for preconditions that depend on application state.

**Docstrings:** Safety instructions in docstrings are read by developers who use the function. Use command-first for function contract violations. Use condition-first for argument preconditions that are not enforced by the type system.

**Commit messages:** Safety instructions in commit messages are read during code review and changelog generation. The command or condition must be the first sentence of the commit body after the signal word. Use command-first for behavioral changes. Use condition-first for conditional breakage.

**Error messages:** Safety instructions in error messages are read during incidents. Use command-first to tell the operator what to do. Use condition-first to explain the system state that caused the error.

**Error message with command-first:**

> **Non-STE:** WARNING: Rate limit exceeded, try again after the reset window.

> **STE:** WARNING: THE RATE LIMIT IS EXCEEDED. DO NOT SEND MORE REQUESTS UNTIL THE RESET WINDOW OPENS. SENDING MORE REQUESTS CAN CAUSE YOUR API KEY TO BE TEMPORARILY BLOCKED. CHECK THE `Retry-After` HEADER FOR THE RESET TIME.

> *Principles applied: P1, P9 — the command "DO NOT SEND MORE REQUESTS" tells the operator what to stop doing. The consequence of ignoring the command is stated.*

Full runnable form — a handler that returns an actionable error:

```python
from http import HTTPStatus

def handle_request(req):
    if rate_limiter.is_exceeded(req.api_key):
        # WARNING: THE RATE LIMIT IS EXCEEDED. DO NOT SEND MORE REQUESTS
        # UNTIL THE RESET WINDOW OPENS. SENDING MORE REQUESTS CAN CAUSE
        # YOUR API KEY TO BE TEMPORARILY BLOCKED. CHECK THE `Retry-After`
        # HEADER FOR THE RESET TIME.
        headers = {"Retry-After": str(rate_limiter.seconds_to_reset(req.api_key))}
        return HTTPStatus.TOO_MANY_REQUESTS, headers, b"rate limit exceeded"
    return process(req)
```

---

## Paradigm-Specific Guidance

### Object-Oriented (Java, C++, C#, Python Classes)

Object-oriented documentation describes class invariants, method contracts, and inheritance rules. Use command-first for prohibitions on subclass overrides. Use condition-first when the state of the object affects the safety of a method call.

**Command-first WARNING for subclass override (Java):**

> **Non-STE:** WARNING: Subclasses of `Authenticator` need to ensure that the `authenticate` method always calls `super.authenticate()` first.

> **STE:** WARNING: DO NOT OVERRIDE THE `authenticate` METHOD WITHOUT CALLING `super.authenticate()` FIRST. IF YOU BYPASS THE BASE AUTHENTICATION, UNTRUSTED REQUESTS CAN ACCESS PROTECTED RESOURCES. ALWAYS PUT `super.authenticate()` AS THE FIRST LINE OF YOUR OVERRIDE.

> *Principles applied: P1, P7 — the command "DO NOT OVERRIDE..." starts the instruction. The prohibition is clear in the first sentence. The required action ("ALWAYS PUT...") follows.*

Full runnable form — a base class and a compliant subclass:

```java
abstract class Authenticator {
    // WARNING: DO NOT OVERRIDE THE `authenticate` METHOD WITHOUT
    // CALLING `super.authenticate()` FIRST. IF YOU BYPASS THE BASE
    // AUTHENTICATION, UNTRUSTED REQUESTS CAN ACCESS PROTECTED
    // RESOURCES. ALWAYS PUT `super.authenticate()` AS THE FIRST LINE
    // OF YOUR OVERRIDE.
    void authenticate(Request req) {
        if (!req.isSigned()) throw new SecurityException("missing signature");
    }
}

class TokenAuthenticator extends Authenticator {
    @Override
    void authenticate(Request req) {
        super.authenticate(); // required: keeps the base checks
        verifyToken(req.token());
    }
}
```

**Condition-first CAUTION for mutable state (Python):**

> **Non-STE:** CAUTION: The `logger` object is shared across modules, be careful about changing the log level at runtime.

> **STE:** CAUTION: BEFORE YOU CHANGE THE `logger.level` AT RUNTIME, CHECK THAT NO OTHER MODULE USES THE SAME LOGGER. IF ANOTHER MODULE EXPECTS A DIFFERENT LOG LEVEL, THE APPLICATION LOGS CAN BECOME INCOMPLETE. SET THE LOG LEVEL IN THE INITIALIZATION FUNCTION. DO NOT CHANGE IT DURING RUNTIME.

> *Principles applied: P1, P11 — the condition "BEFORE YOU CHANGE..." starts the instruction. The reader checks the precondition before acting.*

Full runnable form — a shared logger configured once at startup:

```python
import logging

logger = logging.getLogger("app")  # shared singleton

# CAUTION: BEFORE YOU CHANGE THE `logger.level` AT RUNTIME, CHECK THAT
# NO OTHER MODULE USES THE SAME LOGGER. IF ANOTHER MODULE EXPECTS A
# DIFFERENT LOG LEVEL, THE APPLICATION LOGS CAN BECOME INCOMPLETE.
# SET THE LOG LEVEL IN THE INITIALIZATION FUNCTION. DO NOT CHANGE IT
# DURING RUNTIME.
def configure_logging(level: int) -> None:
    logger.setLevel(level)  # called once, at startup only
```

### Functional (Haskell, Elixir, Clojure, Rust)

Functional documentation describes pure functions, effect types, and referential transparency. Use command-first when an unsafe function can break purity. Use condition-first when laziness or non-strict evaluation creates a hidden precondition.

**Command-first WARNING for unsafe code (Rust):**

> **Non-STE:** WARNING: `unsafe` blocks require the programmer to manually uphold invariants that the compiler does not check.

> **STE:** WARNING: DO NOT ADD AN `unsafe` BLOCK WITHOUT DOCUMENTING THE SAFETY INVARIANTS. AN `unsafe` BLOCK WITHOUT DOCUMENTED INVARIANTS CAN CAUSE UNDEFINED BEHAVIOR, MEMORY CORRUPTION, AND SECURITY VULNERABILITIES. WRITE A `// SAFETY:` COMMENT THAT LISTS EACH INVARIANT AND THE REASON IT HOLDS.

> *Principles applied: P1, P8 — the command "DO NOT ADD AN `unsafe` BLOCK WITHOUT..." starts the instruction. The required action ("WRITE A `// SAFETY:` COMMENT") follows.*

Full runnable form — a safe wrapper over an unsafe raw pointer read:

```rust
/// WARNING: DO NOT ADD AN `unsafe` BLOCK WITHOUT DOCUMENTING THE
/// SAFETY INVARIANTS. AN `unsafe` BLOCK WITHOUT DOCUMENTED
/// INVARIANTS CAN CAUSE UNDEFINED BEHAVIOR, MEMORY CORRUPTION, AND
/// SECURITY VULNERABILITIES. WRITE A `// SAFETY:` COMMENT THAT LISTS
/// EACH INVARIANT AND THE REASON IT HOLDS.
pub unsafe fn read_u32(ptr: *const u32) -> u32 {
    // SAFETY: `ptr` is non-null, 4-byte aligned, and points to
    // initialized memory for the lifetime of this call.
    ptr.read_unaligned()
}
```

**Condition-first CAUTION for lazy evaluation (Haskell):**

> **Non-STE:** CAUTION: Using `foldl` on infinite lists will not terminate.

> **STE:** CAUTION: IF YOU USE `foldl` ON AN INFINITE LIST, THE FUNCTION DOES NOT TERMINATE. THE PROGRAM HANGS INDEFINITELY. USE `foldr` FOR OPERATIONS THAT CAN SHORT-CIRCUIT ON LAZY LISTS. CHECK THAT YOUR LIST IS FINITE BEFORE YOU USE `foldl`.

> *Principles applied: P1, P3 — the condition "IF YOU USE `foldl` ON AN INFINITE LIST" starts the instruction. The consequence (hang) is explained.*

Full runnable form — a GHCi session that shows the difference:

```haskell
-- CAUTION: IF YOU USE `foldl` ON AN INFINITE LIST, THE FUNCTION DOES
-- NOT TERMINATE. THE PROGRAM HANGS INDEFINITELY. USE `foldr` FOR
-- OPERATIONS THAT CAN SHORT-CIRCUIT ON LAZY LISTS. CHECK THAT YOUR
-- LIST IS FINITE BEFORE YOU USE `foldl`.
import Data.List (foldl')

sumFinite :: Num a => [a] -> a
sumFinite = foldl' (+) 0   -- strict: safe on finite lists

-- This never returns; `foldl` builds a thunk chain:
-- sumInfinite = foldl (+) 0 [1..]
```

### Procedural (C, Go, Bash)

Procedural documentation describes memory management, buffer handling, and system calls. Use command-first for memory safety violations. Use condition-first when the program state determines whether a call is safe.

**Command-first WARNING for buffer handling (C):**

> **Non-STE:** WARNING: `gets` reads input without bounds checking and should never be used.

> **STE:** WARNING: DO NOT USE `gets()` IN ANY C PROGRAM. `gets()` READS INPUT WITHOUT BOUNDS CHECKING. A BUFFER OVERFLOW CAN CAUSE ARBITRARY CODE EXECUTION AND SYSTEM COMPROMISE. USE `fgets()` WITH A SIZE LIMIT.

> *Principles applied: P1, P8 — the command "DO NOT USE `gets()`" starts the instruction. The prohibition is absolute ("IN ANY C PROGRAM"). The consequence (arbitrary code execution) justifies the command.*

Full runnable form — a safe read replacement:

```c
/* WARNING: DO NOT USE `gets()` IN ANY C PROGRAM. `gets()` READS INPUT
 * WITHOUT BOUNDS CHECKING. A BUFFER OVERFLOW CAN CAUSE ARBITRARY CODE
 * EXECUTION AND SYSTEM COMPROMISE. USE `fgets()` WITH A SIZE LIMIT. */
char name[64];
if (fgets(name, sizeof(name), stdin) == NULL) {
    /* handle EOF or read error */
}
name[strcspn(name, "\n")] = '\0'; /* remove trailing newline */
```

**Condition-first CAUTION for file descriptors (Go):**

> **Non-STE:** CAUTION: Closing a file descriptor that has already been closed causes a panic.

> **STE:** CAUTION: BEFORE YOU CALL `file.Close()`, CHECK THAT THE FILE IS OPEN. IF YOU CLOSE A FILE THAT IS ALREADY CLOSED, THE PROGRAM PANICS. USE `defer file.Close()` IMMEDIATELY AFTER YOU OPEN THE FILE. THIS PATTERN PREVENTS DOUBLE-CLOSE ERRORS.

> *Principles applied: P1, P12 — the condition "BEFORE YOU CALL `file.Close()`" starts the instruction. The precondition check is stated first. The safe pattern follows.*

Full runnable form — the recommended `defer` pattern:

```go
// CAUTION: BEFORE YOU CALL `file.Close()`, CHECK THAT THE FILE IS
// OPEN. IF YOU CLOSE A FILE THAT IS ALREADY CLOSED, THE PROGRAM
// PANICS. USE `defer file.Close()` IMMEDIATELY AFTER YOU OPEN THE
// FILE. THIS PATTERN PREVENTS DOUBLE-CLOSE ERRORS.
f, err := os.Open("data.csv")
if err != nil {
    return err
}
defer f.Close() // single owner; no second Close() anywhere
```

### Declarative (SQL, Terraform, Kubernetes YAML)

Declarative documentation describes desired state, resource specifications, and destructive operations. Use command-first for destructive state changes. Use condition-first when a configuration value depends on infrastructure state.

**Command-first WARNING for destructive SQL:**

> **Non-STE:** WARNING: This migration truncates the audit log table.

> **STE:** WARNING: DO NOT RUN THIS MIGRATION WITHOUT A FULL DATABASE BACKUP. THE MIGRATION TRUNCATES THE `audit_log` TABLE. ALL AUDIT RECORDS ARE DELETED PERMANENTLY. THE DATA CANNOT BE RECOVERED. RUN THE BACKUP COMMAND: `pg_dump audit_log > audit_log_backup.sql`. VERIFY THE BACKUP BEFORE YOU CONTINUE.

> *Principles applied: P1, P5 — the command "DO NOT RUN THIS MIGRATION WITHOUT A FULL DATABASE BACKUP" starts the instruction. The precondition command is stated first. The consequence clarifies why.*

Full runnable form — a migration file with a guard:

```sql
-- WARNING: DO NOT RUN THIS MIGRATION WITHOUT A FULL DATABASE BACKUP.
-- THE MIGRATION TRUNCATES THE `audit_log` TABLE. ALL AUDIT RECORDS ARE
-- DELETED PERMANENTLY. THE DATA CANNOT BE RECOVERED. RUN THE BACKUP
-- COMMAND: `pg_dump audit_log > audit_log_backup.sql`. VERIFY THE
-- BACKUP BEFORE YOU CONTINUE.
--
-- Safe pre-check: fail the migration if the table is unexpectedly large
-- and no backup marker exists.
DO $$
BEGIN
  IF NOT EXISTS (SELECT 1 FROM backup_markers WHERE table_name = 'audit_log')
     AND (SELECT count(*) FROM audit_log) > 0
  THEN
    RAISE EXCEPTION 'audit_log backup missing; abort migration';
  END IF;
END $$;

TRUNCATE TABLE audit_log;
```

**Condition-first CAUTION for Kubernetes resource limits:**

> **Non-STE:** CAUTION: Setting resource limits too low causes OOMKilled errors.

> **STE:** CAUTION: IF YOU SET THE `memory.limits` VALUE TOO LOW, THE POD IS KILLED WITH AN OOMKILLED ERROR. THE APPLICATION RESTARTS. REQUESTS TO THE APPLICATION FAIL DURING THE RESTART. MONITOR THE ACTUAL MEMORY USAGE IN STAGING BEFORE YOU SET THE LIMIT IN PRODUCTION. USE A LIMIT THAT IS AT LEAST 50 PERCENT ABOVE THE AVERAGE USAGE.

> *Principles applied: P1, P11 — the condition "IF YOU SET THE `memory.limits` VALUE TOO LOW" starts the instruction. The cascade of consequences follows. The corrective action is specific.*

Full runnable form — a manifest with a measured limit:

```yaml
# CAUTION: IF YOU SET THE `memory.limits` VALUE TOO LOW, THE POD IS
# KILLED WITH AN OOMKILLED ERROR. THE APPLICATION RESTARTS. REQUESTS
# TO THE APPLICATION FAIL DURING THE RESTART. MONITOR THE ACTUAL
# MEMORY USAGE IN STAGING BEFORE YOU SET THE LIMIT IN PRODUCTION.
# USE A LIMIT THAT IS AT LEAST 50 PERCENT ABOVE THE AVERAGE USAGE.
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: web
          resources:
            requests:
              memory: "256Mi"
            limits:
              memory: "768Mi"   # avg usage 512Mi + 50% headroom
```

### Systems (Rust Ownership, C Memory)

Systems documentation describes ownership, unsafe blocks, and memory layout. Use command-first when an operation can cause undefined behavior. Use condition-first when the safety of an operation depends on a property that the compiler cannot verify.

**Command-first WARNING for pointer alignment (Rust):**

> **Non-STE:** WARNING: Reading from a misaligned pointer is undefined behavior on most platforms.

> **STE:** WARNING: DO NOT READ FROM A POINTER THAT IS NOT CORRECTLY ALIGNED. A MISALIGNED READ CAN CAUSE UNDEFINED BEHAVIOR. UNDEFINED BEHAVIOR CAN CORRUPT MEMORY, CAUSE SECURITY VULNERABILITIES, AND CRASH THE PROGRAM. USE `std::ptr::read_unaligned` FOR UNALIGNED MEMORY. CHECK THE ALIGNMENT WITH `std::mem::align_of` BEFORE YOU READ.

> *Principles applied: P1, P8 — the command "DO NOT READ FROM A POINTER THAT IS NOT CORRECTLY ALIGNED" starts the instruction. The safe alternative is given. The check instruction follows.*

Full runnable form — aligned and unaligned read paths:

```rust
use std::mem::align_of;
use std::ptr;

/// WARNING: DO NOT READ FROM A POINTER THAT IS NOT CORRECTLY ALIGNED.
/// A MISALIGNED READ CAN CAUSE UNDEFINED BEHAVIOR. UNDEFINED BEHAVIOR
/// CAN CORRUPT MEMORY, CAUSE SECURITY VULNERABILITIES, AND CRASH THE
/// PROGRAM. USE `std::ptr::read_unaligned` FOR UNALIGNED MEMORY. CHECK
/// THE ALIGNMENT WITH `std::mem::align_of` BEFORE YOU READ.
unsafe fn load_u64(buf: *const u8, aligned: bool) -> u64 {
    if aligned && (buf as usize) % align_of::<u64>() == 0 {
        ptr::read(buf as *const u64)          // safe when aligned
    } else {
        ptr::read_unaligned(buf as *const u64) // required when not aligned
    }
}
```

**Condition-first CAUTION for manual allocators:**

> **Non-STE:** CAUTION: Custom allocators must return memory with at least the requested alignment or the allocator API contract is violated.

> **STE:** CAUTION: WHEN YOU IMPLEMENT A CUSTOM ALLOCATOR, MAKE SURE THAT THE RETURNED POINTER SATISFIES THE REQUESTED ALIGNMENT. IF THE ALIGNMENT IS NOT SATISFIED, THE ALLOCATOR CONTRACT IS VIOLATED. CODE THAT USES THE ALLOCATOR CAN PRODUCE INCORRECT RESULTS OR CRASH. CALL `std::alloc::Layout::align()` TO GET THE REQUIRED ALIGNMENT.

> *Principles applied: P1, P12 — the condition "WHEN YOU IMPLEMENT A CUSTOM ALLOCATOR" starts the instruction. The precondition (alignment) is stated. The consequence of violation is explained.*

Full runnable form — an allocator that rounds up to the alignment:

```rust
use std::alloc::{Layout, alloc};

/// CAUTION: WHEN YOU IMPLEMENT A CUSTOM ALLOCATOR, MAKE SURE THAT THE
/// RETURNED POINTER SATISFIES THE REQUESTED ALIGNMENT. IF THE ALIGNMENT
/// IS NOT SATISFIED, THE ALLOCATOR CONTRACT IS VIOLATED. CODE THAT USES
/// THE ALLOCATOR CAN PRODUCE INCORRECT RESULTS OR CRASH. CALL
/// `std::alloc::Layout::align()` TO GET THE REQUIRED ALIGNMENT.
unsafe fn alloc_aligned(size: usize, align: usize) -> *mut u8 {
    let layout = Layout::from_size_align(size, align).unwrap();
    let ptr = alloc(layout);
    // `alloc` guarantees `ptr` is a multiple of `layout.align()`.
    assert!(ptr as usize % align == 0, "allocator contract violated");
    ptr
}
```

---

## Extended Examples

### Example 1 — Missing Command (Abstract Description Only)

> **Non-STE:** WARNING: API keys stored in plaintext configuration files are a major security risk.

> **STE:** WARNING: DO NOT STORE API KEYS IN PLAINTEXT CONFIGURATION FILES. STORE API KEYS IN ENVIRONMENT VARIABLES OR A SECRETS MANAGER. PLAINTEXT API KEYS IN VERSION CONTROL CAN CAUSE UNAUTHORIZED ACCESS AND DATA THEFT.

> *Principles applied: P1, P9 — the non-STE version describes the risk but gives no command. The STE version starts with "DO NOT STORE," gives an alternative, and explains the consequence. The reader learns the action in the first four words.*

Full runnable form — a test that fails on a committed secret:

```python
# WARNING: DO NOT STORE API KEYS IN PLAINTEXT CONFIGURATION FILES.
# STORE API KEYS IN ENVIRONMENT VARIABLES OR A SECRETS MANAGER.
# PLAINTEXT API KEYS IN VERSION CONTROL CAN CAUSE UNAUTHORIZED ACCESS
# AND DATA THEFT.
def test_no_secret_in_config(config_path):
    text = config_path.read_text()
    assert "sk_live_" not in text, "plaintext API key found in config"
```

### Example 2 — Missing Condition (Consequence Only)

> **Non-STE:** WARNING: THE DATABASE TRANSACTION CAN FAIL SILENTLY.

> **STE:** WARNING: IF YOU DO NOT CHECK THE RETURN VALUE OF `transaction.commit()`, THE TRANSACTION CAN FAIL SILENTLY. DATA THAT YOU THINK IS SAVED IS NOT SAVED. THIS SILENT DATA LOSS CAN CAUSE APPLICATION INCONSISTENCY. CHECK THE RETURN VALUE AND HANDLE THE `RollbackError` CASE.

> *Principles applied: P1, P4 — the non-STE version states only the risk. The STE version adds the condition ("IF YOU DO NOT CHECK...") before the consequence. The reader learns when the risk applies, not just that it exists.*

Full runnable form — a commit that checks the result:

```python
# WARNING: IF YOU DO NOT CHECK THE RETURN VALUE OF
# `transaction.commit()`, THE TRANSACTION CAN FAIL SILENTLY. DATA THAT
# YOU THINK IS SAVED IS NOT SAVED. THIS SILENT DATA LOSS CAN CAUSE
# APPLICATION INCONSISTENCY. CHECK THE RETURN VALUE AND HANDLE THE
# `RollbackError` CASE.
try:
    transaction.commit()
except RollbackError as exc:
    logger.error("commit failed: %s", exc)
    raise
```

### Example 3 — Command Buried in Background Information

> **Non-STE:** WARNING: Configuration drift between environments is a common cause of production incidents and represents a significant operational risk to the platform's availability, with the remedy being to always use the same configuration templates across all environments and verify them before each deployment.

> **STE:** WARNING: DO NOT USE DIFFERENT CONFIGURATION TEMPLATES FOR EACH ENVIRONMENT. USE THE SAME TEMPLATE FOR ALL ENVIRONMENTS. VERIFY THE CONFIGURATION BEFORE EACH DEPLOYMENT. CONFIGURATION DRIFT CAN CAUSE PRODUCTION INCIDENTS AND SERVICE UNAVAILABILITY.

> *Principles applied: P1, P9 — the non-STE version buries the command 30 words into the sentence. The STE version puts "DO NOT USE" at the start. The reader knows the prohibition immediately. The consequence follows.*

Full runnable form — a CI check that diffs configs:

```bash
# WARNING: DO NOT USE DIFFERENT CONFIGURATION TEMPLATES FOR EACH
# ENVIRONMENT. USE THE SAME TEMPLATE FOR ALL ENVIRONMENTS. VERIFY THE
# CONFIGURATION BEFORE EACH DEPLOYMENT. CONFIGURATION DRIFT CAN CAUSE
# PRODUCTION INCIDENTS AND SERVICE UNAVAILABILITY.
diff -q config/base.yaml config/staging.yaml || exit 1
diff -q config/base.yaml config/prod.yaml    || exit 1
```

### Example 4 — Wrong Condition Order (Consequence Before Condition)

> **Non-STE:** WARNING: PERMANENT DATA LOSS CAN OCCUR IF YOU DO NOT EXPORT THE DATA BEFORE YOU RUN THE CLEANUP SCRIPT.

> **STE:** WARNING: BEFORE YOU RUN THE CLEANUP SCRIPT, EXPORT THE DATA. IF YOU DO NOT EXPORT THE DATA, THE SCRIPT REMOVES THE DATA PERMANENTLY. THE DATA CANNOT BE RECOVERED. RUN `export-data --output backup.json` AND VERIFY THE FILE BEFORE YOU RUN THE CLEANUP SCRIPT.

> *Principles applied: P1, P3 — the non-STE version puts the consequence before the condition. The reader learns the risk before learning when it applies. The STE version puts the condition first ("BEFORE YOU RUN..."). The reader learns the context, then the risk.*

Full runnable form — a guarded cleanup script:

```bash
# WARNING: BEFORE YOU RUN THE CLEANUP SCRIPT, EXPORT THE DATA. IF YOU
# DO NOT EXPORT THE DATA, THE SCRIPT REMOVES THE DATA PERMANENTLY.
# THE DATA CANNOT BE RECOVERED. RUN `export-data --output backup.json`
# AND VERIFY THE FILE BEFORE YOU RUN THE CLEANUP SCRIPT.
export-data --output backup.json
test -s backup.json || { echo "backup empty; abort"; exit 1; }
./cleanup.sh
```

### Example 5 — Passive Voice Instead of Command

> **Non-STE:** CAUTION: The input data should be validated before it is processed by the pipeline.

> **STE:** CAUTION: VALIDATE THE INPUT DATA BEFORE THE PIPELINE PROCESSES IT. IF THE PIPELINE PROCESSES INVALID DATA, THE OUTPUT CAN BE INCORRECT. THE INCORRECT OUTPUT CAN PROPAGATE TO DOWNSTREAM SYSTEMS. USE THE `validateSchema` FUNCTION TO CHECK THE DATA STRUCTURE AND TYPES.

> *Principles applied: P1, P9 — the non-STE version uses passive voice ("should be validated"). The STE version uses an imperative command ("VALIDATE THE INPUT DATA"). The command is the first word after the colon. The consequence explains why validation matters.*

Full runnable form — a validation step in a pipeline:

```python
# CAUTION: VALIDATE THE INPUT DATA BEFORE THE PIPELINE PROCESSES IT.
# IF THE PIPELINE PROCESSES INVALID DATA, THE OUTPUT CAN BE INCORRECT.
# THE INCORRECT OUTPUT CAN PROPAGATE TO DOWNSTREAM SYSTEMS. USE THE
# `validateSchema` FUNCTION TO CHECK THE DATA STRUCTURE AND TYPES.
def run_pipeline(raw):
    validateSchema(raw)        # imperative: validate first
    return transform(raw)
```

### Example 6 — Multiple Commands Without Hierarchy

> **Non-STE:** WARNING: You need to sanitize inputs, escape SQL queries, validate return types, and check authentication tokens before processing the request, or data breaches can occur.

> **STE:** WARNING: BEFORE YOU PROCESS THE REQUEST, COMPLETE THESE CHECKS: (1) SANITIZE ALL INPUT DATA. (2) USE PARAMETERIZED SQL QUERIES. (3) VALIDATE THE RETURN TYPES. (4) VERIFY THE AUTHENTICATION TOKEN. IF YOU SKIP ANY CHECK, A SECURITY BREACH OR DATA LOSS CAN OCCUR.

> *Principles applied: P1, P4 — the non-STE version lists four commands in one run-on sentence. The STE version uses a numbered list with one command per item. The condition ("BEFORE YOU PROCESS") starts the instruction. Each command is imperative and self-contained.*

Full runnable form — a request handler that runs each check as a step:

```python
# WARNING: BEFORE YOU PROCESS THE REQUEST, COMPLETE THESE CHECKS:
# (1) SANITIZE ALL INPUT DATA. (2) USE PARAMETERIZED SQL QUERIES.
# (3) VALIDATE THE RETURN TYPES. (4) VERIFY THE AUTHENTICATION TOKEN.
# IF YOU SKIP ANY CHECK, A SECURITY BREACH OR DATA LOSS CAN OCCUR.
def process_request(req):
    data = sanitize(req.body)                       # (1)
    rows = db.query("SELECT * FROM u WHERE id=%s",  # (2) parameterized
                    (data["id"],))
    result = validate_return_type(rows)            # (3)
    verify_token(req.headers["Authorization"])      # (4)
    return result
```

---

## Edge Cases

### Edge Case 1 — When a Framework Method Name Conflicts with a Command Word

Some frameworks use method names that are the same as STE-Code command words (for example, `check`, `set`, `get`, `do`). When the command in the safety instruction is also a framework method name, use the method name in backticks only when referring to the method. Use the plain word as the command.

> **Non-STE:** WARNING: Check that you check the `check()` return value before proceeding.

> **STE:** WARNING: CHECK THE RETURN VALUE OF THE `check()` METHOD BEFORE YOU CONTINUE. IF `check()` RETURNS `false`, THE AUTHENTICATION IS NOT VALID. DO NOT PROCESS THE REQUEST. AN INVALID AUTHENTICATION CAN PERMIT UNAUTHORIZED ACCESS.

> *Principles applied: P1, P5 — the command word "CHECK" is plain uppercase. The method name `check()` is in backticks. The reader distinguishes the instruction from the method reference.*

Full runnable form — an auth guard that calls `check()`:

```python
# WARNING: CHECK THE RETURN VALUE OF THE `check()` METHOD BEFORE YOU
# CONTINUE. IF `check()` RETURNS `false`, THE AUTHENTICATION IS NOT
# VALID. DO NOT PROCESS THE REQUEST. AN INVALID AUTHENTICATION CAN
# PERMIT UNAUTHORIZED ACCESS.
def guard(req):
    if authenticator.check(req.token) is False:  # check() return value
        raise PermissionError("invalid authentication")
    return handle(req)
```

### Edge Case 2 — When the Condition Is Always True for a Subset of Users

Some conditions apply only to a specific deployment configuration, operating system, or library version. When the condition is not universal, use an "IF" clause that names the specific scenario. Do not write a command that is wrong for the other users.

> **Non-STE:** WARNING: DO NOT USE THE `fetch` API IN NODE.JS BEFORE VERSION 18.

> **STE:** WARNING: IF YOU USE NODE.JS BEFORE VERSION 18, DO NOT USE THE `fetch` API. THE `fetch` API IS NOT AVAILABLE IN NODE.JS BEFORE VERSION 18. YOUR APPLICATION CRASHES WITH A `ReferenceError`. USE `node-fetch` OR UPGRADE TO NODE.JS 18 OR LATER.

> *Principles applied: P1, P10 — the condition "IF YOU USE NODE.JS BEFORE VERSION 18" scopes the prohibition. Users on Node.js 18 or later know the command does not apply to them. The alternative is given.*

Full runnable form — a version-gated import:

```javascript
// WARNING: IF YOU USE NODE.JS BEFORE VERSION 18, DO NOT USE THE
// `fetch` API. THE `fetch` API IS NOT AVAILABLE IN NODE.JS BEFORE
// VERSION 18. YOUR APPLICATION CRASHES WITH A `ReferenceError`. USE
// `node-fetch` OR UPGRADE TO NODE.JS 18 OR LATER.
let fetchImpl;
if (process.versions.node.startsWith("18") ||
    Number(process.versions.node.split(".")[0]) >= 18) {
  fetchImpl = fetch;                 // global since Node 18
} else {
  fetchImpl = require("node-fetch"); // polyfill for older runtimes
}
```

### Edge Case 3 — When a Command and a Condition Are Both Required

Some safety instructions need both a command and a condition. When both are required, put the condition first (per the rule: "give this condition first"). The condition tells the reader when the command applies. The command tells the reader what to do.

> **Non-STE:** WARNING: Always run the database migration tool and make sure you are connected to the correct database before running the schema update.

> **STE:** WARNING: BEFORE YOU RUN THE SCHEMA UPDATE, CONNECT TO THE CORRECT DATABASE. RUN THE MIGRATION TOOL WITH THE `--check` FLAG. IF YOU RUN THE SCHEMA UPDATE ON THE WRONG DATABASE, THE SCHEMA IS CORRUPTED AND THE APPLICATION CANNOT START.

> *Principles applied: P1, P9 — the condition "BEFORE YOU RUN THE SCHEMA UPDATE" comes first. The command "CONNECT TO THE CORRECT DATABASE" follows. The reader knows the sequence: check the condition, then execute the command.*

Full runnable form — a migration runner with a pre-check:

```bash
# WARNING: BEFORE YOU RUN THE SCHEMA UPDATE, CONNECT TO THE CORRECT
# DATABASE. RUN THE MIGRATION TOOL WITH THE `--check` FLAG. IF YOU RUN
# THE SCHEMA UPDATE ON THE WRONG DATABASE, THE SCHEMA IS CORRUPTED AND
# THE APPLICATION CANNOT START.
export DATABASE_URL="postgres://app@staging:5432/app"
migrate --check        # fails fast if the connection is wrong
migrate up             # only reaches here on the correct database
```

### Edge Case 4 — When a Safety Instruction References Generated Code

Generated files (from tools such as `protoc`, `graphql-codegen`, or `terraform plan`) may contain auto-generated comments that look like safety instructions. These generated comments break the command-first or condition-first rule. For generated code:

- Do not modify the generated comments. The generator overwrites your changes.
- Add your own STE-Code WARNING or CAUTION above the generated block. Your instruction follows the command-first or condition-first rule.
- If the generated code has a safety concern that is not documented, open an issue with the generator project.

> **Generated comment (leave as-is):** // Note: This method is generated. Do not edit.

> **Your wrapper with command-first:** WARNING: DO NOT EDIT THE `generated/` DIRECTORY MANUALLY. THE GENERATOR OVERWRITES YOUR CHANGES ON THE NEXT BUILD. IF YOU CHANGE THE GENERATED CODE, YOUR CHANGES ARE LOST. EDIT THE `.proto` SOURCE FILE AND RUN THE GENERATOR AGAIN.

> *Principles applied: P1, P7 — the command "DO NOT EDIT" starts the instruction. The consequence (lost changes) follows. The correct workflow is explained.*

Full runnable form — a build step that regenerates from source:

```makefile
# WARNING: DO NOT EDIT THE `generated/` DIRECTORY MANUALLY. THE
# GENERATOR OVERWRITES YOUR CHANGES ON THE NEXT BUILD. IF YOU CHANGE
# THE GENERATED CODE, YOUR CHANGES ARE LOST. EDIT THE `.proto` SOURCE
# FILE AND RUN THE GENERATOR AGAIN.
generated/:
	protoc --python_out=generated/ api.proto   # regenerates from source
```

### Edge Case 5 — Internationalization of Command and Condition Words

When your documentation is translated, the command words (DO NOT, ALWAYS, CHECK, MAKE SURE) and condition words (IF, BEFORE, WHEN) must also be translated. Use the standard translation for these words. Maintain a glossary of translated command and condition words.

The command or condition must remain the first element after the translated signal word:

| Language | DO NOT | ALWAYS | IF | BEFORE YOU |
|----------|--------|--------|----|------------|
| English | DO NOT | ALWAYS | IF | BEFORE YOU |
| Spanish | NO | SIEMPRE | SI | ANTES DE |
| French | NE PAS | TOUJOURS | SI | AVANT DE |
| German | NICHT | IMMER | WENN | BEVOR SIE |
| Japanese | 禁止 | 必ず | 場合 | 前に |

The word order rules are the same in all languages. The command or condition comes first. The consequence comes after. Do not change the structure for any language.

Full runnable form — a localized warning (Spanish) in a docstring:

```python
# ADVERTENCIA: NO GUARDE CLAVES DE API EN EL CÓDIGO FUENTE. SIEMPRE
# USE VARIABLES DE ENTORNO O UN GESTOR DE SECRETOS. LAS CLAVES EN EL
# CÓDIGO FUENTE PUEDEN CAUSAR ACCESO NO AUTORIZADO Y FUGAS DE DATOS.
def get_client():
    return Client(os.environ["API_KEY"])
```

---

## Cross-References

- **Rule 1.4** — Use only approved verb forms and adjective forms. The command in a safety instruction must use an approved verb (for example, "check," "make sure," "use," "do not").
- **Rule 1.11** — One term per concept. Use the same command words across all safety instructions. Do not use "check" in one instruction and "verify" in another for the same action.
- **Rule 1.12** — Technical verbs (build, deploy, test, lint) are allowed. Use technical verbs in commands when they are the correct term (for example, "DO NOT DEPLOY," "ALWAYS SANITIZE").
- **Rule 4.1** — Write short and clear sentences. The command or condition must be a short sentence. The reader must understand it in one reading.
- **Rule 4.2** — Use the active voice. Commands are inherently active. Conditions must also use the active voice (for example, "IF YOU DO NOT SET..." not "IF THE TIMEOUT IS NOT SET...").
- **Rule 5.3** — Use the imperative (command) form for instructions. Every WARNING or CAUTION instruction uses the imperative mood for the command part.
- **Rule 5.4** — Write each step as a command. When a safety instruction has multiple actions, write each action as a separate command.
- **Rule 7.1** — Use an applicable word to identify the level of risk. The signal word (WARNING or CAUTION) comes before the command or condition. Choose the correct signal word before you write the command.
- **Rule 7.3** — Give an explanation to show the risk or possible result. The command or condition tells the reader what to do. The explanation tells the reader why. Both are required in a complete safety instruction.
- **Section 1 (Vocabulary)** — All words used in commands and conditions must come from the approved vocabulary unless they are technical code nouns.
- **Section 5 (Procedural Writing)** — Safety instructions are procedural sentences. Follow all procedural writing rules for the command and condition parts.

---

## Grammar Notes

### Imperative Mood in Commands

Commands in safety instructions use the imperative mood. The imperative mood addresses the reader directly and tells them what to do (or not do). The subject "you" is implied and not written.

The four imperative forms used in code documentation safety instructions:

1. **Positive imperative:** CHECK THE RETURN VALUE. MAKE SURE THAT THE FILE EXISTS. BACK UP THE DATABASE.
2. **Negative imperative (prohibition):** DO NOT COMMIT THE API KEY. DO NOT USE THIS FUNCTION. DO NOT SKIP THE VALIDATION STEP.
3. **Emphatic positive imperative:** ALWAYS SANITIZE THE INPUT. ALWAYS VERIFY THE SIGNATURE. ALWAYS USE PARAMETERIZED QUERIES.
4. **Sequence imperative:** BEFORE YOU [ACTION], [COMMAND].

Do not use modal verbs in commands. Modal verbs weaken the instruction:

> **Correct:** CHECK THE RETURN VALUE BEFORE YOU CONTINUE.
> **Incorrect:** You should check the return value before continuing.
> **Incorrect:** The return value must be checked before continuing.

### Condition Clause Grammar

Condition clauses use subordinating conjunctions (IF, BEFORE, WHEN, UNLESS). The condition clause is a dependent clause. It must be attached to an independent clause that contains the consequence or the command.

**Correct condition-first structure:** IF [condition], [consequence/command]. [Explanation].

**Incorrect (consequence first):** [Consequence] IF [condition]. [Explanation].

The condition clause uses the present tense, even when referring to a future action:

> **Correct:** IF YOU DO NOT SET THE TIMEOUT, THE APPLICATION HANGS.
> **Incorrect:** IF YOU WILL NOT SET THE TIMEOUT, THE APPLICATION WILL HANG.

### Sentence Length for Commands and Conditions

The command or condition sentence must not be more than 20 words. This limit makes sure the reader understands the instruction quickly. If the full safety instruction needs more words, use multiple sentences. The first sentence is the command or condition. The following sentences give the explanation and consequence.

> **Correct (19 words):** DO NOT USE THE `eval()` FUNCTION WITH DATA THAT COMES FROM AN UNTRUSTED SOURCE. EVAL() CAN EXECUTE ARBITRARY CODE.
>
> **Correct (split across sentences):** DO NOT USE THE `eval()` FUNCTION WITH UNTRUSTED DATA. EVAL() CAN EXECUTE ARBITRARY CODE. ARBITRARY CODE EXECUTION CAN CAUSE A COMPLETE SYSTEM COMPROMISE.

The condition sentence can also be split:

> **Correct (condition first, then consequence):** IF YOU DO NOT SANITIZE THE INPUT DATA, THE QUERY CAN FAIL. THE FAILURE CAN CAUSE DATA CORRUPTION. SANITIZE ALL INPUT WITH THE `cleanInput` FUNCTION.

### Punctuation After the Signal Word

The signal word is followed by a colon (:) and a single space. The command or condition sentence starts with an uppercase letter. Use a period (.) at the end of each sentence. Do not use semicolons to join the command and the consequence.

> **Correct:** WARNING: DO NOT STORE THE PRIVATE KEY IN THE REPOSITORY. THE PRIVATE KEY CAN BE ACCESSED BY UNAUTHORIZED USERS.
>
> **Incorrect:** WARNING: do not store the private key in the repository; the private key can be accessed by unauthorized users.

### Parallel Structure in Multi-Command Instructions

When a safety instruction contains multiple commands, use parallel grammatical structure. Each command must use the same verb form. Use a numbered list for clarity.

> **Correct:**
> WARNING: BEFORE YOU DEPLOY, COMPLETE THESE STEPS:
> (1) BACK UP THE DATABASE.
> (2) RUN THE MIGRATION SCRIPTS.
> (3) VERIFY THE APPLICATION HEALTH CHECK.
>
> **Incorrect:**
> WARNING: Before deploying you should back up the database, running migration scripts must be done, and the health check is verified.

### "Make Sure" as a Command Pattern

"Make sure" is a special command pattern in STE-Code. It is used when the reader must verify a condition before acting. "Make sure" is followed by a "that" clause that describes the condition to verify.

> **Correct:** MAKE SURE THAT THE DATABASE CONNECTION IS OPEN BEFORE YOU RUN THE QUERY.
> **Correct:** MAKE SURE THAT THE INPUT DATA IS SANITIZED BEFORE THE PIPELINE PROCESSES IT.

Do not use "make sure" when a direct imperative verb is clearer:

> **Better:** SANITIZE THE INPUT DATA BEFORE THE PIPELINE PROCESSES IT.
> **Acceptable:** MAKE SURE THAT THE INPUT DATA IS SANITIZED BEFORE THE PIPELINE PROCESSES IT.

Use "make sure" for verification of existing state. Use direct imperatives for actions the reader must perform.

---

<!-- a-sec7-rule7.3.md -->

# Rule 7.3 — Give an Explanation to Show the Risk or Possible Result

> **Source:** Adapted from ASD-STE100 Issue 9, Rule 7.3

> **Source:** [master.md#sec7-rule7.3](ste-code/grouped/)

## Original Rule

**Rule 7.3** If it is possible, always tell your reader about the problems that can occur if the reader does not obey the safety instruction. If there is a clear and specified risk, the person who does the task will understand the risk and be more careful.

**Spec examples:**

(Refer to the underlined risk or possible result.)

> **WARNING:** DO NOT SWALLOW THE SOLVENT. ALWAYS MAKE SURE THAT YOU KNOW THE SAFETY PRECAUTIONS AND FIRST AID INSTRUCTIONS FOR SOLVENTS. SOLVENTS ARE POISONOUS AND CAN CAUSE INJURY OR DEATH.

> **CAUTION:** DO NOT USE BLEACH OR CLEANSERS THAT CONTAIN CHLORINE TO CLEAN THE UNIT. THESE CLEANING AGENTS CAN CAUSE CORROSION.

> IF THEY FALL, PERMANENT DAMAGE TO THE PARTS CAN OCCUR.

## STE-Code Adaptation

**Rule 7.3** In code documentation, if it is possible, always tell your reader about the problems that can occur if the reader does not obey the safety instruction. If there is a clear and specified risk, the developer who uses the code will understand the risk and be more careful.

Severity mapping: The risk explanation must match the severity from Rule 7.1. For release-note and changelog severity, map the levels as follows: WARNING to BREAKING, CAUTION to DEPRECATED, NOTE to NOTE.

A risk explanation has three parts: (1) the violation or failure to obey the instruction, (2) the immediate consequence, and (3) the cascading or final harm. Write the chain in cause-first order: "If you do X, Y can happen." Do not stop at "Y must not happen" without naming what Y is. An instruction without a risk explanation is a prohibition the reader can dismiss. A risk explanation turns the prohibition into a reason.

### Examples

> *Adapted from spec pair:* Non-STE: `WARNING: DO NOT SWALLOW THE SOLVENT. ... SOLVENTS ARE POISONOUS AND CAN CAUSE INJURY OR DEATH.`  |  STE: `WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.` (ASD-STE100 Issue 9, Rule 7.3, page 100 — the WARNING names the poison and the injury or death; the code-domain pair names the exposure and the breach.)

> **Non-STE:** WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE.
>
> **STE:** WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.
>
> *Adapted from spec pattern: WARNING with risk explanation — "SOLVENTS ARE POISONOUS AND CAN CAUSE INJURY OR DEATH."*

A complete README section that uses this pair, with the risk explanation written in context:

```markdown
## Security Setup

WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE.
API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.

Store the key in an environment variable named `PAYMENTS_API_KEY`.
Add the `.env` file to `.gitignore`. A committed key stays in the
repository history after you remove it, so rotate the key after a leak.
```

> **Non-STE:** CAUTION: DO NOT USE DEPRECATED FUNCTIONS.
>
> **STE:** CAUTION: DO NOT USE DEPRECATED FUNCTIONS. DEPRECATED FUNCTIONS CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.
>
> *Adapted from spec pattern: CAUTION with risk explanation — "THESE CLEANING AGENTS CAN CAUSE CORROSION."*

A JSDoc comment that uses this pair, with the specific deprecated function named:

```javascript
/**
 * CAUTION: DO NOT USE THE `formatDate` FUNCTION.
 * DEPRECATED FUNCTIONS CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.
 *
 * `formatDate` uses the host time zone. The output changes between
 * servers, so two users can see two different dates for the same event.
 * Use `formatDateUTC` instead.
 *
 * @deprecated since v3.2.0
 */
function formatDate(value) { /* ... */ }
```

> **Non-STE:** MAKE SURE THAT YOU SET THE CONNECTION TIMEOUT.
>
> **STE:** IF YOU DO NOT SET THE CONNECTION TIMEOUT, THE APPLICATION CAN BECOME UNAVAILABLE AND PERMANENT DATA LOSS CAN OCCUR.
>
> *Adapted from spec pattern: consequence statement — "IF THEY FALL, PERMANENT DAMAGE TO THE PARTS CAN OCCUR."*

A configuration file and the docstring that explain the timeout risk:

```python
def connect(host: str, port: int, timeout: float | None = None) -> Socket:
    """Open a TCP connection to the server.

    IF YOU DO NOT SET THE CONNECTION TIMEOUT, THE APPLICATION CAN
    BECOME UNAVAILABLE AND PERMANENT DATA LOSS CAN OCCUR.

    Without a timeout, a connection that never answers keeps the calling
    thread blocked. Blocked threads fill the worker pool. When the pool
    is full, the application stops accepting new requests. Writes that
    wait for a blocked connection are not committed, so the data is lost.

    Parameters:
        timeout: Seconds to wait before the connect fails. The default is
            None, which means wait forever. Always pass a value.
    """
```

> **See also:** Rule 7.1 — Use an Applicable Word (for Example, "Warning" or "Caution") to Identify the Level of Risk; Rule 7.2 — Start a Safety Instruction with a Clear and Accurate Command or Condition; Rule 7.4 — Use Imperative Mood for Instructions

---

## Code-Domain Explanation

Rule 7.3 addresses a fundamental gap in software documentation: instructions that tell the reader _what_ to avoid but not _why_ the avoidance matters. In aerospace, a mechanic who understands that a solvent is poisonous will handle it more carefully. In code, a developer who understands that an omitted timeout causes data loss will take the instruction seriously.

The rule applies differently across documentation types:

**README files.** README files give setup instructions and usage warnings. A README that says "do not use Node.js versions below 18" without explanation leaves new contributors vulnerable. The README must add: "Node.js versions below 18 do not include the `fetch` API. The application uses `fetch` for all network requests. If you use a version below 18, the requests will fail without an error message." The risk explanation connects the prohibition to a specific, observable failure.

```markdown
## Requirements

CAUTION: USE NODE.JS VERSION 18 OR HIGHER.
NODE.JS VERSIONS BELOW 18 DO NOT INCLUDE THE `fetch` API.
THE APPLICATION USES `fetch` FOR ALL NETWORK REQUESTS.
IF YOU USE A VERSION BELOW 18, THE REQUESTS WILL FAIL WITHOUT AN ERROR MESSAGE.

Run `node --version` before you run `npm install`.
```

**API documentation.** API docs describe function contracts. A docstring that says "do not pass null" is incomplete. It must also say: "If you pass null, the function throws a `NullPointerException` and the transaction is not committed. Uncommitted transactions can cause database lock contention." The reader now understands the cascading effect, not just the immediate error.

```java
/**
 * CAUTION: DO NOT PASS NULL FOR THE `orderId` PARAMETER.
 * A NULL `orderId` CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.
 *
 * If you pass null, the method throws NullPointerException and the
 * transaction is not committed. An uncommitted transaction holds a row
 * lock. Locked rows can block other requests and cause database
 * contention for all users of the table.
 */
Order loadOrder(String orderId) { /* ... */ }
```

**Docstrings and inline comments.** Docstrings carry both usage notes and warnings. A docstring that says "this function is not thread-safe" without explanation is ignored. The docstring must add: "If two goroutines call this function at the same time, the internal map can become corrupt. Map corruption causes silent data loss because no error is returned." The risk explanation transforms an abstract property into a concrete hazard.

```go
// CAUTION: THE `Counter` TYPE IS NOT THREAD-SAFE.
// THE `Counter` TYPE CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.
//
// If two goroutines call Add at the same time, the internal map can
// become corrupt. Map corruption causes silent data loss because no
// error is returned. Use CounterSafe, which uses a mutex, for concurrent
// code.
type Counter struct { values map[string]int }
```

**Commit messages.** Commit messages serve as historical records and review context. A commit that says "remove the `--force` flag from the deploy script" documents a change. The body must add: "If the `--force` flag is used, the deploy script overwrites the production database without confirmation. Overwriting the production database can cause permanent loss of user data." Future readers who consider reintroducing the flag will see the recorded risk.

```
WARNING: Remove the --force flag from the deploy script.

The --force flag made the deploy script overwrite the production
database without confirmation. A wrong branch name then destroyed
all user data. Overwriting the production database can cause
permanent loss of user data.

The script now fails if the target is the production database unless
you set DEPLOY_TO_PROD=true. Keep this guard. Do not add --force back.
```

**Error messages.** Error messages are the last line of defense. An error that says "configuration not found" tells the user a fact. A better error says: "The configuration file `config.toml` was not found. The application cannot start without this file. If the application starts without configuration, it uses unsafe default values that can expose sensitive data in logs." The risk explanation turns a missing-file notice into an actionable security warning.

```
WARNING: THE CONFIGURATION FILE config.toml WAS NOT FOUND.
THE APPLICATION CANNOT START WITHOUT THIS FILE.
IF THE APPLICATION STARTS WITHOUT CONFIGURATION, IT USES UNSAFE
DEFAULT VALUES THAT CAN EXPOSE SENSITIVE DATA IN LOGS.

Check that config.toml is in the working directory. Set the
CONFIG_PATH environment variable to the file location.
```

**Changelogs and release notes.** A changelog entry that says "BREAKING: removed the `legacy_auth` module" tells users about a deletion. It must also say: "If your code imports `legacy_auth`, the build will fail. You must replace all imports with the `auth_v2` module. A build failure can delay your deployment and cause service downtime." The risk explanation helps users plan their migration. A changelog without risk explanations is a list of facts. A changelog with risk explanations is a migration guide.

```markdown
## [4.0.0] - 2026-08-01

### BREAKING
- Removed the `legacy_auth` module.

  WARNING: IF YOUR CODE IMPORTS `legacy_auth`, THE BUILD WILL FAIL.
  YOU MUST REPLACE ALL IMPORTS WITH THE `auth_v2` MODULE.
  A BUILD FAILURE CAN DELAY YOUR DEPLOYMENT AND CAUSE SERVICE DOWNTIME.

  Run `grep -r legacy_auth src/` to find every import. The `auth_v2`
  module uses token scopes instead of the old role list. See the
  migration guide before you upgrade.
```

**The risk explanation must match the signal word level.** The original ASD-STE100 defines two severity levels: WARNING (risk of injury or death) and CAUTION (risk of equipment damage). In code documentation, WARNING maps to data loss, security breach, or system unavailability. CAUTION maps to incorrect results, degraded performance, or build failures. A risk explanation under a WARNING must describe a severe outcome. A risk explanation under a CAUTION must describe a moderate outcome. Do not use WARNING for a build failure. Do not use CAUTION for a data breach. Mismatched severity erodes trust in all safety instructions in the document.

## Paradigm-Specific Guidance

**Object-Oriented (Java, C++, C#, Python classes).** In OOP, risk explanations often involve state corruption and inheritance contracts. A warning about a mutable field must explain that subclasses can modify the field in unexpected ways. A caution about a non-final method must explain that overriding can violate the base class invariant.

> **Non-STE:** CAUTION: DO NOT OVERRIDE THE `initialize()` METHOD.
>
> **STE:** CAUTION: DO NOT OVERRIDE THE `initialize()` METHOD. IF YOU OVERRIDE `initialize()`, THE BASE CLASS CONNECTION POOL IS NOT SET. CONNECTIONS WITHOUT A POOL CAN CAUSE RESOURCE EXHAUSTION AND APPLICATION CRASHES.
>
> *Principles applied: P3 (get → is not set), P7 (initialize as verb, not noun). Risk connects override to pool state to crash.*

```python
class Database:
    def __init__(self):
        self._pool = self._build_pool()

    def initialize(self):
        """CAUTION: DO NOT OVERRIDE THE `initialize()` METHOD.
        IF YOU OVERRIDE `initialize()`, THE BASE CLASS CONNECTION POOL IS
        NOT SET. CONNECTIONS WITHOUT A POOL CAN CAUSE RESOURCE EXHAUSTION
        AND APPLICATION CRASHES.

        Subclasses that override initialize must call super().initialize()
        first, or the pool stays None and every query fails open."""
        self._ready = True
```

**Functional (Haskell, Elixir, Clojure, Rust).** In functional paradigms, risk explanations often involve purity violations and lazy evaluation surprises. A warning about an impure function must explain that referential transparency is broken. A caution about an unsafe IO operation must explain that laziness delays the side effect beyond the expected execution point.

> **Non-STE:** WARNING: `unsafePerformIO` IS DANGEROUS.
>
> **STE:** WARNING: DO NOT USE `unsafePerformIO` IN PRODUCTION CODE. `unsafePerformIO` REMOVES THE IO TYPE SAFETY GUARANTEE. WITHOUT THE IO GUARANTEE, SIDE EFFECTS CAN RUN AT UNEXPECTED TIMES. SIDE EFFECTS AT UNEXPECTED TIMES CAN CAUSE RACE CONDITIONS AND SILENT DATA CORRUPTION.
>
> *Principles applied: P10 (no slang: "dangerous" → specific risk), P4 (approved adjective forms). Risk traces from type-safety removal to corruption.*

```haskell
-- WARNING: DO NOT USE `unsafePerformIO` IN PRODUCTION CODE.
-- `unsafePerformIO` REMOVES THE IO TYPE SAFETY GUARANTEE.
-- WITHOUT THE IO GUARANTEE, SIDE EFFECTS CAN RUN AT UNEXPECTED TIMES.
-- SIDE EFFECTS AT UNEXPECTED TIMES CAN CAUSE RACE CONDITIONS AND
-- SILENT DATA CORRUPTION.
--
-- cacheLookup reads a file inside a pure function. Two calls with the
-- same key can return different values because the file changes between
-- them. Referential transparency is broken.
secret :: Key -> Value
secret k = unsafePerformIO (readSecretFromFile k)
```

**Procedural (C, Go, Bash).** In procedural code, risk explanations often involve resource lifetimes and error-code neglect. A warning about a `malloc` without `free` must explain the leak's cumulative effect. A caution about an ignored return code must explain the silent failure path.

> **Non-STE:** WARNING: YOU MUST FREE THE BUFFER.
>
> **STE:** WARNING: YOU MUST FREE THE BUFFER AFTER EACH `malloc` CALL. EACH UNFREED BUFFER STAYS IN MEMORY UNTIL THE PROCESS STOPS. IN A LONG-RUNNING PROCESS, UNFREED BUFFERS CAN USE ALL AVAILABLE MEMORY. MEMORY EXHAUSTION CAN CAUSE THE OPERATING SYSTEM TO STOP THE PROCESS.
>
> *Principles applied: P1 (use → after each call), P9 (short, clear nouns). Risk traces from unfreed buffer to OS termination.*

```c
/* WARNING: YOU MUST FREE THE BUFFER AFTER EACH `malloc` CALL.
   EACH UNFREED BUFFER STAYS IN MEMORY UNTIL THE PROCESS STOPS.
   IN A LONG-RUNNING PROCESS, UNFREED BUFFERS CAN USE ALL AVAILABLE
   MEMORY. MEMORY EXHAUSTION CAN CAUSE THE OPERATING SYSTEM TO STOP
   THE PROCESS. */
char *buf = malloc(1024);
if (buf == NULL) { return ERR_NOMEM; }
parse(buf);
free(buf);   /* without this line, the leak grows every call */
```

**Declarative (SQL, Terraform, Kubernetes YAML).** In declarative configurations, risk explanations often involve cascading side effects from a single declaration. A Terraform resource change can destroy and recreate infrastructure. A Kubernetes manifest misconfiguration can expose internal services.

> **Non-STE:** CAUTION: DO NOT CHANGE THE `family` FIELD.
>
> **STE:** CAUTION: DO NOT CHANGE THE `family` FIELD IN THE `aws_db_instance` RESOURCE. TERRAFORM INTERPRETS A CHANGE TO `family` AS A DESTROY-AND-RECREATE OPERATION. A DESTROY-AND-RECREATE OPERATION REMOVES THE CURRENT DATABASE AND ALL ITS DATA. THE REMOVED DATA CANNOT BE RECOVERED.
>
> *Principles applied: P3 (show → interprets), P11 (one term: destroy-and-recreate). Risk explains the interpreter behavior behind the field change.*

```hcl
resource "aws_db_instance" "main" {
  # CAUTION: DO NOT CHANGE THE `family` FIELD IN THIS RESOURCE.
  # TERRAFORM INTERPRETS A CHANGE TO `family` AS A DESTROY-AND-RECREATE
  # OPERATION. A DESTROY-AND-RECREATE OPERATION REMOVES THE CURRENT
  # DATABASE AND ALL ITS DATA. THE REMOVED DATA CANNOT BE RECOVERED.
  family = "postgres16"
}
```

**Systems (Rust ownership, C memory, kernel documentation).** Systems documentation carries the highest-risk instructions. A warning about undefined behavior in C must explain the practical consequence, not just cite the standard. A Rust `unsafe` block documentation must explain which safety invariant the caller must uphold and what happens if it is not.

> **Non-STE:** WARNING: THIS FUNCTION IS UNSAFE. THE CALLER MUST NOT ALIAS THE POINTER.
>
> **STE:** WARNING: THIS FUNCTION IS UNSAFE. THE CALLER MUST MAKE SURE THAT NO OTHER POINTER REFERS TO THE SAME MEMORY. IF TWO POINTERS REFER TO THE SAME MEMORY, THE COMPILER CAN REMOVE LOADS AND STORES THAT THE PROGRAM NEEDS. REMOVED LOADS AND STORES CAN CAUSE VALUES TO APPEAR FROM DIFFERENT EXECUTION TIMELINES, WHICH IS UNDEFINED BEHAVIOR.
>
> *Principles applied: P2 (alias → refer to, specified part of speech), P8 (standard technical nouns: undefined behavior). Risk connects aliasing to compiler optimization to undefined behavior.*

```rust
/// WARNING: THIS FUNCTION IS UNSAFE.
/// THE CALLER MUST MAKE SURE THAT NO OTHER POINTER REFERS TO THE SAME MEMORY.
/// IF TWO POINTERS REFER TO THE SAME MEMORY, THE COMPILER CAN REMOVE
/// LOADS AND STORES THAT THE PROGRAM NEEDS. REMOVED LOADS AND STORES CAN
/// CAUSE VALUES TO APPEAR FROM DIFFERENT EXECUTION TIMELINES, WHICH IS
/// UNDEFINED BEHAVIOR.
///
/// `write_volatile` writes through `ptr` with no aliasing check. Keep the
/// pointed-to memory exclusive to this call while it runs.
pub unsafe fn write_volatile(ptr: *mut u32, value: u32) { /* ... */ }
```

## Extended Examples

> **Non-STE:** WARNING: DO NOT USE `eval()`.
>
> **STE:** WARNING: DO NOT USE `eval()` WITH DATA FROM EXTERNAL SOURCES. `eval()` RUNS THE INPUT AS CODE WITH THE SAME PRIVILEGES AS THE APPLICATION. A MALICIOUS INPUT CAN RUN ARBITRARY COMMANDS ON THE HOST SYSTEM. ARBITRARY COMMANDS CAN CAUSE DATA THEFT, DATA DESTRUCTION, OR SYSTEM COMPROMISE.
>
> *Principles applied: P5 (technical code noun: `eval`), P3 (use → runs, approved meaning). Risk traces from eval to full system compromise.*

```javascript
// WARNING: DO NOT USE `eval()` WITH DATA FROM EXTERNAL SOURCES.
// `eval()` RUNS THE INPUT AS CODE WITH THE SAME PRIVILEGES AS THE APPLICATION.
// A MALICIOUS INPUT CAN RUN ARBITRARY COMMANDS ON THE HOST SYSTEM.
// ARBITRARY COMMANDS CAN CAUSE DATA THEFT, DATA DESTRUCTION, OR SYSTEM COMPROMISE.
function runFilter(userInput) {
  // Bad: eval(userInput)
  return JSON.parse(userInput); // Safe: parse only, no code execution
}
```

> **Non-STE:** CAUTION: PAGINATION IS MANDATORY.
>
> **STE:** CAUTION: YOU MUST USE PAGINATION FOR ALL LIST ENDPOINTS. WITHOUT PAGINATION, A SINGLE REQUEST CAN RETURN EVERY RECORD IN THE DATABASE. A LARGE RESULT SET CAN CAUSE MEMORY EXHAUSTION ON THE SERVER. MEMORY EXHAUSTION CAN CAUSE THE SERVER TO STOP AND ALL CONNECTED CLIENTS TO DISCONNECT.
>
> *Principles applied: P9 (short, clear: pagination), P1 (use → use). Risk traces from missing pagination to server crash.*

```python
@app.get("/users")
def list_users(page: int = 1, per_page: int = 50):
    """CAUTION: YOU MUST USE PAGINATION FOR ALL LIST ENDPOINTS.
    WITHOUT PAGINATION, A SINGLE REQUEST CAN RETURN EVERY RECORD IN THE
    DATABASE. A LARGE RESULT SET CAN CAUSE MEMORY EXHAUSTION ON THE SERVER.
    MEMORY EXHAUSTION CAN CAUSE THE SERVER TO STOP AND ALL CONNECTED
    CLIENTS TO DISCONNECT.

    Reject requests where per_page is above 100. Use keyset pagination on
    the `id` column for stable ordering."""
    return db.paginate(page, per_page)
```

> **Non-STE:** WARNING: CORS IS NOT CONFIGURED PROPERLY.
>
> **STE:** WARNING: THE CORS CONFIGURATION USES A WILDCARD ORIGIN (`*`). A WILDCARD ORIGIN LETS ANY WEBSITE SEND REQUESTS WITH THE USER'S CREDENTIALS. AN ATTACKER CAN MAKE AN AUTHENTICATED REQUEST FROM A MALICIOUS WEBSITE. AUTHENTICATED REQUESTS FROM A MALICIOUS ORIGIN CAN CAUSE DATA THEFT AND ACCOUNT TAKEOVER.
>
> *Principles applied: P5 (CORS, wildcard as technical nouns), P6 (non-approved word as technical noun). Risk traces from wildcard to account takeover.*

```javascript
// WARNING: THE CORS CONFIGURATION USES A WILDCARD ORIGIN (`*`).
// A WILDCARD ORIGIN LETS ANY WEBSITE SEND REQUESTS WITH THE USER'S
// CREDENTIALS. AN ATTACKER CAN MAKE AN AUTHENTICATED REQUEST FROM A
// MALICIOUS WEBSITE. AUTHENTICATED REQUESTS FROM A MALICIOUS ORIGIN CAN
// CAUSE DATA THEFT AND ACCOUNT TAKEOVER.
app.use(cors({
  origin: ["https://app.example.com"], // not "*"
  credentials: true,
}));
```

> **Non-STE:** WARNING: RACE CONDITION.
>
> **STE:** WARNING: TWO GOROUTINES CAN WRITE TO THE `counter` VARIABLE AT THE SAME TIME. CONCURRENT WRITES TO A GO VARIABLE WITHOUT A MUTEX CAUSE A DATA RACE. DATA RACES CAN MAKE THE COUNTER VALUE INCORRECT. AN INCORRECT COUNTER CAN CAUSE BILLING ERRORS AND FINANCIAL LOSS.
>
> *Principles applied: P7 (no technical noun as verb: "race" is a noun here), P3 (make → cause). Risk traces from data race to financial loss.*

```go
// WARNING: TWO GOROUTINES CAN WRITE TO THE `counter` VARIABLE AT THE SAME
// TIME. CONCURRENT WRITES TO A GO VARIABLE WITHOUT A MUTEX CAUSE A DATA
// RACE. DATA RACES CAN MAKE THE COUNTER VALUE INCORRECT. AN INCORRECT
// COUNTER CAN CAUSE BILLING ERRORS AND FINANCIAL LOSS.
var counter int
var mu sync.Mutex

func increment() {
    mu.Lock()
    defer mu.Unlock()
    counter++ // protected: no data race
}
```

> **Non-STE:** CAUTION: DO NOT SKIP MIGRATIONS.
>
> **STE:** CAUTION: DO NOT SKIP DATABASE MIGRATIONS. EACH PENDING MIGRATION CAN ADD, REMOVE, OR CHANGE COLUMNS. IF THE APPLICATION STARTS WITHOUT APPLYING ALL MIGRATIONS, THE APPLICATION SCHEMA DOES NOT MATCH THE DATABASE SCHEMA. SCHEMA MISMATCHES CAN CAUSE QUERY FAILURES, SILENT DATA LOSS, AND APPLICATION CRASHES.
>
> *Principles applied: P1 (skip → skip), P4 (approved adjective: pending). Risk traces from skipped migration to crashes.*

```sql
-- CAUTION: DO NOT SKIP DATABASE MIGRATIONS.
-- EACH PENDING MIGRATION CAN ADD, REMOVE, OR CHANGE COLUMNS.
-- IF THE APPLICATION STARTS WITHOUT APPLYING ALL MIGRATIONS, THE
-- APPLICATION SCHEMA DOES NOT MATCH THE DATABASE SCHEMA. SCHEMA
-- MISMATCHES CAN CAUSE QUERY FAILURES, SILENT DATA LOSS, AND CRASHES.
--
-- Run this before you start the application after a deploy:
--   alembic upgrade head
SELECT version_num FROM alembic_version;
```

> **Non-STE:** WARNING: HARDCODED SECRETS.
>
> **STE:** WARNING: THE CONFIGURATION FILE CONTAINS HARDCODED SECRETS. HARDCODED SECRETS BECOME PART OF THE SOURCE CODE HISTORY. ANY PERSON WITH ACCESS TO THE REPOSITORY CAN READ THE SECRETS. AN ATTACKER WITH REPOSITORY ACCESS CAN USE THE SECRETS TO ACCESS PRODUCTION SYSTEMS, DATABASES, AND THIRD-PARTY SERVICES.
>
> *Principles applied: P5 (secrets as technical noun), P3 (part of → become part of). Risk traces from hardcoded secrets to full infrastructure access.*

```yaml
# WARNING: THE CONFIGURATION FILE CONTAINS HARDCODED SECRETS.
# HARDCODED SECRETS BECOME PART OF THE SOURCE CODE HISTORY. ANY PERSON
# WITH ACCESS TO THE REPOSITORY CAN READ THE SECRETS. AN ATTACKER WITH
# REPOSITORY ACCESS CAN USE THE SECRETS TO ACCESS PRODUCTION SYSTEMS,
# DATABASES, AND THIRD-PARTY SERVICES.
#
# Replace the literal value with ${DATABASE_PASSWORD} and load it from
# the secret store. Then rotate the exposed password and remove the file
# from history with `git filter-repo`.
database:
  password: "s3cr3t-password"   # remove this line
```

## Edge Cases

**When a framework name is also an "unapproved" word.** Some framework names overlap with everyday English words that STE restricts. For example, the React framework `Suspense` is both a technical noun and an ordinary English word. A warning that says "DO NOT NEST SUSPENSE BOUNDARIES" could confuse readers who interpret Suspense as an emotion, not a component. The risk explanation must anchor the word in its technical meaning: "IF YOU NEST `Suspense` COMPONENTS, THE INNER SUSPENSE BOUNDARY CAN CAPTURE THE FALLBACK OF THE OUTER BOUNDARY. CAPTURED FALLBACKS CAN CAUSE INFINITE LOADING STATES AND UNRESPONSIVE PAGES." The code-formatted backticks and the repeated technical context disambiguate the term.

```jsx
// CAUTION: DO NOT NEST `Suspense` COMPONENTS.
// IF YOU NEST `Suspense` COMPONENTS, THE INNER SUSPENSE BOUNDARY CAN
// CAPTURE THE FALLBACK OF THE OUTER BOUNDARY. CAPTURED FALLBACKS CAN
// CAUSE INFINITE LOADING STATES AND UNRESPONSIVE PAGES.
function Page() {
  return (
    <Suspense fallback={<Spinner />}>
      <Suspense fallback={<Spinner />}>  {/* nested: captures fallback */}
        <Comments />
      </Suspense>
    </Suspense>
  );
}
```

**When a code keyword conflicts with the rule.** Keywords like `break`, `continue`, `return`, and `throw` carry control-flow meaning that risk explanations must address precisely. A warning that says "DO NOT USE `return` INSIDE A `finally` BLOCK" must explain the interaction: "IF YOU USE `return` IN A `finally` BLOCK, THE `return` REPLACES ANY EXCEPTION THAT WAS THROWN IN THE `try` BLOCK. THE REPLACED EXCEPTION IS LOST AND CANNOT BE CAUGHT BY CALLERS. SILENTLY LOST EXCEPTIONS CAN HIDE ERRORS THAT CAUSE INCORRECT PROGRAM BEHAVIOR." The risk explanation addresses the language-level semantic collision, not the word itself.

```java
// CAUTION: DO NOT USE `return` INSIDE A `finally` BLOCK.
// IF YOU USE `return` IN A `finally` BLOCK, THE `return` REPLACES ANY
// EXCEPTION THAT WAS THROWN IN THE `try` BLOCK. THE REPLACED EXCEPTION IS
// LOST AND CANNOT BE CAUGHT BY CALLERS. SILENTLY LOST EXCEPTIONS CAN HIDE
// ERRORS THAT CAUSE INCORRECT PROGRAM BEHAVIOR.
try {
  doWork();
} finally {
  cleanup();
  // return result;  // removes any exception from doWork()
}
```

**When the rule should be relaxed for generated code.** Generated code (protobuf stubs, OpenAPI clients, database ORM models) often contains instructions that violate Rule 7.3 because the generator produces terse, repetitive output. A generated file comment that says "DO NOT EDIT" without explanation is acceptable only if a companion document or the code generator's documentation explains the risk. If the generated code is the sole artifact the developer sees, the risk must still be explained: "DO NOT EDIT THIS FILE. THIS FILE IS REGENERATED EACH TIME YOU RUN `make generate`. IF YOU EDIT THE FILE, YOUR CHANGES ARE LOST THE NEXT TIME `make generate` RUNS. LOST CHANGES CAN CAUSE BUILD FAILURES AND REGRESSION BUGS."

```go
// Code generated by protoc-gen-go. DO NOT EDIT.
// DO NOT EDIT THIS FILE. THIS FILE IS REGENERATED EACH TIME YOU RUN
// `make generate`. IF YOU EDIT THE FILE, YOUR CHANGES ARE LOST THE NEXT
// TIME `make generate` RUNS. LOST CHANGES CAN CAUSE BUILD FAILURES AND
// REGRESSION BUGS.
package pb
```

**When the risk is probabilistic, not guaranteed.** Many software risks are not deterministic: a race condition may manifest only under load, a memory leak may exhaust resources only after days. Rule 7.3 still applies. Use "can" instead of "will" for probabilistic risks: "IF TWO THREADS WRITE TO THE MAP AT THE SAME TIME, A DATA RACE CAN OCCUR. THE DATA RACE CAN CAUSE INCORRECT MAP CONTENTS. INCORRECT MAP CONTENTS CAN CAUSE WRONG QUERY RESULTS AND SILENT DATA CORRUPTION." The word "can" communicates uncertainty without diminishing the severity.

```java
// CAUTION: THE CACHE IS NOT THREAD-SAFE.
// IF TWO THREADS WRITE TO THE MAP AT THE SAME TIME, A DATA RACE CAN OCCUR.
// THE DATA RACE CAN CAUSE INCORRECT MAP CONTENTS. INCORRECT MAP CONTENTS
// CAN CAUSE WRONG QUERY RESULTS AND SILENT DATA CORRUPTION.
// (A race may not happen on every run. Under load, it can.)
Map<String, Object> cache = new HashMap<>();
```

**When multiple risks share one instruction.** A single "DO NOT" instruction may prevent several different problems. List the risks in order of severity, from most severe to least severe: "DO NOT DISABLE TLS VERIFICATION. WITHOUT TLS VERIFICATION, A MAN-IN-THE-MIDDLE ATTACKER CAN DECRYPT AND CHANGE THE TRAFFIC. CHANGED TRAFFIC CAN CAUSE DATA THEFT, CREDENTIAL LEAKAGE, AND UNAUTHORIZED TRANSACTIONS." Each risk is a separate "can cause" clause that builds the cumulative case for the instruction.

```python
# WARNING: DO NOT DISABLE TLS VERIFICATION.
# WITHOUT TLS VERIFICATION, A MAN-IN-THE-MIDDLE ATTACKER CAN DECRYPT AND
# CHANGE THE TRAFFIC. CHANGED TRAFFIC CAN CAUSE DATA THEFT, CREDENTIAL
# LEAKAGE, AND UNAUTHORIZED TRANSACTIONS.
import urllib3
urllib3.disable_warnings()  # remove this line
```

**When the risk is a cascading chain with no single owner.** Distributed systems failures often involve emergent behavior where no single component is at fault. A warning about removing a circuit breaker must explain the cascading effect across services: "IF YOU REMOVE THE CIRCUIT BREAKER FROM THE PAYMENT SERVICE, A SLOWDOWN IN THE INVENTORY SERVICE CAN PROPAGATE TO THE PAYMENT SERVICE. THE PROPAGATED SLOWDOWN CAN CAUSE TIMEOUTS IN THE ORDER SERVICE. ORDER SERVICE TIMEOUTS CAN CAUSE CUSTOMERS TO PLACE DUPLICATE ORDERS. DUPLICATE ORDERS CAN CAUSE INCORRECT CHARGES AND FINANCIAL LOSS." The risk explanation traces the chain across three services without blaming any single component.

```yaml
# WARNING: DO NOT REMOVE THE CIRCUIT BREAKER FROM THE PAYMENT SERVICE.
# IF YOU REMOVE THE CIRCUIT BREAKER, A SLOWDOWN IN THE INVENTORY SERVICE
# CAN PROPAGATE TO THE PAYMENT SERVICE. THE PROPAGATED SLOWDOWN CAN CAUSE
# TIMEOUTS IN THE ORDER SERVICE. ORDER SERVICE TIMEOUTS CAN CAUSE
# CUSTOMERS TO PLACE DUPLICATE ORDERS. DUPLICATE ORDERS CAN CAUSE
# INCORRECT CHARGES AND FINANCIAL LOSS.
payment_service:
  circuit_breaker:
    enabled: true   # keep true
```

**When the risk affects a different team than the reader.** In large organizations, the person who reads the documentation is often not the person who suffers the consequence. An infrastructure engineer reading an application warning may not feel the urgency. The risk explanation must bridge the organizational gap: "DO NOT DEPLOY WITHOUT CONTACTING THE DATABASE TEAM FIRST. THE DATABASE TEAM MUST LOCK THE SCHEMA BEFORE DEPLOYMENT. IF YOU DEPLOY WITHOUT A SCHEMA LOCK, THE MIGRATION CAN CONFLICT WITH ANOTHER DEPLOYMENT. SCHEMA CONFLICTS CAN CAUSE DATA CORRUPTION THAT AFFECTS ALL TEAMS USING THE DATABASE." The phrase "affects all teams using the database" connects the reader's action to consequences beyond their immediate team.

```markdown
## Deploy Checklist

WARNING: DO NOT DEPLOY WITHOUT CONTACTING THE DATABASE TEAM FIRST.
THE DATABASE TEAM MUST LOCK THE SCHEMA BEFORE DEPLOYMENT.
IF YOU DEPLOY WITHOUT A SCHEMA LOCK, THE MIGRATION CAN CONFLICT WITH
ANOTHER DEPLOYMENT. SCHEMA CONFLICTS CAN CAUSE DATA CORRUPTION THAT
AFFECTS ALL TEAMS USING THE DATABASE.

Open the #db-deploys channel and request a lock before you run the
migration. Wait for the lock confirmation before you continue.
```

## Cross-References

- **Rule 1.1 (Use approved words):** The words in your risk explanation must come from the STE-Code dictionary. See the Canonical Synonym Table for substitutes (for example, replace non-approved verbs with their approved general-purpose equivalents such as use, set, check, make, get, remove, keep).
- **Rule 1.6 (Non-approved words only as technical nouns):** When a risk explanation must include a non-approved word (for example, `deadlock`, `thrashing`, `replay attack`), present it as a technical code noun and define it on first use.
- **Rule 1.10 (No slang, jargon, or regional terms):** A risk explanation that says "this will brick your deployment" fails Rule 1.10 and Rule 7.3 simultaneously. Replace "brick" with the specific consequence: "THIS WILL MAKE THE DEPLOYMENT PERMANENTLY UNAVAILABLE."
- **Rule 7.1 (Use clear, specific safety signal words):** The signal word (WARNING or CAUTION) sets the severity level. Rule 7.3 connects the signal word to the concrete consequence. A WARNING demands a risk of injury or data loss. A CAUTION demands a risk of incorrect results or system damage.
- **Rule 7.2 (Place safety instructions before the related step):** The instruction must come before the risky action. The risk explanation in Rule 7.3 comes immediately after the instruction, before the reader proceeds. The order is: signal word → instruction → risk explanation → action.
- **Rule 7.4 (Use imperative mood for instructions):** The instruction part of a Rule 7.3 warning must use imperative mood ("DO NOT USE"), not descriptive ("using this is not recommended"). The risk explanation part may use declarative mood to state the consequence.
- **Section 1 (Words):** All words in risk explanations follow the noun-verb-adjective rules of Section 1. A risk sentence like "This initiates a cascade failure" violates Rule 1.2 (initiate → start) and Rule 1.3 (cascade as unapproved modifier). The STE version: "This can start a sequence of failures."

> **See also:** Rule 7.1 — Use an Applicable Word (for Example, "Warning" or "Caution") to Identify the Level of Risk; Rule 7.2 — Start a Safety Instruction with a Clear and Accurate Command or Condition; Rule 7.4 — Use Imperative Mood for Instructions

## Grammar Notes

The original ASD-STE100 Rule 7.3 carries grammatical justification that adapts directly to code documentation.

**Causal connective "IF...THEN" structure.** The original spec uses "IF THEY FALL, PERMANENT DAMAGE TO THE PARTS CAN OCCUR." The "IF" clause states the violation (not obeying the instruction). The main clause states the consequence. This structure is mandatory for risk explanations in code documentation. Always state the violation first, then the consequence. Do not reverse the order: "PERMANENT DATA LOSS CAN OCCUR IF YOU DO NOT SET THE TIMEOUT" is grammatically correct but less effective because the reader processes the gravity before knowing the cause. The STE pattern puts cause before effect so the reader follows the logical chain.

**Modal verb "can" versus "will."** Use "can" for risks that are possible but not certain. Use "will" only for risks that are guaranteed. "A data race can cause incorrect results" (possible). "A build will fail if a required dependency is not declared" (guaranteed). Never use "may" — it introduces ambiguity about permission versus possibility, and STE restricts "may" to permission contexts only. Never use "might" — it is less direct than "can" and is listed as an unapproved word in the STE dictionary.

**Active voice in risk explanations.** The subject of a risk sentence must be the thing that causes harm, not an abstract noun. "Data loss can occur" identifies the concrete harm. "There can be a loss of data" is passive and indirect. The active form makes the risk tangible. For systemic risks where no single agent exists, use the system or component as the subject: "The database can reject inconsistent writes." "Inconsistent writes can be rejected" is passive and hides the agent.

**Article usage in risk statements.** Do not omit articles from risk explanations. "Buffer overflow can cause crash" is incorrect. Write: "A buffer overflow can cause a crash." The indefinite article "a" before "buffer overflow" establishes that any single overflow triggers the risk. The indefinite article before "crash" establishes the type of failure. Omitting articles makes the risk sound like a headline, not an explanation.

**Sentence length constraint.** Risk explanations can chain consequences, but each link in the chain must stay within the 20-word procedural limit. Break long causal chains into separate sentences: "WITHOUT A TIMEOUT, THE CONNECTION CAN HANG FOREVER. A HANGING CONNECTION CAN USE ALL AVAILABLE THREADS. EXHAUSTED THREADS CAN CAUSE THE SERVER TO REJECT NEW REQUESTS." Each sentence states one causal link. The cumulative effect is a multi-step risk chain that the reader can process incrementally.

**Avoid "ing" forms as main verbs in risk explanations.** Do not write: "Not setting the timeout causing the connection to hang." Write: "If you do not set the timeout, the connection can hang." The "-ing" form "causing" is a participle, not a main verb. The risk explanation requires a finite verb ("can hang") to form a complete clause that assigns the consequence to the violation.

**Avoid semicolons and nested clauses.** The causal relationship between violation and consequence must not depend on semicolons or deeply nested subordinate clauses. Write two simple sentences joined by the logical chain: "If you skip the migration, the schema does not match. A schema mismatch can cause query failures." Do not write: "If you skip the migration, which creates a schema mismatch that can cause query failures, the deployment will fail." The nested version buries the risk chain and exceeds the 2-level clause depth limit.

**Definite versus indefinite articles in multi-risk chains.** When a risk chain involves a series of consequences, use the indefinite article "a" for the first mention of each consequence and the definite article "the" for subsequent references to the same consequence: "An unhandled promise rejection can cause a memory leak. The memory leak can cause the process to use more memory over time." The shift from "a" to "the" signals to the reader that "the memory leak" refers back to the consequence just introduced. Do not use "this" as a determiner in risk chains ("This memory leak can cause...") — STE treats "this" without an explicit noun as potentially ambiguous. Always pair "this" with the noun it modifies: "This type of memory leak."

**Imperative versus declarative mood in compound warnings.** A complete Rule 7.3 instruction has two grammatical moods. The instruction is imperative: "DO NOT DISABLE TLS VERIFICATION." The risk explanation is declarative: "Without TLS verification, an attacker can decrypt the traffic." Do not mix moods within a single sentence. Do not write: "Do not disable TLS verification because an attacker can decrypt the traffic." The conjunction "because" weakens the imperative by making the instruction sound like a suggestion. Use a period and start a new sentence for the risk explanation. The pause between the command and the consequence gives the reader a moment to register the instruction before processing its justification.

## Practical Application

Apply Rule 7.3 during documentation review with this checklist:

1. Find every WARNING and CAUTION in the document.
2. For each, ask: "What happens if the reader ignores this?"
3. If the answer is not written after the instruction, add it.
4. Check that the risk explanation uses "can" (probabilistic) or "will" (guaranteed) correctly.
5. Verify the risk matches the signal word severity (WARNING = data loss/security, CAUTION = incorrect results/build failures).
6. Confirm the risk chain reads cause-first: "If you do X, Y can happen." Not effect-first: "Y can happen if you do X."
7. Break any risk explanation over 20 words into separate causal-link sentences.
8. Replace any "-ing" participles with finite verbs ("causing" → "can cause").
9. Replace "may" and "might" with "can" or "will."
10. Check that technical nouns in code formatting are defined on first use in the risk chain.

A document where every safety instruction carries a clear, specific risk explanation is a document developers trust. A document where instructions carry unexplained prohibitions is a document developers ignore. The difference is Rule 7.3.



## rules-sec8.md

# Level 5 — Punctuation and Word Count (Section 8)

Section 8 of STE-Code governs punctuation and word-count mechanics in code
documentation. It contains seven rules: 8.1 (no semicolon), 8.2 (hyphens),
8.3 (parentheses usage), 8.4 (colon in vertical lists), 8.5 (parentheses and
word count), 8.6 (elements that count as one word), and 8.7 (hyphenated words
count as one word).

This is the full-standard (Level 5) slice. Use it when an LLM generates or
revises code documentation: README files, API reference docs, docstrings, inline
comments, commit messages, error messages, configuration comments, and
specification documents. All guidance below is faithful to the STE-Code
standard and uses code-domain examples only.

Quick reference — the seven rules:

- 8.1 No semicolon (;) in documentation prose.
- 8.2 Hyphenate directly related words (compound adjectives / technical nouns).
- 8.3 Parentheses: references, abbreviations, item IDs, alternatives, singular/plural, explanations.
- 8.4 A colon before a vertical list acts as a period (sentence boundary) with word-count limits.
- 8.5 Parenthetical text counts as one word in the enclosing sentence but is its own separate sentence.
- 8.6 Numbers, units, abbreviations, identifiers, quoted text, titles/labels, and proper nouns each count as one word.
- 8.7 A hyphenated word group counts as one word.

## Rule 8.1 — No semicolon (;)

You may use all standard English punctuation marks in code documentation except
the semicolon (;). The semicolon is forbidden because it lets you pack two
independent clauses into one sentence, which is hard to read — especially for
non-native English readers — and because the semicolon is a statement terminator
in many languages (C, C++, Java, JavaScript, Rust, Go), causing cognitive
interference in documentation prose.

Fix every violation the same way: split the semicolon-separated sentence into two
or more independent sentences. Each new sentence stands alone with its own
subject and verb. This aligns with Rule 3.1 (simple sentences) and Rule 4.1
(short sentences).

Applies to: README, API reference docs, docstrings, inline comments, commit
messages, error messages, configuration comments, and specification documents.
Does NOT apply to source code (where the semicolon is syntax) or to code shown
inside code blocks / inline backticks.

### Examples

Non-STE: Call the function to parse the response data; handle any errors that occur.
STE:    Call the function to parse the response data. Handle any errors that occur.

Non-STE: The cache is invalid after a write operation; you must flush it before the next read.
STE:    The cache is invalid after a write operation. You must flush it before the next read.

Non-STE: The server supports WebSocket connections; these use a persistent channel instead of the standard request-response cycle.
STE:    The server supports WebSocket connections. These connections use a persistent channel instead of the standard request-response cycle.

Non-STE: POST /sessions creates a new session and returns a token; the token must be included in the Authorization header of subsequent requests.
STE:    A POST request to /sessions makes a new session and returns a token. You must include the token in the Authorization header of all later requests.

Non-STE: Invalid port number; specify a value between 1024 and 65535.
STE:    The port number is not valid. Specify a value between 1024 and 65535.

Non-STE: The authentication middleware now checks token expiry before decoding; expired tokens return a 401 before reaching the route handler.
STE:    The authentication middleware now checks token expiry before decoding. Expired tokens return a 401 status code before they reach the route handler.

### Paradigm notes
- Object-oriented: split constructor initialization from post-condition; for getter/setter pairs, write each method's description as its own sentence.
- Functional: describe the happy path as one sentence, the error path as a second sentence. Do not reinforce the `|>` / `>>` / `.` pipe with a semicolon in prose.
- Procedural (C, Go, Bash): write each step as its own sentence; use "then" at the start of the second sentence for tight sequences.
- Declarative (SQL, Terraform, Kubernetes): write each property and each effect as its own sentence.
- Systems (Rust ownership, C memory): write the safety rule as one sentence and the consequence as a second sentence introduced with "thus" or "as a result." For Undefined Behavior, never use a semicolon — the consequence must be a standalone sentence.

### Edge cases
1. Semicolons inside code blocks / inline backticks are language syntax, not prose. Keep them. The rule governs surrounding prose only.
2. Generator-inserted semicolons in auto-generated docs (OpenAPI, JSDoc, protobuf) are not your violation; apply 8.1 to the source comments you author.
3. Semicolons inside quoted strings (error output, logs) are quoted material — keep them; prose around must obey 8.1.
4. Do not use a semicolon as a "super-comma" in a complex list. Use a bullet list or table instead.
5. Chat / informal PR-thread messages: 8.1 is optional. Commit messages are permanent history and must follow 8.1.
6. A semicolon inside a regex, CSV row, or data string is data, not prose — keep it in the code span.

### Cross-references
Rule 1.1 (approved words for connecting clauses), Rule 3.1 (simple sentences),
Rule 4.1 (short sentences), Rule 4.4 (connecting words replace the semicolon),
Rule 8.2 (hyphen versus semicolon).

## Rule 8.2 — Use hyphens (-) to connect directly related words

Use a hyphen to connect two or more words that function as one concept, most
often a compound adjective before a noun. The hyphen signals to the reader that
the words form a single unit and removes ambiguity about which word modifies
which. A hyphen joins words; a semicolon/colon joins clauses. Keep the two
distinct.

The five code-domain hyphenation categories:

1. Compound adjectives before a noun: high-priority task, read-only file,
   thread-safe method, event-driven architecture, type-safe interface,
   run-time error, end-to-end test, point-to-point connection,
   server-side rendering, client-side validation, just-in-time compilation,
   fire-and-forget pattern.
2. Two-word fractions / numbers: seventy-two, three-fourths, one hundred and
   sixty-two.
3. Uppercase-or-number + noun giving shape/configuration: L-shaped bracket,
   T-shaped connector, 64-bit register, 8-byte alignment, 128-bit value,
   3-prong connector.
4. Verbs whose first part is a noun or different part of speech: dry-run,
   hot-reload, cold-start, hard-code, soft-delete, short-circuit.
5. Prefix ending in a vowel + root starting with a vowel: pre-initialized,
   re-entrant, de-allocated, anti-aliasing, re-indexed.

### Examples

Non-STE: The high priority task must acquire the write lock before it can modify the shared data structure.
STE:    The high-priority task must get the write lock before it can change the shared data structure.

Non-STE: A read only file descriptor to open the configuration for parsing.
STE:    A read-only file descriptor to open the configuration for parsing.

Non-STE: A non negative integer that sets the buffer size. / A read only reference to the internal cache.
STE:    A non-negative integer that sets the buffer size. / A read-only reference to the internal cache.

Non-STE: The thread safe singleton uses lazy initialization to defer object creation until the first access.
STE:    The thread-safe singleton uses lazy initialization to defer object creation until the first access.

Non-STE: The left joined table uses a fully qualified column name from the user provided input.
STE:    The left-joined table uses a fully-qualified column name from the user-provided input.

Non-STE: The memory mapped file uses a copy on write page that is atomically reference counted.
STE:    The memory-mapped file uses a copy-on-write page that is atomically-reference-counted.

### Paradigm key terms
- OO: read-only property, write-only field, lazy-initialized singleton, reference-counted pointer, thread-safe collection, lock-free algorithm.
- Functional: pure-function semantics, side-effect-free computation, higher-order function, copy-on-write map, lazily-evaluated sequence, lock-free CAS loop.
- Procedural: null-terminated string, zero-initialized struct, stack-allocated array, const-qualified parameter, short-circuit evaluation, newline-delimited output.
- Declarative: left-joined table, fully-qualified column name, read-only attribute, base64-encoded value, cluster-scoped resource, blue-green deployment.
- Systems: move-semantics transfer, borrow-checked reference, memory-mapped I/O, copy-on-write page, lock-free stack, use-after-free bug.

### Edge cases
1. Keep hyphenated tool/library names as-is (create-react-app). Do not add a second hyphen (correct: "the create-react-app template"; wrong: "create-react-app-template").
2. In prose, hyphenate code keywords used as compound adjectives ("the type-of operator", "a full-outer-join operation"); in code spans, reproduce exactly (`typeof x`, `FULL OUTER JOIN`).
3. Leave generated output as-is; add a NOTE in surrounding prose if the generator omits hyphens.
4. An established unhyphenated compound (codebase, filename, namespace) may stay if it is unambiguous and consistent project-wide; otherwise hyphenate.
5. API endpoints / URL paths use kebab-case as proper nouns — keep hyphens in the path (`/api/read-only-access`); prose hyphenation follows 8.2 separately.

### Grammar notes
- Attributive (before noun) takes a hyphen; predicative (after a linking verb) does not: "the thread-safe collection" vs "the collection is thread safe."
- Adverbs ending in "-ly" do NOT take a hyphen: "a fully qualified name", not "fully-qualified".
- "self-" prefix always takes a hyphen (self-contained, self-signed).
- Do not insert hyphens into code identifiers (`getUserProfile`, not "get-user-profile"); use the identifier verbatim in backticks.

### Cross-references
Rule 1.1 (approved words), Rule 1.5 (technical nouns as first element),
Rule 1.9 (shorten long compounds), Rule 1.11 (consistent form), Rule 8.1,
Rule 8.6 (hyphenated term counts as one word), Rule 8.7.

## Rule 8.3 — Use of parentheses

You may use parentheses in code documentation for seven purposes:

1. References to modules, diagrams, or text: "Call the request handler (Figure 3, Module A)." / "Deploy the service (refer to sections 2 thru 5)."
2. Letters or numbers that identify diagram or text items: "Disconnect the endpoints (2) and (12) from the load balancer (8)."
3. Work-step identification in a procedure: "(1) Install the dependency package (4) in the project directory (8)."
4. Abbreviations, placed immediately after the full term: "A Command Line Interface (CLI) is a text-based interface…"
5. Singular and plural at once: "Before you run the test(s), set the environment variable(s)."
6. Explanations of words or part of a sentence: "Increase the timeout slowly (not more than 1000 ms each step)."
7. An alternative: "Use the left (right) API key for the staging (production) environment."

Square brackets [ ] are reserved for optional parameters in code syntax. Parentheses are the only permitted brackets for parenthetical information in prose. Do not use commas before an opening parenthesis except when the parenthetical is an alternative at the end of a list.

### Examples by doc type

README: This project provides a Command Line Interface (CLI) for managing your deployment pipeline. Follow the setup guide (refer to docs/getting-started.md) before you run the server.

API docs: The timeout parameter accepts an integer in milliseconds (ms). To use seconds, set the unit flag to "s" (available in version 2.1 and later). If the request fails, the server returns a 404 (Not Found) status.

Docstrings: timeout: milliseconds to wait (1 to 30000). / "Calculate the factorial of n (a non-negative integer)."

Commit messages: feat(auth): add PKCE support (issue #482). / fix(ui): correct z-index conflict between dropdown and modal (regression from v2.3).

Error messages: Cannot find the configuration file (searched: /etc/myapp/config.yaml, ~/.config/myapp/config.yaml, ./config.yaml). / Invalid value for --workers: 0 (valid range: 1 to 64).

### Paradigm notes
- OO: parentheses show method parameters, constructors, type parameters; "the `process` method (inherited from `BasePipeline`, which implements `core.Pipeline`)". Default values in tables: "milliseconds to wait before failure (default: 5000)."
- Functional: group type parameters; "the `State` monad passes an immutable state value… Use `StateT` (the transformer variant) to combine it with another monad."
- Procedural: return codes — "0 (success), -1 (I/O error), -2 (malformed input), -3 (timeout)"; ownership — "the caller must free the returned buffer (allocated by this function)."
- Declarative: enumeration values — "set the `provider` field to one of: "aws", "gcp", "azure" (lowercase only)"; "set `replicas` to the number of pod copies (range: 1 to 100, production minimum: 1)."
- Systems: ownership transfer — "this function takes ownership of the value (the caller cannot use it after the call)"; SAFETY invariants — "(invariant enforced by caller)."

### Edge cases
1. Framework/library names that are common words: clarify with a parenthetical on first use — "Use Flask (the Python web framework)…", "React (a JavaScript UI library)…".
2. Code keywords that are punctuation (Rust `()`, `<T>`): keep code literals distinct; explain in a separate sentence, do not nest.
3. Auto-generated docs (JSDoc, Sphinx, rustdoc): leave generated signatures untouched; apply 8.3 to human-written description fields.
4. Never nest parentheses. Restructure or split: "Set the cache TTL to 3600 (one hour). For production, set the cache TTL to 86400 (one day)." / "JWT is an abbreviation for JSON Web Token."
5. CLI help text: use parentheses sparingly — alternative or explanation patterns only; long descriptions belong in a man page.

### Cross-references
Rule 1.1 (abbreviation words), Rule 1.3 (approved meanings in explanations),
Rule 1.9 (short technical nouns), Rule 5.1 (parenthetical counts toward sentence
length), Rule 6.3 (one step per numbered line), Rule 8.2 (hyphens are not
parentheses). Period goes outside the closing parenthesis unless the
parenthetical is a complete sentence (then it becomes its own sentence).

## Rule 8.4 — Colon in a vertical list

In a vertical list, the colon (:) before the list acts as a period (full stop).
The introductory text before the colon is a complete sentence and must obey the
sentence-length limits: maximum 20 words for procedural text, 25 words for
descriptive text. Each list item after the colon is a new sentence with its own
limit (20 procedural / 25 descriptive).

The colon always ends the introductory sentence. Enumerated items must be
vertical (bullets or numbered), never inline. Em-dashes are not a substitute;
only the colon introduces a vertical list.

### Examples

Non-STE: To handle all possible error conditions, the following exception types must be caught and processed by the error handler: database connection timeouts which occur when the primary node is unreachable, authentication failures caused by expired or invalid tokens, and validation errors due to malformed request payloads.
STE:
To handle possible error conditions, the error handler catches these exception types:
- Database connection timeout
- Authentication failure
- Validation error.

Non-STE: ...supports these environment profiles that you can use for deployment: a development profile for local testing..., a staging profile..., and a production profile...
STE:
The configuration file supports these environment profiles:
- Development
- Staging
- Production.

Non-STE: A successful request to the GET /users/{id} endpoint returns a JSON response body that contains the following fields which describe the user account...: an id field..., a username field..., an email field..., a created_at field..., and a status field...
STE:
A GET request to /users/{id} returns a JSON response with these fields:
- `id` — The unique user identifier (UUID string)
- `username` — The display name
- `email` — The verified email address
- `created_at` — The account creation timestamp (ISO 8601)
- `status` — The account status (`active`, `suspended`, or `pending_verification`).

### Guidance by doc type
- README: keep the introduction to the category only; move version numbers, caveats, and compatibility notes into list items or a prior sentence.
- API docs: name the endpoint/resource and what the list enumerates; put type, default, and validation in each item (Args:/Returns:/Raises: sections align naturally).
- Docstrings: "This function handles these edge cases: - Empty input strings - Input with only whitespace…".
- Commit messages: the subject line is a standalone summary, not a list introduction; the body's intro must be short.
- Error messages: use a short intro ("The database migration failed for one of these reasons:") then one item per cause or recovery step.

### Paradigm notes
- OO: "The ConnectionPool constructor accepts these arguments: - url — A valid JDBC connection string… - maxConnections — The largest number of concurrent connections."
- Functional: "The ParseResult enum represents the result of parsing a configuration file. The enum has these variants: - Ok(Config) — … - Err(ParseError::Io) — …"
- Procedural: state the goal, then imperative steps — "Make sure that Go 1.21 or later is installed. … Then do these steps: - Clone the repository. - Run `go mod download`."
- Declarative: "The instance_type variable sets the EC2 instance size. The variable accepts these values: - t3.micro - t3.small - t3.medium." Put exclusions in a NOTE after the list.
- Systems: enumerate every precondition as its own bulleted item — "The caller must obey these safety conditions: - The pointer must not be null. - The pointer must be aligned to a 4-byte boundary. - …"

### Edge cases
1. Code tokens in backticks inside the introduction count as one word each, but prefer introductions with few code tokens and fewer than 15 total words.
2. Limit nested lists to one level; the parent item is a short category heading with its own colon.
3. A code block inside a list item is exempt from word count; keep the surrounding prose short.
4. Long framework/resource names belong in the list items, not the introduction.
5. Generator-produced colon-lists (OpenAPI, `--help`): obey 8.4 in source comments; accept the generator's boilerplate.

### Cross-references
Rule 1.1 (approved words in items), Rule 3.1 (one subject-verb-object per item),
Rule 3.3 (lists satisfy paragraph brevity), Rule 4.1 (limits apply at two
points: intro and each item), Rule 6.3 (procedural lists), Rule 8.1 (the colon
replaces semicolon-joined enumerations). The colon before a vertical list is the
approved replacement for semicolon-joined clause lists.

## Rule 8.5 — Parentheses and word count

When you put text in parentheses, it counts as ONE WORD in the enclosing
sentence. But the words inside the parentheses also form a separate sentence
with its own word-count limit (20 procedural / 25 descriptive). An identifier in
parentheses (a number, letter, or alphanumeric identifier) and an abbreviation
in parentheses each count as one word and do not need to obey the sentence-length
limit, because they are not prose.

Two types of parentheticals:
- Identifier parentheticals: (10), (EACCES), (CI/CD), (v2.1) — one word, no sentence limit.
- Explanatory parentheticals: (the DEBUG flag is off), (the worker runs every 60 seconds) — one word in the main sentence, but a complete separate sentence that must obey the limit.

Do not use parentheses to hide safety conditions, required steps, or warnings
the reader must act on. If the information is important enough to include, it is
important enough to be a main sentence.

### Examples

Non-STE: Make sure that the DEBUG environment variable is set to false before you run the deployment script in the production cluster (the DEBUG flag must be explicitly disabled for all production workloads to prevent accidental log leakage).
STE:    Make sure that the DEBUG environment variable is set to false (the DEBUG flag is off).

Non-STE: Remove the health check flag number ten from the deployment configuration.
STE:    Remove the health check flag (10).

Non-STE: Installation and Configuration of a Continuous Integration and Continuous Deployment Pipeline for the Application
STE:    Configuration of a Continuous Integration/Continuous Deployment (CI/CD) Pipeline

Non-STE: The timeout parameter sets the request timeout in seconds (this parameter is optional and defaults to 30 if not provided, but if you set retries greater than zero you should increase the timeout accordingly to account for the cumulative wait time across all retry attempts).
STE:    The timeout parameter sets the request timeout in seconds. The default value is 30. This parameter is optional. NOTE: If you set retries to a value larger than zero, increase the timeout to account for the cumulative wait time.

### Guidance by doc type
- README: do not bury conditional instructions in parentheses; split long asides into their own sentences.
- API docs: identifiers (200, 404, application/json, optional) count as one word; do not embed full conditional logic in a parameter description.
- Docstrings: short parentheticals ((int, optional), (default: 30)) are fine; move algorithmic explanations out.
- Commit messages: issue refs ((#1234)), (breaking), (auth) count as one word; put justification in the body, not in parentheses.
- Error messages: keep error codes and recovery hints short ((Error code: EACCES), (try: chmod 600)); never put the whole recovery procedure in parentheses — use a list.

### Paradigm notes
- OO: (User), (abstract), (Factory pattern) are identifier parentheticals, one word each; move inheritance rationale to its own paragraph.
- Functional: (Eq a), (when x > 0), (:else) are short; move transformation-chain descriptions to a list.
- Procedural: (exit code 1), (-v), (if root) are identifier parentheticals; promote error-branch logic to separate sentences.
- Declarative: (PostgreSQL 14+), (required), (default: true) are short; move migration/back-compat history out of parentheses into a NOTE/BREAKING block.
- Systems (stricter): never put safety-critical information in parentheses. Use the main sentence or a `# Safety` section — "The caller must obey these conditions: - The pointer must be valid for writes. - …"

### Edge cases
1. Function-call notation in backticks (`authenticate()`, `parse(input)`) is one atomic word; its internal parentheses are not Rule 8.5 parentheticals.
2. A URL in parentheses is an identifier (one word); if the parenthetical adds explanatory text after the URL, that text forms a separate sentence.
3. Never nest parentheses. Use an em-dash for the inner aside or split into a sentence.
4. Library/method names with parentheses as part of the canonical spelling (`expect()`) stay in backticks and count as one word.
5. Generator-inserted parentheticals (type hints, defaults) are accepted; follow 8.5 for any you write manually.

### Cross-references
Rule 1.5 (code nouns in parentheses), Rule 1.6 (non-approved words only as
technical nouns — parentheses are not a loophole), Rule 3.1 (the parenthetical
is a sentence), Rule 3.3 (long parentheticals signal a restructure), Rule 4.1
(word limits apply to the parenthetical sentence), Rule 8.1 (a semicolon inside
a parenthetical is still forbidden), Rule 8.4 (a parenthetical can hold a nested
list).

## Rule 8.6 — Elements that count as one word

For sentence-length counting, count each of these as ONE WORD:

1. Numbers: "Do steps 13 thru 16 a minimum of three times." / "The configuration file has twenty-one keys." Do NOT count numbers that identify paragraphs or work steps (document numbering).
2. Numbers with units of measurement: "Make sure that the timeout is 10 ms." / "The payload is 20 MB." / "The latency must be 10 μs." ("10 ms" is one word).
3. Abbreviations (acronyms and initialisms): "For remote access, use the VPN." / "During this security check, obey OWASP guidelines." / "a.m." with its number is one word.
4. Alphanumeric identifiers: "Tag error code E36L7." / "Examine the No. 1 handler installation." / `user_preferences`, `ERR_PG_TIMEOUT_0099`, `OrderPaymentFailed`.
5. Quoted text: words between quotation marks, backticks, or `<code>` tags count as one word — `"Service Overview"`, `C = (A - B) - 0.063 mm` (a formula is one word), `useUserProfile(userId)`.
6. Titles, headings, and text on UI elements / labels: "refer to the Operations Runbook for the applicable safety procedures." / "refer to Error Handling and Recovery, page block 1001." / dialog warnings quoted verbatim count as one word.
7. Proper nouns of individuals, groups, organizations, and geopolitical entities: "The creator of Linux was Linus Torvalds." / "the Apache Software Foundation."

Applying 8.6 collapses many seemingly-long sentences into compliance. A README
sentence that looks like 17 words may count as 12 once "GitHub Actions" (proper
noun), "CI/CD" (abbreviation), "AWS Lambda" (proper noun), and "Serverless
Framework" (proper noun) each become one word.

### Examples

Non-STE: ...validate the signature of each incoming request using the public key obtained from the OpenID Connect identity provider, and the token must have an expiry time of not more than three hundred and sixty seconds...
STE:    The JWT authentication middleware must validate the signature of each incoming request. The token must have an expiry time of not more than 360 seconds to be valid for processing. ("JWT" = 1 word; "360 seconds" = 1 word.)

Non-STE: ...set the property called http.client.retry.max.attempts to a numeric value of five and also set the property http.client.retry.backoff.millis to a numeric value of one thousand...
STE:    In `application.properties`, set `http.client.retry.max.attempts` to 5. Set `http.client.retry.backoff.millis` to 1000. (file path = 1; each prop name = 1; "5", "1000" = 1 each.)

Non-STE: ...freeze the checkout container to two hundred and fifty millicores of CPU and five hundred and twelve mebibytes of memory...
STE:    In the Kubernetes manifest, set the `checkout` container to 250m CPU and 512Mi memory. Set the limit to 500m CPU and 1Gi memory. ("checkout" = 1; "250m CPU", "512Mi", "500m CPU", "1Gi" = 1 each.)

### Paradigm notes
- OO: class/method/interface/package names are proper nouns or identifiers (1 word each); "Abstract Factory Pattern" is one word.
- Functional: type signatures and monad stacks quoted count as one word — `validate :: Config -> Either ValidationError Config`, `ReaderT Env (ExceptT AppError IO) a`.
- Procedural: `pthread_mutex_lock(&mtx)` (quoted, 1 word), `EAGAIN` (identifier, 1 word), `context.Context` (proper noun, 1 word).
- Declarative: `users(email_address, created_at)` (quoted, 1 word), `aws_lambda_function.main` (identifier, 1 word), `readinessProbe.httpGet.path` (identifier, 1 word).
- Systems: `fn process<'a>(data: &'a [u8]) -> Cow<'a, str>` (quoted, 1 word), `0x7fff5fbff8c0` (identifier, 1 word).

### Edge cases
1. Framework names with "unapproved" words (Express, Swift, React) are proper nouns (1 word); do not rewrite them to obey word rules.
2. Code keywords quoted in docs (`class`, `return`, `async`) count as one word; do not replace them with synonyms. When used in your own prose, apply the dictionary normally.
3. Generated text you cannot change (Javadoc `@see`, auto-generated OpenAPI descriptions) counts as one word (category 6).
4. Nested quoted text: the outer backtick/`<code>` boundary defines the unit; everything inside counts as one word.
5. Semantic versions (`1.2.3-alpha.1+build.456`), Git hashes (`a1b2c3d`), image digests (`sha256:abc123...`) are alphanumeric identifiers (1 word). "Version 1.2.3" = two words ("Version" + "1.2.3").
6. Document part numbers (rule/section numbers in cross-refs, step numbers, issue IDs as references) are structural and not counted as quantities.

### Cross-references
Rule 1.1 (proper nouns/identifiers exempt from approved-word rule), Rule 1.5
(framework/library names are technical nouns and proper nouns), Rule 1.6
(non-approved words inside proper nouns/identifiers allowed), Rule 1.14
(American spelling exemptions for proper nouns), Rule 8.7 (hyphenated words also
count as one), Rule 4.1 (the 20/25 limits these counts serve).

## Rule 8.7 — Hyphenated words count as one word

A hyphenated group of words counts as ONE WORD when you count sentence length.
The hyphen joins two or more words into a single unit the reader processes as one
concept, so the 20-word (procedural) / 25-word (descriptive) limits measure the
unit as one word, not as the number of words inside it.

Two cases:

Case 1 — Hyphenated compound adjectives (attributive, before a noun):
- `read-only file descriptor` — "read-only" is one word.
- `thread-safe singleton`, `event-driven architecture`, `low-latency cache`,
  `client-side rendering pipeline`, `end-to-end test suite`,
  `backward-compatible API`.
- After a linking verb / after the noun, do NOT hyphenate and count each word:
  "The singleton is thread safe" (5 words: "thread" and "safe" are separate).

Case 2 — Long hyphenated technical nouns:
- `cutoff-switch power connection` (3 words: `cutoff-switch` / `power` / `connection`)
- `main-gear-door retraction-winch handle` (3 words: `main-gear-door` / `retraction-winch` / `handle`)
- Code-domain: `build-time environment variable` (3 words), `client-side rendering pipeline` (3 words), `end-to-end test suite` (3 words), `check-out request handler` (3 words), `sign-in error message` (3 words), `look-up table index` (3 words). Words after the hyphenated unit are separate.

### Examples

Non-STE: The open function returns a read only file descriptor.
STE:    The open function returns a read-only file descriptor. ("read-only" = 1 word)

Non-STE: To calibrate the retry interval, use the try and error method.
STE:    To calibrate the retry interval, use the trial-and-error method. ("trial-and-error" = 1 word)

Non-STE: Set the build time environment variable to the path of the staging cluster...
STE:    Set the build-time environment variable to the path of the staging cluster... ("build-time" = 1 word)

Non-STE: The client side rendering pipeline builds the page in the browser.
STE:    The client-side rendering pipeline builds the page in the browser. ("client-side" = 1 word)

Non-STE: Use a thread safe singleton for the cache.
STE:    Use a thread-safe singleton for the cache. ("thread-safe" = 1 word)

Word-count proof: "The build-time environment variable must point to the staging cluster." = 10 words. `build-time` is one word, not two.

### Interaction with other rules
- With Rule 8.2: hyphenate per 8.2, then count the hyphenated unit as one word per 8.7. ("open-source" hyphenated per 8.2; counts as one word per 8.7. "JSON" is an abbreviation, one word per 8.6.)
- With Rule 8.6: a hyphenated term is a separate case — it is not an abbreviation or identifier, but still counts as one word. Do not double-count.
- Exception: a hyphen in a spelled-out numeral (twenty-one, forty-seven) or a range (pages 10-15) is covered by Rule 8.6 (numbers count as one word), not 8.7.

### Common code-domain hyphenated terms (each = one word before a noun)

| Term | Type |
|------|------|
| read-only, write-only, thread-safe, event-driven | compound adjective |
| client-side, server-side, end-to-end, backward-compatible, low-latency | compound adjective |
| build-time, run-time, sign-in, check-out, request-response | technical noun |

When a term in this table follows the noun or a linking verb, write it as separate words and count each word.

### Cross-references
Rule 8.2 (when to use hyphens), Rule 8.6 (other one-word elements),
Rule 4.1 (sentence-length limit), Rule 4.2 (do not omit words / use contractions).

---

### How an LLM should apply Section 8 when generating code documentation
1. Never write a semicolon in prose; split into sentences (8.1).
2. Hyphenate compound adjectives before nouns; keep predicates separate (8.2, 8.7).
3. Use parentheses only for the seven allowed purposes; never nest them; never hide safety info in them (8.3, 8.5).
4. Introduce vertical lists with a short colon sentence; each item is its own sentence under 20/25 words (8.4).
5. When counting length, collapse numbers+units, abbreviations, identifiers, quoted code, titles, and proper nouns to one word each, and hyphenated groups to one word (8.6, 8.7).



## rules-sec9.md

# Level 5 — Section 9: Sentence Construction & Word Usage (Rules 9.1–9.4)

This sub-document distills the four "writing-level" rules of STE-Code for use by an
LLM that generates or revises code documentation. It covers how to restructure
sentences when a word-for-word replacement fails (9.1), how to use each approved
word with its exact meaning and part of speech (9.2), why phrasal verbs are
prohibited (9.3), and why consistent terminology across a document or project is
mandatory (9.4).

These four rules sit at the top of the STE-Code writing stack. When a candidate
word is not in the controlled terminology, try a word-for-word replacement (9.2).
If no same-part-of-speech alternative keeps the meaning, restructure the sentence
(9.1). Never reach the meaning through a phrasal verb (9.3), and never vary the
term you picked (9.4).

All examples are code-domain. Code symbols (keywords, framework names, function
and variable names) are technical nouns and never change — only surrounding prose
is edited.

---

## Rule 9.1 — Restructure When a Word-for-Word Replacement Is Not Sufficient

**Core instruction.** Use a different sentence construction when you cannot replace
an unapproved word with an approved word of the same part of speech without
changing the meaning.

**When restructuring is required:**
1. You must change the grammatical structure to use the approved alternative.
2. A word-for-word replacement gives a meaningless or unclear result.
3. The approved alternative would change the meaning.
4. The word to replace is not in the controlled terminology at all.

**Procedure when a replacement fails:**
- Think about the *purpose* of the sentence, then select different words.
- Frequently you must: select different words, use a different verb form, write
  shorter sentences, remove unnecessary information, or get more detail from a
  developer.
- Keep code symbols unchanged (Rule 1.5). Only the prose around them changes.

**Code-domain examples (Non-STE → STE):**

| Non-STE | STE | Why |
|---|---|---|
| A timeout value of 5000 ms is **acceptable** for this endpoint. | A timeout value of 5000 ms is **permitted** for this endpoint. | "acceptable" not approved; "permitted" is same part of speech and keeps meaning → word-for-word replacement is enough, no restructure. |
| The stack trace in the console must be **visible** during the debugging session. | During the debugging session, **make sure that you can see** the stack trace in the console. | "visible" (adj) → "see" (verb); restructure around the agent "you." |
| **Loop** the function twice to remove null values from the array. | **Run** the function for two iterations to remove null values from the array. | "loop" not approved; "iteration" (noun) + "run" (verb) replace it; "twice" → "two" (technical). |
| Without this change, the behavior of the function can be **uncertain**. | Without this change, it is possible that the function will not behave as expected. | "uncertain" not in terminology; word-for-word fails → new sentence. |
| **Just** add a single log statement to the method. | **Only** add a single log statement to the method. | "just" → "only"; do NOT use "immediately" here (changes meaning). |

**Restructuring patterns (reuse these):**

- *Adjective → verb:* "X is visible/configurable/accessible" → "make sure that you
  can see/set/open X." Example: "The configuration panel is accessible only to
  administrators." → "Only administrators can open the configuration panel."
- *Noun → verb:* nominalizations ("retrieval", "validation", "execution") pair with
  light verbs ("perform", "carry out"). Drop the light verb: "perform the retrieval
  of X" → "get X." Example: "The service performs the validation of each request"
  → "The service checks each request."
- *Split long sentences* before a conjunction ("and", "or", "but"), a conditional
  ("if", "when"), or between cause/effect. After splitting, each sentence must
  stand alone.

**Per documentation type:**

- *README:* replace passive with active instructions; move complex detail to a
  separate doc; use bullets; drop marketing language.
  Non-STE: "This library leverages asynchronous I/O to facilitate high-throughput
  data processing." → STE: "This library uses async I/O. It can process large
  quantities of data quickly."
- *API docs:* keep parameter names unchanged (Rule 1.5); restructure the
  description around the approved word; use a different subject if the original
  subject depends on an unapproved word; split compound descriptions.
  Non-STE: "This endpoint facilitates the retrieval of user profiles." →
  STE: "This endpoint gets user profiles."
- *Docstrings/comments:* use the approved verb form even if longer; move complex
  detail out; never change a code symbol.
  Non-STE: `"""Computes the aggregate of the supplied metrics and persists them."""`
  → STE: `"""Gets the total of the metrics and saves them."""`
- *Commit messages:* imperative summary ("Add feature"); put detail in the PR.
  Non-STE: "Implemented utilization of the cached connection pool to expedite
  request handling." → STE: "Use the cached connection pool to make requests
  faster."
- *Error messages:* state what happened and what to do; keep stack traces/symbols
  unchanged.
  Non-STE: "The application encountered an unrecoverable exception while attempting
  to instantiate the connection pool." → STE: "The application cannot start the
  connection pool. Look at the log for more data."

**Paradigm-specific notes:**

- *OOP (Java/C#/C++/Python classes):* "provides an abstraction that facilitates"
  → restructure to the concrete purpose. Non-STE:
  "The `BaseRepository` class provides an abstraction that facilitates data access
  operations across multiple database backends." → STE: "The `BaseRepository`
  class lets you use the same data access methods with different databases."
- *Functional (Haskell/Elixir/Rust):* type signatures stay unchanged; "maps over"/
  "folds" are technical verbs only when naming an op — in general prose use
  "applies a function to each element."
- *Procedural (C/Go/Bash):* "deallocate" → "free" or "release"; "pipe command A to
  command B" → "send the output of command A to command B" unless "pipe" is a
  keyword in context.
- *Declarative (SQL/Terraform/K8s):* naturally passive/stative — split and use
  active: Non-STE: "This Deployment manifest orchestrates the rollout of three
  replicated Pods, ensuring high availability through automated rescheduling." →
  STE: "This Deployment makes three copies of the Pod. If a Pod stops, the system
  starts a new Pod automatically."
- *Systems (Rust ownership/C memory):* keywords (`move`, `borrow`) keep their
  technical meaning in code font; in prose, "borrow" → "get a reference to", "own"
  → "has".

**Edge cases:**

- *Framework name = English word* (Flask, Vite, Express, Tailwind): keep the name
  unchanged; never use it as a verb. "Flask your application" → "Use Flask with
  your application."
- *Keyword = approved word* (Rust `use`, `move`; `return`; `break`): code font =
  technical noun; prose = approved meaning. "You must move the value with the
  `move` keyword, then give it back from the function."
- *Generated code symbols* with unapproved words (e.g. `utilizeData()`): keep the
  symbol; describe it with approved words — "The `utilizeData()` function uses the
  data to make a report."
- *Quoted log/error text:* keep verbatim (it is data); explain it with approved
  prose.
- *Restructuring loses precision* (e.g. security audit): (1) split + clarifying
  note, (2) keep the term in code font with a glossary definition, or (3) for an
  internal expert audience keep it as a technical noun with an approved-word
  definition on first use.
- *Algorithm names* (QuickSort, Two-Phase Commit): technical nouns, keep unchanged;
  describe behavior with approved words.

---

## Rule 9.2 — Use Each Approved Word Correctly

**Core instruction.** Use each approved word with its approved meaning and its
approved part of speech. In STE-Code, an approved word usually has exactly one
approved meaning; other standard-English meanings are not approved.

**Key facts:**
- Before using a word, check the STE-Code dictionary's approved-meaning column.
- A word may be approved for one meaning only (e.g. "wear" = "become damaged by
  friction", not "have on body"). Pick a different word for the other meaning.
- A small set of words is approved as more than one part of speech — each with a
  restricted meaning (see "Multiple parts of speech" below).
- Code symbols (keywords, framework/library names, function/var names) are
  technical nouns (Rule 1.5) and exempt from this rule — but your *prose* about
  them must follow it.

**Code-domain examples (Non-STE → STE):**

| Non-STE | STE | Why |
|---|---|---|
| Execute the initialization script before you start the server. | **Run** the initialization script before you start the server. | "execute" not approved; "run" is the one approved verb for "run a program". |
| When the error count goes down, restart the service. | When the error count **decreases**, restart the service. | "goes down" (physical movement) → "decreases" (number). |
| **Log** the exception details to the output stream. | **Write** the exception details to the log. | "log" approved as noun only, not verb. |
| The config **help** shows all command-line options. | The configuration **help text** shows all command-line options. | "help" approved as verb only, not noun. |
| The recursive call **damaged** the call stack. | The recursive call **caused damage** to the call stack. | "damage" approved as noun only, not verb. |
| This configuration option **governs** whether the linter enforces the rule set. | This configuration option **sets** how the linter applies the rules. | "governs"/"enforces" not approved; restructure around "sets". |
| The `render` method leverages a virtual DOM diffing algorithm to minimize expensive DOM manipulations. | The `render` method **uses** a virtual DOM diff algorithm. This algorithm **decreases** the number of DOM changes. | "leverages"→"uses"; "minimize"→split; "expensive"→restate; "manipulations"→"changes". |

**Words approved as multiple parts of speech** (restricted meaning each):

- **build** — verb: "construct software from source" (technical verb, Rule 1.12);
  noun: "the result of a build" or "a version". Be specific: "the build output"
  not "the build" when you mean the artifact.
- **run** — verb: "start and operate software"; noun only in compounds "test run",
  "dry run". Never "do a run" — "run the tests" or "do a test run".
- **set** — verb: "put into a specified state"; noun: "a group of related items".
  Avoid "the set timeout" (looks like an adjective) → "the timeout value that you
  set".
- **check** — verb: "make sure something is correct"; noun only in compounds
  "type check", "health check", "lint check". Never "do a check" — "check" or "do a
  health check".
- **flush** — verb: "remove remaining data from a buffer"; adjective: "where one
  surface fully touches a different surface". Primary spec example.
- **free** — verb: "release"; adjective: "not restricted".
- **close** — verb: "shut"; adjective: "near" (avoid the adjective in technical
  contexts; use "nearest port").

**Per documentation type:**

- *README:* every verb an approved verb in its approved meaning ("leverage"→"use",
  "facilitate"→"help"); every concept noun approved ("functionality"→"feature",
  "capability"→"can"); "build"/"run" handled per the table above.
- *API docs:* `GET` (uppercase, HTTP method) is a technical noun; "get" (verb) is
  approved. "Send a GET request to this endpoint to get the user data." "return" is
  a verb; "the return value" is allowed (noun adjunct) but "the return of the
  function" is not.
- *Docstrings:* "do" only for general actions (else specific verb); "make" = "create"
  (not "make a call"→"call", not "make a request"→"send a request", but "make a
  copy" ok); `using` keyword in code font = technical noun, prose "use" = verb.
- *Commit messages:* imperative approved verb ("Implement feature"→"Add feature",
  "Introduce breaking change"→"Add breaking change"); "fix" verb ok, "a fix" noun
  not; "update" verb only.
- *Error messages:* "cannot" not "unable to"/"failed to"; "must" only when the user
  must act to continue (else state the state: "The file does not exist" not "The
  file must exist"); "if" for conditional action.

**Paradigm-specific notes:**

- *OOP:* `extend`/`implements`/`override`/`abstract` are keywords in code font; in
  prose use "is a child of", "uses the interface", "replaces the parent method",
  "is a base class. You cannot make an instance of it." Non-STE: "This class
  implements the `Serializable` interface." → STE: "This class uses the
  `Serializable` interface."
- *Functional:* `map`/`reduce`/`filter`/`apply` are function names (technical
  nouns); in prose use "apply the function to each element", "combine the elements
  into a single value", "remove elements that do not match", "use the function on
  the value" — never the verb forms.
- *Procedural (C/Go):* `free()`/`open()`/`close()`/`read()` are function names;
  prose: "free the memory", "open the file", "the port is available" (not "open"),
  "read the data from the buffer" (not "do a read").
- *Declarative:* `CREATE`/`SELECT`/`DROP` are SQL keywords; in prose "make a table",
  "get rows from the table", "remove the table"; `terraform apply` stays in code
  font, prose "use `terraform apply` to make the changes".
- *Systems (Rust):* `move` as technical verb ok ("when you move a value"); `borrow`
  → "get a reference to"; `drop` as technical verb ok ("the value drops when it
  goes out of scope"); `own` → "has". "ownership" is a technical noun.

**Edge cases:**

- *Framework name = unapproved word* (Express, Flask, Fresh, FastAPI): technical
  noun, keep unchanged, never as a verb. "Express your API routes" → "Use the
  `Express` framework to write your API routes."
- *Keyword = approved word* (Rust `use`, `move`; `return`; `break`): code font =
  keyword; prose = approved meaning. "Do not break the API contract" → "Do not
  change the API contract."
- *Generated code:* keep unapproved symbol names; describe with approved words. If
  public API, wrap with an approved name that calls the generated function. If you
  own the generator, template approved symbol names from the start.
- *Quoted error/log text:* keep verbatim; explain with approved prose.

**Cross-references:** Rule 1.1 (approved words), 1.2 (part of speech), 1.3 (approved
meanings), 1.4 (approved forms), 1.5 (technical nouns), 1.7 (no technical-noun
verbs), 1.12 (technical verbs), 9.1, 9.3, 9.4, and the STE-Code Dictionary (source
of truth).

---

## Rule 9.3 — Do Not Make Phrasal Verbs

**Core instruction.** When you use two words together, do not make a phrasal verb.
A phrasal verb = an approved verb + a particle/preposition whose combined meaning
differs from the parts (e.g. "put out", "give off", "carry out"). Replace it with a
single approved verb of the same meaning. Only a small number of phrasal verbs are
approved, each with a restricted meaning (see below).

**Why it matters in code docs:** phrasal verbs are ambiguous (one phrase, many
meanings), hard for non-native readers, and unsearchable ("remove" won't match
"take off" or "strip out"). One approved verb is always preferred.

**Code-domain examples (Non-STE → STE):**

| Non-STE | STE | Why |
|---|---|---|
| The compiler **puts out** a warning. | The compiler **emits** a warning. | "put out" phrasal → single verb "emit". |
| The function **gives off** an error code. | The function **returns** an error code. | "give off" phrasal → "return". |
| The cleanup task **carries out** the deallocation. | The cleanup task **does** the deallocation. | "carry out" → "do". |
| The test runner **runs through** all suites and **prints out** a report. | The test runner **executes** all suites and **prints** a report. | "run through"→"execute"; "prints out"→"prints" ("out" adds nothing). |
| The framework **sets up** the routing table. | The framework **configures** the routing table. | "set up" → "configure" (or "install"/"create" by context). |
| The middleware **looks at** headers and **filters out** fields. | The middleware **examines** headers and **removes** fields. | "look at"→"examine"; "filter out"→"remove" (note: "filter" alone is an approved verb). |
| The cleanup job **kicks in** and **clears out** sessions. | The cleanup job **starts** and **removes** sessions. | "kick in"/"clear out" informal → "start"/"remove". |
| The compiler **breaks down** the source, then **goes on** to generate IR. | The compiler **divides** the source, then **continues** to generate IR. | "break down"→"divides"; "go on"→"continues". |
| The plugin lets you **hook into** the pipeline and **tap into** the stream. | The plugin lets you **connect to** the pipeline and **subscribe to** the stream. | "hook into"/"tap into" slang → "connect"/"subscribe". |

**README / type-specific replacements:**

- README: "set up"→"configure"/"install"; "run through"→"complete"; "check out"→
  "examine"; "go through"→"read"; "pick up where you left off"→"continue"; "break
  down the architecture"→"describe the architecture".
- API docs: verb must match the operation exactly — GET "gets", POST "creates"/
  "sends"; "looks up"→"finds", "hands off"→"sends", "takes in"→"receives", "spits
  out"→"returns", "fills in"→"completes".
- Commit messages: clean up→remove/delete/tidy; fix up→correct/repair; speed
  up→accelerate/make faster; cut down→reduce; rip out/strip out→remove; wire up→
  connect; flesh out→complete/expand.
- Error messages: "could not hook up"→"could not connect"; "blew up"→"failed";
  "out of whack"→"not consistent".
- Changelogs: "did away with"→"removed"; "added back"→"restored"; "ironed out"→
  "corrected"; "phased out"→"ended".

**Paradigm-specific notes:**

- *OOP:* "sets up the state"→"initializes"; "tears down"→"releases"; "hands off
  ownership"→"transfers ownership"; "looks up the dependency"→"finds"; "wraps up
  the transaction"→"completes".
- *Functional:* "maps over"→"applies a transformation to each element"; "pipes
  through"→"sends through"; "folds down"→"combines"; "reaches out to"→"sends a
  request to".
- *Procedural:* "reach out to the API"→"send a request"; "pull down"→"get"; "go
  through each record"→"examine"; "put together"→"make". C: "free up"→"release"/
  "free"; "hands back"→"returns".
- *Declarative:* "brings up instances"→"creates"; "spins up pods"→"starts"; "tears
  down"→"removes"; "joins together"→"joins ... with".
- *Systems:* "hands off ownership"→"transfers"; "holds onto"→"keeps a reference";
  "gives up the lock"→"releases"; "carves out"→"allocates".

**Approved phrasal verbs (restricted meaning — the only ones allowed):**

| Phrasal verb | Meaning | Example |
|---|---|---|
| log in / log out | start/end an authenticated session | "The user must log in before they can access the dashboard." |
| follow up | take further action after an initial step | "Follow up the installation with the configuration step." |
| back up | make a copy for safekeeping | "Back up the database before you apply the migration." |
| roll back | return to a previous state | "Roll back the deployment if the health check fails." |

Do not use "sign in/out", "log on/off". "Back up" (two words) means only "make a
copy" — not movement or support.

**Edge cases:**

- *Framework name contains a phrasal verb* (`setuptools`, `cleanup`, `rollback`):
  the name is a technical noun — keep it. But describe its behavior with an
  approved verb: "`setuptools` configures the package metadata" (not "sets up").
- *Code keyword = phrasal component* (`break`, `continue`, `throw`, `catch`): as a
  keyword/noun or technical verb it is fine ("the `break` statement exits the
  loop"); as a phrasal verb it is not ("breaks out of the loop"→"exits the loop";
  "catches up with the stream"→"synchronizes with the stream").
- *Not every verb+preposition is a phrasal verb.* If the preposition is a normal
  prepositional phrase (location/direction/target) and the verb keeps its meaning,
  it is allowed: "runs on the server", "flows from input to output", "write the
  configuration to the file". Test: remove the preposition — if the meaning stays
  roughly the same, it is allowed; if the meaning changes completely, it is a
  phrasal verb. ("write up the report" = compose formally → not allowed.)
- *Generated docs:* fix the source doc comments (JSDoc/Sphinx/rustdoc) so the
  published output is compliant. Third-party docs you cannot edit need not be
  corrected.
- *No single verb exists:* apply Rule 9.1. "calls back the caller with the result"
  → "sends the result to the caller through a callback". "warms up"→"loads the
  data"; "flags up"→"reports"/"marks"; "churns through"→"processes".

**Cross-references:** Rule 1.1 (dictionary), 1.2 (part of speech — the particle is
not a preposition of direction), 1.4 (approved forms), 1.11 (one term per concept —
mixing "set up" and "configure" violates consistency), 1.12 (technical verbs — do
not replace "serialize" with "turn into a string"), 9.1 (escape hatch), 9.2 (each
non-phrasal word must carry its approved meaning).

---

## Rule 9.4 — Always Use a Consistent Style

**Core instruction.** When you select terminology or wording, always use a
consistent style: the same term for the same thing, the same verb for the same
action, and the same sentence structure for the same type of instruction. Variation
is a defect, not a stylistic virtue.

**Why:** every synonym forces the reader to ask "is this the same thing or a
different thing?" — a cognitive tax that causes misidentification and bugs. In code
docs this means a parameter called "retry count" in one section and "max attempts"
in another gets misconfigured at runtime.

**Three consistency domains (each maintained independently):**

1. *Lexical* — one term per concept. Audit with grep. Pick one noun for one file
   ("configuration file", never alternating with "settings file"/"config").
2. *Syntactic* — same structure for the same action. All setup steps share one
   template (imperative verb + purpose clause); do not switch to passive/conditional
   for some steps.
3. *Semantic* — same meaning across files/modules/types. If "build" = "compile and
   link" in the README, it must not mean "compile, link, and package" in CI docs.

**Per documentation type:**

- *README:* one term for the artifact ("library" not "package" mid-doc).
- *API docs:* one name for each endpoint/method/parameter; prose must match the
  schema field name (`createdAt`, not "creation date"/"timestamp").
- *Docstrings:* use the parameter name from the signature (`max_retries`, not
  "maximum attempts"/"retry limit").
- *Commit messages:* one imperative verb per change category ("Add" for new
  features — not "Introduce"/"Insert"/"Create"; "Fix" — not "Resolve"/"Correct"/
  "Patch").
- *Error messages:* the same failure mode must produce identical text every time
  (`E_CONNECT_FAIL` = "Cannot connect to the remote host" in every module).
- *CLI help:* same template for every flag ("Enables/Disables [adjective] output").

**Code-domain examples (Non-STE → STE):**

- Setup verbs: "Install the dependencies. Then fetch the source. After that set up
  the environment. Finally get the database running." → "Install the dependencies.
  Then download the source. After that set the environment variables. Finally start
  the database." (one verb per action)
- Noun across docs: README "auth package" / API "auth package" / error "auth
  module" → all "authentication library".
- API reference: "Retrieves all items" / "Use this to create" / "Gets item by ID" /
  "Removes the specified item" → all third-person singular: "Returns all items" /
  "Creates a new item" / "Returns the item with the specified ID" / "Removes the
  item with the specified ID".
- Commit log: "Add" / "Introduce" / "Insert" / "Create" → all "Add".
- Error messages: "Connection refused by peer" / "Cannot establish link to remote"
  / "Failed to connect to upstream server" → all "Cannot connect to the remote
  host".
- CLI flags: "--verbose Enable verbose output / --quiet Suppress all logging /
  --debug Turns on debug-level messages" → "--verbose Enables verbose output /
  --quiet Disables all output / --debug Enables debug output".

**Paradigm-specific notes:**

- *OOP:* reuse the base-class docstring template in every subclass; don't abbreviate
  class names inconsistently (`UserRepository`, not `UserRepo`/"user repo").
- *Functional:* one anchor phrase for pure functions ("returns a new list"); don't
  mix "produces a result"/"yields output"; keep the monad metaphor constant.
- *Procedural:* predictable I/O step pattern; same error-check phrasing for every
  `if err != nil`.
- *Declarative:* same phrasing per resource type (`aws_instance` = "a virtual machine
  in AWS EC2" everywhere); Kubernetes resource names are proper nouns — `ConfigMap`,
  `Pod`, never "config map"/"configuration map".
- *Systems:* consistency is a safety property. Rust terms "ownership"/"move"/
  "borrow"/"lifetime" are precise — never substitute synonyms ("takes possession"/
  "relinquishes control" → "takes ownership"/"moves").

**Edge cases:**

- *Framework-mandated terminology* (React "props", "hooks"): the framework is the
  authority — use its term everywhere, never translate to an STE-Code synonym.
- *Generated docs:* fix the source docstrings; don't post-process output. For
  conventional-commits changelogs, enforce an allowed-verb convention and reject
  non-standard verbs in CI.
- *Cross-project (monorepo):* per-service docs follow the service glossary;
  system-level docs define a system-wide glossary mapping each system term to its
  service-level term.
- *Multiple valid industry names* (e.g. "GitHub Actions workflow" vs "pipeline"):
  pick one, document it in the project glossary, never alternate.
- *Version renames* ("packages" ↔ "workspaces"): each version's docs use that
  version's canonical name; migration guides must state the rename explicitly.

**Canonical synonym table — pick the preferred term and use it everywhere:**

| Preferred | Do NOT alternate with |
|---|---|
| use | utilize, leverage, employ |
| start | initiate, commence, bootstrap |
| show | display, render, present |
| make | create, generate, produce |
| get | retrieve, fetch, obtain |
| set | configure, assign, establish |
| check | verify, validate, ensure |
| remove | delete, eliminate, purge |
| keep | retain, preserve, maintain |
| send | transmit, dispatch, forward |

**Cross-references:** Rule 1.1 (approved words — consistency needs one approved
term), 1.3 (approved meanings — "set" can't mean both "configure" and "collection"),
1.5 (technical nouns must also be consistent), 1.11 (one term per concept — the
lexical foundation of 9.4), 9.1 (restructure rather than introduce a synonym), 9.2
(incorrect usage in one place breaks the chain).

---

*Section 9 covers the four writing-level rules. For the controlled terminology
(dictionary A–Z), the full rule set (Sections 1–8, 10+), extensions, and the
provenance catalogue, see the other Level 5 sub-documents.*
