<!-- 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).*
