<!-- 01-principles.md -->

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

Level 5 is the full STE-Code standard: every rule, the extension vocabulary, the
reference catalogue, and provenance. This sub-document is the **core principles**
slice — Section 1, which governs *words*. Every other section of STE-Code assumes
these fourteen rules already hold.

Use this file when you generate, review, or lint code documentation with an LLM.

## The three gates

A word is allowed in STE-Code prose only if it passes one of three gates:

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

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

## Definitions

- **Controlled terminology** — the STE-Code approved word list. Each entry gives
  one part of speech and one approved meaning, plus the approved verb and
  adjective forms.
- **Code-domain technical noun** — a noun term for a specified concept in
  software development, applicable to a subject field (Rule 1.5).
- **Code-domain technical verb** — a verb term for a specified operation or
  process in software development (Rule 1.12).
- **Project glossary** — the project, company, industry, or subject-field list of
  approved technical nouns and verbs. It is checked before the controlled
  terminology for domain names, and the repository is its source of truth.

## Rule index

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

---

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

In code documentation, use words that are:

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

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

Worked vocabulary swaps:

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

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

Examples by documentation type:

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

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

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

Paradigm notes:

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

---

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

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

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

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

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

When you replace a word, make sure that the meaning does not change.

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

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

---

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

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

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

Four-step check for every approved word you write:

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

Worked check:

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

---

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

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

Verb entry: `COMPILE (v), COMPILES, COMPILED, COMPILED`

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

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

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

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

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

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

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

---

## Rule 1.5 — Code-domain technical noun categories

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

STE-Code gives the categories to help you select the technical nouns for your
project glossary and to use them correctly. You may use a code-domain technical
noun in procedural and descriptive writing when you can put it in one or more of
these **nineteen** categories. The words shown are examples only, not a complete
list.

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

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

---

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

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

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

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

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

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

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

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

---

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

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

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

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

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

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

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

---

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

If your project, company, industry, or subject field already has an approved
name for a class, module, function, method, variable, component, or process, use
that name. These names live in your project glossary, API documentation, coding
standards, or company documentation. Do not invent your own names for items that
already have established names. The source of truth is the repository.

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

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

---

## Rule 1.9 — Select short, easy technical nouns

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

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

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

---

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

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

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

---

## Rule 1.11 — One technical noun per item

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

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

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

---

## Rule 1.12 — Code-domain technical verb categories

A code-domain technical verb is a verb term that refers to a specified operation
or process in software development and is applicable to a subject field. The
controlled terminology does not include them all; keep yours in the project
glossary or terminology database.

Code-domain technical verbs must obey the same rules as other approved verbs.
Use them in procedural and descriptive texts when you can put them in one or more
of these four categories (examples only, not a complete list):

1. **Development processes**
   - a) Write and modify code: compile, concatenate, import, inject, instantiate,
     lint, minify, marshal, optimize, polyfill, refactor, resolve, shim, stub,
     substitute, tokenize, transpile, trace, vectorize
   - b) Test and verify code: assert, benchmark, debug, fuzz, instrument, mock,
     profile, snapshot, spy, stub, unit-test
   - c) Build and package: bundle, deploy, package, publish, release, tag, version
   - d) Manage dependencies: hoist, install, link, lock, pin, update, upgrade

2. **Computer processes and applications**
   - a) Input and output: click, copy, cut, digitize, enter, paste, press, print,
     scan, swipe, tap, type
   - b) UI and application operations: clear, close, delete, deselect, disable,
     drag, enable, encrypt, erase, filter, hide, highlight, invalidate, maximize,
     minimize, navigate, open, save, scroll, select, show, sort, store, submit,
     toggle, validate, zoom in, zoom out
   - c) System operations: abort, authenticate, authorize, boot, cache,
     communicate, configure, debug, deserialize, download, format, hydrate,
     initialize, install, load, log, manage, mount, process, reboot, render,
     retry, serialize, spawn, synchronize, throttle, update, upgrade, upload

3. **Instructions and information for applicable subject fields**
   - a) Algorithmic, mathematical, data: aggregate, bisect, compute, concatenate,
     convert, count, decode, encode, escape, filter, hash, index, map, merge,
     normalize, parse, pipeline, precompute, recalculate, reduce, tokenize,
     transform, validate, verify
   - b) Database and storage: backup, compact, flush, index, migrate, persist,
     query, replicate, restore, roll back, seed, shard, upsert, vacuum,
     write-ahead
   - c) Network and communication: broadcast, connect, disconnect, establish,
     forward, handshake, intercept, listen, poll, proxy, reject, resolve, route,
     send, stream, timeout, tunnel, unsubscribe, webhook
   - d) Security and authentication: authenticate, authorize, decrypt, decode,
     encode, encrypt, hash, revoke, salt, sanitize, sign, validate, verify

4. **Legal and licensing terms** — only for legal and regulatory texts:
   acknowledge, assign, comply with, conform to, disclose, enforce, explain,
   grant, inform, license, modify, notify, permit, regulate, sign, supersede,
   waive

If there is an approved verb in the controlled terminology that accurately gives
the instruction or information, use the approved verb. Do not use a code-domain
technical verb if you can write the same sentence with approved words.

> **Non-STE:** If you detect a null pointer exception in the parser, fix it before
> the response returns to the client.
>
> **STE:** If you find a null pointer exception in the parser, fix it before the
> response returns to the client.

> **STE:** Read the API key from the configuration file. ("Enter" is a
> code-domain technical verb, category 2 a.)

> **Non-STE:** Run the database migration to version 3, then verify the row
> counts before you open the service.
>
> **STE:** Run the migration of the database schema to version 3, then check the
> row counts before you open the service. (Prefer approved "run" + technical noun
> "migration" over the technical verb "migrate" when precision is not lost.)

Dual-category note: a word may be both a technical verb (Rule 1.12) and a
technical noun (Rule 1.5). For example `deploy` is a technical verb (category 1
c) and a technical noun (category 5); `serialize` is a technical verb and also a
method name (technical noun). Let your project glossary decide the role.

---

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

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

The most common violation is the **light verb construction**: a weak verb (do,
make, perform, execute, run) paired with a nominalized technical verb.

| Do not write | Write |
|---|---|
| Make a commit of your changes | Commit your changes |
| Do a compile of the source files | Compile the source files |
| Execute a rollback of the migration | Roll back the migration |
| The import of the module takes ten seconds | The import operation for the module takes ten seconds |
| The merge of the feature branch caused a conflict | The merge operation of the feature branch caused a conflict |

Dual-category exception: when a word fits both a technical verb category (Rule
1.12) and a technical noun category (Rule 1.5), you may use it as a noun.

| Word | Technical Verb | Technical Noun |
|------|---------------|---------------|
| build | 1 c) Build and package | 3) Development tools |
| deploy | 1 c) Build and package | 5) Infrastructure, deployment, and platforms |
| test | 1 b) Test and verify code | 3) Development tools |
| commit | 2 c) System operations | 4) Data structures |
| merge | 1 c) Build and package | 4) Data structures |
| release | 1 c) Build and package | 5) Infrastructure, deployment, and platforms |
| patch | 1 a) Write and modify code | 4) Data structures |
| log | 2 c) System operations | 13) Runtime environments |
| import | 1 a) Write and modify code | 4) Data structures |

Article test: if you can put "a / an / the" before the word and the sentence
stays grammatical, the word is acting as a noun. If it is not a dual-category
word, the usage violates Rule 1.13. "The build failed" is correct (dual-category);
"the compile failed" is wrong (compile is only a technical verb).

Quoted tool output (Rule 1.5 category 10) is exempt: a compiler message that says
"compile error" is text you did not write and must not be changed.

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

---

## Rule 1.14 — Use American English spelling unless other official directives tell you differently

Use the spelling specified in the STE-Code controlled terminology (American
English). Use a different spelling only if other project specifications, style
guides, contracts, or official directives apply.

If quoted text has British English spelling — an error message, a code comment, a
user interface label, terminal output — do not change it. Keep the quoted text as
it is (Rule 8.6). The surrounding prose must use American English spelling.

Common British → American pairs:

| British | American | Context |
|---------|----------|---------|
| colour | color | UI, terminal, theming |
| behaviour | behavior | feature descriptions, bug reports |
| organise | organize | restructuring, refactoring |
| analyse | analyze | profiling, data processing |
| licence (noun) | license | software license, license key |
| defence | defense | security fixes |
| centre | center | layout, positioning |
| initialise | initialize | object initialization |
| serialise | serialize | object serialization |
| optimise | optimize | performance optimization |
| parametrise | parameterize | parameterized types |
| cancelled | canceled | canceled operations |
| customise | customize | custom behavior |
| minimise | minimize | rollout minimization |
| synchronise | synchronize | state sync |
| traveller | traveler | traveler pattern |

> **Non-STE:** The log file shows the colour of each output line. Initialise the
> variable before you use it in the loop.
>
> **STE:** The log file shows the color of each output line. Initialize the
> variable before you use it in the loop.

> **STE:** The terminal shows the message `Colour profile not recognised`.
> (Quoted terminal output keeps its British spelling; the prose around it uses
> American English.)

> **See also:** Rule 8.6 — Use Quoted Texts Correctly.

---

## Extension adjectives for Section 1

These adjectives are approved extensions to the controlled terminology, added for
the code domain. Use them as the specified part of speech (Rule 1.2).

| Adjective | Definition | STE example |
|-----------|------------|-------------|
| idempotent | Describes an operation that produces the same result when applied more than once, with no extra side effects after the first run. | Make the retry handler idempotent so a second call with the same input does not duplicate the record. |
| immutable | Describes a data structure or value that cannot be changed after it is created, which prevents accidental shared-state bugs. | Keep the request context immutable so concurrent threads cannot overwrite each other's values during a single operation. |
| atomic | Describes an operation that completes fully or not at all, with no partial result visible to other processes. | Wrap the balance update in an atomic transaction so the debit and credit always succeed or fail together. |
| thread-safe | Describes code that functions correctly when accessed by multiple threads at the same time without external locking. | Mark the singleton constructor thread-safe so two threads can call it on first use without creating two instances. |
| asynchronous | Describes a call or task that starts and returns before its work finishes, so the caller can do other work meanwhile. | Make the file upload asynchronous so the user interface stays responsive while the transfer runs in the background. |
| concurrent | Describes tasks that make progress within the same time period, interleaved by the scheduler rather than strictly sequentially. | Run the test suites in concurrent processes so the full check finishes in a fraction of the time. |

The full extension inventory (nouns, verbs, and adjectives) is in
`ste-code/artifacts/level5/06-extensions.md`.

---

## Reference catalogue

These external references inform the STE-Code controlled vocabulary. They are
**not** part of the standard; they are kept in `.agents/reference/` outside
`final/`. They are listed here as a catalogue only.

| Reference | Type | Source |
|---|---|---|
| Microsoft Writing Style Guide | page | https://learn.microsoft.com/en-us/style-guide/welcome/ |
| MicrosoftDocs/microsoft-style-guide (GitHub source) | page | https://github.com/MicrosoftDocs/microsoft-style-guide |
| Google Style Guides | page | https://google.github.io/styleguide/ |
| Kong/apiglossary | page | https://github.com/Kong/apiglossary |
| dwyl/technical-glossary | raw | https://raw.githubusercontent.com/dwyl/technical-glossary/main/README.md |
| jvalentino/glossary | page | https://github.com/jvalentino/glossary |
| GitHub Official Glossary | page | https://docs.github.com/en/get-started/learning-about-github/github-glossary |
| DevOps Style Guide Glossary | page | https://tydukes.github.io/coding-style-guide/glossary/ |
| ryanwi software-terms.dic | raw | https://gist.githubusercontent.com/ryanwi/6135845/raw/software-terms.dic |
| OpenSTE.org | pointer | https://openste.org/ |
| en-wl/wordlist (SCOWL) | page | https://github.com/en-wl/wordlist |
| MichaelWehar 5000-more-common | raw | https://raw.githubusercontent.com/MichaelWehar/Public-Domain-Word-Lists/master/5000-more-common.txt |
| dwyl/english-words | pointer | https://github.com/dwyl/english-words |

The full catalogue, with local mirror paths, is in
`ste-code/artifacts/level5/07-catalogue.md`.

---

## Provenance

Section 1 of STE-Code is adapted from ASD-STE100 Issue 9, Part 1, Section 1
(Words). The adaptation is semantic, not a word swap: each rule keeps its intent
and structure, and the examples and categories are re-expressed for software
documentation. Two structural changes apply to this section:

- The 22 technical noun categories of the source specification become **19**
  code-domain categories (Rule 1.5).
- The technical verb categories become **4** code-domain categories (Rule 1.12).

Per-rule source mapping and the original rule text are in
`ste-code/final/rules/a-sec1-rule1.*.md`, and the tier-wide provenance record is
in `ste-code/artifacts/level5/08-provenance.md`.

---

## Section 1 checklist for LLM generation and review

For each word in the prose you generate:

1. Is the word approved in the controlled terminology? If yes, check the part of
   speech (1.2), the meaning (1.3), and the form (1.4).
2. If it is not approved, is it a code-domain technical noun in one of the 19
   categories (1.5, 1.6)? Use it only as a noun (1.7).
3. If it is not a noun, is it a code-domain technical verb in one of the 4
   categories (1.12)? Use it only as a verb (1.13), and prefer an approved verb
   when one carries the same meaning.
4. Prefer the name already used in the repository or project glossary (1.8), keep
   it short (1.9), avoid slang and jargon (1.10), and use the same name for the
   same item everywhere (1.11).
5. Spell in American English (1.14), but never change quoted text.

If a word passes no gate, replace it or rewrite the sentence.

---

<!-- 02-synonyms.md -->

# Level 5 — Code-Domain Technical Noun Categories (Rule 1.5)

> Slice 02 of STE-Code Level 5 (full standard: all rules + extensions + catalogue + provenance).
> Source: ASD-STE100 Issue 9, Rule 1.5 (master.md lines 1698-1878), adapted to the code-documentation domain.
> Companion rules: 1.1 (approved words), 1.6-1.11 (gate mechanics).

## When to use this slice

Use this reference when you must decide whether a word that is NOT in the STE-Code approved dictionary may still appear in code documentation — READMEs, API reference, docstrings, commit messages, ADRs, error messages, and test specs.

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

A code-domain technical noun is a noun term that refers to a specified software concept and is applicable to a given codebase, library, or system. The approved-term dictionary does not list project-specific technical nouns because each codebase, framework, and ecosystem uses different terminology. You can find them in your project glossary, API reference, or architecture decision records (ADRs).

STE-Code gives you the categories below, with examples, to help you:
- Select technical nouns to register in your project glossary.
- Use technical nouns correctly in documentation.

You may use a technical noun in procedural and descriptive code documentation if it fits one or more of the categories below.

**Non-STE vs STE.** "Use the thing to call the function that gets data from the database." → "Use the `fetchUser` method of the `UserRepository` to retrieve a `User` record from the `PostgreSQL` database." (`fetchUser`, `UserRepository`, `User`, `PostgreSQL` are technical nouns — categories 1, 6, 19.)

## How Rule 1.5 fits with the other rules

- **Rule 1.1** requires an approved dictionary word for all common vocabulary. Use an approved word whenever one exists.
- **Rule 1.5** is the complement: it permits a word outside the dictionary when it names a technical concept.
- **Rule 1.6** forbids any non-approved word unless it is a technical noun (classified in a category below) or part of one.
- Together, 1.1 + 1.5 + 1.6 form the gate: a word is allowed if it is approved (1.1) OR a classified code-domain technical noun (1.5); otherwise 1.6 forbids it.

**Glossary registration (required).** Before you use a code-domain technical noun, add it to the project glossary with: the noun term; the STE-Code category (or categories) it belongs to; the approved meaning in the project context; and an example sentence that uses it correctly.

---

## The 19 code-domain technical noun categories

### Category 1 — API and library components
Terms that refer to all API and library components. For example, technical nouns in API reference docs, SDK manifests, or interface definition files.
`endpoint, method, parameter, query parameter, path parameter, request body, response body, header, status code, module, class, interface, type alias, enum, constant, decorator, middleware, route handler, serializer, DTO, model, schema, callback, hook, plugin`

Non-STE: "Call the thing that makes users."
STE: "Call the `POST /api/v1/users` endpoint with a `CreateUserRequest` body to create a `User` resource."

### Category 2 — Applications, services, and subsystems
Terms that refer to all types of applications, services, and their subsystems, and the locations that are part of these units.
`web application, mobile app, desktop client, CLI tool, microservice, monolith, API gateway, load balancer, database server, message broker, cache layer, container, pod, cluster, frontend, backend, admin panel, user dashboard, authentication service, payment service, notification service, search engine, CDN, reverse proxy, serverless function, cron job, worker process`

Non-STE: "The thing that runs the website broke."
STE: "The `nginx` reverse proxy on the `web-01` frontend server stopped responding."

### Category 3 — Development tools and support equipment
Terms that refer to all types of development tools, SDKs, and their components, and locations that are part of these items.
`IDE, code editor, terminal emulator, compiler, interpreter, transpiler, bundler, linter, formatter, debugger, profiler, package manager, version control system, CI runner, test framework, assertion library, mocking library, static analyzer, API client, database client, container runtime, orchestration tool, IaC tool, monitoring dashboard, log aggregator, feature flag service, secrets manager`

Non-STE: "Run the check tool to find problems."
STE: "Run `ESLint` with the `@company/eslint-config` preset to find lint violations."

### Category 4 — Dependencies, packages, and technical debt
Terms that refer to dependencies, packages, and technical debt that can cause regressions or malfunctions.
`dependency, transitive dependency, package, library, framework, runtime, polyfill, shim, vendor bundle, dead code, deprecated API, legacy module, orphaned code, code smell, TODO comment, FIXME comment, zombie import, circular dependency, peer dependency, dev dependency, optional dependency, pinned version, lockfile, SBOM, supply chain artifact, third-party script, ad-hoc patch, monkey-patch, workaround code`

Non-STE: "There's a problem with one of the things we installed."
STE: "The `lodash@4.17.20` transitive dependency introduces a prototype pollution vulnerability (CVE-2020-8203)."

### Category 5 — Hosting, CI/CD, and deployment infrastructure
Terms that refer to the management, structure, and operations of hosting, CI/CD, and deployment infrastructure.
`cloud provider, region, availability zone, data center, Kubernetes cluster, namespace, Docker registry, artifact repository, build pipeline, deployment pipeline, staging environment, production environment, sandbox environment, on-premise server, virtual machine, bare-metal host, edge location, CDN endpoint, storage bucket, message queue, event bus, API gateway endpoint, load balancer target group, auto-scaling group, service mesh, ingress controller`

Non-STE: "Deploy to the cloud place."
STE: "Deploy the `orders-service` container image to the `us-east-1` `production` Kubernetes cluster in namespace `orders`."

### Category 6 — Systems, subsystems, and architectural components
Terms that refer to the structure, operation, composition, and system design of software.
`architecture, design pattern, layered architecture, hexagonal architecture, microservice, event-driven architecture, CQRS, event sourcing, pub/sub, message queue, event bus, database shard, read replica, write-ahead log, connection pool, circuit breaker, retry policy, rate limiter, cache layer, CDN edge, feature flag, A/B test variant, canary deployment, blue-green deployment, rolling update, service registry, configuration provider, secret store, reverse proxy, API gateway route, middleware chain, plugin system, dependency injection container, ORM, migration runner`

Non-STE: "The system uses a pattern to handle failures gracefully."
STE: "The `PaymentGateway` client uses a `CircuitBreaker` pattern — after 5 consecutive failures, it opens and returns cached fallback responses for 30 seconds."

### Category 7 — Mathematical, algorithmic, and scientific terms
Terms that refer to algorithms, data structures, computational concepts, and methodologies.
`algorithm, data structure, Big-O notation, time complexity, space complexity, hash table, binary tree, linked list, graph, trie, bloom filter, LRU cache, consistent hashing, recursion, memoization, dynamic programming, greedy algorithm, backtracking, binary search, quicksort, mergesort, topological sort, Dijkstra, BFS, DFS, A*, Paxos, Raft, two-phase commit, saga pattern, idempotency key, eventual consistency, CAP theorem, ACID, BASE, vector clock, Lamport timestamp, Merkle tree, consistent hashing ring, shard key, partition key, compound index, covering index, query plan, cardinality, selectivity, normalization, denormalization, OLTP, OLAP, ETL, stream processing, batch processing, map-reduce, actor model, CSP, semaphore, mutex, atomic operation, CAS`, `O(n log n)`, `f(x) = x² + 3x - 2`

Non-STE: "The search is fast because it uses a good algorithm."
STE: "The `SearchIndex` uses a `BloomFilter` (`O(k)` lookup) to skip negative lookups before falling back to a `B-Tree` index scan."

### Category 8 — Codebase navigation and project structure
Terms that refer to codebase navigation, project structure, and directory/import hierarchy.
`directory, subdirectory, file path, import path, package root, module root, workspace root, monorepo root, source directory, test directory, build output, entry point, barrel export, index file, re-export, absolute import, relative import, path alias, symlink, Git root, branch, tag, commit, HEAD, upstream, origin, fork, submodule, subtree, vendor directory, node_modules, virtual environment, GOPATH, classpath, namespace, package scope, module scope, public API surface, internal package, private module, exported symbol`

Non-STE: "The file is in the utils folder somewhere."
STE: "The `formatCurrency` helper is in `src/shared/utils/formatting.ts`, re-exported from the barrel file at `src/shared/utils/index.ts`."

### Category 9 — Numbers, units of measurement, and time
Terms that refer to metrics, benchmarks, timing data, and quantitative measurements.
`latency, throughput, response time, p50, p95, p99, p999, ops/sec, req/sec, RPM, RPS, QPS, TPS, bytes, KB, MB, GB, TB, KiB, MiB, ms, µs, ns, s, min, hr, CPU core, thread count, memory usage, heap size, stack size, GC pause, cold start time, warm start time, bootstrap time, build time, deploy time, MTTR, MTBF, uptime, downtime, error rate, success rate, availability (99.9%, 99.99%), RPO, RTO, SLO, SLI, SLA, concurrency, connection count, pool size, batch size, page size, offset, limit, TTL, timeout, interval, poll interval, retry delay, backoff multiplier, rate limit (tokens/sec), quota, sample rate, cardinality`

Non-STE: "The API is pretty fast most of the time."
STE: "The `GET /search` endpoint has a p95 latency of 120 ms and a p99 latency of 350 ms at 5000 RPM."

### Category 10 — Quoted text
Terms that refer to texts that you cannot change in code documentation. For example, quoted error messages, log output, API responses, UI string literals, and command-line output.
`error message, stack trace, log line, HTTP response body, JSON payload, XML response, environment variable value, CLI flag, command option, shell command output, status code text, exception message, assertion message, deprecation warning, compiler diagnostic, linter rule ID, test failure message, benchmark output, profiler report, API route pattern, SQL query string, GraphQL query, regex pattern, glob pattern, cron expression, semantic version string, git commit hash, UUID string, JWT token (example)`, `"Connection refused"`, `"404 Not Found"`, `"TypeError: Cannot read properties of undefined"`, `"--config=./prod.yaml"`, `"npm ERR! code ERESOLVE"`

Non-STE: "If you get an error about the database, restart it."
STE: "If the application logs `\"FATAL: sorry, too many clients already\"` from `PostgreSQL`, restart the `pgbouncer` connection pooler."

---

<!-- 03-dictionary.md -->

# Level 5 — Adapted Dictionary A–Z

This sub-document is the **controlled-terminology catalogue** slice of STE-Code level 5 (the full standard). It lists every approved word and every unapproved word with its approved alternative(s), adapted from ASD-STE100 Issue 9, Part 2 (Dictionary, pages 149–434) to the code-documentation domain. Use it as the lookup table when an LLM must decide whether a word is permitted in STE-Code prose, and what to write instead.

> **Source:** Adapted from ASD-STE100 Issue 9, Part 2 — Dictionary, pages 149–434.
> **Domain adaptation:** aerospace → code documentation (API docs, commit messages, README sections, code comments).
> **Preserved:** word alphabetization, STE/non-STE pair format, approved/unapproved status, parts of speech.
> **Replaced:** aerospace examples with code examples.
> **Entries:** 562 (454 approved headwords, 108 unapproved). Word counts in the source header are stale aerospace-format boilerplate; 562 is the true count in this catalogue.

---

## How to read this dictionary

- **UPPERCASE headwords** are approved in STE-Code.
- **lowercase headwords** are not approved; the entry gives the approved alternative(s) to use instead.
- **(v)** = verb, **(n)** = noun, **(adj)** = adjective, **(adv)** = adverb, **(prep)** = preposition, **(conj)** = conjunction, **(pron)** = pronoun, **(art)** = article.
- **(TN)** = code-domain Technical Noun, **(TV)** = code-domain Technical Verb. A (TN) headword is an approved technical noun; a (TV) is an approved technical verb.
- For each entry: the approval status, the approved alternative(s) where relevant, and one representative STE / non-STE code-documentation pair.
- A word not in this list may still be permitted if it is a code-domain technical noun (Rule 1.5, 19 categories) or technical verb (Rule 1.12, 4 categories), or is in your project glossary.

---

# A

### A (art) — approved
- STE: A config file is included in the root directory.
- Non-STE: Config files included in root directory.

### abandon (v) - UNNAPROVED — unapproved
- Use instead: TERMINATE (v), STOP (v). IF THE BUILD FAILS, STOP THE DEPLOYMENT PIPELINE
- STE: If the build fails, stop the deployment pipeline.
- STE: If the values are incorrect, terminate the test run.
- Non-STE: If the build fails, abandon the deployment pipeline.
- Non-STE: If the values are incorrect, abandon the test procedure.

### ability (n) - UNNAPROVED — unapproved
- Use instead: CAN (v). ONE CONFIGURATION CAN HANDLE REQUESTS FOR ALL THE ENDPOINTS
- STE: One configuration can handle requests for all the endpoints.
- Non-STE: One configuration has the ability to handle requests for all the endpoints.

### able (adj) - UNNAPROVED — unapproved
- Use instead: CAN (v). IF YOU CAN RUN THE SCRIPT, DO THE APPLICABLE CHECKS
- STE: If you can run the script, do the applicable checks.
- Non-STE: If you are able to run the script, do the applicable checks.

### abnormal (adj) - UNNAPROVED — unapproved
- Use instead: UNUSUAL (adj), INCORRECT (adj). WATCH FOR UNUSUAL LOG ENTRIES
- STE: Watch for unusual log entries.
- STE: If you find an incorrect value in the output, do a debug run.
- Non-STE: Watch for abnormal log entries.
- Non-STE: If you find an abnormal value in the output, do a debug run.

### abnormality (n) - UNNAPROVED — unapproved
- Use instead: BUG (TN). EXAMINE THE REPORTED STACK TRACE FOR BUGS
- STE: Examine the reported stack trace for bugs.
- Non-STE: Examine the reported stack trace for abnormalities.

### ABOUT (prep) — approved
- STE: For data about the configuration of the module, refer to the README.
- STE: The build takes approximately 5 minutes.
- Non-STE: For data regarding the configuration of the module, refer to the README.
- Non-STE: The build takes about 5 minutes.

### ABOVE (prep) — approved
- STE: Move the cursor above the target line.
- STE: The response time must be more than 200 ms.
- Non-STE: Move the cursor to a position above the target line.
- Non-STE: The response time must be above 200 ms.

### ABRASIVE (adj) - (retained; no STE-code direct equivalent) — approved

### abrupt (adj) - UNNAPROVED — unapproved
- Use instead: SUDDEN (adj), SUDDENLY (adv). THE WATCHDOG PREVENTS SUDDEN SHUTDOWN OF THE SERVICE
- STE: The watchdog prevents sudden shutdown of the service.
- STE: If the process stops suddenly, examine the logs.
- Non-STE: The watchdog prevents abrupt shutdown of the service.
- Non-STE: If the process comes to an abrupt stop, examine the logs.

### absence (n) - UNNAPROVED — unapproved
- Use instead: NONE (pron), NOT (adv), NO (adj). IF NONE OF THE TESTS FAIL, CONTINUE THE DEPLOYMENT
- STE: If none of the tests fail, continue the deployment.
- STE: If the tests are not failing, continue the deployment.
- Non-STE: In the absence of test failures, continue the deployment.
- Non-STE: In the absence of test failures, continue the deployment.

### absent (adj) - UNNAPROVED — unapproved
- Use instead: MISSING (adj), NO (adj). IF ONE OR MORE FILES ARE MISSING, ADD AN ENTRY IN THE CHANGELOG
- STE: If one or more files are missing, add an entry in the changelog.
- Non-STE: If one or more files are absent, add an entry in the changelog.

### absolutely (adv) - UNNAPROVED — unapproved
- Use instead: FULLY (adv). MAKE SURE THAT THE CONNECTION IS FULLY ESTABLISHED
- STE: Make sure that the connection is fully established.
- Non-STE: Make sure that the connection is absolutely established.

### ABSORB (v) — approved
- STE: The buffer absorbs the input data.
- STE: The cache layer absorbs the load from repeated queries.
- Non-STE: The buffer takes up the input data.
- Non-STE: The cache layer mitigates the load from repeated queries.

### absorption (n) - UNNAPROVED — unapproved
- Use instead: ABSORB (v). MEASURE THE TIME THAT IS NECESSARY FOR THE LOG SYSTEM TO ABSORB THE INCOMING EVENTS
- STE: Measure the time that is necessary for the log system to absorb the incoming events.
- Non-STE: Measure the rate of absorption of incoming events by the log system.

### abundant (adj) - UNNAPROVED — unapproved
- Use instead: LARGE (adj). LOG THE ERRORS WITH A LARGE QUANTITY OF CONTEXT DATA
- STE: Log the errors with a large quantity of context data.
- Non-STE: Log the errors with abundant context data.

### abut (v) - UNNAPROVED — unapproved
- Use instead: TOUCH (v). THE WIDGET TOUCHES THE BOUNDARY OF THE CONTAINER
- STE: The widget touches the boundary of the container.
- Non-STE: The widget abuts the boundary of the container.

### accelerate (v) - UNNAPROVED — unapproved
- Use instead: INCREASE (v), FASTER (adj). A LARGER BUFFER SIZE INCREASES THE SPEED OF DATA TRANSFER
- STE: A larger buffer size increases the speed of data transfer.
- STE: To make the build process faster, use parallel compilation.
- Non-STE: A larger buffer size accelerates data transfer.
- Non-STE: To accelerate the build process, use parallel compilation.

### ACCEPT (v) — approved
- STE: Accept the pull request if it passes all checks.
- Non-STE: Merge the pull request if it passes all checks.

### acceptable (adj) - UNNAPROVED — unapproved
- Use instead: PERMITTED (adj), SATISFACTORY (adj), READY (adj). A RESPONSE TIME OF
- STE: A response time of 200 ms is permitted.
- STE: If the condition of the build is not satisfactory, run it again.
- Non-STE: A response time of 200 ms is acceptable.
- Non-STE: If the condition of the build is not acceptable, run it again.

### acceptance (n) - UNNAPROVED — unapproved
- Use instead: ACCEPT (v). BEFORE YOU ACCEPT THE MERGE REQUEST, DO THE SPECIFIED REVIEW CHECKLIST
- STE: Before you accept the merge request, do the specified review checklist.
- Non-STE: Before acceptance of the merge request, do the specified review checklist.

### ACCESS (n) — approved
- STE: Get access to the repository for the authentication module.
- Non-STE: Access the repository for the authentication module.

### accessible (adj) - UNNAPROVED — unapproved
- Use instead: ACCESS (n). SCROLL THE VIEW UNTIL YOU CAN GET ACCESS TO THE FUNCTIONS THAT HAVE PUBLIC ANNOTATIONS
- STE: Scroll the view until you can get access to the functions that have public annotations.
- Non-STE: Scroll the view until the functions with public annotations are accessible.

### ACCIDENT (n) — approved
- STE: To prevent accidents, make sure that the backups are configured.
- Non-STE: To prevent accidents, ensure that backups are in place.

### ACCIDENTAL (adj) — approved
- STE: To prevent accidental deletion of the files, confirm the operation.
- Non-STE: To prevent inadvertent deletion of the files, confirm the operation.

### ACCIDENTALLY (adv) — approved
- STE: If you accidentally press the delete key, restore the file from the recycle bin.
- Non-STE: If you inadvertently press the delete key, restore the file from the recycle bin.

### accommodate (v) - UNNAPROVED — unapproved
- Use instead: LET (v). DIFFERENT CONFIGURATIONS LET YOU HANDLE DIFFERENT TYPES OF INPUT
- STE: Different configurations let you handle different types of input.
- Non-STE: Different configurations accommodate different types of input.

### accomplish (v) - UNNAPROVED — unapproved
- Use instead: DO (v), COMPLETE (v). DO THIS BUILD STEP FIRST
- STE: Do this build step first.
- STE: The pipeline must complete this stage in 5 minutes.
- Non-STE: Accomplish this build step first.
- Non-STE: The pipeline must accomplish this stage in 5 minutes.

### ACCORDING to (prep) - UNNAPROVED — unapproved
- Use instead: REFER (v) TO. TO CONFIGURE THE MODULE, REFER TO THE DEVELOPER
- STE: To configure the module, refer to the developer's guide.
- Non-STE: Configure the module according to the developer's guide.

### ACCOUNT for (v) - UNNAPROVED — unapproved
- Use instead: MAKE SURE (v). MAKE SURE THAT YOU TRACK ALL DEPENDENCIES AND PACKAGES
- STE: Make sure that you track all dependencies and packages.
- Non-STE: All dependencies and packages must be accounted for.

### accumulate (v) - UNNAPROVED — unapproved
- Use instead: COLLECT (v). IF LOGS COLLECT IN THE BUFFER, FLUSH THEM
- STE: If logs collect in the buffer, flush them.
- Non-STE: If logs accumulate in the buffer, flush them.

### accumulation (n) - UNNAPROVED — unapproved
- Use instead: QUANTITY (n), COLLECT (v). REMOVE LARGE QUANTITIES OF OBSOLETE LOGS
- STE: Remove large quantities of obsolete logs.
- STE: If errors collect frequently, examine the connection for issues.
- Non-STE: Remove large accumulations of obsolete logs.
- Non-STE: If accumulation of errors is frequent, examine the connection for issues.

### accuracy (n) - UNNAPROVED — unapproved
- Use instead: PRECISION (n). THE PRECISION OF THE CALCULATION CAN CHANGE
- STE: The precision of the calculation can change.
- Non-STE: The accuracy of the calculation can change.

### ACCURATE (adj) - ACCURATELY (adv) — approved
- STE: The measurement must be accurate.
- STE: Apply the patch accurately on the target branch.
- Non-STE: The measurement must be precise.
- Non-STE: Put the patch accurately on the target branch.

### achieve (v) - UNNAPROVED — unapproved
- Use instead: GET (v). SET THE FLAG TO GET MAXIMUM PERFORMANCE
- STE: Set the flag to get maximum performance.
- Non-STE: Set the flag to achieve maximum performance.

### acquire (v) - UNNAPROVED — unapproved
- Use instead: GET (v). THE MODULE GETS THIS DATA FROM THREE ENDPOINTS
- STE: The module gets this data from three endpoints.
- Non-STE: The module acquires this data from three endpoints.

### acrid (adj) - UNNAPROVED — unapproved
- Use instead: Not applicable. Retained for completeness

### ACROSS (prep) — approved
- STE: Search across all modules for the deprecated function.
- Non-STE: Search all modules for the deprecated function.

### act (v) - UNNAPROVED — unapproved
- Use instead: Use an accurate verb. THE EVENT TRIGGER INVOKES THE HANDLER
- STE: The event trigger invokes the handler.
- Non-STE: The event trigger acts on the handler.

### action (n) - UNNAPROVED — unapproved
- Use instead: STEP (n), PROCEDURE (n), TASK (n). DO THE STEPS THAT FOLLOW
- STE: Do the steps that follow.
- STE: Do not do this procedure in the production environment.
- Non-STE: Do the following actions.
- Non-STE: This action must not be done in the production environment.

### ACTIVATE (v) — approved
- STE: The build pipeline activates the deployment mode.
- STE: Start the container.
- Non-STE: The build pipeline triggers the deployment mode.
- Non-STE: Activate the container.

### ACTIVE (adj) — approved
- STE: Read the config from the active branch.
- Non-STE: Read the config from the current branch.

### activity (n) - UNNAPROVED — unapproved
- Use instead: TASK (n), PROCEDURE (n), WORK (n). A CONTRIBUTOR CAN DO THESE REVIEW TASKS
- STE: A contributor can do these review tasks.
- STE: Do this procedure in the development branch.
- Non-STE: A contributor can do these review activities.
- Non-STE: Do this activity in the development branch.

### actuate (v) - UNNAPROVED — unapproved
- Use instead: START (v), RUN (v), PUSH (v). START THE SERVER
- STE: Start the server.
- STE: Run the script.
- Non-STE: Actuate the server.
- Non-STE: Actuate the script.

### actuation (n) - UNNAPROVED — unapproved
- Use instead: OPERATION (n). MONITOR THE OPERATION OF THE BACKGROUND WORKER
- STE: Monitor the operation of the background worker.
- Non-STE: Monitor the actuation of the background worker.

### ADAPT (v) — approved
- STE: Adapt the connector to the database schema.
- STE: The middleware layer adapts to the protocol of the connected services.
- Non-STE: Adjust the connector to fit the database schema.
- Non-STE: The middleware layer conforms to the protocol of the connected services.

### ADD (v) — approved
- STE: Add 5 lines of configuration to the file.
- Non-STE: Append 5 lines of configuration to the file.

### addition (n) - UNNAPROVED — unapproved
- Use instead: ADD (v). TO GET THE CORRECT BEHAVIOR, ADD SPECIAL FLAGS, AS NECESSARY
- STE: To get the correct behavior, add special flags, as necessary.
- Non-STE: To get the correct behavior through the addition of special flags, as necessary.

### additional (adj) - UNNAPROVED — unapproved
- Use instead: MORE (adj). THIS SECTION GIVES MORE INFORMATION ABOUT DEPLOYMENT
- STE: This section gives more information about deployment.
- Non-STE: This section gives additional information about deployment.

### adequate (adj) - UNNAPROVED — unapproved
- Use instead: SUFFICIENT (adj). MAKE SURE THAT BUFFERS HAVE SUFFICIENT CAPACITY AND THROUGHPUT
- STE: Make sure that buffers have sufficient capacity and throughput.
- Non-STE: Make sure that buffers have adequate capacity and throughput.

### adhere (v) - UNNAPROVED — unapproved
- Use instead: ATTACH (v), OBEY (v). THE PATCH MUST ATTACH CORRECTLY
- STE: The patch must attach correctly.
- STE: Obey the coding standards.
- Non-STE: The patch must adhere correctly.
- Non-STE: Adhere to the coding standards.

### adhesion (n) - UNNAPROVED — unapproved
- Use instead: Not applicable. Retained for completeness

### ADJACENT (adj) - ADJACENT TO (prep) — approved
- STE: Do not modify the adjacent function.
- STE: The config file is located adjacent to the main module.
- Non-STE: Do not modify the function that is next to it.
- Non-STE: The config file is located next to the main module.

### adjoining (adj) - UNNAPROVED — unapproved
- Use instead: ADJACENT (adj). ALIGN THE IMPORTS WITH THE ADJACENT MODULES
- STE: Align the imports with the adjacent modules.
- Non-STE: Align the imports with the adjoining modules.

### ADJUST (v) — approved
- STE: Adjust the timeout to the value given in Table 1.
- STE: The auto-scaler adjusts to sudden changes in load.
- Non-STE: Tune the timeout to the value given in Table 1.
- Non-STE: The auto-scaler adapts to sudden changes in load.

### ADJUSTABLE (adj) - ADJUSTMENT (n) — approved
- STE: The two parameters are adjustable.
- STE: Make sure that the adjustment is in the limits given in Table 1.
- Non-STE: The two parameters can be tuned.
- Non-STE: Make sure that the tuning is in the limits given in Table 1.

### admit (v) - UNNAPROVED — unapproved
- Use instead: LET (v). OPEN THE PORT TO LET TRAFFIC GO INTO THE CONTAINER
- STE: Open the port to let traffic go into the container.
- Non-STE: Open the port to admit traffic into the container.

### adopt (v) - UNNAPROVED — unapproved
- Use instead: USE (v). IF THE BUILD FAILS, USE THIS FALLBACK SCRIPT
- STE: If the build fails, use this fallback script.
- Non-STE: Adopt this fallback script if the build fails.

### advance (n) - UNNAPROVED — unapproved
- Use instead: FORWARD (adj). THE FORWARD MOVEMENT OF THE ITERATOR MUST BE SEQUENTIAL
- STE: The forward movement of the iterator must be sequential.
- Non-STE: The advance of the iterator must be sequential.

### advance (v) - UNNAPROVED — unapproved
- Use instead: SET (v), FORWARD (adv). SET THE POINTER TO THE NEXT NODE
- STE: Set the pointer to the next node.
- STE: Move the cursor forward.
- Non-STE: Advance the pointer to the next node.
- Non-STE: Advance the cursor.

### adverse (adj) - UNNAPROVED — unapproved
- Use instead: BAD (adj). REFER TO SECTION
- STE: Refer to Section 6 for instructions about how to handle bad network conditions.
- Non-STE: Refer to Section 6 for instructions about how to handle adverse network conditions.

### advisable (adj) - UNNAPROVED — unapproved
- Use instead: RECOMMEND (v). THE TECHNICAL LEAD RECOMMENDS THAT YOU REBUILD THE CONTAINERS AT INTERVALS OF TWO WEEKS
- STE: The technical lead recommends that you rebuild the containers at intervals of two weeks.
- Non-STE: It is advisable to rebuild the containers at intervals of two weeks.

### advise (v) - UNNAPROVED — unapproved
- Use instead: TELL (v), RECOMMEND (v). TELL THE REVIEWER THAT THE CHANGES ARE READY
- STE: Tell the reviewer that the changes are ready.
- STE: The security officer recommends the applicable authentication protocol.
- Non-STE: Advise the reviewer that the changes are ready.
- Non-STE: The security officer advises on the applicable authentication protocol.

### affect (v) - UNNAPROVED — unapproved
- Use instead: EFFECT (n). THREAD LOCKS HAVE AN UNWANTED EFFECT ON THE SCHEDULER
- STE: Thread locks have an unwanted effect on the scheduler.
- Non-STE: Thread locks affect the scheduler.

### AFT (adj), AFT (adv) — approved

### AFTER (conj) — approved
- STE: After you deploy the update, do a smoke test.
- Non-STE: Following deployment of the update, do a smoke test.

### AGAIN (adv) — approved
- STE: Run the test again.
- Non-STE: Rerun the test.

# B

### BACK (adj), BACK (adv) — approved
- STE: Revert to the back version.
- STE: Navigate back to the previous page.
- Non-STE: Revert to the previous version.
- Non-STE: Go backwards to the previous page.

### BACK up (v) - UNNAPROVED — unapproved
- Use instead: Not applicable as standalone verb in STE-Code. Use SAVE (v) or COPY (v) for data; REVERSE (v) for motion.
- STE: Save the database before the migration.
- STE: Copy the configuration files.
- Non-STE: Back up the database before the migration.
- Non-STE: Back up the configuration files.

### BAD (adj) — approved
- STE: Refer to Section 6 for instructions about how to handle bad build states.
- Non-STE: Refer to Section 6 for instructions about how to handle unsatisfactory build states.

### BALANCE (n), BALANCE (v) — approved
- STE: Make sure that the load is in balance across all nodes.
- STE: Balance the workload across all workers.
- Non-STE: Make sure that the load is balanced across all nodes.
- Non-STE: Distribute the workload across all workers.

### base (n) - UNNAPROVED — unapproved
- Use instead: Use FOUNDATION (n) for conceptual base, ROOT (n) for positional base
- STE: The foundation of the architecture is the data layer.
- STE: Start from the root of the project.
- Non-STE: The base of the architecture is the data layer.
- Non-STE: Start from the base of the project.

### BE (v) — approved
- STE: If there is an error in the log, restart the service.
- STE: Unhandled exceptions are dangerous.
- Non-STE: If an error exists in the log, restart the service.
- Non-STE: Unhandled exceptions constitute a danger.

### BECAUSE (conj) — approved
- STE: Do not use raw input, because it is a security risk.
- Non-STE: Do not use raw input, since it is a security risk.

### BECOME (v) — approved
- STE: The connection becomes unstable.
- Non-STE: The connection turns unstable.

### BEFORE (conj) — approved
- STE: Before you run the migration, read the release notes.
- Non-STE: Prior to running the migration, read the release notes.

### BEGIN (v) — approved
- STE: Begin the build process.
- Non-STE: Initiate the build process.

### BELOW (prep) — approved
- STE: See the example below the code block.
- Non-STE: See the example beneath the code block.

### BEND (v) — approved

### BETWEEN (prep) — approved
- STE: Put the middleware between the client and the server.
- Non-STE: Insert the middleware between the client and the server.

### BLOCK (n) — approved
- STE: Put a comment block above the function.
- Non-STE: Add documentation above the function.

### BOND (v) — approved

### BOTTOM (n), BOTTOM (adj) — approved
- STE: Scroll to the bottom of the file.
- STE: The bottom layer of the stack is the database.
- Non-STE: Scroll to the end of the file.
- Non-STE: The lowest layer of the stack is the database.

### BRACKET (n) - (TN) — approved
- STE: Use square brackets for array access.
- Non-STE: Use the bracket notation for array access.

### BREAK (v) — approved
- STE: Do not break the public API.
- STE: Break out of the loop when the flag is set.
- Non-STE: Do not cause breaking changes to the public API.
- Non-STE: Exit the loop when the flag is set.

### bring (v) - UNNAPROVED — unapproved
- Use instead: GET (v), MOVE (v). GET THE DEPENDENCIES INTO THE CONTAINER
- STE: Get the dependencies into the container.
- Non-STE: Bring the dependencies into the container.

### broad (adj) - UNNAPROVED — unapproved
- Use instead: WIDE (adj). WIDE TEST COVERAGE
- STE: Wide test coverage.
- Non-STE: Broad test coverage.

### BUG (n) - (TN) — approved
- STE: Use the bug tracker to log defects.
- Non-STE: Use the issue tracker to log defects.

### build (v) - UNNAPROVED — unapproved
- Use instead: COMPILE (v), MAKE (v). COMPILE THE PROJECT
- STE: Compile the project.
- Non-STE: Build the project.

### BURN (v) — approved
- STE: Burn the ISO image to the USB drive.
- Non-STE: Write the ISO image to the USB drive.

### BUT (conj) — approved
- STE: The build passes, but the tests fail.
- Non-STE: The build passes, however the tests fail.

### BY (prep) — approved
- STE: Build the project by the CMake tool.
- STE: Authenticate by OAuth.
- Non-STE: Build the project using CMake.
- Non-STE: Authenticate via OAuth.

### BYTE (n) - (TN) — approved
- STE: The buffer holds 1024 bytes.
- Non-STE: The buffer has a size of 1024 bytes.

# C

### CALCULATE (v) — approved
- STE: Calculate the checksum of the file.
- Non-STE: Compute the checksum of the file.

### call (v) - UNNAPROVED — unapproved
- Use instead: Three meanings: 1. NAME (v). NAME THE FUNCTION "init." 2. INVOKE (TV) - as technical verb. 3. REFER (v) TO.
- STE: Name the function "init."
- STE: Contact the administrator.
- Non-STE: Call the function "init."
- Non-STE: Call the administrator.

### CAN (v) — approved
- STE: A misconfiguration can cause a crash.
- STE: You can run the script after the build is completed.
- Non-STE: A misconfiguration could cause a crash.
- Non-STE: You are able to run the script after the build is completed.

### CANCEL (v) — approved
- STE: Cancel the deployment pipeline.
- Non-STE: Abort the deployment pipeline.

### CANNOT (v) — approved
- STE: You cannot access this endpoint without authentication.
- Non-STE: You are unable to access this endpoint without authentication.

### capable (adj) - UNNAPROVED — unapproved
- Use instead: CAN (v). THE SERVICE CAN RECOVER FROM FAILURES AUTOMATICALLY
- STE: The service can recover from failures automatically.
- Non-STE: The service is capable of recovering from failures automatically.

### care (n) - UNNAPROVED — unapproved
- Use instead: BE CAREFUL, CAUTION (n). BE CAREFUL WHEN YOU CHANGE THE CONFIGURATION
- STE: Be careful when you change the configuration.
- Non-STE: Take care when changing the configuration.

### carry (v) - UNNAPROVED — unapproved
- Use instead: MOVE (v), TRANSMIT (v). MOVE THE DATA TO THE CACHE
- STE: Move the data to the cache.
- Non-STE: Carry the data to the cache.

### CARRY out (v) - UNNAPROVED — unapproved
- Use instead: DO (v). DO THE REVIEW
- STE: Do the review.
- Non-STE: Carry out the review.

### case (n) - UNNAPROVED — unapproved
- Use instead: For conditional: IF (conj). For coding structure: use SWITCH CASE as technical noun.
- STE: If the flag is true, log the event.
- STE: Add a switch case for the error state.
- Non-STE: In case the flag is true, log the event.
- Non-STE: Handle the error case.

### CATCH (v) — approved
- STE: Catch the exception and log it.
- Non-STE: Trap the exception and log it.

### CAUSE (v) — approved
- STE: The null pointer caused the crash.
- Non-STE: The null pointer resulted in the crash.

### CAUTION (n) — approved
- STE: Obey the cautions in this README.
- Non-STE: Follow the cautions in this README.

### CENTER (n) — approved
- STE: Align the text to the center.
- Non-STE: Center the text.

### CHANGE (v), CHANGE (n) — approved
- STE: Change the function signature.
- STE: Record the changes in the changelog.
- Non-STE: Modify the function signature.
- Non-STE: Log the changes in the changelog.

### CHECK (n) — approved
- STE: Do a check of the input values.
- Non-STE: Validate the input values.

### check (v) - UNNAPROVED — unapproved
- Use instead: Not approved as verb; use VERIFY (v) or CHECK (n) with DO.
- STE: Do a check of the values.
- STE: Verify the data integrity.
- Non-STE: Check the values.
- Non-STE: Check the data integrity.

### choose (v) - UNNAPROVED — unapproved
- Use instead: SELECT (v), ALTERNATIVE (adj). SELECT THE CORRECT CONFIGURATION
- STE: Select the correct configuration.
- Non-STE: Choose the correct configuration.

### CLEAN (v), CLEAN (adj) — approved
- STE: Clean the temporary files.
- Non-STE: Delete the temporary files.

### CLEAR (adj) — approved
- STE: A clear code path for the request.
- STE: Clear documentation for the API.
- Non-STE: An unobstructed code path for the request.
- Non-STE: Understandable documentation for the API.

### CLICK (n), CLICK (v) - (TN/TV) — approved
- STE: Click the "Submit" button.
- Non-STE: Press the "Submit" button.

### CLOSE (v) — approved
- STE: Close the file handle.
- Non-STE: Release the file handle.

### CODE (n) - (TN) — approved
- STE: The code is in the `src/` directory.
- Non-STE: The source is in the `src/` directory.

### COLLECT (v) — approved
- STE: Collect the metrics from all nodes.
- Non-STE: Gather the metrics from all nodes.

### COME (v) — approved
- STE: When the service comes online, start the tests.
- Non-STE: When the service starts, start the tests.

### COMMENT (n) - (TN) — approved
- STE: Add a comment to explain the algorithm.
- Non-STE: Document the algorithm in the code.

### COMMIT (v) - (TV) — approved
- STE: Commit the changes to the repository.
- Non-STE: Save the changes to the repository.

### COMPARE (v) — approved
- STE: Compare the hash value with the expected hash.
- Non-STE: Check the hash value against the expected hash.

### COMPATIBLE (adj) — approved
- STE: The library is compatible with version 3.0.
- Non-STE: The library works with version 3.0.

### compile (v) - UNNAPROVED — unapproved
- Use instead: Technical verb (TV) for translating source code. COMPILE THE SOURCE FILES
- STE: Compile the source files.
- Non-STE: Build the source files.

### COMPLETE (v) — approved
- STE: Complete the setup wizard.
- Non-STE: Finish the setup wizard.

### COMPONENT (n) — approved
- STE: The component is imported in the module.
- Non-STE: The component is used in the module.

### COMPRESS (v) — approved
- STE: Compress the log files before archiving.
- Non-STE: Zip the log files before archiving.

### CONDITION (n) — approved
- STE: The condition of the build is satisfactory.
- STE: If the condition is true, continue.
- Non-STE: The build state is good.
- Non-STE: If the conditional evaluates to true, continue.

### CONFIGURATION (n) - (TN) — approved
- STE: The configuration file is in YAML format.
- Non-STE: The config file is in YAML format.

### confirm (v) - UNNAPROVED — unapproved
- Use instead: MAKE SURE (v). MAKE SURE THAT THE BUILD IS SUCCESSFUL
- STE: Make sure that the build is successful.
- Non-STE: Confirm that the build is successful.

### CONNECT (v) — approved
- STE: Connect the client to the server.
- Non-STE: Establish a connection between the client and the server.

### CONTAIN (v) — approved
- STE: The module contains the helper functions.
- Non-STE: The module includes the helper functions.

### CONTACT (v) — approved
- STE: Contact the system administrator.
- Non-STE: Get in touch with the system administrator.

### CONTINUE (v) — approved
- STE: If the build passes, continue the deployment.
- Non-STE: If the build passes, proceed with the deployment.

### CONTROL (n), CONTROL (v) — approved
- STE: The control of the access is role-based.
- STE: Control the workflow with the dashboard.
- Non-STE: Access is role-based.
- Non-STE: Manage the workflow with the dashboard.

### COPY (v) — approved
- STE: Copy the config to the staging environment.
- Non-STE: Duplicate the config to the staging environment.

### CORRECT (adj) — approved
- STE: Make sure that the test results are correct.
- Non-STE: Verify that the test results are correct.

### CORRECTLY (adv) — approved
- STE: Make sure that the package is correctly installed.
- Non-STE: Ensure the package is correctly installed.

### COUNT (v) — approved
- STE: Count the records in the database.
- Non-STE: Get the count of records in the database.

### COVER (n) — approved

### CRASH (v) - (TV) — approved
- STE: If the application crashes, read the logs.
- Non-STE: If the application fails, read the logs.

### CREATE (v) — approved
- STE: Create a new instance of the class.
- Non-STE: Instantiate a new object of the class.

### CUT (v) — approved
- STE: Cut the text and paste it in the new location.
- Non-STE: Move the text to the new location.

# D

### DAMAGE (n) — approved
- STE: The damage to the data is irreversible.
- Non-STE: The data corruption is irreversible.

### danger (n) - UNNAPROVED — unapproved
- Use instead: RISK (n). THIS OPERATION HAS A RISK OF DATA LOSS
- STE: This operation has a risk of data loss.
- Non-STE: There is a danger of data loss with this operation.

### DANGEROUS (adj) — approved
- STE: This command is dangerous.
- Non-STE: This command poses a danger.

### DATA (n) - (TN) — approved
- STE: The data is stored in the cache.
- Non-STE: The information is stored in the cache.

### DEACTIVATE (v) — approved
- STE: Deactivate the background worker.
- Non-STE: Disable the background worker.

### DEBUG (v) - (TV) — approved
- STE: Debug the application with the attached profiler.
- Non-STE: Troubleshoot the application with the attached profiler.

### DECREASE (v) — approved
- STE: Decrease the timeout value.
- Non-STE: Lower the timeout value.

### DEEP (adj) — approved
- STE: Deep directory structure.
- Non-STE: Nested directory structure.

### DEFAULT (n) - (TN) — approved
- STE: The default value is 8080.
- Non-STE: The initial value is 8080.

### DEFECT (n) - (TN) — approved
- STE: Log the defect in the tracking system.
- Non-STE: Log the bug in the tracking system.

### DEFINE (v) — approved
- STE: The header file defines the interface.
- Non-STE: The header file declares the interface.

### delete (v) - UNNAPROVED — unapproved
- Use instead: REMOVE (v). REMOVE THE FILE FROM THE DIRECTORY
- STE: Remove the file from the directory.
- Non-STE: Delete the file from the directory.

### DEPLOY (v) — approved
- STE: Deploy the application to production.
- Non-STE: Release the application to production.

### DEPRECATED (adj) - (TN) — approved
- STE: The deprecated function will be removed in version 4.0.
- Non-STE: The outdated function will be removed in version 4.0.

### DESIGN (n) — approved
- STE: The design of the API follows REST principles.
- Non-STE: The architecture of the API follows REST principles.

### destroy (v) - UNNAPROVED — unapproved
- Use instead: BREAK (v), REMOVE (v). BREAK THE OLD SESSION
- STE: Break the old session.
- Non-STE: Destroy the old session.

### DEVELOP (v) - (TV) — approved
- STE: Develop the feature in a separate branch.
- Non-STE: Build the feature in a separate branch.

### DIFFERENT (adj) — approved
- STE: The two implementations have different performance.
- Non-STE: The two implementations differ in performance.

### DIMENSION (n) — approved
- STE: The array has three dimensions.
- Non-STE: The array is three-dimensional.

### DIRECTORY (n) - (TN) — approved
- STE: The source files are in the `src/` directory.
- Non-STE: The source files are in the `src/` folder.

### DISABLE (v) - (TV) — approved
- STE: Disable the feature flag.
- Non-STE: Turn off the feature flag.

### DISCARD (v) — approved
- STE: Discard the deprecated code.
- Non-STE: Remove the deprecated code.

### DISCONNECT (v) — approved
- STE: Disconnect the socket.
- Non-STE: Close the socket.

### DISPLAY (v), DISPLAY (n) — approved
- STE: The terminal displays the log output.
- Non-STE: The terminal shows the log output.

### DIVIDE (v) — approved
- STE: Divide the tasks among the workers.
- Non-STE: Distribute the tasks among the workers.

### DO (v) — approved
- STE: Do the build step.
- Non-STE: Execute the build step.

### DOCUMENT (v) - (TV) — approved
- STE: Document the public API.
- Non-STE: Write docs for the public API.

### DOWN (adv), DOWN (prep) — approved
- STE: Scroll down the page.
- STE: The server is down.
- Non-STE: Scroll to the lower part of the page.
- Non-STE: The server is not operational.

### DOWNLOAD (v) - (TV) — approved
- STE: Download the package from the registry.
- Non-STE: Get the package from the registry.

### DRAIN (v) — approved
- STE: Drain the connection pool.
- Non-STE: Empty the connection pool.

### DRAW (v) — approved
- STE: Draw the architecture diagram.
- Non-STE: Create the architecture diagram.

### DROP (v) — approved
- STE: Drop the table from the database.
- Non-STE: Delete the table from the database.

### DRY (adj), DRY (v) — approved

# E

### EACH (adj) — approved
- STE: Each module has a README file.
- Non-STE: Every module has a README file.

### EASY (adj) — approved
- STE: The setup is easy.
- Non-STE: The setup is straightforward.

### EDIT (v) - (TV) — approved
- STE: Edit the configuration file with a text editor.
- Non-STE: Modify the configuration file with a text editor.

### EFFECT (n) — approved
- STE: The effect of the change is small.
- Non-STE: The impact of the change is small.

### EJECT (v) — approved
- STE: Eject the volume.
- Non-STE: Unmount the volume.

### ELEMENT (n) — approved
- STE: Each element of the list has an index.
- Non-STE: Each item of the list has an index.

### ELSE (adv) - (TN) — approved
- STE: If the value is null, return 0; else return the value.
- Non-STE: If the value is null, return 0; otherwise return the value.

### EMPTY (adj) — approved
- STE: An empty string.
- Non-STE: A zero-length string.

### ENABLE (v) - (TV) — approved
- STE: Enable the debug mode.
- Non-STE: Turn on the debug mode.

### END (n), END (v) — approved
- STE: The end of the file.
- STE: End the session.
- Non-STE: The final byte of the file.
- Non-STE: Terminate the session.

### ensure (v) - UNNAPROVED — unapproved
- Use instead: MAKE SURE (v). MAKE SURE THAT THE DATABASE IS CONNECTED
- STE: Make sure that the database is connected.
- Non-STE: Ensure that the database is connected.

### enter (v) - UNNAPROVED — unapproved
- Use instead: PUT (v), TYPE (v). TYPE YOUR PASSWORD
- STE: Type your password.
- Non-STE: Enter your password.

### ENVIRONMENT (n) - (TN) — approved
- STE: The staging environment is a copy of production.
- Non-STE: The staging setup is a copy of production.

### EQUAL (adj), EQUAL (v) — approved
- STE: The two hashes are equal.
- STE: The result equals zero.
- Non-STE: The two hashes are the same.
- Non-STE: The result is zero.

### ERASE (v) — approved
- STE: Erase the sensitive data from memory.
- Non-STE: Wipe the sensitive data from memory.

### ERROR (n) - (TN) — approved
- STE: The error occurred at line 42.
- Non-STE: The issue occurred at line 42.

### establish (v) - UNNAPROVED — unapproved
- Use instead: MAKE (v), START (v). MAKE A CONNECTION
- STE: Make a connection.
- Non-STE: Establish a connection.

### EVALUATE (v) - (TV) — approved
- STE: Evaluate the expression at runtime.
- Non-STE: Compute the expression at runtime.

### EVENT (n) - (TN) — approved
- STE: The event triggers the callback.
- Non-STE: The event fires the callback.

### EXAMINE (v) — approved
- STE: Examine the code for security issues.
- Non-STE: Review the code for security issues.

### EXAMPLE (n) — approved
- STE: This is an example of a correct API call.
- Non-STE: This demonstrates a correct API call.

### except (prep) - UNNAPROVED — unapproved
- Use instead: BUT NOT, OTHER THAN. ALL MODULES EXCEPT THE DATABASE ARE AVAILABLE
- STE: All modules except the database module are available.
- Non-STE: All modules other than the database module are available.

### EXECUTE (v) - (TV) — approved
- STE: Execute the script from the terminal.
- Non-STE: Run the script from the terminal.

### EXPAND (v) — approved
- STE: Expand the macro at compile time.
- Non-STE: The macro is substituted at compile time.

### explain (v) - UNNAPROVED — unapproved
- Use instead: DESCRIBE (v), TELL (v). DESCRIBE THE ERROR CONDITION
- STE: Describe the error condition.
- Non-STE: Explain the error condition.

### EXPORT (v) - (TV) — approved
- STE: Export the function from the library.
- Non-STE: Make the function available from the library.

### EXTEND (v) — approved
- STE: Extend the base class to add new methods.
- Non-STE: Subclass the base class to add new methods.

# F

### FAIL (v) — approved
- STE: If the test fails, examine the logs.
- Non-STE: If the test does not pass, examine the logs.

### failure (n) - UNNAPROVED — unapproved
- Use instead: DOES NOT WORK, STOPS. IF THE SERVICE STOPS, RESTART IT
- STE: If the service stops, restart it.
- Non-STE: In case of service failure, restart it.

### FALL (v) — approved

### FALSE (adj) - (TN) — approved
- STE: If the condition is false, skip the block.
- Non-STE: If the condition does not hold, skip the block.

### FAST (adj), FAST (adv) — approved
- STE: Fast response time.
- Non-STE: Low latency.

### FATAL (adj) - (TN) — approved
- STE: A fatal error occurred.
- Non-STE: A critical error occurred.

### FETCH (v) — approved
- STE: Fetch the records from the database.
- Non-STE: Retrieve the records from the database.

### FIELD (n) - (TN) — approved
- STE: The `email` field of the form must be validated.
- Non-STE: The `email` input of the form must be validated.

### FILE (n) - (TN) — approved
- STE: The configuration file is in TOML format.
- Non-STE: The config is in TOML format.

### FILL (v) — approved
- STE: Fill the array with default values.
- Non-STE: Initialize the array with default values.

### FILTER (n), FILTER (v) — approved
- STE: Filter the results by status.
- Non-STE: Select only the results that match the status.

### FIND (v) — approved
- STE: Find the root cause of the error.
- Non-STE: Determine the root cause of the error.

### FINISH (v) — approved
- STE: Finish the setup.
- Non-STE: Complete the setup.

### FIRST (adj), FIRST (adv) — approved
- STE: Define the variable first.
- Non-STE: Initially define the variable.

### fit (v) - UNNAPROVED — unapproved
- Use instead: INSTALL (v), ADD (v). INSTALL THE PACKAGE
- STE: Install the package.
- Non-STE: Fit the package into the project.

### FIX (v) — approved
- STE: Fix the memory leak.
- Non-STE: Resolve the memory leak.

### FLAG (n) - (TN) — approved
- STE: Set the debug flag to true.
- Non-STE: Enable the debug flag.

### FLOW (n), FLOW (v) — approved
- STE: The flow of data through the pipeline.
- STE: The data flows through the channel.
- Non-STE: The data stream through the pipeline.
- Non-STE: The data passes through the channel.

### follow (v) - UNNAPROVED — unapproved
- Use instead: OBEY (v). OBEY THE CODING GUIDELINES
- STE: Obey the coding guidelines.
- Non-STE: Follow the coding guidelines.

### FOR (prep) — approved
- STE: For examples, refer to the README.
- Non-STE: To see examples, refer to the README.

### FORCE (n) — approved
- STE: Force the application to restart.
- Non-STE: Compel the application to restart.

### FORMAT (n) - (TN) — approved
- STE: The file format is JSON.
- Non-STE: The file is in JSON.

### FORWARD (adv) — approved
- STE: Move the pointer forward.
- Non-STE: Advance the pointer.

### FREE (adj) — approved
- STE: The code is free of errors.
- Non-STE: The code has no errors.

### FROM (prep) — approved
- STE: Import the module from the package.
- Non-STE: Import the module out of the package.

### FULL (adj) — approved
- STE: Full test suite.
- Non-STE: Complete test suite.

### FUNCTION (n) — approved
- STE: The function returns a string.
- STE: The function of the middleware is to authenticate requests.
- Non-STE: The method returns a string.
- Non-STE: The role of the middleware is to authenticate requests.

# G

### GET (v) — approved
- STE: Get the data from the API.
- STE: The service gets unstable under load.
- Non-STE: Fetch the data from the API.
- Non-STE: The service becomes unstable under load.

### GIVE (v) — approved
- STE: This section gives the build instructions for the module.
- Non-STE: This section provides the build instructions for the module.

### GO (v) — approved
- STE: Go to the next phase of the pipeline.
- Non-STE: Proceed to the next phase of the pipeline.

### GOOD (adj) — approved
- STE: Good test coverage.
- Non-STE: Satisfactory test coverage.

### GROUP (n), GROUP (v) — approved
- STE: Group the tests by module.
- Non-STE: Organize the tests by module.

# H

### handle (v) - UNNAPROVED — unapproved
- Use instead: PROCESS (v), MANAGE (v). PROCESS THE EXCEPTION
- STE: Process the exception.
- Non-STE: Handle the exception.

### happen (v) - UNNAPROVED — unapproved
- Use instead: OCCUR (v). AN EXCEPTION OCCURRED DURING INITIALIZATION
- STE: An exception occurred during initialization.
- Non-STE: An exception happened during initialization.

### HARD (adj) — approved
- STE: A hard limit on the number of connections.
- Non-STE: A strict limit on the number of connections.

### HAVE (v) — approved
- STE: The class has two methods.
- Non-STE: The class contains two methods.

### HEAD (n) — approved
- STE: The head of the queue.
- Non-STE: The front of the queue.

### HELP (n), HELP (v) — approved
- STE: This README helps you to set up the project.
- Non-STE: This README assists you in setting up the project.

### HIGH (adj) — approved
- STE: High load on the server.
- Non-STE: Heavy load on the server.

### HIT (v) — approved
- STE: Hit the endpoint with a GET request.
- Non-STE: Send a GET request to the endpoint.

### HOLD (v) — approved
- STE: Hold the lock until the operation completes.
- Non-STE: Keep the lock until the operation completes.

### HOOK (n) - (TN) — approved
- STE: Use a pre-commit hook to validate the code.
- Non-STE: Use a pre-commit script to validate the code.

### HOW (adv) — approved
- STE: How to compile the project.
- Non-STE: Instructions to compile the project.

# I

### IDENTIFY (v) — approved
- STE: Identify the source of the memory leak.
- Non-STE: Find the source of the memory leak.

### IF (conj) — approved
- STE: If the status code is 500, retry the request.
- Non-STE: In the event of a 500 status code, retry the request.

### IGNORE (v) — approved
- STE: Ignore the case sensitivity.
- Non-STE: Do not consider the case sensitivity.

### IMMEDIATELY (adv) — approved
- STE: Restart the service immediately.
- Non-STE: Restart the service right away.

### IMPLEMENT (v) - (TV) — approved
- STE: Implement the interface.
- Non-STE: Code the interface.

### IMPORT (v) - (TV) — approved
- STE: Import the module at the top of the file.
- Non-STE: Include the module at the top of the file.

### IMPORTANT (adj) — approved
- STE: Important security note.
- Non-STE: Critical security note.

### IN (prep) — approved
- STE: In the directory `src/lib/`.
- Non-STE: Within the directory `src/lib/`.

### INCLUDE (v) — approved
- STE: The package includes the dependencies.
- Non-STE: The package contains the dependencies.

### INCORRECT (adj) — approved
- STE: Incorrect syntax.
- Non-STE: Wrong syntax.

### INCREASE (v) — approved
- STE: Increase the buffer size.
- Non-STE: Make the buffer larger.

### INDEX (n) - (TN) — approved
- STE: The index of the element is 0.
- Non-STE: The position of the element is 0.

### indicate (v) - UNNAPROVED — unapproved
- Use instead: SHOW (v). THE LOG SHOWS THE ERROR TYPE
- STE: The log shows the error type.
- Non-STE: The log indicates the error type.

### INITIALIZE (v) - (TV) — approved
- STE: Initialize the variable to zero.
- Non-STE: Set the variable to zero initially.

### INPUT (n) - (TN) — approved
- STE: Validate the user input.
- Non-STE: Validate the data entered by the user.

### insert (v) - UNNAPROVED — unapproved
- Use instead: PUT (v), ADD (v). PUT THE RECORD INTO THE DATABASE
- STE: Put the record into the database.
- Non-STE: Insert the record into the database.

### inspect (v) - UNNAPROVED — unapproved
- Use instead: EXAMINE (v), REVIEW (v). REVIEW THE CODE FOR VULNERABILITIES
- STE: Review the code for vulnerabilities.
- Non-STE: Inspect the code for vulnerabilities.

### INSTALL (v) — approved
- STE: Install the package with npm.
- Non-STE: Set up the package with npm.

### INSTRUCTION (n) — approved
- STE: Obey the instructions in the README.
- Non-STE: Follow the instructions in the README.

### INTERFACE (n) - (TN) — approved
- STE: The interface defines three methods.
- Non-STE: The contract defines three methods.

### INVALID (adj) - (TN) — approved
- STE: An invalid token.
- Non-STE: A bad token.

### ISOLATE (v) — approved
- STE: Isolate the component for unit testing.
- Non-STE: Separate the component for unit testing.

### IT (pron) — approved
- STE: The package. It is in the registry.
- Non-STE: The package is in the registry.

# J

### JOIN (v) — approved
- STE: Join the two strings.
- Non-STE: Concatenate the two strings.

# K

### KEEP (v) — approved
- STE: Keep the connection open.
- Non-STE: Maintain the connection.

### KEY (n) - (TN) — approved
- STE: The key for the cache entry is the user ID.
- Non-STE: The identifier for the cache entry is the user ID.

### KILL (v) — approved
- STE: Kill the process with SIGTERM.
- Non-STE: Terminate the process with SIGTERM.

### KNOW (v) — approved
- STE: You must know the API specification.
- Non-STE: You must be familiar with the API specification.

# L

### LARGE (adj) — approved
- STE: A large dataset.
- Non-STE: A big dataset.

### LAST (adj), LAST (adv) — approved
- STE: Execute the teardown last.
- Non-STE: Execute the teardown at the end.

### LAYER (n) - (TN) — approved
- STE: The data access layer handles queries.
- Non-STE: The data tier handles queries.

### LEFT (adj), LEFT (adv) — approved
- STE: Align the text left.
- Non-STE: Align the text to the left.

### LENGTH (n) — approved
- STE: The length of the array is 10.
- Non-STE: The array has 10 elements.

### LESS (adj), LESS (adv), LESS (prep) — approved
- STE: Less memory usage.
- Non-STE: Lower memory usage.

### LET (v) — approved
- STE: Let the process complete before you restart.
- Non-STE: Allow the process to complete before you restart.

### LEVEL (n) — approved
- STE: Set the log level to debug.
- Non-STE: Set the logging severity to debug.

### LIBRARY (n) - (TN) — approved
- STE: Import the standard library.
- Non-STE: Include the standard library.

### LIFT (v) — approved
- STE: Lift the function to a separate module.
- Non-STE: Extract the function to a separate module.

### LIGHT (adj) — approved
- STE: A light process with small memory footprint.
- Non-STE: A lightweight process.

### LIMIT (n), LIMIT (v) — approved
- STE: Limit the number of requests.
- Non-STE: Restrict the number of requests.

### LINE (n) — approved
- STE: The error is at line 42.
- Non-STE: The error is on line 42.

### LINK (n), LINK (v) — approved
- STE: Link the library to the project.
- Non-STE: Connect the library to the project.

### LIST (n), LIST (v) — approved
- STE: List the files in the directory.
- Non-STE: Show the files in the directory.

### LOAD (n), LOAD (v) — approved
- STE: Load the configuration file.
- Non-STE: Read the configuration file.

### locate (v) - UNNAPROVED — unapproved
- Use instead: FIND (v). FIND THE ERROR IN THE LOGS
- STE: Find the error in the logs.
- Non-STE: Locate the error in the logs.

### LOCK (v) — approved
- STE: Lock the mutex.
- Non-STE: Acquire the mutex.

### LOG (n), LOG (v) - (TN/TV) — approved
- STE: Log the error to the file.
- Non-STE: Write the error to the file.

### LONG (adj) — approved
- STE: A long process.
- Non-STE: A time-consuming process.

### LOOK (v) — approved
- STE: Look at the error message.
- Non-STE: Examine the error message.

### LOOP (n) - (TN) — approved
- STE: The for loop iterates 10 times.
- Non-STE: The iteration runs 10 times.

### LOOSE (adj) — approved
- STE: Loose coupling between modules.
- Non-STE: Decoupled modules.

### LOW (adj) — approved
- STE: Low latency.
- Non-STE: Minimal delay.

### LOWER (v) — approved
- STE: Lower the log level.
- Non-STE: Reduce the log level.

# M

### main (adj) - UNNAPROVED — unapproved
- Use instead: PRIMARY (adj). THE PRIMARY CAUSE OF THE CRASH IS A NULL POINTER
- STE: The primary cause of the crash is a null pointer.
- Non-STE: The main cause of the crash is a null pointer.

### MAKE (v) — approved
- STE: Make a copy of the file.
- Non-STE: Create a copy of the file.

### MAKE SURE (v) — approved
- STE: Make sure that the tests pass.
- Non-STE: Ensure that the tests pass.

### MANAGE (v) - (TV) — approved
- STE: The package manager manages dependencies.
- Non-STE: The package manager handles dependencies.

### MANDATORY (adj) — approved
- STE: The API key is mandatory.
- Non-STE: The API key is required.

### MANUAL (adj), MANUAL (n) — approved
- STE: Manual review of the code.
- STE: Read the manual before you start.
- Non-STE: Human review of the code.
- Non-STE: Read the docs before you start.

### MANY (adj) — approved
- STE: Many requests per second.
- Non-STE: Numerous requests per second.

### MAP (v) - (TV) — approved
- STE: Map the array to uppercase.
- Non-STE: Transform each element of the array.

### MARK (n), MARK (v) — approved
- STE: Mark the function as deprecated.
- Non-STE: Flag the function as deprecated.

### MATCH (v) — approved
- STE: The pattern must match the input.
- Non-STE: The pattern must correspond to the input.

### MATERIAL (n) — approved
- STE: Refer to the training material.
- Non-STE: Refer to the training resources.

### MAXIMUM (adj), MAXIMUM (n) — approved
- STE: Maximum connections is 100.
- Non-STE: The limit is 100 connections.

### MEASURE (v) — approved
- STE: Measure the response time.
- Non-STE: Calculate the response time.

### MEMORY (n) - (TN) — approved
- STE: The application uses 256 MB of memory.
- Non-STE: The application uses 256 MB of RAM.

### MERGE (v) - (TV) — approved
- STE: Merge the feature branch into main.
- Non-STE: Combine the feature branch into main.

### MESSAGE (n) — approved
- STE: The error message describes the issue.
- Non-STE: The error text describes the issue.

### METHOD (n) - (TN) — approved
- STE: The method takes two parameters.
- Non-STE: The function takes two parameters.

### MINIMUM (adj), MINIMUM (n) — approved
- STE: The minimum password length is 8.
- Non-STE: The password must be at least 8 characters.

### MINUS (prep) — approved
- STE: The value is total minus overhead.
- Non-STE: The value is total less overhead.

### MISSING (adj) — approved
- STE: A missing dependency.
- Non-STE: A dependency that is not installed.

### MIX (v) — approved
- STE: Do not mix concerns in a single module.
- Non-STE: Do not combine concerns in a single module.

### MODE (n) - (TN) — approved
- STE: The debug mode shows more information.
- Non-STE: Debug builds show more information.

### MODEL (n) - (TN) — approved
- STE: The user model has three fields.
- Non-STE: The user schema has three fields.

### modify (v) - UNNAPROVED — unapproved
- Use instead: CHANGE (v). CHANGE THE FILE PERMISSIONS
- STE: Change the file permissions.
- Non-STE: Modify the file permissions.

### MODULE (n) - (TN) — approved
- STE: Each module has its own namespace.
- Non-STE: Each package has its own namespace.

### MONITOR (v) — approved
- STE: Monitor the server logs.
- Non-STE: Watch the server logs.

### MORE (adj), MORE (adv) — approved
- STE: More memory allocation.
- Non-STE: Additional memory allocation.

### MOST (adj), MOST (adv) — approved
- STE: Most errors occur at startup.
- Non-STE: The majority of errors occur at startup.

### MOVE (v) — approved
- STE: Move the file to the archive.
- Non-STE: Transfer the file to the archive.

### MUCH (adj), MUCH (adv) — approved
- STE: Not much memory usage.
- Non-STE: Low memory usage.

### MUST (v) — approved
- STE: You must validate all inputs.
- Non-STE: You have to validate all inputs.

# N

### NAME (n), NAME (v) — approved
- STE: Name the variable `count`.
- Non-STE: Call the variable `count`.

### NEAR (adj), NEAR (prep) — approved
- STE: Near the end of the file.
- Non-STE: Close to the end of the file.

### NECESSARY (adj) — approved
- STE: It is necessary to restart the service.
- Non-STE: You must restart the service.

### need (v) - UNNAPROVED — unapproved
- Use instead: MUST (v), NECESSARY (adj). YOU MUST INSTALL THE DEPENDENCIES
- STE: You must install the dependencies.
- Non-STE: You need to install the dependencies.

### NEVER (adv) — approved
- STE: Never store passwords in plain text.
- Non-STE: Do not store passwords in plain text under any circumstances.

### NEW (adj) — approved
- STE: A new instance of the class.
- Non-STE: A fresh instance of the class.

### NEXT (adj) — approved
- STE: The next iteration.
- Non-STE: The following iteration.

### NO (adj) — approved
- STE: No errors in the output.
- Non-STE: Zero errors in the output.

### NONE (pron) — approved
- STE: None of the tests fail.
- Non-STE: All tests pass.

### normal (adj) - UNNAPROVED — unapproved
- Use instead: USUAL (adj). THE USUAL BEHAVIOR IS TO RETURN ZERO
- STE: The usual behavior is to return zero.
- Non-STE: The normal behavior is to return zero.

### NOT (adv) — approved
- STE: Do not use deprecated functions.
- Non-STE: Avoid using deprecated functions.

### NOTE (n), NOTE (v) — approved
- STE: Add a note in the code.
- Non-STE: Add a comment in the code.

### NULL (adj) - (TN) — approved
- STE: The pointer is null.
- Non-STE: The pointer is empty.

### NUMBER (n) — approved
- STE: The number of records is 100.
- Non-STE: The count of records is 100.

# O

### OBJECT (n) - (TN) — approved
- STE: Create a new object of the User class.
- Non-STE: Instantiate the User class.

### OBEY (v) — approved
- STE: Obey the coding standards.
- Non-STE: Follow the coding standards.

### OCCUR (v) — approved
- STE: An exception occurred at runtime.
- Non-STE: An exception was thrown at runtime.

### OF (prep) — approved
- STE: The name of the function.
- Non-STE: The function's name.

### OFF (adv), OFF (prep) — approved
- STE: Turn off the feature flag.
- Non-STE: Disable the feature flag.

### ON (adv), ON (prep) — approved
- STE: Turn on the debug mode.
- Non-STE: Enable the debug mode.

### ONLY (adv) — approved
- STE: Only the admin can run this command.
- Non-STE: Solely the admin can run this command.

### OPEN (v), OPEN (adj) — approved
- STE: Open the file for reading.
- STE: An open port on the firewall.
- Non-STE: Read the file.
- Non-STE: A listening port on the firewall.

### OPERATE (v) — approved
- STE: Operate the application through the CLI.
- Non-STE: Run the application through the CLI.

### OPERATION (n) — approved
- STE: The operation of the request is asynchronous.
- Non-STE: The request is processed asynchronously.

### option (n) - UNNAPROVED — unapproved
- Use instead: ALTERNATIVE (n), CAN (v). YOU CAN USE AN ALTERNATIVE CONFIGURATION
- STE: You can use an alternative configuration.
- Non-STE: You have the option to use another configuration.

### OR (conj) — approved
- STE: Use Python or Node.js.
- Non-STE: Use Python; alternatively use Node.js.

### ORDER (n) — approved
- STE: Execute the steps in the given order.
- Non-STE: Execute the steps sequentially.

### OTHER (adj) — approved
- STE: The other endpoint returns JSON.
- Non-STE: The alternative endpoint returns JSON.

### OUTPUT (n) - (TN) — approved
- STE: The output of the command is a list.
- Non-STE: The command prints a list.

### over (prep) - UNNAPROVED — unapproved
- Use instead: MORE THAN, ABOVE. MORE THAN THE THRESHOLD
- STE: More than the threshold.
- Non-STE: Over the threshold.

### OVERRIDE (v) - (TV) — approved
- STE: Override the default behavior in the subclass.
- Non-STE: Replace the default behavior in the subclass.

# P

### PACKAGE (n) - (TN) — approved
- STE: Install the package with pip.
- Non-STE: Install the library with pip.

### PAGE (n) — approved
- STE: The landing page of the application.
- Non-STE: The home screen of the application.

### PARAMETER (n) - (TN) — approved
- STE: The function takes two parameters.
- Non-STE: The function accepts two arguments.

### PART (n) — approved
- STE: A part of the documentation.
- Non-STE: A section of the documentation.

### PASS (v) — approved
- STE: The test passes.
- Non-STE: The test succeeds.

### PASTE (v) — approved
- STE: Paste the text into the editor.
- Non-STE: Insert the copied text into the editor.

### PATH (n) - (TN) — approved
- STE: The path to the config file is `/etc/app/`.
- Non-STE: The location of the config file is `/etc/app/`.

### PATTERN (n) - (TN) — approved
- STE: The regex pattern matches the input.
- Non-STE: The regular expression matches the input.

### perform (v) - UNNAPROVED — unapproved
- Use instead: DO (v). DO THE BUILD
- STE: Do the build.
- Non-STE: Perform the build.

### PERFORMANCE (n) — approved
- STE: The performance of the query is good.
- Non-STE: The query runs fast.

### PERMANENT (adj) — approved
- STE: Write the data to permanent storage.
- Non-STE: Write the data to persistent storage.

### permit (v) - UNNAPROVED — unapproved
- Use instead: LET (v), ALLOW (v). THE API LETS YOU SEND
- STE: The API lets you send 100 requests per minute.
- Non-STE: The API permits 100 requests per minute.

### PERSON (n) — approved
- STE: Only one person can access the account.
- Non-STE: Only a single user can access the account.

### PIPE (n) - (TN) — approved
- STE: Use a pipe to connect the commands.
- Non-STE: Use the pipe operator to connect the commands.

### PLACE (n), PLACE (v) — approved
- STE: Place the hook in the lifecycle at the right position.
- Non-STE: Insert the hook into the lifecycle.

### PLUS (prep) — approved
- STE: The total is the base plus the overhead.
- Non-STE: The total is the sum of the base and overhead.

### POINT (n) — approved
- STE: The entry point of the application is `main()`.
- Non-STE: The application starts at `main()`.

### PORT (n) - (TN) — approved
- STE: The application listens on port 8080.
- Non-STE: The application uses port 8080.

### POSITION (n) — approved
- STE: The position of the element in the array is 0.
- Non-STE: The index of the element in the array is 0.

### POSSIBLE (adj) — approved
- STE: A possible solution is to increase the timeout.
- Non-STE: One solution could be to increase the timeout.

### POWER (n) — approved
- STE: The processing power of the server is sufficient.
- Non-STE: The server has enough CPU.

### PREPARE (v) — approved
- STE: Prepare the environment for deployment.
- Non-STE: Set up the environment for deployment.

### PREVENT (v) — approved
- STE: Use parameterized queries to prevent SQL injection.
- Non-STE: Use parameterized queries to avoid SQL injection.

### PREVIOUS (adj) — approved
- STE: The previous version had a bug.
- Non-STE: The prior version had a bug.

### PRIMARY (adj) — approved
- STE: The primary key of the table is the `id` field.
- Non-STE: The main key of the table is the `id` field.

### PROBLEM (n) — approved
- STE: Identify the root cause of the problem.
- Non-STE: Find what caused the issue.

### PROCEDURE (n) — approved
- STE: Do the deployment procedure.
- Non-STE: Follow the deployment procedure.

### process (n), process (v) - UNNAPROVED — unapproved
- Use instead: A running program. THE PROCESS PID IS
- STE: Process the request synchronously.
- Non-STE: Handle the request synchronously.

### provide (v) - UNNAPROVED — unapproved
- Use instead: GIVE (v), RETURN (v). RETURN THE RESULT
- STE: The function returns the result.
- Non-STE: The function provides the result.

### PULL (v) — approved
- STE: Pull the latest changes from the repository.
- Non-STE: Fetch the latest changes from the repository.

### PUSH (v) — approved
- STE: Push the commit to the remote.
- Non-STE: Upload the commit to the remote.

### PUT (v) — approved
- STE: Put the value in the variable.
- Non-STE: Assign the value to the variable.

# Q

### QUALITY (n) — approved
- STE: Code quality is important.
- Non-STE: The standard of the code is important.

### QUANTITY (n) — approved
- STE: A large quantity of data.
- Non-STE: A lot of data.

### QUERY (n) - (TN) — approved
- STE: The query returns 10 rows.
- Non-STE: The SQL statement returns 10 rows.

### QUICK (adj), QUICKLY (adv) — approved
- STE: Process the request quickly.
- Non-STE: Process the request fast.

# R

### RAISE (v) — approved
- STE: Raise an exception when the value is null.
- Non-STE: Throw an exception when the value is null.

### RANGE (n) — approved
- STE: The port range is 8000-8080.
- Non-STE: The ports go from 8000 to 8080.

### READ (v) — approved
- STE: Read the file from disk.
- Non-STE: Load the file from disk.

### READY (adj) — approved
- STE: The build is ready for deployment.
- Non-STE: The build can be deployed.

### RECEIVE (v) — approved
- STE: Receive the HTTP response.
- Non-STE: Get the HTTP response.

### RECOMMEND (v) — approved
- STE: The style guide recommends this format.
- Non-STE: The style guide suggests this format.

### RECORD (v) — approved
- STE: Record the error in the log.
- Non-STE: Log the error.

### reduce (v) - UNNAPROVED — unapproved
- Use instead: DECREASE (v). DECREASE THE MEMORY USAGE
- STE: Decrease the memory usage.
- Non-STE: Reduce the memory usage.

### REFER (v) — approved
- STE: Refer to the API documentation for details.
- Non-STE: See the API documentation for details.

### REFRESH (v) - (TV) — approved
- STE: Refresh the page to see the changes.
- Non-STE: Reload the page to see the changes.

### REJECT (v) — approved
- STE: Reject the commit if tests fail.
- Non-STE: Deny the commit if tests fail.

### RELEASE (v) — approved
- STE: Release the new version to production.
- STE: Release the memory after use.
- Non-STE: Publish the new version to production.
- Non-STE: Free the memory after use.

### REMAINING (adj) — approved
- STE: Fix the remaining warnings.
- Non-STE: Fix the leftover warnings.

### REMOVE (v) — approved
- STE: Remove the deprecated function.
- Non-STE: Delete the deprecated function.

### REPAIR (v) — approved
- STE: Repair the broken build.
- Non-STE: Fix the broken build.

### REPEAT (v) — approved
- STE: Repeat the operation for each item.
- Non-STE: Loop through the items and do the operation.

### REPLACE (v) — approved
- STE: Replace the old library with the new one.
- Non-STE: Swap the old library for the new one.

### REPORT (n), REPORT (v) - (TN/TV) — approved
- STE: Report the bug in the issue tracker.
- Non-STE: Log the bug in the issue tracker.

### REQUEST (n), REQUEST (v) - (TN/TV) — approved
- STE: The HTTP request returns 200 OK.
- Non-STE: The HTTP call returns 200 OK.

### require (v) - UNNAPROVED — unapproved
- Use instead: MUST (v). YOU MUST INSTALL NODE
- STE: You must install Node.js.
- Non-STE: The project requires Node.js.

### RESOURCE (n) - (TN) — approved
- STE: Free the resources after use.
- Non-STE: Release the resources after use.

### RESPONSE (n) - (TN) — approved
- STE: The response contains the user data.
- Non-STE: The reply contains the user data.

### RESTART (v) — approved
- STE: Restart the service.
- Non-STE: Stop and start the service.

### RESULT (n) — approved
- STE: The result of the query is an empty set.
- Non-STE: The query returns no rows.

### RETRY (v) - (TV) — approved
- STE: Retry the request after 5 seconds.
- Non-STE: Try the request again after 5 seconds.

### RETURN (v) — approved
- STE: The function returns the computed value.
- Non-STE: The function gives back the computed value.

### review (n) - UNNAPROVED — unapproved
- Use instead: EXAMINE (v). EXAMINE THE CODE FOR ISSUES
- STE: Examine the code for issues.
- Non-STE: Review the code for issues.

### RIGHT (adj), RIGHT (adv) — approved
- STE: Align the text right.
- Non-STE: Align the text to the right.

### RISK (n) — approved
- STE: The risk of data loss is small.
- Non-STE: There is little chance of data loss.

### ROOT (n) - (TN) — approved
- STE: The config file is in the root of the project.
- STE: Run the command as root.
- Non-STE: The config file is at the top level of the project.
- Non-STE: Run the command with superuser privileges.

### ROUTE (n) - (TN) — approved
- STE: The route `/users` returns the user list.
- Non-STE: The endpoint `/users` returns the user list.

### RULE (n) — approved
- STE: The validation rule checks the email format.
- Non-STE: The validation checks the email format.

### RUN (v) — approved
- STE: Run the script from the terminal.
- Non-STE: Execute the script from the terminal.

# S

### SAFE (adj), SAFETY (n) — approved
- STE: A safe default value prevents crashes.
- STE: For data safety, encrypt the backup.
- Non-STE: A sensible default value prevents crashes.
- Non-STE: For security, encrypt the backup.

### SAME (adj) — approved
- STE: The two functions return the same result.
- Non-STE: The two functions return identical results.

### SAMPLE (n) — approved
- STE: A code sample is in the `examples/` directory.
- Non-STE: An example is in the `examples/` directory.

### SAVE (v) — approved
- STE: Save the file to disk.
- Non-STE: Write the file to disk.

### SCHEDULE (v) — approved
- STE: Schedule the job to run daily.
- Non-STE: Set the job to run daily.

### SEARCH (v) - (TV) — approved
- STE: Search the logs for error messages.
- Non-STE: Look through the logs for error messages.

### SECTION (n) — approved
- STE: Refer to the Security section of the README.
- Non-STE: See the Security part of the README.

### SEE (v) — approved
- STE: See the documentation for details.
- Non-STE: Refer to the documentation for details.

### SELECT (v) — approved
- STE: Select the database from the list.
- Non-STE: Choose the database from the list.

### SEND (v) — approved
- STE: Send the request to the server.
- Non-STE: Make the request to the server.

### separate (adj) - UNNAPROVED — unapproved
- Use instead: ISOLATED (adj), DIFFERENT (adj), NOT CONNECTED. KEEP THE MODULES ISOLATED
- STE: Keep the modules isolated from each other.
- Non-STE: Keep the modules separate from each other.

### SEQUENCE (n) — approved
- STE: Execute the steps in the given sequence.
- Non-STE: Execute the steps in order.

### SERVER (n) - (TN) — approved
- STE: The server listens on port 443.
- Non-STE: The service listens on port 443.

### SERVICE (n) - (TN) — approved
- STE: The authentication service is down.
- Non-STE: The auth service is not running.

### SET (n), SET (v) — approved
- STE: Set the variable to 10.
- Non-STE: Assign 10 to the variable.

### SHORT (adj) — approved
- STE: A short timeout of 1 second.
- Non-STE: A brief timeout of 1 second.

### SHOW (v) — approved
- STE: The command shows the file contents.
- Non-STE: The command displays the file contents.

### SHUT down (v) - UNNAPROVED — unapproved
- Use instead: STOP (v). STOP THE SERVER
- STE: Stop the server.
- Non-STE: Shut down the server.

### SIGNAL (n) - (TN) — approved
- STE: Send a SIGTERM signal to the process.
- Non-STE: Terminate the process.

### SIMPLE (adj) — approved
- STE: A simple function with one responsibility.
- Non-STE: A straightforward function with one responsibility.

### SINGLE (adj) — approved
- STE: A single instance of the application.
- Non-STE: One instance of the application.

### SIZE (n) — approved
- STE: The size of the file is 2 MB.
- Non-STE: The file is 2 MB.

### SLOW (adj), SLOWLY (adv) — approved
- STE: Slowly increase the timeout value.
- Non-STE: Gradually increase the timeout value.

### SMALL (adj) — approved
- STE: A small amount of memory is allocated.
- Non-STE: A negligible amount of memory is allocated.

### SOCKET (n) - (TN) — approved
- STE: Open a socket on port 3000.
- Non-STE: Create a connection on port 3000.

### SOLUTION (n) — approved
- STE: The solution to the memory leak is to use weak references.
- Non-STE: Fix the memory leak by using weak references.

### SOME (adj), SOME (pron) — approved
- STE: Some tests fail under load.
- Non-STE: A few tests fail under load.

### SOURCE (n) — approved
- STE: Find the source of the bug.
- Non-STE: Locate where the bug originates.

### SPACE (n) — approved
- STE: Make sure that there is sufficient disk space.
- Non-STE: Check that there is enough disk space.

### SPECIAL (adj), SPECIALLY (adv) — approved
- STE: Use the special config for staging.
- Non-STE: Use the staging-specific config.

### SPECIFIED (adj) — approved
- STE: Use the specified port number from the config.
- Non-STE: Use the port number that is given in the config.

### SPEED (n) — approved
- STE: The speed of the query is fast.
- Non-STE: The query is fast.

### STACK (n) - (TN) — approved
- STE: Push the value onto the stack.
- Non-STE: Add the value to the stack.

### stage (n) - UNNAPROVED — unapproved
- Use instead: STEP (n). DURING THIS STEP, DO NOT MERGE THE BRANCH
- STE: During this step, do not merge the branch.
- Non-STE: At this stage, do not merge the branch.

### STANDARD (adj) — approved
- STE: Follow the standard coding conventions.
- Non-STE: Follow the usual coding conventions.

### START (n), START (v) — approved
- STE: Start the application.
- Non-STE: Launch the application.

### state (n) - UNNAPROVED — unapproved
- Use instead: CONDITION (n). EXAMINE THE CONDITION OF THE SYSTEM
- STE: Examine the condition of the system.
- Non-STE: Examine the state of the system.

### STATUS (n) - (TN) — approved
- STE: The status of the service is "healthy."
- Non-STE: The service is healthy.

### STAY (v) — approved
- STE: Make sure that the connection stays open.
- Non-STE: Keep the connection open.

### STEP (n) — approved
- STE: Do steps 1 through 5 in the given order.
- Non-STE: Follow the procedure steps 1-5.

### STOP (v) — approved
- STE: Stop the process.
- STE: When the errors stop, check the logs.
- Non-STE: Kill the process.
- Non-STE: When the errors cease, check the logs.

### store (v) - UNNAPROVED — unapproved
- Use instead: KEEP (v), SAVE (v). KEEP THE CONFIG FILES IN VERSION CONTROL
- STE: Keep the config files in version control.
- Non-STE: Store the config files in version control.

### STREAM (n) - (TN) — approved
- STE: Process the data as a stream.
- Non-STE: Process the data in chunks.

### STRING (n) - (TN) — approved
- STE: The response returns a JSON string.
- Non-STE: The response returns JSON text.

### STRONG (adj) — approved
- STE: Use a strong password.
- Non-STE: Use a secure password.

### STRUCTURE (n) — approved
- STE: The structure of the project follows MVC.
- Non-STE: The project layout follows MVC.

### SUFFICIENT (adj), SUFFICIENTLY (adv) — approved
- STE: Make sure that there is sufficient disk space.
- Non-STE: Make sure that there is enough disk space.

### SUDDEN (adj), SUDDENLY (adv) — approved
- STE: If the service fails suddenly, read the logs.
- Non-STE: If the service fails unexpectedly, read the logs.

### SUPPLY (n), SUPPLY (v) — approved
- STE: Supply the API key as a query parameter.
- Non-STE: Provide the API key as a query parameter.

### SURFACE (n) — approved
- STE: The API surface of the library is small.
- Non-STE: The public interface of the library is small.

### SYSTEM (n) — approved
- STE: The authentication system uses JWT.
- Non-STE: The authentication module uses JWT.

# T

### TABLE (n) — approved
- STE: The `users` table has four columns.
- Non-STE: The `users` database table has four columns.

### TAG (n) - (TN) — approved
- STE: Add a version tag to the commit.
- Non-STE: Mark the commit with a version number.

### take (v) - UNNAPROVED — unapproved
- Use instead: Use more accurate verbs: FETCH (v), CONSUME (v), REQUIRE (v).
- STE: The query consumes 100 ms.
- Non-STE: The query takes 100 ms.

### TASK (n) — approved
- STE: The asynchronous task runs in the background.
- Non-STE: The background job runs asynchronously.

### TELL (v) — approved
- STE: The log file tells you the error location.
- Non-STE: The log file shows you the error location.

### TEMPORARY (adj) — approved
- STE: Create a temporary file for the intermediate data.
- Non-STE: Create a temp file for the intermediate data.

### TERMINATE (v) - (TV) — approved
- STE: Terminate the hung process.
- Non-STE: Kill the hung process.

### TEST (n) — approved
- STE: Run the unit tests before you merge.
- Non-STE: Execute the test suite before merging.

### test (v) - UNNAPROVED — unapproved
- Use instead: TEST (n) with DO. DO A TEST OF THE MODULE
- STE: Do a test of the module.
- Non-STE: Test the module.

### TEXT (n) - (TN) — approved
- STE: The response body contains plain text.
- Non-STE: The response body is a string.

### THAN (conj) — approved
- STE: The new version is faster than the previous version.
- Non-STE: The new version outperforms the previous version.

### THAT (conj), THAT (pron) — approved
- STE: Make sure that the tests pass.
- Non-STE: Ensure the tests pass.

### THE (art) — approved
- STE: The function returns a value.
- Non-STE: Function returns a value.

### THEN (adv) — approved
- STE: Compile the code. Then, run the tests.
- Non-STE: Compile the code and subsequently run the tests.

### THICK (adj) — approved

### THREAD (n) - (TN) — approved
- STE: Run the task in a separate thread.
- Non-STE: Run the task in parallel.

### THROUGH (prep) — approved
- STE: Route the request through the proxy.
- Non-STE: Pass the request via the proxy.

### THROW (v) - (TV) — approved
- STE: The function throws an error on invalid input.
- Non-STE: The function raises an error on invalid input.

### THUS (adv) — approved
- STE: The token expires. Thus, the request fails.
- Non-STE: The token expires; therefore, the request fails.

### TIME (n) — approved
- STE: The response time is 200 ms.
- Non-STE: The latency is 200 ms.

### TIMEOUT (n) - (TN) — approved
- STE: Set the timeout to 30 seconds.
- Non-STE: Configure a 30-second time limit.

### TO (prep) — approved
- STE: Navigate to the settings page.
- Non-STE: Go to the settings page.

### TOKEN (n) - (TN) — approved
- STE: Pass the token in the Authorization header.
- Non-STE: Include the token in the request.

### TOO (adv) — approved
- STE: Too many open connections.
- Non-STE: Excessively many open connections.

### TOP (adj), TOP (n) — approved
- STE: The top of the file contains the imports.
- Non-STE: The beginning of the file contains the imports.

### TOUCH (v) — approved
- STE: Touch the file to update its modification date.
- Non-STE: Update the file timestamp.

### TRACK (v) - (TV) — approved
- STE: Track the changes with git.
- Non-STE: Monitor the changes with git.

### TRAIN (v) - (TV) — approved
- STE: Train the model on the training set.
- Non-STE: Fit the model to the training data.

### TRANSFER (v) — approved
- STE: Transfer the file via SCP.
- Non-STE: Copy the file via SCP.

### TRIGGER (v) - (TV) — approved
- STE: The event triggers the callback.
- Non-STE: The event fires the callback.

### true (adj) - UNNAPROVED — unapproved
- Use instead: A Boolean value. THE CONDITION IS TRUE
- STE: The condition is true.
- Non-STE: The condition evaluates to truth.

### TRY (v) — approved
- STE: Try the request again.
- Non-STE: Retry the request.

### TURN (v) — approved
- STE: Turn on the feature flag.
- Non-STE: Enable the feature flag.

### TYPE (n) - (TN) — approved
- STE: The type of the variable is string.
- Non-STE: The variable is a string.

# U

### under (prep) - UNNAPROVED — unapproved
- Use instead: BELOW (prep), LESS THAN. BELOW THE THRESHOLD
- STE: Below the threshold.
- Non-STE: Under the threshold.

### UNLOCK (v) — approved
- STE: Unlock the mutex.
- Non-STE: Release the mutex.

### UNSTABLE (adj) - (TN) — approved
- STE: The connection is unstable.
- Non-STE: The connection is flaky.

### UNTIL (prep) — approved
- STE: Retry the request until it succeeds.
- Non-STE: Keep retrying the request while it fails.

### UNUSUAL (adj) — approved
- STE: Watch for unusual log entries.
- Non-STE: Watch for unexpected log entries.

### UP (adv), UP (prep) — approved
- STE: Bring the service up.
- Non-STE: Start the service.

### UPDATE (v) - (TV) — approved
- STE: Update the package to the latest version.
- Non-STE: Upgrade the package to the latest version.

### USE (v) — approved
- STE: Use the API to fetch data.
- Non-STE: Utilize the API to fetch data.

### USUAL (adj), USUALLY (adv) — approved
- STE: Usually, the request returns 200 OK.
- Non-STE: Typically, the request returns 200 OK.

# V

### valid (adj) - UNNAPROVED — unapproved
- Use instead: CORRECT (adj). MAKE SURE THAT THE INPUT IS CORRECT
- STE: Make sure that the input is correct.
- Non-STE: Make sure that the input is valid.

### VALIDATE (v) - (TV) — approved
- STE: Validate the user input before processing.
- Non-STE: Check the user input before processing.

### VALUE (n) — approved
- STE: The value of the environment variable is "production".
- Non-STE: The environment variable is set to "production".

### VARIABLE (n) - (TN) — approved
- STE: Declare the variable before use.
- Non-STE: Define the variable before use.

### verify (v) - UNNAPROVED — unapproved
- Use instead: MAKE SURE (v). MAKE SURE THAT THE SIGNATURE IS CORRECT
- STE: Make sure that the signature is correct.
- Non-STE: Verify the signature.

### VERSION (n) - (TN) — approved
- STE: The current version is 3.2.1.
- Non-STE: The release is 3.2.1.

### VERY (adv) — approved
- STE: Increase the value very slowly.
- Non-STE: Increment the value in tiny steps.

### via (prep) - UNNAPROVED — unapproved
- Use instead: THROUGH (prep), BY (prep). AUTHENTICATE THROUGH OAUTH
- STE: Authenticate through OAuth.
- Non-STE: Authenticate via OAuth.

### VIEW (n), VIEW (v) - (TN) — approved
- STE: The log view shows recent entries.
- Non-STE: The log display shows recent entries.

### visible (adj) - UNNAPROVED — unapproved
- Use instead: SEE (v). MAKE SURE THAT YOU CAN SEE THE OUTPUT IN THE TERMINAL
- STE: Make sure that you can see the output in the terminal.
- Non-STE: Make sure that the output is visible in the terminal.

### VISUAL (adj) — approved
- STE: Do a visual inspection of the UI.
- Non-STE: Visually inspect the UI.

### VOLUME (n) — approved
- STE: Mount the volume to the container.
- Non-STE: Attach the storage to the container.

# W

### WAIT (v) — approved
- STE: Wait for the asynchronous task to complete.
- Non-STE: Block until the async task finishes.

### WANT (v) — approved
- STE: Install the package that you want.
- Non-STE: Install the desired package.

### WARNING (n) - (TN) — approved
- STE: The compiler shows a warning for the deprecated function.
- Non-STE: The compiler warns about the deprecated function.

### watch (v) - UNNAPROVED — unapproved
- Use instead: MONITOR (v). MONITOR THE LOG OUTPUT
- STE: Monitor the log output for errors.
- Non-STE: Watch the log output for errors.

### WE (pron) — approved
- STE: We recommend using the latest API.
- Non-STE: The team recommends using the latest API.

### WEAK (adj) — approved
- STE: A weak reference does not prevent garbage collection.
- Non-STE: A soft reference does not prevent garbage collection.

### WEIGHT (n) — approved
- STE: The weight of the config value is 0.5.
- Non-STE: The priority of the config value is 0.5.

### WHEN (conj) — approved
- STE: When the build finishes, deploy the artifact.
- Non-STE: After the build finishes, deploy the artifact.

### WHERE (conj) — approved
- STE: Find the line where the error occurred.
- Non-STE: Find the line at which the error occurred.

### WHILE (conj) — approved
- STE: Log the progress while the script runs.
- Non-STE: Log the progress as the script executes.

### whole (adj) - UNNAPROVED — unapproved
- Use instead: ENTIRE (adj). EXAMINE ALL OF THE CODEBASE
- STE: Examine all of the codebase.
- Non-STE: Examine the whole codebase.

### WIDE (adj) — approved
- STE: Wide test coverage.
- Non-STE: Broad test coverage.

### WILL (v) — approved
- STE: The docs will help you to set up the project.
- Non-STE: The docs are going to help you set up the project.

### WITH (prep) — approved
- STE: Compare the result with the expected value.
- Non-STE: Compare the result against the expected value.

### WITHOUT (prep) — approved
- STE: Run the build without caching.
- Non-STE: Run the build with caching disabled.

### WORK (n) — approved
- STE: Do the work in a dedicated branch.
- Non-STE: Do the task in a dedicated branch.

### WORKER (n) - (TN) — approved
- STE: The worker processes jobs from the queue.
- Non-STE: The background job processor handles the queue.

### WRITE (v) — approved
- STE: Write the result to a file.
- Non-STE: Save the result to a file.

### wrong (adj) - UNNAPROVED — unapproved
- Use instead: INCORRECT (adj). MARK THE VARIABLE TO PREVENT INCORRECT USAGE
- STE: Mark the variable as private to prevent incorrect usage.
- Non-STE: Mark the variable as private to prevent wrong usage.

# Y

### YES (adv) — approved
- STE: Does the test pass? Yes or no?
- Non-STE: Is the test passing? Affirmative or negative?

### yet (conj) - UNNAPROVED — unapproved
- Use instead: BUT (conj). COMPILE THE PROJECT, BUT SKIP THE TESTS
- STE: Compile the project, but skip the tests.
- Non-STE: Compile the project, yet skip the tests.

### yet (adv) - UNNAPROVED — unapproved
- Use instead: AT THIS TIME. DO NOT DEPLOY THE FEATURE AT THIS TIME
- STE: Do not deploy the feature at this time.
- Non-STE: Do not deploy the feature yet.

### YOU (pron) — approved
- STE: You can run the script from the command line.
- Non-STE: The user can run the script from the command line.

### YOUR (adj) — approved
- STE: If you get an error in your terminal, read the logs.
- Non-STE: If an error appears in the terminal, read the logs.

# Z

### ZERO (n) - (TN) — approved
- STE: Initialize the counter to zero.
- Non-STE: Set the counter to 0.

### List of Recurring Errors - Code-Documentation Domain — approved

### Summary Statistics — approved

---

## Reference & scope notes


> **Note:** The source file `ste-code/merged/master.md` (extracted from ASD-STE100 Issue 9, pages 149-434) contains only the Dictionary A-Z entries. The official ASD-STE100 also includes:
> - **Change History** - tracked via the Highlights section (pages 3-28 of the spec)
> - **Change Form** - a template for submitting proposed changes to the standard
> - **Subject-to-Rule Index** - cross-references subjects to governing rules
> - **List of Approved Verbs** - quick-reference table of ~200 approved verbs (included in Dictionary intro, pages 147-148 of master.md)
> - **List of Recurring Errors** - common mistakes writers make (included in Dictionary intro, pages 145-146 of master.md)
>
> These sections were not available in the enriched files used to create `master.md`. The adaptation above covers all Dictionary A-Z entries present in the extraction.

---

## List of Recurring Errors - Code-Documentation Domain

> Adapted from master.md pages 145-146

| Non-STE | STE-Code Alternative |
|---------|---------------------|
| acceptable (adj) | PERMITTED (adj) |
| alternate (adj) | ALTERNATIVE (adj) |
| avoid (v) | PREVENT (v) |
| check (v) | VERIFY (v) or CHECK (n) with DO |
| complete (adj) | COMPLETED (adj) |
| damage (v) | DAMAGE (n) with CAUSE |
| ensure (v) | MAKE SURE (v) |
| fit (v) | INSTALL (v) |
| follow (v) | OBEY (v) |
| further (adj) | MORE (adj) |
| have to (v) | MUST (v) |
| however (adv) | BUT (conj) |
| insert (v) | PUT (v) |
| main (adj) | PRIMARY (adj) |
| may (v) | CAN (v) |
| need (v) | NECESSARY (adj) / MUST (v) |
| perform (v) | DO (v) |
| portion (n) | PART (n) |
| press (v) | PUSH (v) |
| repeat (v) | DO ... AGAIN |
| require (v) | NECESSARY (adj) / MUST (v) |
| shall (v) | MUST (v) |
| should (v) | MUST (v) |
| since (conj) | BECAUSE (conj) |
| test (v) | TEST (n) with DO |
| therefore (adv) | THUS (adv) |
| under (prep) | BELOW (prep) / IN (prep) |
| using (v) | USE (v) / WITH (prep) |

---

## Summary Statistics

- **Approved words adapted:** ~875 (all UPPERCASE entries from original)
- **Unapproved words adapted:** ~1274 (all lowercase entries with approved alternatives)
- **Code-domain technical nouns added (TN):** ~60 (for terms not present in original aerospace STE)
- **Code-domain technical verbs added (TV):** ~40 (for software-specific operations)
- **Total entries in this adaptation:** ~2000+
- **Source:** ste-code/merged/master.md lines 5591-10976
- **Original specification:** ASD-STE100 Issue 9, January 2025, Part 2 - Dictionary, Pages 149-434

---

*End of STE-Code Adapted Dictionary A-Z*

---

<!-- 04-templates.md -->

# Level 5 — Document Templates (code review / PR feedback)

Level 5 is the full STE-Code standard: every rule, the extension vocabulary, the
reference catalogue, and provenance. This sub-document is the **document
templates** slice — reusable, code-domain skeletons you can drop into an LLM
prompt when it generates or reviews code documentation: README pages, API
reference entries, docstrings, inline comments, commit messages, error messages,
configuration comments, and pull-request descriptions.

The templates below are distilled from the standard's rules on consistency
(Rule 9.4), safety instructions (Rule 7.2), sentence construction (Rule 9.1),
and the word / grammar rules that govern each genre. They are faithful to the
standard and use code-domain examples only. Use them as fill-in-the-blank
scaffolds; do not invent rules that are not in the standard.

## The three consistency templates (Rule 9.4)

Every genre below obeys the same three consistency rules. Pick one term, one
verb, and one sentence structure per action, and reuse it every time that
action appears.

- **Lexical consistency** — one term per concept. Do not alternate between
  "configuration file," "settings file," and "config" for the same file.
- **Syntactic consistency** — same structure for the same action. All setup
  steps, all configuration steps, and all verification steps share one template.
  The template signals the step type before the reader parses the content.
- **Semantic consistency** — same meaning for the same term across files,
  modules, and documentation types. If "build" means "compile and link" in the
  README, it must not mean "compile, link, and package" in the CI docs.

A reviewer comment that flags a synonym swap is a valid STE-Code finding.

---

## Template 1 — README / procedural doc page (Rules 5.3, 5.4, 8.1, 9.4)

Use imperative sentences for each step. Put a descriptive statement before the
command only when the reader needs context first (Rule 5.4). One sentence per
step. No semicolons (Rule 8.1).

```
## <Section title>

<Optional one-sentence context: why this step exists.>

1. <Imperative verb> <object> to <purpose clause>.
2. <Imperative verb> <object> to <purpose clause>.
3. <Imperative verb> <object>.
```

Worked example (STE):

```
## Configure the server

1. Open the configuration file in a text editor.
2. Change the port number in the configuration file.
3. Save the configuration file and close it.
4. Build the project with the build command.
```

Non-STE (three names for one file, three verbs for one action): "Open the
configuration file… Change the port in the settings file… Save the config…
Compile the project… Make the binary…" — each synonym forces the reader to
pause and ask "is this the same thing?"

## Template 2 — API reference entry (Rules 1.3, 9.1, 9.4)

Name each parameter exactly as it appears in the signature. Use the approved
word for the field's meaning (e.g. "permitted," not "acceptable"). Keep the
description to one short sentence.

```
### `VERB /path` — <Short resource name>

<One sentence: what the endpoint does.>

| Parameter   | Type    | Description                              |
|-------------|---------|------------------------------------------|
| `<name>`    | `<type>`| <One short sentence using the exact name.>|

**Responses**
- `200` — <one sentence>
- `4xx` — <one sentence>
```

Worked example (STE): the parameter `timeout_ms` is described as "A timeout
value of 5000 ms is permitted for this endpoint." (approved word "permitted").
The same field must be called `timeout_ms` in prose, schema, and code — never
"creation date" / "timestamp" / "created time" for one response field.

---

## Template 3 — Function docstring (Rules 1.9, 9.4)

The docstring uses the same term that appears in the signature. A parameter
named `max_retries` is "max_retries" in the body, never "maximum attempts" or
"retry limit." Use the shortest unambiguous term (Rule 1.9).

```
def <name>(<params>) -> <type>:
    """<One sentence: what the function does.>

    Args:
        <param>: <one short sentence, same name as signature>
    Returns:
        <one short sentence>
    """
```

Worked example (STE):

```python
def validate_email_address(value: str) -> bool:
    """Validate an email address against RFC 5322.

    Args:
        value: The string to validate.
    Returns:
        True if the string is a valid address.
    """
```

Do not write the 36-word paraphrase of the regex pattern — the signature and
the standard name the concept.

## Template 4 — Inline comment (Rules 1.9, 8.1, 9.4)

One short sentence. The code or the key name carries the context; the comment
only names the purpose in the shortest form. No semicolons.

```
# <Short phrase: the purpose of the next block>
```

Worked examples (STE):
- Config: `# Maximum number of parallel workers.` (the key `max_workers` and
  value `8` already state the rest — do not copy a 9-word phrase as the comment).
- Test: `# Checks that the fetch utility returns JSON from the API endpoint.`
  (the function name and `assert` line name the subject and expectation).

---

## Template 5 — Commit message (Rules 5.3, 7.1, 7.2, 9.4)

Imperative, one verb per category, consistent across the project. If the
convention is `Add`, do not mix in `Introduce`, `Insert`, or `Create`. If the
convention is `Fix`, do not mix in `Resolve`, `Correct`, or `Patch`.

```
<Type>: <Imperative summary in one sentence, <= 72 chars>

<Optional body: one sentence per point. For safety, start with the
command or condition (Rule 7.2).>
```

Worked examples (STE):
- `Add the configuration parser for the YAML settings file.`
- `Fix the connection leak in the worker pool.`
- Safety body: `WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. ALWAYS USE
  ENVIRONMENT VARIABLES OR A SECRETS MANAGER TO STORE API KEYS. API KEYS IN
  SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.`

If a commit needs many unapproved words, write a shorter message and put the
details in the pull-request description.

---

## Template 6 — Error message (Rules 7.1, 7.2, 9.4)

An error code must produce the same text every time (reliability property, Rule
9.4). Start with a signal word when the message carries risk. The reader
correlates the message with the code by the exact code name.

```
<Optional signal word: WARNING | CAUTION> <Clear command or condition, one sentence.>
```

Worked examples (STE):
- `E_CONNECT_FAIL: Cannot connect to the database. Check the connection string.`
- `WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE.`

Do not let `E_CONNECT_FAIL` say "connection refused" in module A and "cannot
connect to server" in module B — the operator cannot search logs reliably.

## Template 7 — Configuration-file comment (Rules 1.9, 8.1, 9.4)

The key and value state the setting; the comment names only the purpose. One
sentence per option. No semicolons (split purpose and trade-off into two
sentences).

```
# <Purpose of this option, one short phrase.>
<key> = <value>
# <Optional trade-off, one sentence.>
```

Worked example (STE):

```
# Maximum number of parallel workers.
max_workers = 8
# A higher value uses more memory.
```

---

## Template 8 — Pull-request / review description (Rules 5.3, 5.4, 8.1, 9.4)

Write instructions as imperative sentences. Give context before a command only
when the reviewer needs it. One sentence per point; use numbered steps for
multi-step workflows so the reviewer can complete one before reading the next.

```
## Summary
<One or two sentences: what this change does.>

## Changes
1. <Imperative verb> <object>.
2. <Imperative verb> <object>.
3. <Imperative verb> <object>.

## Test plan
1. <Imperative verb> <object> to <purpose>.
2. <Imperative verb> <object>.

## Notes
<Optional context sentence before the action, if the reviewer needs it.>
```

Worked example (STE):

```
## Summary
Add the linter to the pre-commit hook.

## Changes
1. Create a new feature branch from the `main` branch.
2. Make your code changes on the feature branch.
3. Commit your changes with a descriptive message.
4. Push the branch to the remote repository.
5. Open a pull request against `main`.

## Test plan
1. Run the linter before you submit the pull request.
2. Squash your commits into a single change.
```

Non-STE (one 40-word sentence joined by "and"): "Create a new feature branch
from the main branch and make your code changes on that branch and then commit
your changes with a descriptive message and push the branch to the remote
repository and open a pull request against the main branch." — the reader
cannot complete one step before reading the next.

---

## Template 9 — Object-oriented inheritance docstring (Rule 9.4)

When you document a class hierarchy, use the same phrasing for overridden
methods. The base-class docstring sets the template; each subclass reuses it and
adds only the subclass-specific behavior.

```
class <Base>:
    """<Template sentence for the method.>"""

class <Sub>(<Base>):
    """<Same template sentence.> <Subclass-specific behavior.>"""
```

Worked example (STE):

```python
class Connection:
    """Establish a connection to the remote host."""

class TlsConnection(Connection):
    """Establish a connection to the remote host. Use TLS for transport."""
```

Non-STE: base says "Connects to server," subclass says "Opens a socket to the
backend," grandchild says "Initiates TCP handshake with data node" — three
templates for one operation.

---

## Sentence-construction fallback (Rule 9.1)

When a word is not approved and a word-for-word swap is not enough, restructure
the sentence — do not keep the unapproved word. Common approved swaps:

| Do not write        | Write             | Why |
|---------------------|-------------------|-----|
| execute the script  | run the script    | "run" is the approved verb |
| generate the artifact | make the artifact | "make" is approved |
| utilize / leverage  | use               | inflated verb |
| bootstrap / initiate | start            | "start" is approved |
| retrieve / fetch    | get               | "get" is approved |
| transmit            | send              | "send" is approved |
| validate / verify   | check             | "check" is approved |
| unable to           | cannot            | "cannot" is approved |
| acceptable          | permitted         | approved adjective |
| visible             | you can see       | verb replaces adjective |

If the part of speech differs or the meaning would change, write a new sentence
with a different structure that keeps the same technical meaning.

## Reviewer checklist (apply to any genre above)

1. One term per concept (lexical consistency).
2. One verb per action, reused everywhere (lexical + syntactic consistency).
3. Same sentence structure for the same step type (syntactic consistency).
4. Same meaning for the same term across files (semantic consistency).
5. One sentence per step; no semicolons (Rule 8.1).
6. Signature name == docstring name == prose name (Rule 9.4).
7. Safety / error text starts with a command or condition and is identical
   wherever the same code appears (Rules 7.2, 9.4).
8. Only approved words, code-domain technical nouns, or code-domain technical
   verbs (Section 1 gates).

---

<!-- 05-grammar.md -->

# Level 5 — Grammar (Rules 2.1–2.3, 3.1–3.7)

Level 5 is the full STE-Code standard. This sub-document is the **grammar** slice:
the rules that govern how words combine into technical nouns (Section 2) and into
sentences (Section 3). These rules are the structural backbone that the vocabulary
rules in Section 1 and the clarity rules in Sections 4–9 assume already hold.

Use this file when you generate, review, or lint code documentation with an LLM and
need to enforce sentence shape — short technical nouns, approved verb forms, active
voice, and no auxiliary-verb constructions.

## What "grammar" covers here

- **Section 2 — Technical nouns:** keep multi-word nouns short (Rule 2.1), write long
  technical nouns in full then shorten them (Rule 2.2), hyphenate related words as one
  unit (Rule 2.3).
- **Section 3 — Sentence structure:** use only the approved verb forms (Rule 3.1),
  only the approved tenses (Rule 3.2), use the past participle as an adjective (Rule 3.3),
  do not build auxiliary-verb constructions (Rule 3.4), use "-ing" forms only as technical
  nouns/modifiers (Rule 3.5), use the active voice (Rule 3.6), and prefer a verb over a
  noun when an approved verb exists (Rule 3.7).

The three-word limit for a noun phrase (Rule 2.1) interacts with hyphenation: a hyphenated
unit counts as one word, so `main-feature-flag` + `rollback-handler` + `trigger` is three
words, not five.

---

## Rule 2.1 — Keep technical nouns short

To keep multi-word technical nouns short, use prepositions (for example "of," "on," "in,"
and "for") and explain the multi-word technical nouns. A technical noun that the code domain
uses — a module name, class name, configuration key, endpoint path, error type, or test
fixture — must stay short so the reader can parse it without effort.

When a phrase names a code component with more than a few words, break the phrase into small
nouns that connect with prepositions. Do not write one long noun that stacks modifiers.

Why this matters:

- A stacked noun such as `authentication_token_expiration_refresh_interval_setting` hides
  which part owns which. A short noun with prepositions shows the tree: the setting belongs
  to the interval, the interval to the expiration, the expiration to the token.
- Short technical nouns match how code is already structured. A config key, class, or JSON
  field is one short concept; prepositions in the sentence show how those concepts relate.
- Follow the Microsoft and Google style guides: use short, plain words. Do not use `utilize`,
  `leverage`, or `employ` when `use` is enough; do not use `commence`, `initiate`, or
  `terminate` when `start` and `stop` are enough.
- Approved code-domain adjectives stay attached to the short noun they modify: `idempotent`,
  `immutable`, `thread-safe`, `atomic`, `nullable`, `deprecated`, `stateless`,
  `backward-compatible`, `asynchronous`, `concurrent`, `deterministic`. Write
  `the idempotent retry policy`, not `idempotentretrypolicy`.

How to apply:

1. Find a noun that stacks two or more modifiers (a "noun chain").
2. Split the chain at the ownership or containment points.
3. Connect the parts with `of`, `on`, `in`, or `for`.
4. If a part is itself a code component, name it with its short technical noun (its class,
   key, or file), not a merged word.
5. In instruction text, use the approved verbs: `set`, `get`, `make`, `show`, `check`,
   `remove`, `send`, `start`, `stop`, `use`, `update`. Do not use `configure` for `set`,
   `retrieve` for `get`, `delete`/`purge` for `remove`, or `display` for `show`.

Worked pairs:

| Do not write | Write |
|---|---|
| Authentication token expiration refresh interval setting | Setting of the refresh interval of the expiration of the authentication token |
| Install the forward service request validator middleware config tags. | Install the config tags on the validator middleware of the request of the forward service. |
| Remove the database migration script output directory lock files. | Remove the lock files that lock the output directory of the migration script of the database. |
| Payment gateway timeout retry exhaustion notification handler | Handler of the notification of the exhaustion of the retry of the timeout of the payment gateway |

See also: Rule 1.5 (what counts as a technical noun), Rule 1.3 (keep verbs and nouns plain),
Rule 2.2 (when a noun must stay long), Rule 2.3 (hyphenate related pairs).

---

## Rule 2.2 — Write long technical nouns in full

When a technical code noun has more than three words, write it in full. Then use one of
these methods to make the technical code noun clear:

- Give a shorter form of the technical code noun.
- Use hyphens (-) between words that you use as one unit.
- Use prepositions (for example "of," "on," "in," "for," and "to") to split a long noun into
  short, separate parts (see Rule 2.1).

A long multi-word code noun can be a long technical noun, or a combination of shorter
technical nouns. Frequently it is not possible to divide technical code nouns into smaller
parts because they are the technical nouns your company, framework, or subject field uses.
Thus, write technical code nouns in their approved form.

**Method 1 — Shorter form.** If a long technical code noun comes from an official code
document (an API specification, a schema, an OpenAPI file, an architecture diagram), write it
in full the first time it occurs. Then, if possible, explain the noun and use a shorter form
or approved abbreviation in the rest of the document.

> Initialize the user session cache invalidation lock handler (the handler that locks the
> cache of the user session; in this procedure, we call it the "invalidation lock handler").
> Run the invalidation lock handler before the shutdown hook releases the cache.

> The Main Form Validation Module (MFVM) is a TypeScript module that includes a Main Export
> Controller Unit (MECU) and a Data Bridge (DB). The Dynamic Config Unit (DECU) sends events
> to operate the MFVM.

If an approved technical code noun has three words or fewer, you do not need an abbreviation.

**Method 2 — Prepositions.** When a long technical code noun is a chain of short nouns (for
example "user authentication token refresh failure retry policy"), put the key noun first,
then attach the modifiers with "of," "on," "in," "for," or "to."

| Do not write | Write |
|---|---|
| Configure the user authentication token refresh failure retry policy before you deploy. | Configure the retry policy for the failure of the refresh of the user authentication token before you deploy. |
| Install the background worker queue overflow alert suppression rule on the staging cluster. | Install the alert suppression rule on the overflow of the background worker queue on the staging cluster. |
| Remove the database connection pool exhaustion recovery timeout configuration parameter. | Remove the configuration parameter that sets the recovery timeout for the exhaustion of the database connection pool. |

**Method 3 — Hyphenate.** When two or more words act as a single modifier before a noun, use
a hyphen to show they are one unit. Do not hyphenate when the first word is an "-ly" adverb
(for example "a publicly documented API" stays open).

| Do not write | Write |
|---|---|
| Set the request response mapping handler to the new schema. | Set the request-response mapping handler to the new schema. |
| Run the build time configuration check after you compile. | Run the build-time configuration check after you compile. |
| Add an end to end test for the payment flow. | Add an end-to-end test for the payment flow. |
| Use the out of band signal to stop the long running job. | Use the out-of-band signal to stop the long-running job. |

Note: hyphenation groups words into one unit but does not make a long technical noun short.
If the hyphenated unit still has more than three words (for example "request-response mapping
handler"), write it in full the first time, then use the shorter form ("mapping handler").

How to apply in code documentation:

1. Find the long technical code noun (more than three words).
2. Write it in full the first time it occurs; keep the exact approved form from the source.
3. Give a shorter form or approved abbreviation in parentheses right after.
4. In the rest of the document, use only the shorter form or abbreviation.
5. If the noun is a chain of short nouns, split it with prepositions (Rule 2.1).
6. If two or more words act as one modifier, hyphenate them.
7. Do not fill a procedure with abbreviations; a short clear noun beats a string of letters.

See also: Rule 2.1 (three-word limit), Rule 1.5 (technical noun categories), Rule 1.3
(use, set, get, make, show, check, remove, send, start, stop).

---

## Rule 2.3 — Use hyphens between words used as one unit

A hyphen is a punctuation mark that connects words or parts of words. Use hyphens between
words to show how related words operate as one unit. This method makes the multi-word code
nouns agree with Rule 2.1. Hyphenated words always count as one word, so a hyphenated code
noun fills only one of the three-word slots that Rule 2.1 allows for a noun phrase.

Do not connect words that are not related, because the hyphen changes the meaning of the
multi-word code noun. If you are not sure, explain the noun in the clearest way, then use a
shorter form, an approved verb such as `get`, `set`, `make`, `start`, or an official approved
abbreviation from your glossary.

If an approved technical code noun includes hyphens — for example `input-output stream`,
`thread-safe queue`, or `backward-compatible API` — do not change it. If it is too long, write
it in full the first time it occurs, then use the shorter-technical-noun method.

Do not use hyphens to make groups of more than three words. Keep the hyphen group to at most
three words; split longer chains with prepositions such as `of`, `on`, or `in`.

Approved hyphenated code examples:

| Example | Note |
|---|---|
| Make sure that the fail-safe shutdown-handler connection is safe. | 3 words: make / sure / connection |
| Inspection of the request rate-limit device. | 3 words: inspection / of / device |
| The thread-safe queue keeps the order of the write operations. | 3 words: queue / keeps / order |
| Remove the backward-compatible API client before you make the change. | 3 words |

When a hyphen joins two related words, the pair counts as one unit. Apply this in procedural
and descriptive code documentation so the reader can parse the noun without re-reading.

| Do not write | Write |
|---|---|
| Move the `main-feature-flag-rollback-handler` trigger to start the test run. | Move the `main-feature-flag` rollback-handler trigger to start the test run. |
| Remove the `data-adapter` assembly (8) from the view body. | Remove the `data adapter` assembly (8) from the view body. |
| The `input output stream` is part of the logging system. | The `input-output stream` is part of the logging system. |

Cautions:

- Do not hyphenate a three-word approved technical noun (`data adapter`, `pipeline validator`);
  adding a hyphen changes the count and confuses the reader.
- Keep a hyphen the official name already has (`input-output stream`); removing it changes
  the term.

See also: Rule 2.1 (the three-word limit hyphenated units help you meet), Rule 1.5
(hyphenated code terms such as `thread-safe queue` and `backward-compatible API`),
Rule 2.2 (pair hyphenated nouns with short approved verbs).

---

## Section 3 — Sentence structure

Section 3 governs how approved words form sentences. The dictionary gives each approved verb
with four forms; Section 3 tells you which forms and tenses you may use, how to keep the
active voice, and how to avoid auxiliary-verb constructions.

### The four approved verb-form categories

1. **Development operations** — build, compile, test, lint, format, commit, push, deploy, rollback
2. **Data operations** — read, write, serialize, deserialize, parse, encode, decode, query, insert, migrate
3. **Application operations** — handle, route, authenticate, authorize, validate, schedule, dispatch, resolve
4. **Communication operations** — send, receive, publish, subscribe, stream, poll, broadcast, connect

The plain everyday verbs also apply: `use`, `start`, `stop`, `show`, `make`, `get`, `set`,
`check`, `do`, `send`, `remove`, `keep`.

---

## Rule 3.1 — Use only the verb forms given in the dictionary

The STE-Code dictionary gives the verb forms you can use for each approved verb. Use only
those forms. Do not use other forms (gerunds, participles used as verbs with auxiliaries, or
inflected forms that are not listed).

Every approved verb appears with four forms, in this order: base form, third-person singular,
simple past, past participle. The simple future is not a separate line; make it with "will"
and the base form.

| Line in the entry | Form | Example with WRITE |
|---|---|---|
| Line 1 | Base form (infinitive and imperative) | WRITE — "Write the log." / "to write the log" |
| Line 2 | Third-person singular, simple present | WRITES — "The logger writes the record." |
| Line 3 | Simple past | WROTE — "The job wrote the record." |
| Line 4 | Past participle (as an adjective) | WRITTEN — "the written log" |

How to apply:

1. Find the verb in the STE-Code dictionary.
2. If the verb is not in the dictionary, use the approved verb instead: `make` (not
   `generate`), `get` (not `retrieve`), `check` (not `verify`), `use` (not `utilize`), `start`
   (not `initiate`), `stop` (not `terminate`), `remove` (not `delete`), `show` (not `render`),
   `do` (not `execute`), `keep` (not `maintain`).
3. If the verb is in the dictionary, use only one of the four listed forms.
4. Do not make a new form from an approved verb. "Parsing," "parseable," and "parser" are not
   verb forms of PARSE; a noun such as "parser" is approved only when the dictionary or a
   technical-noun category gives it.
5. Use the past participle only as an adjective ("the parsed manifest," "the deprecated
   method"). Do not use it with "have," "has," "had," or "get" to make a verb.

| Do not write | Write |
|---|---|
| The linter validates the file and is reporting the errors. | The linter validates the file. It reports the errors to the terminal. |
| The script has written the output to the log. | The script wrote the output to the log. Then the test starts. |
| The service utilizes a token cache and leverages the parser. | The service uses a token cache. The service parses each request. |
| The loader does the parsing and the validating. | The loader parses the manifest. Then the loader validates the schema. |
| The migration had deleted the deprecated column. | The migration removed the deprecated column. Then the migration stopped the open connections. |

See also: Rule 3.2 (approved tenses), Rule 3.3 (past participle as adjective), Rule 3.4
(avoid auxiliary verbs), Rule 3.6 (active voice), Rule 1.1 (word gates), Rule 1.5
(technical noun categories), the STE-Code dictionary (a-dictionary.md).

---

## Rule 3.2 — Use only these verb forms and tenses

Use only these verb forms and tenses of verbs:

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

Do not use other forms and tenses that are not approved:

- The present perfect (have/has parsed)
- The past perfect (had parsed)
- The present/past progressive (is/was parsing)
- The future progressive (will be parsing)
- The perfect progressive (has been parsing, had been parsing)
- The gerund used as a verb with an auxiliary (is parsing, keeps parsing)

Approved verb-form table (code verbs):

| Infinitive | Imperative + object | Simple present | Simple past | Simple future | Past participle (adj) |
|---|---|---|---|---|---|
| (To) Parse | Parse + object | It parses | It parsed | It will parse | The parsed file |
| (To) Write | Write + object | It writes | It wrote | It will write | The written log |
| (To) Build | Build + object | It builds | It built | It will build | The built artifact |
| (To) Send | Send + object | It sends | It sent | It will send | The sent request |
| (To) Validate | Validate + object | It validates | It validated | It will validate | The validated token |

How to select the correct form:

1. **Infinitive** — after a modal verb or to state a purpose: "Use this flag to parse the file."
2. **Imperative** — for each step of a procedure: "Parse the file. Write the log."
3. **Simple present** — for a general fact, repeated action, or system behavior: "The parser reads the file."
4. **Simple past** — for a complete action: "The build failed."
5. **Simple future** — "will" + base form for a later action: "The job will start at 02:00."
6. **Past participle** — only as an adjective before a noun: "the parsed file," "the deprecated method."

How to correct an unapproved form:

- Present perfect ("has parsed") → simple past ("parsed").
- Past perfect ("had parsed") → simple past in two sentences with "Then".
- Progressive ("is parsing," "was parsing") → simple present or simple past; if two actions
  happen together, write two sentences and add "at the same time".
- Future progressive ("will be parsing") → simple future ("will parse").
- Passive with unapproved auxiliary ("is being parsed") → name the actor and use the active
  voice (Rule 3.6).

| Do not write | Write |
|---|---|
| The linter has found three errors. | The linter found three errors in the source file. |
| The server was processing the request when the timeout occurred. | The server processed the request. Then the timeout occurred. |
| The framework had already initialized the pool. | The framework made the connection pool. Then the query started. |
| The scheduler is deploying the build while the tests are running. | The scheduler sends the build to production. The tests run at the same time. |
| You should be setting the timeout, then you will be restarting. | Set the timeout value. Then start the service again. |

See also: Rule 3.1 (dictionary forms), Rule 3.3 (past participle as adjective), Rule 3.4
(avoid auxiliary verbs), Rule 3.5 ("-ing" only as noun/modifier), Rule 3.6 (active voice),
Rule 1.1 (word gates), the STE-Code dictionary.

---

## Rule 3.3 — Use the past participle form as an adjective

When you use the past participle form as an adjective, it shows the condition of something.
This is not passive voice. Use the past participle form of an approved verb as an adjective:

- Before a noun
- After a verb form of "to be," "to become," or "to stay"

Do not use the past participle form if it is not in the STE-Code dictionary. Approved
adjectives in the dictionary that are the past participle of verbs that are not approved
(for example "permitted," "damaged") have part of speech "(adj)" and are permitted.

How to know it is an adjective and not passive voice:

1. The word gives the **condition** of the thing, not an action an actor does.
2. You can put it directly before the noun: "the parsed file," "the deprecated method,"
   "the closed connection".
3. You can put it after "is," "becomes," or "stays": "the cache is initialized," "the endpoint
   becomes deprecated," "the record stays locked".
4. If the sentence names an actor and an action ("the file was parsed by the loader"), it is
   passive voice — write the active voice instead (Rule 3.6).

Approved code-domain past participles used as adjectives:

| Past participle (adj) | Example noun phrase | Condition it shows |
|---|---|---|
| parsed | the parsed manifest | The parser read the file. |
| serialized | the serialized record | The record is in a transport format. |
| deserialized | the deserialized object | The object is in memory again. |
| initialized | the initialized cache | The cache is ready for use. |
| deprecated | the deprecated method | The method is old. Do not use it. |
| allowed | the allowed memory | The limit the configuration gives. |
| corrupted | the corrupted index | The data is not correct. |
| locked | the locked row | Another transaction holds the row. |
| written | the written log | The log file is on disk. |
| given | the given options | The options the caller sends. |
| built | the built artifact | The build made the artifact. |
| signed | the signed token | The token has a valid signature. |

Cautions:

- Do not make a new past participle from an unapproved verb. Write "the removed branch," not
  "the deleted branch," unless "delete"/"deleted (adj)" is in the dictionary.
- Do not use a past participle as a verb with "have," "has," or "had" (Rule 3.2).
- Do not put more than one past participle before the same noun; split into two short
  sentences if the phrase becomes difficult.
- Prefer the plain word: "started" not "commenced," "used" not "utilized," "stopped" not
  "terminated".

| Do not write | Write |
|---|---|
| The method has been deprecated by the API team. | The method is deprecated in release 4.2. Do not use the deprecated method in new code. |
| The record gets locked, then the transaction is committed. | The transaction writes the locked record. Then the transaction ends. |
| The gateway validates the signed token on each request. | (already active — "signed" is the adjective before "token") |
| The build artifact stays uncompiled until the pipeline has compiled. | The artifact stays unbuilt until the pipeline builds the modified sources. |

See also: Rule 3.1 (dictionary forms), Rule 3.2 (approved tenses), Rule 3.4 (avoid auxiliary
verbs), Rule 3.5 ("-ing" as noun/modifier), Rule 3.6 (active voice), Rule 1.1 (word gates),
the STE-Code dictionary (approved adjectives with "(adj)").

---

## Rule 3.4 — Do not use auxiliary verbs to make complex verb constructions

Do not use the past participle form as a verb together with the auxiliary verb "have." Do not
use auxiliary verbs ("have," "be," "will," "can," "must," "should," "is to be") with a past
participle to build compound tenses or passive voice. These constructions make complex verb
forms that STE-Code does not approve. Write the action with a simple, approved verb form:

- Use the simple past instead of "have/has/had + past participle" (present or past perfect).
- Use the active voice with a clear agent instead of "be + past participle" (passive voice,
  Rule 3.6).
- Use the imperative (command) form for instructions instead of "is to be + past participle."
- Use "you can + base verb" instead of "can be + past participle" when the reader is the agent.
- Use "will + base verb" with a named agent instead of "will be + past participle + by + agent."

When a compound construction is unavoidable for correctness, split it into separate simple
sentences. Rule 3.2 lists the only approved verb forms.

| Do not write | Write |
|---|---|
| The build has compiled the module before the test runs. | The build compiled the module. Then the test runs. |
| The migration is to be run before you deploy. | Before you deploy the service, run the migration. |
| The cache can be cleared. | You can clear the cache. |
| The timeout must be set before the job starts. | Set the timeout before the job starts. |
| The report will be generated by the scheduler. | The scheduler will generate the report. |
| The connection pool has been created before the first query is sent. | The connection pool was created. Then the first query is sent. |
| The configuration file must be validated before the server starts. | Validate the configuration file before the server starts. |
| The user credentials are to be encrypted at rest and the key is rotated. | Encrypt the user credentials at rest. Rotate the key every month. |
| The temporary files had been deleted before the backup started. | The cleanup task deleted the temporary files. Then the backup started. |

See also: Rule 3.2 (approved tenses), Rule 3.3 (past participle as adjective), Rule 3.5
("-ing" as noun/modifier), Rule 3.6 (active voice).

---

## Rule 3.5 — Use the "-ing" form only as a technical noun or modifier

Words with an "-ing" form can be a verb, an adjective, a noun, or a long group of modifiers.
These different functions can cause ambiguity or long complex sentences. Thus, words with an
"-ing" form are usually not permitted as verbs. Use an "-ing" word only as a technical noun
(for example a section title or heading) or as a modifier inside a technical noun.

Approved "-ing" words in STE-Code:

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

Why the progressive verb form is not approved: Rule 3.2 lists the only permitted forms and
tenses. The present progressive ("is running," "are deploying," "was processing") is not on
that list, so you must not use "-ing" to describe an action. Replace the progressive with the
simple present or simple past, and break a long continuous clause into short separate
sentences. The "-ing" form also hides auxiliary-verb constructions that Rule 3.4 forbids.

Approved "-ing" technical nouns (titles/headings): Logging, Monitoring, Testing and Fault
Isolation, Handling, Packaging, Shipping, Troubleshooting, Building, Deployment.

Approved "-ing" modifiers (inside a technical noun): logging service, monitoring agent,
routing table, switching relay, caching layer, building pipeline, binding configuration,
streaming endpoint, rendering engine.

Do not pull the "-ing" word out of the technical noun and use it as a verb: "The caching layer
stores the result" is approved; "The layer is caching the result" is not.

| Do not write | Write |
|---|---|
| When you are running this script, obey the safety checks. | When you run this script, obey all the safety checks. |
| The background worker is processing the queue and writing results. | The background worker processes the queue. It writes the results to the cache. |
| Developers committing code without running tests risk breaking the build. | Before you commit code, run the test suite. Make sure the tests pass. |
| The matching algorithm is comparing the remaining items. | The matching algorithm compares the remaining items during the iteration. |
| Something going wrong during the migration can corrupt the database. | If something goes wrong during the migration, the database can stay in a broken state. |

See also: Rule 3.2 (present progressive not approved), Rule 3.4 (auxiliary-verb constructions
forbidden), Rule 1.5 (technical-noun categories that the "-ing" modifier/noun uses depend on).

---

## Rule 3.6 — Use the active voice

Use the active voice in all code documentation. In descriptive writing, the passive voice is
permitted only when the agent (the person, service, or component that does the action) is
unknown.

In the active voice, the subject does the action ("A does B"). In the passive voice, the
subject receives the action ("B is done by A"). To test for passive voice, ask "by whom or by
what?" If the sentence answers, it is passive — convert it to active by using the agent as the
subject.

Four methods to convert passive to active:

- **Method 1** — When "by" identifies the agent, move the agent to the subject position.
- **Method 2** — Change an infinitive verb to an active verb.
- **Method 3** — In procedural writing, change the verb to the imperative (command) form.
- **Method 4** — When the agent is not given, use "you" (reader) or "we" (your organization)
  as the subject.

| Do not write (passive) | Write (active) |
|---|---|
| The API response is parsed by the middleware. | The middleware parses the API response. |
| The database connection is established by the connection pool. | The connection pool establishes the database connection at startup. |
| The dependencies can be installed with this command. | Install the dependencies with this command: npm install |
| The configuration file can be edited with a text editor. | You can edit the configuration file with a text editor. |
| The package can be installed with pip install. | Install the package with this command: pip install . |
| Support for WebSocket connections is provided by this library. | This library supports WebSocket connections. |
| The input string is validated and a boolean is returned by this method. | This method validates the input string and returns a boolean. |
| The authentication bug was fixed. | Fix the authentication bug. |

When the agent is unknown and you cannot identify it, passive is correct:

> Passive (correct): During the network request, the payload was corrupted before the checksum
> was computed. The agent is unknown because the failure occurs only under heavy load.

> Active (incorrect): During the network request, the socket corrupted the payload. — "socket"
> is not the true cause; the active sentence misleads the reader about where to fix the bug.

Use the active voice in each documentation type:

- **README** — procedural sections use the imperative with "you" as the implied agent;
  descriptive sections use the project/library/tool as the subject.
- **API docs** — use the method/function as the subject; for callbacks, use the callback as the
  subject; for return values, use the function as the subject ("This function returns a
  `Promise<User>`", not "A `Promise<User>` is returned").
- **Docstrings/comments** — the summary line uses the imperative; the body uses the function as
  the subject.
- **Commit messages** — imperative mood, inherently active ("Fix the authentication bug", not
  "The authentication bug was fixed").

See also: Rule 3.1 (dictionary forms), Rule 3.2 (approved tenses), Rule 3.3 (past participle as
adjective), Rule 3.4 (avoid auxiliary verbs), Rule 3.5 ("-ing" as noun/modifier).

---

## Rule 3.7 — Use an approved verb to describe an action, not a noun

If there is an approved verb that describes an action, use the approved verb. Verbs describe
actions more clearly than nouns or other parts of speech. The four approved technical-code-verb
categories give you the verbs you can use (see the Section 3 table). If a word is not approved
as a verb in the dictionary, do not use it as a verb — use a different sentence construction
(usually the noun form of the word).

Why verbs, not nouns: a noun names a thing; a verb names the work. "validate the token" tells
the reader to run the check; "validation of the token" makes the reader ask whether to run it,
log it, or skip it. Prefer the plain approved verb — `use`, `start`, `stop`, `show`, `make`,
`get`, `set`, `check`, `do`, `send`, `remove`, `keep` — over wordy substitutes such as
*utilize*, *leverage*, *employ*, *commence*, *terminate*, or *initiate*.

| Do not write | Write |
|---|---|
| The ohmmeter gives an indication of 450 ohms. | The ohmmeter shows 450 ohms. |
| Before the removal of the unit, make sure the power is OFF. | Before you remove the unit, make sure the power is OFF. |
| The profiler gives an indication of 200ms latency. | The profiler shows 200ms latency. |
| Before the initialization of the service, check the config. | Before you initialize the service, check the config. |
| Cache the response. | Do a cache of the response. (cache is a technical noun, not an approved verb) |
| The function gives a result of 500 OK. | The function returns 500 OK. |
| The parser does a verification of the payload. | You validate the payload before you store it. |
| A read of the config, then a write of the config. | Read the config, then write the config. |
| A transmission of the event, then a reception. | Send the event, then receive the event. |

See also: Rule 3.2 (approved verb forms and tenses), Rule 1.5 (noun-form fallback when a word
is not an approved verb), the extension approved verbs — use, start, stop, show, make, get, set,
check, do, send, remove, keep.

---

<!-- 06-extensions.md -->

# Level 5 — Extensions

Level 5 is the full STE-Code standard. This sub-document is the **extensions** slice:
the approved code-domain vocabulary that sits on top of the core rules in Sections 1–9.
It has two parts:

1. **Extension adjectives** — single approved words (such as `idempotent`, `immutable`,
   `atomic`) that you may attach to a short technical noun without breaking the word-count
   limits of Section 2.
2. **Domain extension vocabulary** — grouped lists of approved code-domain verbs, nouns,
   and signal words for common domains (build, testing, security, version control, and so
   on), each with the rules it must obey and the weak alternatives it replaces.

Use this file when you generate or review code documentation with an LLM and need a compact,
machine-readable list of the words STE-Code accepts beyond its core dictionary.

## How extensions relate to the rules

Extensions are not a new rule set. Each extension still obeys the core rules:

- **Rule 1.1** (approved words only) — every extension word is on an approved list.
- **Rule 2.1** (short technical nouns) — keep the noun short; the adjective attaches to it.
- **Rule 3.1 / 3.7** (prefer a verb) — domain verbs such as `build`, `test`, `deploy` replace
  noun phrases such as "perform a build of" or "do a deployment of".
- **Rule 7.1 / 7.2 / 7.3** (risk and safety words) — the signal-word group replaces vague
  warnings such as "heads up" or "be careful" with `WARNING`, `CAUTION`, `BREAKING`, `DEPRECATED`.

A hyphenated extension adjective counts as one word under Rule 2.1. Write
`the idempotent retry policy` (three words), not `idempotentretrypolicy`. Keep the hyphen
before the noun: `thread-safe`, `backward-compatible`, `read-only`, `stateless`.

---

## Part 1 — Extension adjectives

These adjectives are approved as single words. Each entry gives the definition and one
STE / Non-STE code-documentation pair so you can see the contrast. The Non-STE line shows
the weak alternative the extension replaces (usually `leverage` / `utilize` / `employ` plus a
nominalized verb).

### idempotent
- **meaning**: An operation that produces the same result when applied more than once, with no extra side effects after the first run.
- **STE**: Make the retry handler idempotent so a second call with the same input does not duplicate the record.
- **Non-STE**: Leverage an idempotent retry handler so a duplicate invocation will not create a redundant record.

### immutable
- **meaning**: A data structure or value that cannot be changed after it is created, which prevents accidental shared-state bugs.
- **STE**: Keep the request context immutable so concurrent threads cannot overwrite each other's values during a single operation.
- **Non-STE**: Utilize an immutable request context so concurrent threads will not overwrite shared values during processing.

### atomic
- **meaning**: An operation that completes fully or not at all, with no partial result visible to other processes.
- **STE**: Wrap the balance update in an atomic transaction so the debit and credit always succeed or fail together.
- **Non-STE**: Employ an atomic transaction to encapsulate the balance update so debit and credit always commit or roll back together.

### thread-safe
- **meaning**: Code that functions correctly when accessed by multiple threads at the same time without external locking.
- **STE**: Mark the singleton constructor thread-safe so two threads can call it on first use without creating two instances.
- **Non-STE**: Leverage a thread-safe singleton constructor so concurrent threads will not instantiate duplicate objects on first access.

### asynchronous
- **meaning**: A call or task that starts and returns before its work finishes, so the caller can do other work meanwhile.
- **STE**: Make the file upload asynchronous so the user interface stays responsive while the transfer runs in the background.
- **Non-STE**: Utilize an asynchronous upload mechanism so the user interface remains responsive while the transfer executes in the background.

### concurrent
- **meaning**: Tasks that make progress within the same time period, interleaved by the scheduler rather than strictly sequentially.
- **STE**: Run the test suites in concurrent processes so the full check finishes in a fraction of the single-threaded time.
- **Non-STE**: Employ concurrent processes to execute the test suites so the whole check terminates faster than a single-threaded run.

### deterministic
- **meaning**: A function whose output depends only on its inputs, with no hidden state or time-based variation between runs.
- **STE**: Keep the hash function deterministic so the same key always maps to the same bucket across restarts.
- **Non-STE**: Leverage a deterministic hash function so an identical key consistently maps to the same bucket after restarts.

### deprecated
- **meaning**: An API or feature that still works but that the maintainers plan to remove, so avoid new use of it.
- **STE**: Mark the old login endpoint deprecated and show a warning that points to the new token-based method.
- **Non-STE**: Flag the legacy login endpoint as deprecated and utilize a warning that redirects callers to the token-based method.

### nullable
- **meaning**: A field or variable that can hold a null value to indicate the absence of a meaningful value.
- **STE**: Make the middle-name field nullable so the profile save does not fail when the value is absent.
- **Non-STE**: Configure the middle-name field as nullable so the profile persistence will not fail when the value is missing.

### serializable
- **meaning**: An object that can be converted to a byte stream and rebuilt elsewhere without losing its data.
- **STE**: Make the session object serializable so the cache layer can store it and restore it on the next request.
- **Non-STE**: Utilize a serializable session object so the cache layer can persist and reconstitute it on the following request.

### stateless
- **meaning**: A service that keeps no client data between requests, which makes horizontal scaling simpler and safer.
- **STE**: Build the authentication proxy stateless so any node can answer a request without shared session memory.
- **Non-STE**: Employ a stateless authentication proxy so every node can service a request without shared session storage.

### backward-compatible
- **meaning**: A change that older clients can still use without modification because the old interface still works.
- **STE**: Keep the API response backward-compatible so existing mobile apps keep working after the schema update.
- **Non-STE**: Leverage a backward-compatible response format so legacy mobile clients remain functional after the schema update.

### read-only
- **meaning**: A resource or mode that permits inspection but forbids any write, update, or delete operation.
- **STE**: Open the database handle read-only during reports so the query tool cannot change production data by mistake.
- **Non-STE**: Utilize a read-only database handle for reports so the query tool cannot mutate production data accidentally.

### recursive
- **meaning**: A function that calls itself with a smaller part of the problem until it reaches a base case.
- **STE**: Write the directory walker recursive so it visits every nested folder without a manual loop stack.
- **Non-STE**: Employ a recursive directory walker so it traverses each nested folder without an explicit loop stack.

### monotonic
- **meaning**: A counter or clock that only increases and never goes backward, which makes ordering safe.
- **STE**: Use a monotonic sequence for the event id so replays never create a lower number than a prior record.
- **Non-STE**: Leverage a monotonic sequence for the event identifier so replays never yield a lower value than prior records.

### transitive
- **meaning**: A permission or relation that flows through a chain, so a grant to a group reaches its members.
- **STE**: Make the role grant transitive so a user in a child team inherits the parent team's read access automatically.
- **Non-STE**: Utilize a transitive role grant so a member of a child team inherits the parent team's read access automatically.

### volatile
- **meaning**: A memory value that another thread or device can change at any time, so the compiler must reload it.
- **STE**: Declare the status flag volatile so the loop reads the hardware register again instead of using a cached copy.
- **Non-STE**: Employ a volatile status flag so the loop reloads the hardware register rather than using a cached copy.

### hierarchical
- **meaning**: Data or permissions arranged in parent-child levels where a child inherits settings from its ancestor.
- **STE**: Store the configuration in a hierarchical map so a child setting overrides only the matching branch of the tree.
- **Non-STE**: Utilize a hierarchical configuration map so a child setting overrides solely the matching branch of the tree.

### normalized
- **meaning**: A database schema arranged to remove redundant data and reduce update anomalies across tables.
- **STE**: Keep the user table normalized so the address lives in one row and every order references it by id.
- **Non-STE**: Utilize a normalized user table so the address resides in one row and each order references it by identifier.

### incremental
- **meaning**: A build or update that processes only the changed parts instead of recomputing the whole result.
- **STE**: Run an incremental compile so the tool rebuilds only the modules whose source changed since the last run.
- **Non-STE**: Employ an incremental compile so the tool reconstructs only the modules whose source changed since the prior run.

---

## Part 2 — Domain extension vocabulary

Each domain below lists the approved code-domain words, the weak alternatives they replace,
the core rules that govern them, and one STE / Non-STE example. Use these as drop-in vocabulary
when documenting the matching domain.

### Build and Package
Operations for compiling, assembling, bundling, and distributing software artifacts.
- **Approved**: build, compile, bundle, package, deploy, publish, release, tag, version, transpile, minify, polyfill, ship
- **Replaces**: make a build of → build; perform compilation → compile; create a bundle → bundle; generate the artifact → build; assemble → build; construct → build; fabricate → build
- **Rules**: Rule 1.12, Rule 1.13, Rule 1.1, Rule 1.7
- **Example**: STE: Build the Docker image. Then deploy the container to the registry. | Non-STE: Perform a build of the Docker image and then do a deployment to the registry.

### Testing and Quality Assurance
Operations for verifying code correctness, measuring performance, and ensuring quality.
- **Approved**: test, assert, mock, stub, spy, benchmark, profile, instrument, debug, unit-test, lint, check
- **Replaces**: validate → check; verify → check; ensure → make sure; run validation → check; perform testing → test; execute tests → run tests; carry out verification → check
- **Rules**: Rule 1.12, Rule 1.1, Rule 1.5, Rule 4.1
- **Example**: STE: Run the test suite. Check that the coverage is above 80 percent. | Non-STE: Execute the test suite and verify that coverage exceeds 80%.

### Dependency Management
Operations for installing, updating, locking, and resolving software dependencies.
- **Approved**: install, update, upgrade, pin, lock, link, hoist, resolve, uninstall, add, remove
- **Replaces**: fetch dependencies → install; retrieve packages → install; pull down → install; bump → update; snag → install; grab → get
- **Rules**: Rule 1.12, Rule 1.1, Rule 1.10, Rule 1.11
- **Example**: STE: Install the dependencies with npm install. Pin the versions in the lock file. | Non-STE: Snag the deps and bump the versions.

### Version Control
Operations for tracking changes, branching, merging, and collaborating on source code.
- **Approved**: commit, branch, merge, rebase, tag, push, pull, clone, fork, checkout, revert, cherry-pick, stash, stage, reset
- **Replaces**: save changes → commit; upload → push; download → pull/clone; combine → merge; split off → branch
- **Rules**: Rule 1.12, Rule 1.7, Rule 1.13, Rule 1.1
- **Example**: STE: Commit the changes. Then push the branch to the remote repository. | Non-STE: Git the changes and then push them up. (Uses Git as a verb, Rule 1.7 violation)

### Security
Operations for authentication, authorization, encryption, and protecting systems from threats.
- **Approved**: authenticate, authorize, encrypt, decrypt, hash, salt, sanitize, validate, sign, revoke, audit, escape
- **Replaces**: secure → encrypt/protect; lock down → restrict; harden → make secure; obfuscate → hide
- **Rules**: Rule 1.12, Rule 7.1, Rule 1.5, Rule 1.1
- **Example**: STE: WARNING: Sanitize all user input before you process it. Unsanitized input can cause SQL injection attacks. | Non-STE: CAUTION: Always clean your inputs.

### Logging and Monitoring
Operations for recording events, measuring system health, and observing runtime behavior.
- **Approved**: log, monitor, trace, instrument, observe, alert, report, record
- **Replaces**: write to log → log; keep track of → monitor; watch → monitor; spy on → observe; output → write/log
- **Rules**: Rule 1.12, Rule 1.1, Rule 1.5, Rule 5.1
- **Example**: STE: Log the error details to the error file. Monitor the CPU usage. | Non-STE: Do a logging of the exception. Keep an eye on the CPU.

### API Design
Concepts for designing, documenting, and consuming application programming interfaces.
- **Approved**: endpoint, route, handler, middleware, controller, request, response, payload, header, status code, rate limit, query parameter, path parameter, body, schema
- **Replaces**: URL path → endpoint; API method → endpoint; args → parameters; params → parameters; data → payload/body; return value → response
- **Rules**: Rule 1.5, Rule 1.11, Rule 1.8, Rule 4.1
- **Example**: STE: The endpoint returns a JSON object. The object contains a user list and a pagination token. | Non-STE: The API method gives you back a JSON with the users and a next-page thing.

### Configuration Management
Operations for setting up, managing, and maintaining system and application configuration.
- **Approved**: configure, set, initialize, bootstrap, provision, override, default, environment variable, config file, dotenv, settings
- **Replaces**: tweak → set/change; dial in → configure; set up → configure/initialize; wire up → configure/connect; spin up → start/initialize
- **Rules**: Rule 1.12, Rule 1.1, Rule 1.10, Rule 5.4
- **Example**: STE: Set the DATABASE_URL environment variable in the .env file. | Non-STE: Tweak the DATABASE_URL knob in the dotenv thing.

### Object-Oriented Design
Concepts and operations specific to object-oriented programming paradigms.
- **Approved**: instantiate, inherit, override, extend, implement, encapsulate, delegate, inject, compose, abstract class, interface, constructor, method, property, polymorphism
- **Replaces**: make an instance → instantiate; new up → instantiate; subclass → extend/inherit; hide → encapsulate; pass → delegate
- **Rules**: Rule 1.12, Rule 1.5, Rule 1.7, Rule 1.13
- **Example**: STE: The UserRepository class extends BaseRepository. It implements the IAuditable interface. Inject the Database dependency through the constructor. | Non-STE: The repo subclasses the base and hides the data. Pass the DB in via the ctor.

### Functional Programming
Concepts and operations specific to functional programming paradigms.
- **Approved**: compose, curry, map, reduce, fold, filter, recurse, memoize, lift, pattern match, pure function, immutable, closure, higher-order function, monad, functor, applicative
- **Replaces**: chain → compose; loop over → map; combine → reduce/fold; cache results → memoize; call itself → recurse
- **Rules**: Rule 1.12, Rule 1.5, Rule 1.1, Rule 1.11
- **Example**: STE: Map the transformation over the list. Then fold the results with the sum function. | Non-STE: Loop over the array applying the transform and then add everything up.

### Systems Programming
Concepts and operations for memory management, ownership, lifetimes, and low-level system access.
- **Approved**: allocate, deallocate, borrow, own, drop, move, pin, acquire, release, dereference, lifetime, ownership, stack, heap, undefined behavior, dangling pointer, segmentation fault, mutex, atomic
- **Replaces**: free → deallocate; malloc → allocate; clean up → deallocate/drop; grab a lock → acquire; let go → release; shooting yourself in the foot → undefined behavior
- **Rules**: Rule 1.12, Rule 1.5, Rule 1.10, Rule 7.1
- **Example**: STE: Allocate a buffer on the heap. Deallocate the buffer before the function returns. The borrow checker prevents dangling pointers. | Non-STE: Malloc a chunk of memory and free it when you are done. Rust's thingy stops you from shooting yourself in the foot.

### Declarative Configuration
Concepts for describing desired system state through configuration files and infrastructure-as-code.
- **Approved**: provision, converge, reconcile, apply, destroy, declare, resource, provider, module, state, plan, namespace, pod, deployment, service
- **Replaces**: spin up → provision/start; tear down → destroy; make → provision; run → apply; set up → provision
- **Rules**: Rule 1.12, Rule 1.5, Rule 1.1, Rule 4.1
- **Example**: STE: The Terraform resource provisions an AWS EC2 instance. Apply the configuration to converge the infrastructure. | Non-STE: Terraform spins up an EC2 box when you run the apply command.

### Risk and Safety Documentation
Signal words and conventions for documenting security risks, breaking changes, and important notes in code.
- **Approved**: WARNING, CAUTION, BREAKING, DEPRECATED, NOTE, FIXME, TODO, HACK, XXX
- **Replaces**: DANGER → WARNING; IMPORTANT → NOTE/WARNING; BE CAREFUL → CAUTION; ATTENTION → NOTE; heads up → NOTE; watch out → CAUTION
- **Rules**: Rule 7.1, Rule 7.2, Rule 7.3, Rule 1.1
- **Example**: STE: WARNING: DO NOT COMMIT THE API KEY. AN EXPOSED KEY CAN CAUSE UNAUTHORIZED ACCESS. | Non-STE: heads up: don't check in the secret key or bad things happen.

### Commit Message Conventions
Standardized terms and formats for writing clear, consistent commit messages.
- **Approved**: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert, add, remove, update, change
- **Replaces**: implemented → feat/add; added → add/feat; fixed → fix; changed → update/change; removed → remove; bumped → update; patched → fix
- **Rules**: Rule 1.1, Rule 4.1, Rule 5.1, Rule 1.11
- **Example**: STE: feat: Add JWT authentication middleware for API routes. | Non-STE: Implemented JWT auth middleware for the API endpoints.

### Continuous Integration and Delivery
Operations and concepts for automated build, test, and deployment pipelines.
- **Approved**: pipeline, workflow, job, stage, runner, artifact, trigger, checkout, cache, matrix, environment, deploy, rollback, approval, gate
- **Replaces**: CI → pipeline/workflow; CD → deployment pipeline; build step → job/stage; CI runner → runner; kick off → trigger/start; fire → trigger
- **Rules**: Rule 1.5, Rule 1.12, Rule 1.8, Rule 5.2
- **Example**: STE: The pipeline has three stages: build, test, and deploy. Trigger the workflow on every push to the main branch. | Non-STE: The CI kicks off when you push to main and runs the build, test, and deploy stuff.

### Database Operations
Operations for querying, migrating, backing up, and managing database systems.
- **Approved**: query, migrate, seed, backup, restore, roll back, replicate, shard, index, vacuum, compact, flush, persist, transaction, schema
- **Replaces**: run a query → query; do a migration → migrate; populate the DB → seed; dump → backup; snapshot → backup; write to disk → persist/flush
- **Rules**: Rule 1.12, Rule 1.13, Rule 1.5, Rule 1.11
- **Example**: STE: Migrate the database schema to version 3. Seed the development database with test data. | Non-STE: Run the migration script to update the DB and populate it with fake data.

### User Interface Documentation
Terms for documenting UI components, interactions, and interface behavior.
- **Approved**: click, type, scroll, select, drag, drop, toggle, zoom in, zoom out, navigate, press, tap, swipe, hover, focus
- **Replaces**: hit → click/press; push → click/press; enter → type; choose → select; flip → toggle; go to → navigate
- **Rules**: Rule 1.12, Rule 1.5, Rule 1.1, Rule 5.2
- **Example**: STE: Click the Submit button. Type your password in the text field. | Non-STE: Hit the submit thing and enter your pwd in the box.

---

<!-- 07-catalogue.md -->

# Level 5 — Reference Catalogue (vendor / community)

This document catalogues the **external references** that informed STE-Code's
controlled vocabulary. These references are **NOT part of the standard**. They
are vendor and community sources that the dictionary and rules were checked
against. Use them when you need to resolve a word, a term, or a style question
that the STE-Code rules and dictionary do not settle.

Status note for readers: each entry is either bundled locally as a mirror under
`.agents/reference/` (type `page` or `raw`) or is a live external pointer (type
`pointer`). Local mirrors are stored outside `final/` per project rule, so they
do not ship inside the standard itself — only this catalogue does.

How to use this catalogue:
- Need a style decision (voice, capitalization, sentence length)? → Style guides.
- Need a definition of a code-domain term (API, commit, idempotent)? → Glossaries.
- Need to confirm a word is a real English word / spelled right? → Word lists.
- Need to automate checking in CI? → Linters.
- Need to discover more sources? → Pointer / topic indexes.

## Style guides

These set the **voice and conventions** STE-Code inherits: short sentences,
active voice, plain words, consistent terminology.

| Reference | Type | Source | Use for |
|---|---|---|---|
| Microsoft Writing Style Guide | page | [learn.microsoft.com](https://learn.microsoft.com/en-us/style-guide/welcome/) (mirror: `.agents/reference/microsoft-writing-style-guide.md`) | Voice, capitalization, tone, word choice |
| MicrosoftDocs/microsoft-style-guide (GitHub source) | page | [github.com/MicrosoftDocs/microsoft-style-guide](https://github.com/MicrosoftDocs/microsoft-style-guide) (mirror: `.agents/reference/microsoft-style-guide-github.md`) | Same content as above, source repo |
| Google Style Guides | page | [google.github.io/styleguide](https://google.github.io/styleguide/) (mirror: `.agents/reference/google-style-guides.md`) | Technical writing conventions, API docs, capitalization |
| DevOps Style Guide Glossary | page | [tydukes.github.io/coding-style-guide/glossary](https://tydukes.github.io/coding-style-guide/glossary/) (mirror: `.agents/reference/devops-style-guide-glossary.md`) | DevOps and coding style terms |

## Code-domain glossaries

These supply **definitions of terms used in software and code documentation**.
Prefer them over general dictionaries when a word has a code-specific meaning.

| Reference | Type | Source | Use for |
|---|---|---|---|
| Kong/apiglossary | page | [github.com/Kong/apiglossary](https://github.com/Kong/apiglossary) (mirror: `.agents/reference/kong-apiglossary.md`) | API and REST terminology |
| dwyl/technical-glossary | raw | [raw.githubusercontent.com/dwyl/technical-glossary/main/README.md](https://raw.githubusercontent.com/dwyl/technical-glossary/main/README.md) (mirror: `.agents/reference/dwyl-technical-glossary.txt`) | Broad technical terms |
| jvalentino/glossary | page | [github.com/jvalentino/glossary](https://github.com/jvalentino/glossary) (mirror: `.agents/reference/jvalentino-glossary.md`) | Software engineering terms |
| GitHub Official Glossary | page | [docs.github.com/.../github-glossary](https://docs.github.com/en/get-started/learning-about-github/github-glossary) (mirror: `.agents/reference/github-official-glossary.md`) | Git and GitHub terms (commit, fork, pull request) |

## Word lists (spelling & allowed vocabulary)

These are the **authority for whether a word is a real English word and how it is
spelled**. STE-Code also uses them to seed and verify its approved dictionary.

| Reference | Type | Source | Use for |
|---|---|---|---|
| ryanwi software-terms.dic | raw | [gist.githubusercontent.com/ryanwi/6135845/raw/software-terms.dic](https://gist.githubusercontent.com/ryanwi/6135845/raw/software-terms.dic) (mirror: `.agents/reference/ryanwi-software-terms.txt`) | Software-domain word list |
| en-wl/wordlist (SCOWL) | page | [github.com/en-wl/wordlist](https://github.com/en-wl/wordlist) (mirror: `.agents/reference/en-wl-wordlist.md`) | Spell-check word lists (many sizes/levels) |
| MichaelWehar 5000-more-common | raw | [raw.githubusercontent.com/MichaelWehar/Public-Domain-Word-Lists/master/5000-more-common.txt](https://raw.githubusercontent.com/MichaelWehar/Public-Domain-Word-Lists/master/5000-more-common.txt) (mirror: `.agents/reference/michaelwehar-5000-common.txt`) | Common-word supplement |
| OpenSTE.org | pointer | [openste.org](https://openste.org/) | Reference implementation of Simplified Technical English |
| dwyl/english-words (POINTER) | pointer | [raw.githubusercontent.com/dwyl/english-words/master/words.txt](https://raw.githubusercontent.com/dwyl/english-words/master/words.txt) | Large general English word list |
| freeDictionaryAPI english.txt (POINTER) | pointer | [raw.githubusercontent.com/meetDeveloper/freeDictionaryAPI/master/meta/wordList/english.txt](https://raw.githubusercontent.com/meetDeveloper/freeDictionaryAPI/master/meta/wordList/english.txt) | General English word list |

## Linters (automated checking)

Use these to **enforce STE-Code-like rules in CI** (prose lints, not compiler
errors). They are the basis for the style checks STE-Code recommends.

| Reference | Type | Source | Use for |
|---|---|---|---|
| Vale linter | page | [github.com/errata-ai/vale](https://github.com/errata-ai/vale) (mirror: `.agents/reference/vale.md`) | Pluggable prose linter for docs/CI |
| errata-ai/Microsoft | page | [github.com/errata-ai/Microsoft](https://github.com/errata-ai/Microsoft) (mirror: `.agents/reference/vale-microsoft.md`) | Microsoft style rules for Vale |
| errata-ai/Google | page | [github.com/errata-ai/Google](https://github.com/errata-ai/Google) (mirror: `.agents/reference/vale-google.md`) | Google style rules for Vale |
| errata-ai/write-good | page | [github.com/errata-ai/write-good](https://github.com/errata-ai/write-good) (mirror: `.agents/reference/vale-write-good.md`) | write-good style rules for Vale |

## Discovery pointers (topic indexes)

Starting points for **finding more word lists and glossaries** if the above do
not cover a term.

| Reference | Type | Source | Use for |
|---|---|---|---|
| GitHub topic: word-list | pointer | [github.com/topics/word-list](https://github.com/topics/word-list) | More word-list repositories |
| GitHub topic: glossary-terms | pointer | [github.com/topics/glossary-terms](https://github.com/topics/glossary-terms) | More glossary repositories |
| GitHub topic: technical-writing | pointer | [github.com/topics/technical-writing](https://github.com/topics/technical-writing) | More technical-writing resources |
| GitHub topic: controlled-vocabulary | pointer | [github.com/topics/controlled-vocabulary](https://github.com/topics/controlled-vocabulary) | More controlled-vocabulary resources |

---

<!-- 08-provenance.md -->

# Level 5 — Provenance

Level 5 is the full STE-Code standard: every rule, the extension vocabulary, the
reference catalogue, and provenance. This sub-document is the **provenance**
slice. It records where the content of the standard comes from, which pipeline
stage produced each part, and what is inside the standard versus what is only an
external input.

Use this file when you must answer one of these questions:

- Which directory holds the authoritative form of a rule, a dictionary entry, or
  an extension term?
- Which stage created a given file, and from what input?
- Is a word list part of STE-Code, or only a reference that informed it?

## Trust order

When two files disagree, the later stage wins:

`extracted` → `refined` → `grouped` → `adapted` → `enriched (final/rules)` → `final`

`ste-code/final/` is the authoritative form of the standard. Every earlier
directory is kept for traceability, not for reuse in generation.

External references never win. They are inputs to vocabulary work only.

## Pipeline stages

| Stage | Source dir | Role |
|---|---|---|
| A Extraction | `ste-code/extracted/` | Specification PDF to structured pages |
| B Refinement | `ste-code/refined/` | Formatted dictionary and rule markdown |
| C Grouping | `ste-code/grouped/` | Semantic slice and concatenation of pages |
| D Adaptation | `ste-code/adapted/` | Code-domain rule rewrite |
| G Enrichment | `ste-code/final/rules/` | Cross-references and traceability |
| E Extension | `ste-code/extensions/` | Code-domain vocabulary gap-fills |
| References | `.agents/reference/` | Vendor and community vocabulary (catalogued) |

The stages are consolidated into `ste-code/final/` by `assemble_final.py`.

## Stage notes

- **A Extraction** reads the source specification and writes one markdown page
  per specification page. No rewriting occurs at this stage.
- **B Refinement** applies formatting rules only. Dictionary pages become
  tables; rule pages keep the original rule text and its examples.
- **C Grouping** is deterministic. It moves bytes: it slices and concatenates
  refined pages into semantic groups. It does not generate text, so no content
  can be lost or invented here.
- **D Adaptation** re-expresses each rule in the code domain. It keeps the
  original rule statement for traceability and adds a code-domain form and
  code-domain examples.
- **G Enrichment** adds cross-references between rules and the traceability
  links back to the adapted and refined sources.
- **E Extension** adds vocabulary that the code domain needs and the source
  standard does not supply. Extension entries are marked as extensions; they are
  not presented as original rules.

## Inside and outside the standard

| Item | Location | In the standard? |
|---|---|---|
| Rules | `ste-code/final/rules/` | Yes |
| Dictionary and extension vocabulary | `ste-code/extensions/` | Yes |
| Reference catalogue | `ste-code/final/reference-catalogue.md` | Yes, as a catalogue |
| Vendor and community word lists | `.agents/reference/` | No |
| Pipeline tools, state, and logs | `.agents/` | No |

The reference catalogue is part of the standard, but the referenced material is
not. The catalogue records what informed the controlled vocabulary so that a
reader can audit a term without the standard shipping third-party content.

## Reference catalogue (summary)

These external sources inform the STE-Code controlled vocabulary. They are not
part of the standard.

| Reference | Type | Use |
|---|---|---|
| Microsoft Writing Style Guide | page | Plain-language and terminology guidance |
| MicrosoftDocs/microsoft-style-guide | page | Source form of the style guide |
| Google Style Guides | page | Code and documentation conventions |
| Kong/apiglossary | page | API terminology |
| dwyl/technical-glossary | raw | General technical terms |
| jvalentino/glossary | page | General technical terms |
| GitHub Official Glossary | page | Repository and workflow terms |
| DevOps Style Guide Glossary | page | Build, deploy, and operations terms |
| ryanwi software-terms.dic | raw | Software spelling dictionary |
| OpenSTE.org | pointer | Simplified Technical English community work |
| en-wl/wordlist (SCOWL) | page | Word-list coverage checks |
| MichaelWehar 5000-more-common | raw | Common-word frequency checks |
| dwyl/english-words | pointer | Word-list coverage checks |
| freeDictionaryAPI english.txt | pointer | Word-list coverage checks |
| Vale linter | page | Rule enforcement tooling |
| errata-ai/Microsoft | page | Vale rule set |
| errata-ai/Google | page | Vale rule set |
| errata-ai/write-good | page | Vale rule set |
| GitHub topics: word-list, glossary-terms, technical-writing, controlled-vocabulary | pointer | Discovery of further vocabulary sources |

The full catalogue, with the retrieval URL and the local cached file for each
entry, is in `ste-code/final/reference-catalogue.md`.

## Traceability contract

Every rule in `ste-code/final/rules/` can be traced back through the stages:

1. The adapted rule keeps the **original rule statement**, so a reader can
   compare the code-domain form against the source form.
2. The refined page keeps the **source page identifier**, so the adapted rule
   maps to a specific page of the source specification.
3. The extracted page is the raw form of that same page.

If a rule cannot be traced to a refined page, it is an **extension**, not an
adapted rule, and it must be labelled as such.

## Rules for an LLM that uses this file

- Cite `ste-code/final/` when you quote the standard. Do not cite
  `ste-code/extracted/`, `ste-code/refined/`, or `ste-code/grouped/`.
- Do not present an extension term as a rule from the source specification.
- Do not add a word to the controlled vocabulary because it appears in a
  reference in `.agents/reference/`. A reference is evidence, not approval.
- If a term is not in the controlled terminology and not in the extensions, say
  that it is not approved. Do not invent an entry.

---

<!-- rules-sec1-part1.md -->

# Level 5 — Section 1 Rules, Part 1 (Words: 1.1–1.4, 1.10–1.14)

Level 5 is the full STE-Code standard. This sub-document is **Section 1, part 1**:
the nine word-level rules that decide *which words you may use, in what form, with
what meaning, and under which name*.

Rules in this part: **1.1, 1.2, 1.3, 1.4, 1.10, 1.11, 1.12, 1.13, 1.14**.
Rules 1.5–1.9 (technical-noun categories) are in Section 1, part 2.

Use this file when an LLM generates, rewrites, or reviews code documentation:
READMEs, API reference, docstrings and inline comments, commit messages, error
messages, and log output.

## How to apply this part

1. **Gate every word** (Rule 1.1): approved word, code-domain technical noun, or
   code-domain technical verb. Nothing else.
2. **Check the part of speech** (Rule 1.2) and the **meaning** (Rule 1.3).
3. **Check the form** (Rule 1.4): only the listed verb and adjective forms.
4. **Check the name** (Rules 1.10, 1.11): no slang or jargon; one name per item.
5. **Check verb use** (Rules 1.12, 1.13): technical verbs only where an approved
   verb is not sufficient, and never as nouns.
6. **Check the spelling** (Rule 1.14): American English, except in quoted text.

| Rule | Statement | One-line test |
|------|-----------|---------------|
| 1.1 | Use approved words, code-domain technical nouns, or code-domain technical verbs. | Does the word pass one of the three gates? |
| 1.2 | Use approved words only as the specified part of speech. | Is the word used as the part of speech it is approved for? |
| 1.3 | Use approved words only with their approved meanings. | Does the sentence use the one approved meaning? |
| 1.4 | Use only the approved forms of verbs and adjectives. | Is the form in the entry (no invented or `-ing` forms)? |
| 1.10 | Do not use regional, slang, or jargon words as code-domain technical nouns. | Would a developer from another community understand it? |
| 1.11 | Do not use different code-domain technical nouns for the same item. | Is this item called the same thing everywhere? |
| 1.12 | You can use verbs you can include in a code-domain technical verb category. | Is an approved verb sufficient instead? |
| 1.13 | Do not use code-domain technical verbs as nouns. | Is the action written as a verb, not as "do a X"? |
| 1.14 | Use American English spelling unless official directives tell you differently. | Is every unquoted word spelled American English? |

---

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

In code documentation, use words that are:

- approved in the controlled terminology (part 2),
- code-domain technical nouns (Rule 1.5), or
- code-domain technical verbs (Rule 1.12).

A **code-domain technical noun** is a noun term for a specified concept in software
development, applicable to a subject field. A **code-domain technical verb** is a
verb term for a specified operation or process in software development.

The controlled terminology also lists words that are **not** approved, with the
approved alternative. Your project glossary or terminology database holds the
technical nouns and verbs; check it first, then this rule.

Rule 1.1 is the gatekeeping rule: every word in every sentence must pass one gate.
Names of tools, files, commands, classes, and endpoints are technical nouns and do
not need approval. The prose around them does.

### Core substitutions

| Do not write | Write |
|--------------|-------|
| execute | run |
| generate, construct | make |
| configure | set |
| retrieve, fetch | get |
| transmit | send |
| delete, purge | remove |
| validate, verify, ensure | check |
| utilize, leverage | use |
| bootstrap, initiate, commence | start |
| terminate | stop |
| perform | do |
| unable to | cannot |
| invalid, malformed | incorrect, not correct |
| duration | time |
| prior to | before |
| implement | add, make |
| optimize (prose) | make faster, make smaller |

### By documentation type

- **README** — procedural sections take approved imperative verbs; descriptive
  sections take approved adjectives and adverbs ("large" not "substantial",
  "usual" not "conventional", "correct" not "valid").
- **API reference** — names are technical nouns; return, parameter, and error prose
  uses approved verbs.
- **Docstrings and comments** — shortest approved word available. `NOTE:` and
  `WARNING:` are approved nouns; `FIXME:` is a code-domain technical noun.
- **Commit messages** — the smallest vocabulary of all: add, fix, remove, update,
  set, make, check, run. "refactor" is allowed as a technical verb (Rule 1.12).
- **Error messages** — read by end users; no jargon, no slang, no abbreviation
  that is not a technical noun.

### Examples

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

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

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

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

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

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

### Paradigm notes

- **Object-oriented** — class, method, interface, and pattern names are technical
  nouns (Rules 1.5, 1.6). In prose: make (not instantiate), get (not retrieve), set
  (not assign), call, send, keep (not maintain), "is a" / "has a".
- **Functional** — pure, immutable, monad, closure, higher-order function are
  technical nouns. map, fold, reduce, filter, compose, curry are technical verbs
  (Rule 1.12). "Apply" and "pure" carry both an approved sense and a functional
  sense; both are valid.
- **Procedural** — one approved imperative verb per step.
- **Declarative and systems** — keyword names are technical nouns; the surrounding
  instruction uses approved verbs.

### Edge cases

- A framework name that is also a common word (Rails, Spring, Django, Flask) is a
  technical noun when capitalized as a proper noun.
- Code keywords (`goto`, `break`, `continue`, `finally`) keep their code meaning;
  do not use them colloquially.
- Generated documentation (OpenAPI output, JSDoc stubs, godoc) may not follow the
  rule; human-written prose inside it must.
- A technical verb used inside a compound term is part of a technical noun.
- Loanwords and non-English words are not approved unless they are technical nouns.

---

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

Each entry in the controlled terminology gives one part of speech. Use the word
only as that part of speech.

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

When you replace a word, check that the replacement does not change the meaning.
If it does, restructure the sentence.

If a word is not in the controlled terminology:

1. Find the word in a standard English dictionary.
2. Find the best synonym that is approved in the controlled terminology.
3. Use that approved word, or build a different sentence from approved words.

### Part-of-speech violation table

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

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

### Examples

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

> **Non-STE (comment):** `# Static the cache size so the value does not change.`
>
> **STE (comment):** `# Make the cache size static so the value does not change.`

> **Non-STE (comment):** `# Terraform the VPC, then Kubectl the pods into the cluster.`
>
> **STE (comment):** `# Use Terraform to make the VPC. Use kubectl to apply the pod configuration to the cluster.`

---

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

An approved word carries exactly one approved meaning. Using the right word with
the wrong meaning is the most common class of documentation error.

### Procedure

1. Identify the part of speech of the word.
2. Read the approved meaning in the controlled terminology.
3. Compare it to the meaning you intend.
4. If they do not match, use a different approved word or restructure.

### Most-misused approved words

| Approved word | Approved meaning (only this) | Wrong meaning to avoid | Use instead |
|---------------|------------------------------|------------------------|-------------|
| run | execute a program or command | operate, manage, continue | operate, manage, continue |
| return | send a value back from a function to its caller | go back to a state or location | go back |
| call | invoke a function, method, or subroutine | name something | name, refer to as |
| get | fetch or retrieve data from a source | become, understand | become, understand, receive |
| set | put a value into a variable or configuration | become solid, prepare | become solid, prepare |
| make | bring into existence by building or assembling | force, earn | cause, earn |
| send | transmit data to a destination | cause a person to go | cause to go |
| raise | cause an exception or error to occur | increase, lift | increase, lift |
| catch | handle or intercept an exception | capture, become trapped | capture, become trapped |
| pass | give data as an argument to a function | go past, succeed | go past, succeed, give |
| check | examine something to determine correctness or state | stop, restrain | stop, leave |
| break | exit a loop or switch statement immediately | divide, damage, interrupt | split, damage, interrupt |
| continue | skip to the next iteration of a loop | keep doing without interruption | keep |
| fail | an operation did not complete successfully | not pass a test | not pass |
| move | transfer ownership of a value (Rust) | change physical position | go, change position |
| borrow | take a reference without taking ownership | take temporarily | take temporarily |
| follow | come after, go after | act in accordance with | obey |

### Examples

> **Non-STE:** Follow the configuration steps to set up the server.
>
> **STE:** Obey the configuration instructions to set up the server. Then do the
> steps that follow.

> **Non-STE (docstring):** `"""The function will return you to the login screen."""`
>
> **STE (docstring):** `"""The function will go back to the login screen."""`

> **Non-STE:** The background worker runs every night.
>
> **STE:** The background worker operates every night.
> *(The writer means "operates on a schedule", not "executes a program".)*

> **Non-STE (comment):** `# We call this pattern the Repository Pattern.`
>
> **STE (comment):** `# We name this pattern the Repository Pattern.`

> **Non-STE (comment):** `# The middleware serves the cached page and then returns.`
>
> **STE (comment):** `# The middleware gives the cached page to the user and then goes back.`

---

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

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

**Verbs** — `COMPILE (v), COMPILES, COMPILED, COMPILED`

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

Forms that are not listed are not allowed: "compilating" and "compilates" are not
forms of "compile".

**Adjectives** — `FAST (adj) (FASTER, FASTEST)`

Base: fast · Comparative: faster · Superlative: fastest.
Adjectives that form the comparative with "more" and "most" have no listed forms,
because "more" and "most" are approved words.

### Form rules by documentation type

- **README** — imperative (base form) for procedures; simple present for
  description. Do not use the `-ing` form as a main verb.
- **API reference** — simple present, third person singular, because the subject is
  the function: "gives", "accepts", "fails". `GIVE (v), GIVES, GAVE, GIVEN`. The
  past participle is an adjective ("the given input"), not a main verb.
- **Docstrings** — imperative for the first line, simple present for the rest. Do
  not mix forms for the same kind of content.
- **Commit messages** — imperative base form only. Not "Added", not "Adding".
- **Error messages and logs** — simple present or simple past of listed forms only.

### Examples

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

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

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

> **Non-STE (API):** This method is returning a sorted list of users. It is
> accepting an optional filter parameter and is throwing an error when the query is
> failing.
>
> **STE (API):** This method gives a sorted list of users. It accepts an optional
> filter parameter and gives an error when the query fails.

> **Non-STE (commit):** `Fixed memory leak in connection pool and adding timeout configuration`
>
> **STE (commit):** `Fix memory leak in connection pool and add timeout configuration`

---

<!-- rules-sec1-part2.md -->

# Level 5 — Section 1 (Part 2): Rules 1.5–1.9 (Code-Domain Technical Nouns)

This slice covers the five STE-Code rules that govern **code-domain technical nouns** —
the domain-specific vocabulary (class names, libraries, protocols, algorithms, defects,
infrastructure terms) that is permitted in documentation even though it is not in the
approved STE-Code dictionary.

Read this slice together with `rules-sec1-part1.md` (Rules 1.1–1.4) and
`rules-sec1-part3.md` (Rules 1.10–1.14).

## Purpose and scope

- Rule 1.5 — which words may appear as code-domain technical nouns (the 19 categories).
- Rule 1.6 — the *gate*: a non-approved word is allowed only as a technical noun.
- Rule 1.7 — a technical noun must never be used as a verb.
- Rule 1.8 — when several names exist, use the standard/approved one.
- Rule 1.9 — when you must choose a technical noun, pick the shortest unambiguous form.

These five rules answer: *"Is this word allowed, and if so how should I write it?"*

## How the five rules interact

```
Word in documentation?
 ├─ approved STE-Code word (Rule 1.1) ──────────────► use it as its part of speech (Rule 1.2)
 └─ not approved
      └─ is it a code-domain technical noun? (Rule 1.5 / 1.6 gate)
           ├─ NO  ───────────────────────────────────► forbidden (replace with approved word)
           └─ YES
                ├─ use the STANDARD name (Rule 1.8)
                ├─ use the SHORTEST form (Rule 1.9)
                ├─ keep it a NOUN (Rule 1.7) ── not a verb
                └─ register it in the project glossary
```

---

# Rule 1.5 — Use Words That You Can Include in a Code-Domain Technical Noun Category

**Statement:** You may use a word that names a precise code-domain concept if it fits one
of the nineteen categories below. Such words are *code-domain technical nouns* and are
allowed even though they are not in the approved STE-Code dictionary.

The dictionary cannot list every technical noun (there are too many, and each project uses
different ones). Register every technical noun you use in your **project glossary** with:
its term, its category, its approved meaning, and an example sentence.

## The nineteen categories

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

The lists above are **examples only** — Rule 1.5 does not give a complete list of every
possible code-domain technical noun.

## Relationship to other rules

- **Rule 1.1** (approved words): use an approved word whenever one exists. Use a
  code-domain technical noun only when no approved word names the concept.
- **Rule 1.6** (non-approved words as technical nouns): a non-approved word must belong to
  at least one of these nineteen categories to appear at all.

## Quick application guidance

| Documentation type | Primary categories | Example |
|---|---|---|
| README | 1, 3, 5, 17 | "This package provides a middleware for Express." |
| API documentation | 6, 18, 19 | "The `GET /users/:id` route returns a JSON object with a user struct." |
| Docstrings/comments | 4, 7, 15 | "Traverse the binary search tree in-order and return a sorted array." |
| Commit messages | 1, 15, 18 | "Fix race condition in the connection pool that caused a deadlock on PostgreSQL." |
| Error messages | 13, 15, 19 | "Connection refused: the TCP socket on port 5432 timed out after 30 seconds." |
| Test specs | 1, 4, 15 | "The test calls `parseConfig` with a null pointer and checks for an assertion failure." |

## Edge cases

- **Framework names that are also common words** (`React`, `Go`, `Rust`, `Swift`, `Vue`):
  treat as code-domain technical nouns (category 3 or 5); capitalize to distinguish from
  the English verb ("the Swift language", "the Rust compiler").
- **Code keywords in prose** (`if`, `for`, `class`, `return`): when quoted/backticked they
  are category 10; when used as English words they must follow approved meanings.
- **Abbreviations/acronyms** (`API, JSON, SQL`): allowed; define at first use unless
  universally understood by the audience.
- **Project-internal names** (`PhoenixCache`): allowed only if registered in the glossary.
- **Numbers as named tokens** (`Node.js 18`, `404`, `port 5432`): quoted text or category 9;
  must appear verbatim.

<!-- END-RULE-1.5 -->

---

# Rule 1.6 — Use a Non-Approved Word Only As a Code-Domain Technical Noun

**Statement:** A word that is not approved in the controlled terminology may appear only
when it is a code-domain technical noun, or part of one (Rule 1.5).

This is a **gate** with three tests. An unapproved word may stay only if it clears all three.

## The Technical Noun Gate — three tests

| Test | Question | Pass | Fail |
|---|---|---|---|
| 1 | Is the word unapproved? | approved words skip the gate entirely | — |
| 2 | Is it a technical noun, or part of a compound technical noun (19 categories)? | standalone noun or recognized compound | replace with approved word |
| 3 | Is it used as a noun in the sentence? | noun role | verb/adjective role → replace |

Worked trace — *"The main config loader backups the data through the handler pipeline."*

| Phrase | T1 unapproved? | T2 technical noun? | T3 noun? | Result |
|---|---|---|---|---|
| main config loader | yes | "main" is a general adjective, not a recognized compound | — | "main" → "primary" |
| backups | yes | "backup" as a verb is not a noun | used as verb | "makes an auxiliary copy" |
| handler pipeline | yes | "handler + pipeline" not a recognized compound | fails T2 | "processing pipeline" |

Result: *"The primary config loader makes an auxiliary copy of the data through the
processing pipeline."*

## Key dictionary entries

- **BASE (n) — UNAPPROVED.** Alternatives: BOTTOM (surface/stack), ROOT (filesystem).
  Allowed in compounds: `base case` (cat 7), `base class` (cat 1), `base URL` (cat 8).
- **MAIN (adj) — UNAPPROVED.** Alternative: PRIMARY. Allowed in `main branch` (cat 5),
  `main()` / main function (cat 1, entry point).
- **HANDLER (n) — UNAPPROVED.** Alternative: FUNCTION. Allowed in `event handler`,
  `request handler` (cat 1).
- **BACKUP (n, v) — UNAPPROVED.** Alternatives: AUXILIARY (adj), "makes an auxiliary copy"
  (verb). Allowed in `backup file`, `backup_logs` (cat 18), `/api/v1/backup` (cat 19).
- **BOTTOM, FUNCTION, PRIMARY, AUXILIARY, ROOT** — APPROVED (use these as replacements).

## Compound technical noun checklist

A compound counts as a code-domain technical noun only if ALL are true:
1. The words name one concept the domain recognizes.
2. The compound fits one of the 19 categories.
3. Swapping the unapproved word for its approved alternative changes the recognized name
   and causes confusion.

Criterion: does the compound appear in the framework/language/standard official docs?
Yes → technical noun. No → replace the unapproved words with approved ones.

## Most-used categories for Rule 1.6

1 (code components), 3 (dev tools), 5 (infrastructure), 7 (algorithmic), 8 (directory
hierarchy), 18 (database), 19 (computer science/network).

## Examples

- *"The handler processes each incoming event."* → *"The function processes each incoming
  event."* (standalone "handler" is unapproved).
- *"The event handler processes each incoming event."* → STAYS (compound technical noun, cat 1).
- *"The main configuration has the latest values."* → *"The primary configuration…"*
  ("main" as adjective fails; "main branch" would stay).
- *"Check out the main branch, then copy the files to the base of the build folder."* →
  *"…to the bottom of the build folder."* ("base" as surface word → "bottom").

## Edge cases

- **Framework name used as general verb** — `pandas` stays; "data-frame" verb → "load … into
  a data frame".
- **Code keyword as general noun** — "The `class` of objects…" → "category"; keyword
  `return` stays backticked.
- **Invented compounds** (`handler pipeline`, `backup orchestrator`, `main dispatcher`) —
  not recognized → restructure with approved words.
- **Generated docs** — fix the *source* (docstrings/comments), not the generated output.
- **Brand names** — always technical nouns; descriptive echoes still reviewed.

<!-- END-RULE-1.6 -->

---

# Rule 1.7 — Do Not Use Words That Are Technical Nouns as Verbs

**Statement:** Use a code-domain technical noun only as a noun (or as an adjective inside a
compound technical noun). Do **not** use it as a verb.

The repair pattern: use an approved verb followed by the noun in a prepositional phrase.
*Cache the data* → *Put the data in the cache*. *Database the records* → *Store the records
in the database*. *Queue the jobs* → *Put the jobs in a queue*.

## The dual-category exception

Some words are cataloged in **both** a noun category (Rule 1.5) and a verb category
(Rule 1.12). Then the verb form is allowed **in its approved verb sense** only. Decide in
your glossary which part of speech the word has and obey that decision.

| Word | Noun (Rule 1.5) | Verb (Rule 1.12) |
|---|---|---|
| cache | cat 16: "The cache stores responses." | cat 2c: "Cache the responses." |
| log | cat 18: "Write a log entry." | cat 2c: "Log the error." |
| queue | cat 4: "Add the job to the queue." | cat 3a: "Queue the job." |
| filter | cat 4 / 16 | cat 2b: "Filter the results." |
| sort | cat 7 | cat 2b: "Sort the list by name." |
| map | cat 4 | cat 3a: "Map the function over the list." |

RULE: if a word is cataloged as a noun only → obey Rule 1.7. If both → use the verb form
only when the context matches the verb category. Keep noun and verb uses distinct
(*"Log the error and write the entry to the log file"*, not *"Log the log to the log"*).

## Common noun→verb violations by paradigm

| Paradigm | Noun | Wrong (verb) | Right construction |
|---|---|---|---|
| OOP | interface | "Interface the module with…" | "Add an interface between the module and…" |
| OOP | class / singleton / factory | "Class the model." / "Singleton the logger." | "Make a class for…" / "Make the logger a singleton." |
| Functional | monad / functor | "Monad the value." | "Wrap the value in a monad." |
| Functional | closure / lambda | "Closure the var." | "Capture the var in a closure." |
| Procedural | buffer / pointer / heap | "Buffer the output." | "Write the output to a buffer." |
| Declarative | table / schema / index | "Schema the database." | "Apply a schema to the database." |
| Systems | mutex / semaphore / DMA | "Mutex the state." | "Lock the mutex for the state." |

## Tool, brand, and protocol names

These are always code-domain technical nouns — never verbs.

- *"Docker the application, Git the changes"* → *"Containerize the application, commit the changes."*
- *"Google the error, Slack the results"* → *"Search for the error with Google, send the results with Slack."*
- *"Kubernetes the microservices, Terraform the infra"* → *"Deploy the microservices with Kubernetes, provision the infra with Terraform."*
- *"JSON the response, HTTP it to the client"* → *"Encode the response as JSON, send it through HTTP."*
- *"Microservice the monolith, API the services"* → *"Break the monolith into microservices, add an API for each service."*

## Multi-word technical nouns

Keep the full phrase; do not drop a word to make a verb.

- *"Load balance the requests"* → *"Distribute the requests with a load balancer."*
- *"Rate limit the clients"* → *"Set a rate limit for the clients."*
- *"Feature flag the endpoint"* → *"Put the endpoint behind a feature flag."*
- *"Circuit break the service"* → *"Apply a circuit breaker to the service."*

## Edge cases

- **Framework names that are also English verbs** (`React`, `Go`, `Spring`, `Express`) —
  stay nouns: *"Write the middleware with Express and respond to changes with React."*
- **Code keywords as verbs** (`class`, `import`, `return`, `yield`) — refer to them as
  backticked nouns; use approved verbs for the action. (Note: `return` is itself an approved
  verb; format the keyword as `` `return` `` when naming the construct.)
- **Generated symbol names** (`toJson()`, `UserBuilder`) — exempt; refer to them as nouns
  in prose ("makes a `User` object", "encodes output as JSON").

## Preposition-phrase repair reference

| Noun-verb | Repair | Verb | Prep |
|---|---|---|---|
| Cache the data | Put the data in the cache | put | in |
| Queue the job | Add the job to the queue | add | to |
| Buffer the output | Write the output to a buffer | write | to |
| Socket the connection | Send the connection through a socket | send | through |
| Database the records | Store the records in the database | store | in |
| Docker the app | Package the app in a container | package | in |
| JSON the response | Encode the response as JSON | encode | as |

<!-- END-RULE-1.7 -->

---

# Rule 1.8 — Use Code-Domain Technical Nouns Approved in Your Project, Company, Industry, or Subject Field

**Statement:** When more than one name exists for a code concept, use the name from the most
authoritative source. Do not invent names for items that already have established names in
your codebase or domain. Consistency lets readers find the exact element in the source tree.

## Authority hierarchy (highest first)

1. **Source code** — class names, function names, file names, variable names, type names.
2. **Language specification** — keyword names, standard-library names, built-in types.
3. **Framework/library documentation** — API names, component names, hook names, config keys.
4. **Project glossary** — project-specific terms registered under Rule 1.5.
5. **Industry standard** — design-pattern names, protocol names, algorithm names, architecture names.
6. **Company documentation** — internal system/service/team names.

When the codebase name differs from the industry name, mention both with clear context:
codebase name for traceability, industry name for comprehension. Never mix names from
different levels for the same concept in one document.

## Paradigm reference: avoid → use

| Paradigm | Avoid (invented) | Use (approved) | Authority |
|---|---|---|---|
| OOP | user manager / user handler | `UserRepository` | source code |
| OOP | maker pattern | Factory pattern | pattern literature |
| OOP | data layer / DB interface | `IRepository<T>` | source code |
| Functional | maybe-type / chain functions | `Option` / `None`, pattern matching | language stdlib |
| Functional | higher-order function? (keep) | Higher-order function | math terminology |
| Procedural | heap allocation / data record | `malloc`, `struct`, `pointer` | C spec |
| Procedural | green process | `goroutine` | Go spec |
| Declarative | compute instance | `aws_instance` | Terraform provider docs |
| Declarative | retrieval query | `SELECT` statement | SQL standard |
| Systems | ownership handoff | `move` semantics, `borrow` | Rust reference |
| Systems | thread lock | `Mutex` | stdlib |

## Key principles

- Use exact class/function/type names from the source; do not substitute descriptive phrases
  (*"account controller"* → `AccountController`).
- Use exact protocol/algorithm/framework feature names (*"secure web communication"* →
  `HTTPS`; *"function that manages state and side effects"* → `useEffect`).
- **Define each acronym at first use**, then use only the acronym (*"application programming
  interface (API) … The API returns JSON"*). Alternating full form and acronym implies two
  concepts (violates Rule 1.11).
- Keep the capitalization/spelling of the approved name exactly as in the source
  (`userService`, `findById`, `DATABASE_URL`).
- When a framework renames a standard concept (Django "view", Rails "partial"), use the
  framework's own term in framework-specific docs.
- During a migration, use the **target** name; show the old name only as quoted/DEPRECATED.

## Edge cases

- **Codebase uses a non-standard name** (e.g. `DataStore` for a Repository) — use the
  codebase name; optionally note the industry pattern ("`DataStore` (a Repository
  implementation)").
- **Two industry standards compete** (callback/handler/listener; map/dictionary/object) —
  pick one, register it, use it consistently (Rule 1.11); prefer the ecosystem name.
- **Approved name is an acronym** (API, JSON, JWT) — define at first use unless universal.
- **Framework renames a standard concept** — use framework's term in its own docs.
- **Name changes during refactor** — use the new name; mark the old one DEPRECATED.
- **Same package, different registries** (`python-dotenv` on PyPI vs `dotenv` on npm) — use
  the ecosystem-specific name in installation instructions.

<!-- END-RULE-1.8 -->

---

# Rule 1.9 — When You Must Select a Technical Noun, Use One That Is Short and Easy to Understand

**Statement:** When no code-domain technical noun is approved in your project/industry,
select one that is **short (not more than three words)** and easy to understand. Do not use
long descriptive phrases when a shorter term is sufficient. If the context already
identifies the item, use the shortest unambiguous term; add one or two adjectives only when
needed for disambiguation.

## Core insight: context permits brevity

Context sources that make a short term sufficient: a code reference (line number, function
name, file path), a diagram, a preceding definition, an API spec, or a code snippet that
follows the prose. The code itself carries the detail — the prose only needs to name it.

Examples:
- *"asynchronous JavaScript XML HTTP request wrapper utility function (line 42)"* →
  *"`fetchUtility` function (line 42)"*
- *"user account profile information data transfer object"* → *"`UserProfileDTO`"*
- *"multi-platform containerized microservice orchestration and deployment management layer"*
  → *"the Kubernetes cluster"*
- *"the relational database management system server instance"* → *"the database"*

## Long phrase → short form reference

| Long phrase | Short STE form | Context that permits it |
|---|---|---|
| asynchronous JS XML HTTP request wrapper utility function | fetch utility | line number + snippet |
| serialized JSON payload from the remote API endpoint | JSON data from the API endpoint | field name + type |
| user account profile information data transfer object | `UserProfileDTO` | parameter already named |
| relational database management system server instance | database | port + "primary" |
| mutual exclusion lock primitive with timeout acquisition | mutex | class name in code |
| configuration, settings, and options parameters object | `Config` object | object named `Config` |
| dynamically allocated resizable memory region utility | dynamic array | type declared |

## The three-word limit — rationale and exceptions

The limit (≤3 words) reflects working-memory capacity. Exceptions:
1. **Established technical terms** — "continuous integration pipeline", "abstract syntax
   tree", "public key infrastructure certificate" (standard even if >3 words; do not invent a
   shorter form).
2. **Framework/tool proper names** — "GitHub Actions workflow", "AWS Lambda" (use as given).
3. **Fully qualified type names** — use the short name after first reference
   (`SubComponent` for `com.example.module.SubComponent`).
4. **Shortening causes ambiguity** — keep the longer form; clarity overrides brevity.

## Adjectives: keep only disambiguating ones

- Noise: "the configurable application settings object" (all settings objects are
  configurable), "the secure HTTPS protocol" (HTTPS is secure by definition).
- Disambiguating: "the production application settings object" (prod/staging/dev coexist),
  "the legacy HTTPS endpoint" (old and new coexist).

## Abbreviations and acronyms

- **Universal** (use on first reference, expansion optional): API, JSON, SQL, HTML, HTTP,
  URL, DNS, TCP, TLS, CPU, RAM, SSD.
- **Domain-specific** (expand on first use for a general audience): JWT, CORS, ORM, SPA, SSR.
- **Project-specific** (define on first use in every document; accepted only after defined).
- Do **not** invent new abbreviations to satisfy brevity (Rule 1.8 — use the recognized term).

## Paradigm guidance

- **OOP:** use the class name; state inheritance in a separate sentence
  (*"`UserRepository` extends `BaseRepository<User>`"*), not six stacked modifiers.
- **Functional:** name the *result*, not the whole data-flow chain (*"The fold function. It
  reduces a collection to a single value."*).
- **Procedural:** name the function; let the signature carry types (*"The `fprintf`
  function. It writes formatted output to a file descriptor."*).
- **Declarative:** name the resource type; describe config in bullets/table
  (*"The `HorizontalPodAutoscaler` resource. Set min/max replicas."*).
- **Systems:** use short terms (*reference, borrow, lifetime*); the compiler enforces
  guarantees — describe what the programmer controls, not what the compiler prevents.

## Edge cases

- **Short term less well-known than long** (e.g. `AST`) — expand on first use
  ("abstract syntax tree (AST)"), then use the short form. Test: would a 1-year-experienced
  developer in this domain understand it?
- **Framework name is also a short word** (`React`, `Go`) — use as modifier ("the React
  framework") on first use; do not invent abbreviations like "Rkt".
- **Codebase uses long names internally** (`AbstractUserAuthenticationProviderFactoryBean`)
  — Rule 1.8 wins: use the codebase name as given; use a short prose alias only in surrounding
  text ("the factory bean").
- **Shortening creates a homonym** (`pool` = thread/connection/object) — keep the disambiguating
  modifier ("connection pool", "thread pool") when both appear.
- **Generated docs** — auto-generated portions exempt; human-written summaries/descriptions
  must obey the rule.

---

## Cross-references (Rules 1.5–1.9)

- **Rule 1.1 (Approved Words)** — use approved words for common vocabulary; technical nouns
  supply domain terms.
- **Rule 1.2 (Part of Speech)** — technical nouns are nouns; noun-verbing violates it (Rule 1.7).
- **Rule 1.3 (Approved Meanings)** — a technical noun has its registered meaning only.
- **Rule 1.5 (Technical Noun Categories)** — defines which words qualify (this slice).
- **Rule 1.6 (Non-Approved Words as Technical Nouns)** — the gate; pairs with Rule 1.5.
- **Rule 1.7 (No Noun-Verbing)** — technical nouns stay nouns.
- **Rule 1.8 (Standard Technical Nouns)** — choose the approved name among candidates.
- **Rule 1.9 (Short Technical Nouns)** — choose the shortest unambiguous form.
- **Rule 1.10 (No Slang/Jargon)** — invented names are forbidden; use the standard noun.
- **Rule 1.11 (One Term per Concept)** — use the chosen name consistently everywhere.
- **Rule 1.12 (Technical Verbs)** — permits verb forms in the dual-category exception.
- **Rule 1.13 (No Verb-as-Noun)** — inverse of Rule 1.7 for verbs.
- **Rule 1.14 (American English Spelling)** — follow the spec's spelling for spec-defined names.

<!-- END-SLICE -->

---

<!-- rules-sec2.md -->

# Level 5 — Section 2: Technical Nouns (Rules 2.1–2.3)

Source: ASD-STE100 Issue 9, Section 2, adapted for code documentation.
Scope: how to write technical nouns — module names, class names, config keys,
endpoint paths, error types, test fixtures — in API docs, READMEs, commit
messages, runbooks, and code comments.

Section rule set:

| Rule | Title | One-line intent |
|---|---|---|
| 2.1 | Keep technical nouns short | Split noun chains with prepositions (`of`, `on`, `in`, `for`). |
| 2.2 | Write long technical nouns in full | More than three words: write in full on first use, then use a short form or approved abbreviation. |
| 2.3 | Use hyphens between words used as one unit | Hyphenate a related pair; never chain more than three words. |

Shared constraints for the whole section:

- A noun phrase is at most three words. A hyphenated unit counts as one word.
- Use approved verbs: `set`, `get`, `make`, `show`, `check`, `remove`, `send`,
  `start`, `stop`, `use`, `update`. Do not use `configure` for `set`,
  `retrieve` for `get`, `delete`/`purge` for `remove`, `display` for `show`.
- Use short, plain words. Not `utilize`, `leverage`, `employ` — use `use`.
  Not `commence`, `initiate`, `terminate` — use `start` and `stop`.
- Approved code-domain adjectives stay attached to the short noun they modify:
  `idempotent`, `immutable`, `thread-safe`, `atomic`, `nullable`, `deprecated`,
  `stateless`, `backward-compatible`, `asynchronous`, `concurrent`,
  `deterministic`.

---

## Rule 2.1 — Keep Technical Nouns Short

> Source: ASD-STE100 Issue 9, Rule 2.1 · Group 005-rules-sec-2 · Alphabetical key 2

### Rule

To keep multi-word technical nouns short, use prepositions (`of`, `on`, `in`,
`for`) and explain the multi-word technical noun. When a phrase names a code
component with more than a few words, break the phrase into small nouns that
connect with prepositions. Do not write one long noun that stacks modifiers.

### Why it matters in code documentation

- A stacked noun such as `authentication_token_expiration_refresh_interval_setting`
  hides which part owns which. Short nouns with prepositions show the tree.
- Short technical nouns match how code is already structured: a config key, a
  class, or a JSON field is one short concept.
- Long merged nouns are hard to grep, hard to scan, and easy to parse wrongly.

### Procedure

1. Find a noun that stacks two or more modifiers (a "noun chain").
2. Split the chain at the ownership or containment points.
3. Connect the parts with `of`, `on`, `in`, or `for`.
4. If a part is itself a code component, name it with its short technical noun
   (its class, key, or file), not a merged word.
5. In instruction text, use the approved verbs.

### Examples

#### Configuration key — auth token refresh

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

```yaml
# STE-Code: short keys, one concept per level
auth:
  token:
    expiration:
      refresh_interval_seconds: 300

# Non-STE: one long key hides the relationship (do not write this)
authentication_token_expiration_refresh_interval_setting: 300
```

```python
def get_refresh_interval(token):
    """Return the setting of the refresh interval of the expiration of the authentication token."""
    return token.expiration.refresh_interval_seconds
```

#### Deployment labels — middleware config

> **Non-STE:** Install the forward service request validator middleware config tags.
>
> **STE:** Install the config tags on the validator middleware of the request of the forward service.

```bash
kubectl label pods \
  -l app=forward-service \
  middleware=validator \
  config=enabled
```

#### Cleanup task — migration lock files

> **Non-STE:** Remove the database migration script output directory lock files.
>
> **STE:** Remove the lock files that lock the output directory of the migration script of the database.

Use the approved verb `remove`, not `delete` or `purge`.

```python
from pathlib import Path

def remove_migration_lock_files(db_name: str) -> int:
    """Remove the lock files that lock the output directory of the migration script of the database."""
    output_dir = Path("migrations") / db_name / "output"
    removed = 0
    for lock in output_dir.glob("*.lock"):
        lock.unlink()
        removed += 1
    return removed
```

```python
def test_remove_migration_lock_files(tmp_path):
    out = tmp_path / "app" / "output"
    out.mkdir(parents=True)
    (out / "write.lock").write_text("")
    count = remove_migration_lock_files("app")
    assert count == 1
    assert not any(out.glob("*.lock"))
```

#### Test setup — cache hook alignment

> **Non-STE:** Adjust to obtain cache invalidation hook alignment with the event emitter.
>
> **STE:** Adjust the cache invalidation hook until it aligns with the event emitter.

```python
import time

def align_cache_hook(hook, emitter, timeout: float = 5.0) -> bool:
    """Adjust the cache invalidation hook until it aligns with the event emitter."""
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        if hook.target is emitter:
            return True
        hook.nudge()
    return False
```

#### API documentation — retry policy

> **Non-STE:** Payment gateway timeout retry exhaustion notification handler.
>
> **STE:** Handler of the notification of the exhaustion of the retry of the timeout of the payment gateway.

```python
class PaymentGatewayTimeoutRetryExhaustionNotificationHandler:
    """Handler of the notification of the exhaustion of the retry of the timeout of the payment gateway."""

    def handle(self, notice) -> None:
        log.error("retry of the timeout of the payment gateway is exhausted")
```

#### Commit message — schema change

> **Non-STE:** User account profile avatar image storage bucket policy update.
>
> **STE:** Update the policy of the storage bucket of the image of the avatar of the profile of the user account.

#### README section — rate limit

> **Non-STE:** The inbound request rate limit window reset schedule controls the burst.
>
> **STE:** The schedule of the reset of the window of the rate limit of the inbound request controls the burst.

#### Code comment — background job

> **Non-STE:** The background worker queue overflow alert suppression rule runs on the staging cluster.
>
> **STE:** The alert suppression rule on the overflow of the background worker queue runs on the staging cluster.

```python
def install_alert_rule(cluster: str) -> None:
    rule = AlertSuppressionRule(on=OverflowOf(WorkerQueue(background=True)))
    deploy(rule, cluster="staging")
```

### See also

- Rule 2.2 — write a long noun in full, then shorten it.
- Rule 2.3 — hyphenate a related pair, but do not chain more than three words.
- Rule 1.5 — what counts as a technical noun in code documentation.
- Rule 1.3 — use approved words with their approved meanings.

---

## Rule 2.2 — Write Long Technical Nouns in Full

> Source: ASD-STE100 Issue 9, Rule 2.2

### Rule

When a technical code noun has more than three words, write it in full. Then use
one of these methods to make it clear:

- Give a shorter form of the technical code noun.
- Use hyphens (`-`) between words that you use as one unit (see Rule 2.3).
- Use prepositions (`of`, `on`, `in`, `for`, `to`) to split the long noun into
  short parts (see Rule 2.1).

A long multi-word code noun can be one long technical noun or a combination of
shorter ones. Often you cannot divide it, because it is the approved term of
your company, framework, or subject field. In that case, write it as it is, in
its approved form.

### Method 1 — Shorter form of technical code nouns

If a long technical code noun comes from an official code document (an API
specification, a schema, an OpenAPI file, or an architecture diagram), write it
in full the first time it occurs. Explain it if possible, then use a shorter
form or an approved abbreviation in the rest of the document.

> **STE:** Before you do this procedure, initialize the user session cache
> invalidation lock handler (the handler that locks the cache of the user
> session, referred to in this procedure as the "invalidation lock handler").

The short form "invalidation lock handler" has three words and obeys Rule 2.1.

```python
def initialize_session_lock(user_id: str) -> None:
    """Initialize the user session cache invalidation lock handler.

    The invalidation lock handler locks the cache of the user session so that
    a background job cannot read stale data while a write is in flight.
    """
    handler = UserSessionCacheInvalidationLockHandler(user_id)
    handler.engage()   # from here, the "invalidation lock handler"
```

Abbreviations defined on first use work the same way:

> **STE:** The Main Form Validation Module (MFVM) is a TypeScript module that
> includes a Main Export Controller Unit (MECU) and a Data Bridge (DB). The
> MFVM operates in the form submission system. Its function is to validate and
> submit the form data from the Main Form Provider (MFP) to the data stores and
> the validation hooks. The Dynamic Config Unit (DECU) sends events to operate
> the MFVM.

```typescript
// Abbreviation defined on first use, then reused
interface FormPayload { fields: Record<string, unknown>; }

class MainFormValidationModule {       // MFVM
  constructor(
    private readonly exportController: MainExportControllerUnit,  // MECU
    private readonly bridge: DataBridge,                          // DB
    private readonly config: DynamicConfigUnit,                   // DECU
  ) {}

  submit(payload: FormPayload): void {
    this.config.onEvent("submit", () => this.exportController.run(payload));
  }
}
```

If an approved technical code noun has three words or fewer, you do not need an
abbreviation. Do not fill a procedure with letter codes.

| Do not write: | WRITE: |
|---|---|
| The primary parts of the controller are: - The DTA (8) - The PVA (15) - The BA (17) - The VB (20). | A. Remove the data transformer assembly (8) from the view body (20). B. Remove the pipeline validator assembly (15) from its seat. C. Remove the buffer assembly (17) from the view body (20). |
| A. Remove the DTA (8) from the VB (20). B. Remove the PVA (15) from its seat. C. Remove the BA (17) from the VB (20). | A. Remove the data transformer assembly (8) from the view body (20). B. Remove the pipeline validator assembly (15) from its seat. C. Remove the buffer assembly (17) from the view body (20). |

```yaml
# STE-Code: name each part in full; do not pack the parts into letter codes
controller:
  data_transformer_assembly:   # (8)  part of the view body
  pipeline_validator_assembly: # (15) sits on its seat
  buffer_assembly:             # (17) part of the view body

# Non-STE (do not write this):
#   parts: [DTA_8, PVA_15, BA_17, VB_20]
```

```python
def disassemble_controller(view_body, validator_seat):
    view_body.remove(data_transformer_assembly)         # (8)
    validator_seat.remove(pipeline_validator_assembly)  # (15)
    view_body.remove(buffer_assembly)                   # (17)
```

### Method 2 — Use prepositions to break up a long noun

When a long technical code noun is a chain of short nouns, make the main noun
the head of the sentence and attach the rest with `of`, `on`, `in`, `for`, or
`to`.

> **Non-STE:** Configure the user authentication token refresh failure retry policy before you deploy the service to production.
>
> **STE:** Set the retry policy for the failure of the refresh of the user authentication token before you deploy the service to production.

> **Non-STE:** Install the background worker queue overflow alert suppression rule on the staging cluster.
>
> **STE:** Install the alert suppression rule on the overflow of the background worker queue on the staging cluster.

> **Non-STE:** Remove the database connection pool exhaustion recovery timeout configuration parameter from the settings file.
>
> **STE:** Remove the configuration parameter that sets the recovery timeout for the exhaustion of the database connection pool from the settings file.

> **Non-STE:** Update the build script to obtain output directory naming consistency with the package convention.
>
> **STE:** Update the build script until the output directory naming is consistent with the package convention.

```python
def set_recovery_timeout(pool, seconds: float) -> None:
    """Set the configuration parameter that sets the recovery timeout
    for the exhaustion of the database connection pool."""
    pool.config["recovery_timeout_seconds"] = seconds
```

### Method 3 — Hyphenate words that you use as one unit

When two or more words act as a single modifier before a noun, hyphenate them:
`request-response`, `read-write`, `build-time`, `out-of-band`, `end-to-end`,
`run-time`. Do not hyphenate when the first word is an adverb ending in `-ly`
("a publicly documented API" stays open).

> **Non-STE:** Set the request response mapping handler to the new schema before the migration.
>
> **STE:** Set the request-response mapping handler to the new schema before the migration.

> **Non-STE:** Run the build time configuration check after you compile the module.
>
> **STE:** Run the build-time configuration check after you compile the module.

> **Non-STE:** Add an end to end test for the payment flow before you merge the change.
>
> **STE:** Add an end-to-end test for the payment flow before you merge the change.

> **Non-STE:** Use the out of band signal to stop the long running job.
>
> **STE:** Use the out-of-band signal to stop the long-running job.

```python
def handle_request_response(handler: "RequestResponseMappingHandler") -> None:
    """Set the request-response mapping handler to the new schema."""
    handler.apply(schema=SCHEMA_V2)

def run_build_time_check() -> None:
    """Run the build-time configuration check after you compile the module."""
    ...
```

Note: hyphenation groups words into one unit but does not make a long technical
noun short. If the hyphenated unit still has more than three words, write it in
full the first time, then use the shorter form.

### Expanded documentation pairs

> **Non-STE:** The USCIlh must run before the shutdown hook releases the cache. If the USCIlh fails, the stale session remains.
>
> **STE:** Initialize the user session cache invalidation lock handler (the handler that locks the cache of the user session; in this procedure, the "invalidation lock handler"). Run the invalidation lock handler before the shutdown hook releases the cache. If the invalidation lock handler fails, the stale session remains.

```python
class UserSessionCacheInvalidationLockHandler:
    def engage(self) -> None: ...
    def release(self) -> None: ...

def shutdown_hook(session_id: str) -> None:
    handler = UserSessionCacheInvalidationLockHandler(session_id)
    handler.engage()          # invalidation lock handler
    if not handler.release():
        raise StaleSessionError(session_id)
```

> **Non-STE:** The MFVM uses the MECU and the DB. The DECU sends events to the MFVM so that the MFVM can get data from the MFP.
>
> **STE:** The Main Form Validation Module (MFVM) is a TypeScript module that includes a Main Export Controller Unit (MECU) and a Data Bridge (DB). The Dynamic Config Unit (DECU) sends events to operate the MFVM, and the MFVM gets form data from the Main Form Provider (MFP).

```typescript
const mfvm = new MainFormValidationModule(     // MFVM
  mecu,  // Main Export Controller Unit
  db,    // Data Bridge
  decu,  // Dynamic Config Unit
);
decu.onEvent("submit", () => mfvm.submit(mfp.getData()));  // MFP = Main Form Provider
```

> **Non-STE:** Call the DTA to configure the MFVM before you run the build, then check the MFVM output for errors.
>
> **STE:** Use the data transformer adapter to set up the main form validation module before you run the build. Then check the output of the main form validation module for errors.

```bash
make configure MODULE=data-transformer-adapter   # data transformer adapter
make build MODULE=main-form-validation-module    # main form validation module
make test   MODULE=main-form-validation-module && echo "output checked for errors"
```

> **Non-STE:** Update the cross service request tracing correlation identifier generator after the schema change.
>
> **STE:** Update the correlation identifier generator for the tracing of the request across services after the schema change. (On first use, write "cross-service request tracing correlation identifier generator" in full, then use "correlation identifier generator.")

```python
def update_correlation_generator(schema: dict) -> None:
    """Update the cross-service request tracing correlation identifier generator.

    After the first use, this component is the correlation identifier generator.
    """
    CorrelationIdentifierGenerator.for_request_tracing().apply(schema)
```

> **Non-STE:** The CI pipeline docker image layer cache warming step now runs in parallel.
>
> **STE:** The cache warming step for the layer of the Docker image of the CI pipeline now runs in parallel. (On first use, write the full name, then use "cache warming step.")

```yaml
jobs:
  warm_cache:   # cache warming step for the layer of the Docker image of the CI pipeline
    runs-on: ubuntu-latest
    strategy:
      matrix:
        layer: [base, deps, build]
    steps:
      - run: ./scripts/warm-cache.sh "${{ matrix.layer }}"
```

> **Non-STE:** Document the legacy database migration rollback failure notification webhook endpoint in the runbook.
>
> **STE:** Document the webhook endpoint for the notification of the failure of the rollback of the legacy database migration in the runbook. (On first use, write the full name, then use "notification webhook endpoint.")

### Procedure

1. Find the long technical code noun (more than three words) in your sentence.
2. Write it in full the first time it occurs. If it comes from an official
   source (API spec, schema, architecture diagram), keep the approved form.
3. Give a shorter form or an approved abbreviation right after the full form,
   in parentheses.
4. In the rest of the document, use only the shorter form or the abbreviation.
5. If the noun is a chain of short nouns, split it with prepositions (Rule 2.1).
6. If two or more words act as one modifier, hyphenate them (Rule 2.3).
7. Do not fill a procedure with abbreviations. A short, clear noun is better
   than a string of letters.

### See also

- Rule 2.1 — keep technical nouns to three words or fewer.
- Rule 2.3 — hyphens between words used as one unit.
- Rule 1.5 — technical noun categories and your company glossary.
- Rule 1.3 — approved words: use, set, get, make, show, check, remove, send, start, stop.

---

## Rule 2.3 — Use Hyphens Between Words Used as One Unit

> Source: ASD-STE100 Issue 9, Rule 2.3

### Rule

A hyphen connects words or parts of words. Use hyphens between words to show
that related words operate as one unit. This makes multi-word code nouns agree
with Rule 2.1: a hyphenated group always counts as one word, so it fills only
one of the three word slots.

Constraints:

- Do not connect words that are not related. The hyphen changes the meaning of
  the multi-word code noun. If you are not sure, explain the noun in the
  clearest way, then use a shorter form, an approved verb (`get`, `set`, `make`,
  `start`), or an official abbreviation from your glossary.
- If an approved technical code noun already includes hyphens — `input-output
  stream`, `thread-safe queue`, `backward-compatible API` — do not change it.
  If it is too long, write it in full the first time, then use the short form.
- Do not hyphenate groups of more than three words. Split longer chains with
  prepositions such as `of`, `on`, or `in`.
- If an approved technical code noun has three words or fewer, hyphens are not
  necessary.

### Examples

| Example | Note |
|---|---|
| Make sure that the fail-safe shutdown-handler connection is safe. | 3 words |
| Inspection of the request rate-limit device. | 3 words |
| The thread-safe queue keeps the order of the write operations. | 3 words |
| Remove the backward-compatible API client before you make the change. | 3 words |

#### Hyphenate the related pair only

> **Non-STE:** Move the `main-feature-flag-rollback-handler` trigger to start the test run. (four words joined as one unit — not correct)
>
> **STE:** Move the `main-feature-flag` rollback-handler trigger to start the test run. (3 units: main-feature-flag / rollback-handler / trigger)

```bash
# The hyphen joins the related pair only
make test trigger=rollback-handler flag=main-feature-flag
```

```python
def move_trigger(main_feature_flag: str, rollback_handler: str) -> None:
    """Move the main-feature-flag rollback-handler trigger to start the test run."""
    trigger = f"{main_feature_flag}:{rollback_handler}"
    start_test_run(trigger)
```

#### Do not hyphenate a three-word approved technical noun

> **Non-STE:** A. Remove the `data-adapter` assembly (8) from the view body (20). B. Remove the `pipeline-validator` assembly (15) from its seat.
>
> **STE:** A. Remove the `data adapter` assembly (8) from the view body (20). B. Remove the `pipeline validator` assembly (15) from its seat.

```python
def remove_assembly(name: str, part_id: int) -> None:
    """Remove the data adapter assembly (part_id) from the view body."""
    detach(name, part_id)
    log(f"removed {name} assembly {part_id}")

remove_assembly("data adapter", 8)
remove_assembly("pipeline validator", 15)
```

#### Keep a hyphen that the official name already has

> **Non-STE:** The `input output stream` is part of the logging system.
>
> **STE:** The `input-output stream` is part of the logging system.

```python
class LoggingSystem:
    def __init__(self, stream: "InputOutputStream") -> None:
        # The input-output stream is part of the logging system.
        self.stream = stream

    def write(self, message: str) -> None:
        self.stream.push(message)
```

```yaml
logging:
  # The input-output stream is part of the logging system.
  input-output-stream:
    buffer-size: 4096
    flush-on-error: true
```

### See also

- Rule 2.1 — the three-word limit that hyphenated units help you meet.
- Rule 2.2 — write a long noun in full, then use the short form.
- Rule 1.5 — where hyphenated code terms such as `thread-safe queue` and
  `backward-compatible API` are defined.
- Rule 1.3 — pair hyphenated nouns with short approved verbs.

---

## Section 2 quick reference for LLM generation

When you generate code documentation, apply these checks to every noun phrase:

1. Count the words in the noun phrase. Hyphenated units count as one word.
   More than three? Apply Rule 2.1 or Rule 2.2.
2. Is it a stacked chain? Split it with `of`, `on`, `in`, `for`, `to`, with the
   head noun first.
3. Is it an official approved term? Keep its exact form, including its hyphens.
   Write it in full on first use, then use the short form or abbreviation.
4. Do two adjacent words act as one modifier? Hyphenate them — but never
   hyphenate more than three words, and never after an `-ly` adverb.
5. Is the verb approved? Use `set`, `get`, `make`, `show`, `check`, `remove`,
   `send`, `start`, `stop`, `use`, `update`.
6. Never merge a noun chain into one identifier-like word in prose
   (`useraccountprofileavatarimagestoragebucketpolicyupdate`). Prose names the
   parts; code identifiers stay short and nested.

---

<!-- rules-sec3.md -->

# Level 5 — Section 3: Verbs

Scope: Rules 3.1 to 3.7 of STE-Code. These rules control which verbs you use,
which forms of those verbs are legal, and how you build a sentence around them.
Source: ASD-STE100 Issue 9, Part 1, Section 3, adapted to the code domain.

Section contract, in one block:

```
Approved verbs      -> only the verbs in the STE-Code dictionary
Approved forms      -> base, third-person singular, simple past, past participle
Approved tenses     -> infinitive, imperative, simple present, simple past,
                       simple future ("will" + base)
Past participle     -> adjective only
Forbidden           -> perfect, progressive, perfect progressive, passive with
                       auxiliaries, gerund used as a verb
Voice               -> active; passive only when the agent is unknown
Action words        -> verbs, not nominalizations
```

Rule index:

| Rule | Statement |
|---|---|
| 3.1 | Use only the verb forms that the dictionary gives. |
| 3.2 | Use only these verb forms and tenses of verbs. |
| 3.3 | Use the past participle form as an adjective. |
| 3.4 | Do not use auxiliary verbs to make complex verb constructions. |
| 3.5 | Use the "-ing" form only as a technical noun or as a modifier in one. |
| 3.6 | Use the active voice. |
| 3.7 | Use an approved verb to describe an action, not a noun. |

The four approved verb categories (all rules in this section draw from them):

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

---

## Rule 3.1 — Use only the verb forms that the dictionary gives

Source: ASD-STE100 Issue 9, Rule 3.1 (master.md#sec3-rule3.1).

Every approved verb appears in the STE-Code dictionary with exactly four forms,
in this order. If a form is not on one of those four lines, the form is not
approved.

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

How to read an entry:

| Line | Form | WRITE | Where you use it |
|---|---|---|---|
| 1 | Base form (infinitive and imperative) | WRITE | "Write the log." / "to write the log" |
| 2 | Third-person singular, simple present | WRITES | "The logger writes the record." |
| 3 | Simple past | WROTE | "The job wrote the record." |
| 4 | Past participle (as an adjective) | WRITTEN | "the written log" |

The simple future has no line of its own. You make it with "will" plus the base
form: "will write".

Procedure:

1. Find the verb in the STE-Code dictionary.
2. If the verb is not there, do not use it. Use the approved verb instead:
   make (not generate), get (not retrieve), check (not verify), use (not
   utilize), start (not initiate), stop (not terminate), remove (not delete),
   show (not render), do (not execute), keep (not maintain).
3. If the verb is there, use one of the four listed forms only.
4. Do not derive a new form. "Parsing", "parseable", and "parser" are not verb
   forms of PARSE. A noun such as "parser" is approved only when the dictionary
   or a technical noun category gives it.
5. Use the past participle only as an adjective ("the parsed manifest"). Do not
   pair it with "have", "has", "had", or "get" to make a verb.

Examples:

| Non-STE | STE | Why |
|---|---|---|
| The linter validates the file and is reporting the errors to the terminal. | The linter validates the file. It reports the errors to the terminal. | "is reporting" is not a listed form of REPORT. |
| The script has written the output to the log before the test starts. | The script wrote the output to the log. Then the test starts. | Present perfect is not a listed form. |
| The service utilizes a token cache and leverages the parser for each request. | The service uses a token cache. The service parses each request. | "utilize" and "leverage" are not in the dictionary. |
| The parsing of the manifest is done by the loader, and the validating of the schema comes after. | The loader parses the manifest. Then the loader validates the schema. | Gerunds are not listed forms. Name the actor. |
| The migration had deleted the deprecated column and was terminating the open connections. | The migration removed the deprecated column. Then the migration stopped the open connections. | "delete" and "terminate" are unapproved; past perfect and progressive are unapproved. |
| The client will be receiving the streamed records after the broker has been publishing them for one minute. | The broker publishes the records. The client will receive the streamed records after one minute. | Future progressive and perfect progressive are unapproved. "Streamed" is a participle adjective, so it stays. |
| The given options get validated by the gateway, and the removed entries are gotten from the cache. | The gateway validates the given options. The gateway gets the removed entries from the cache. | "get validated" and "are gotten" are unapproved. "Given" and "removed" are participle adjectives. |

```python
# STE: the loader parses the manifest. Then the loader validates the schema.
manifest = loader.parse(path)      # parse -> parses / parsed / parsed
loader.validate(manifest, schema)  # validate -> validates / validated / validated
```

Note (structural carryover): the four-line dictionary layout is a structural
feature of the source standard. The code-domain version keeps the layout with
code verbs. No mapping is forced.

See also: Rules 3.2, 3.3, 3.4, 1.1, 1.5, and the STE-Code dictionary.

---

## Rule 3.2 — Use only these verb forms and tenses of verbs

Source: ASD-STE100 Issue 9, Rule 3.2 (master.md#sec3-rule3.2).

Approved forms and tenses, and nothing else:

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

| Infinitive | Imperative | Simple present | Simple past | Simple future | Past participle (adj) |
|---|---|---|---|---|---|
| (to) parse (regular) | Parse + object | you/we/they parse; it parses | you/we/they parsed; it parsed | will parse | the parsed file |
| (to) write (irregular) | Write + object | you/we/they write; it writes | you/we/they wrote; it wrote | will write | the written log |
| (to) build (irregular) | Build + object | you/we/they build; it builds | you/we/they built; it built | will build | the built artifact |
| (to) send (irregular) | Send + object | you/we/they send; it sends | you/we/they sent; it sent | will send | the sent request |
| (to) validate (regular) | Validate + object | you/we/they validate; it validates | you/we/they validated; it validated | will validate | the validated token |

Not approved:

- Present perfect (have/has parsed)
- Past perfect (had parsed)
- Present/past progressive (is/was parsing)
- Future progressive (will be parsing)
- Perfect progressive (has been parsing, had been parsing)
- The gerund used as a verb with an auxiliary (is parsing, keeps parsing)
- All other complex verb constructions

How to select the correct form:

1. Infinitive — after a modal verb or to state a purpose: "Use this flag to parse the file."
2. Imperative — for each step of a procedure: "Parse the file. Write the log."
3. Simple present — a general fact, a repeated action, or system behavior: "The parser reads the file."
4. Simple past — a complete action: "The build failed."
5. Simple future — "will" plus the base form: "The job will start at 02:00."
6. Past participle — as an adjective before a noun only: "the parsed file".

How to correct an unapproved form:

| Unapproved | Fix |
|---|---|
| has parsed (present perfect) | simple past: parsed |
| had parsed (past perfect) | two sentences in the simple past, joined by "Then" |
| is/was parsing (progressive) | simple present or simple past; if two actions overlap, write two sentences and add "at the same time" |
| will be parsing (future progressive) | simple future: will parse |
| is being parsed (passive with auxiliary) | name the actor, use the active voice (Rule 3.6) |

Examples:

| Non-STE | STE | Fix applied |
|---|---|---|
| The linter has found three errors in the source file. | The linter found three errors in the source file. | present perfect -> simple past |
| The server was processing the request when the timeout occurred. | The server processed the request. Then the timeout occurred. | past progressive -> two sentences |
| The framework had already initialized the connection pool before the query started. | The framework made the connection pool. Then the query started. | past perfect -> simple past; "make" replaces "initialize" |
| The scheduler is deploying the build to production while the tests are running. | The scheduler sends the build to production. The tests run at the same time. | progressive -> simple present, twice |
| The cache has been keeping the serialized records since the service started, and the client will be reading them after the restart. | The cache keeps the serialized records. The client will read the records after the restart. | perfect progressive and future progressive removed |
| To be parsing the configuration file, the loader must be having read access to the directory. | To parse the configuration file, the loader must have read access to the directory. | infinitive and base form after the modal |
| You should be setting the timeout value and then you will be restarting the service. | Set the timeout value. Then start the service again. | imperative for each step |
| The payload is being validated by the gateway and the deprecated field gets removed by the migration. | The gateway validates the payload. The migration removes the deprecated field. | passive progressive -> active simple present |
| The written log and the parsed manifest are showing that the build had completed with the given options. | The written log and the parsed manifest show that the build completed with the given options. | participle adjectives kept; progressive and past perfect removed |
| We have been building the release artifact and the CI pipeline will have run the tests by the time you review the pull request. | We built the release artifact. The CI pipeline will run the tests. Then you can review the pull request. | perfect progressive and future perfect removed |
| If the connection drops, the client is retrying the request until the server responds. | If the connection drops, the client retries the request. Then the server responds. | progressive -> simple present |

```yaml
# .github/workflows/ci.yml
# STE: we built the release artifact. The CI pipeline will run the tests.
jobs:
  build:
    steps:
      - run: make release
  test:
    needs: build
    steps:
      - run: make test
```

```python
# STE: the server processed the request. Then the timeout occurred.
try:
    response = server.process(request)   # process -> processes / processed / processed
except TimeoutError:
    log.write("request timeout after 30 s")
```

Note (structural carryover): the six-column table of verb forms is a structural
feature of the source standard, kept here with approved code verbs.

See also: Rules 3.1, 3.3, 3.4, 3.5, 3.6, 1.1, and the STE-Code dictionary.

---

## Rule 3.3 — Use the past participle form as an adjective

Source: ASD-STE100 Issue 9, Rule 3.3 (master.md#sec3-rule3.3).

A past participle used as an adjective shows the condition of something. This is
not passive voice. Use it:

- Before a noun
- After a form of "to be", "to become", or "to stay"

Do not use a past participle that the STE-Code dictionary does not give. Some
approved adjectives are past participles of verbs that are themselves not
approved; the dictionary marks them "(adj)" and you may use them.

How to tell adjective from passive voice:

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

Approved code-domain participle adjectives:

| Past participle (adj) | Example noun phrase | Condition that it shows |
|---|---|---|
| parsed | the parsed manifest | The parser read the file. |
| serialized | the serialized record | The record is in a transport format. |
| deserialized | the deserialized object | The object is in memory again. |
| initialized | the initialized cache | The cache is ready for use. |
| deprecated | the deprecated method | The method is old. Do not use it. |
| allowed | the allowed memory | The limit that the configuration gives. |
| corrupted | the corrupted index | The data is not correct. |
| locked | the locked row | Another transaction holds the row. |
| written | the written log | The log file is on disk. |
| given | the given options | The options that the caller sends. |
| built | the built artifact | The build made the artifact. |
| signed | the signed token | The token has a valid signature. |

Cautions:

- Do not make a new past participle from an unapproved verb. Write "the removed branch", not "the deleted branch", unless the dictionary gives "delete" or "deleted (adj)".
- Do not use a past participle as a verb with "have", "has", or "had" (Rule 3.2).
- Do not stack more than one past participle before the same noun. If "the parsed and validated payload" becomes difficult, write two short sentences.
- Prefer the plain word: "started" not "commenced", "used" not "utilized" or "leveraged", "stopped" not "terminated".

Correct uses:

- "Inspect all fields of the deserialized object for corruption." ("deserialized" before a noun)
- "When the cache is fully initialized, start the worker threads." ("initialized" after "to be")
- "Do not exceed the allowed memory for the buffer." ("allowed" is an approved adjective)
- "Make sure that the input values are not corrupted." ("corrupted" is an approved adjective)

Corrections:

| Non-STE | STE |
|---|---|
| The parsed file was processed by the loader. | The parsed file is ready for the loader. |
| The method has been deprecated by the API team in release 4.2. | The method is deprecated in release 4.2. Do not use the deprecated method in new code. |
| After the record gets locked, the transaction which was started earlier is being committed. | The transaction writes the locked record. Then the transaction ends. |
| The signed token which had been given to the client is validated by the gateway on each request. | The gateway validates the signed token on each request. |
| When the index becomes corrupted it will have to be being rebuilt by the maintenance job. | When the index becomes corrupted, the maintenance job makes the index again. |
| The build artifact stays uncompiled until the pipeline has compiled the modified sources. | The artifact stays unbuilt until the pipeline builds the modified sources. |
| The user is shown a warning if the uploaded configuration file was found to be malformed. | The CLI shows a warning if the uploaded configuration file is malformed. |
| All of the returned records had already been serialized before the response was sent. | The API sends the serialized records in the response. |
| Make sure that the written log and the given options are not being modified by the plugin. | Make sure that the plugin does not change the written log or the given options. |

```go
// STE: "initialized" comes after "is" and gives the condition of the cache.
if cache.IsInitialized() {
    pool.Start(workerCount)
}
```

```sql
-- STE: the transaction writes the locked record. Then the transaction ends.
BEGIN;
SELECT * FROM orders WHERE id = 42 FOR UPDATE;  -- the locked row
UPDATE orders SET status = 'sent' WHERE id = 42;
COMMIT;
```

Note (structural carryover): the source rule uses hardware conditions to show the
grammar. The code-domain version keeps the grammar and gives software conditions.

See also: Rules 3.1, 3.2, 3.4, 3.5, 3.6, 1.1, and the dictionary adjectives "(adj)".

---

## Rule 3.4 — Do not use auxiliary verbs to make complex verb constructions

Source: ASD-STE100 Issue 9, Rule 3.4 (master.md#sec3-rule3.4).

Do not combine an auxiliary verb ("have", "be", "will", "can", "must", "should",
"is to be") with a past participle to build a compound tense or the passive
voice. These constructions make verb forms that STE-Code does not approve.

Conversion table:

| Construction | Replace with |
|---|---|
| have/has/had + past participle (perfect) | the simple past |
| be + past participle (passive) | the active voice with a named agent (Rule 3.6) |
| is to be + past participle | the imperative (command) form |
| can be + past participle | "you can" + base verb, when the reader is the agent |
| will be + past participle + by + agent | agent + "will" + base verb |

When a compound construction seems unavoidable, split it into separate simple
sentences. Rule 3.2 lists the only approved forms: infinitive, imperative,
simple present, simple past, simple future, and past participle as an adjective.

Examples:

| Non-STE | STE | Fix applied |
|---|---|---|
| The build has compiled the module before the test runs. | The build compiled the module. Then the test runs. | present perfect -> simple past |
| The migration is to be run before you deploy the service. | Before you deploy the service, run the migration. | "is to be" -> imperative |
| The cache can be cleared. | You can clear the cache. | "can be" -> "you can" + base verb |
| The timeout must be set before the job starts. | Set the timeout before the job starts. | "must be" -> imperative |
| The report will be generated by the scheduler. | The scheduler will generate the report. | agent to subject, keep "will" |
| The connection pool has been created before the first query is sent. | The connection pool was created. Then the first query is sent. | present perfect passive -> simple past |
| The configuration file must be validated before the server starts. | Validate the configuration file before the server starts. | imperative for a procedure |
| The user credentials are to be encrypted at rest and the key is rotated monthly. | Encrypt the user credentials at rest. Rotate the key every month. | two imperatives |
| The log entries can be exported to a CSV file by the admin. | The admin can export the log entries to a CSV file. | name the agent, keep the modal |
| An error message will be shown by the validator if the input is empty. | The validator will show an error message if the input is empty. | agent to subject |
| The temporary files had been deleted by the cleanup task before the backup started. | The cleanup task deleted the temporary files. Then the backup started. | past perfect passive -> simple past, sequence with "Then" |

See also: Rules 3.2, 3.3, 3.5, 3.6.

---

## Rule 3.5 — Use the "-ing" form only as a technical noun or as a modifier in a technical noun

Source: ASD-STE100 Issue 9, Rule 3.5 (master.md#sec3-rule3.5).

An "-ing" word can be a verb part, an adjective, a noun, or the head of a long
modifier group. That range causes ambiguity and long sentences. In STE-Code the
"-ing" form is not permitted as a verb.

Approved "-ing" words in STE-Code:

| Part of speech | Words |
|---|---|
| Nouns | logging, monitoring, routing, servicing |
| Adjectives | matching, missing, remaining |
| Pronoun | something |
| Preposition | during |

Why the progressive is not approved: Rule 3.2 permits only the infinitive, the
imperative, the simple present, the simple past, the simple future, and the past
participle as an adjective. The progressive ("is running", "are deploying", "was
processing") is not on that list, and the "-ing" form lives inside it. The
"-ing" form also hides auxiliary-verb constructions that Rule 3.4 forbids: write
"The service starts. Then it logs the request", not "the service is starting and
then it is logging the request".

Approved "-ing" technical nouns (section and document titles):

- Logging
- Monitoring
- Testing and Fault Isolation
- Handling
- Packaging
- Shipping
- Troubleshooting
- Building
- Deployment

Approved "-ing" modifiers inside technical nouns:

- logging service
- monitoring agent
- routing table
- switching relay
- caching layer
- building pipeline
- binding configuration
- streaming endpoint
- rendering engine

Do not pull the "-ing" word out of the technical noun and use it as a verb. "The
caching layer stores the result" is approved. "The layer is caching the result"
is not.

Examples:

| Non-STE | STE | Fix applied |
|---|---|---|
| When you are running this script, obey all the safety checks. | When you run this script, obey all the safety checks. | progressive -> simple present |
| Be careful while the process is starting. | Be careful while the process starts. | progressive -> simple present |
| While the deployment is starting, you must watch the logs and you must not stop the process because stopping it during startup can corrupt the state file. | The deployment starts. While it starts, watch the logs. Do not stop the deployment. If you stop the deployment during startup, the state file can become corrupt. | progressive and gerund clause -> short sentences |
| The background worker is processing the queue and it is writing the results to the cache while the main thread is waiting for the response, causing the request to time out and the user to see an error. | The background worker processes the queue. It writes the results to the cache. The main thread waits for the response. If the main thread waits too long, the request times out and the user sees an error. | three progressives and a cause clause split apart |
| The function is returning the value while the cache is loading the entry, which makes the result incorrect during the first request. | The function returns the value. The cache loads the entry. During the first request, the result is incorrect. | progressive -> simple present |
| The matching algorithm is comparing the remaining items during the iteration and it is removing the missing records from the list. | The matching algorithm compares the remaining items during the iteration. It removes the missing records from the list. | approved adjectives kept; progressive verbs removed |
| Something going wrong during the migration can make the database stay in a broken state. | If something goes wrong during the migration, the database can stay in a broken state. | "something" kept; gerund verb -> simple present |

Long "-ing" subjects become vertical lists:

> **Non-STE:** A script opening a socket without checking the firewall rules and
> sending data to an unknown host, using an unverified certificate without
> reading the security policy, is in danger of causing a breach and thus
> exposing private keys and credentials.
>
> **STE:** Before you open a socket, obey these precautions: (1) Read the
> security policy. (2) Make sure that the firewall rules allow the connection.
> (3) Verify the host certificate. (4) Get the correct credentials to send data
> to the host. If you do not obey these precautions, a breach of private keys
> and credentials can occur.

> **Non-STE:** Developers committing code without running the test suite and
> pushing directly to the main branch, ignoring the review policy, risk breaking
> the build and therefore blocking the release for all team members.
>
> **STE:** Before you commit code, obey these precautions: (1) Run the test
> suite. (2) Make sure that the tests pass. (3) Open a review before you merge to
> the main branch. If you do not obey these precautions, you can break the build
> and block the release for all team members.

See also: Rules 3.2, 3.4, 1.5.

---

<!-- rules-sec4.md -->

---

## Rule 4.5 — Use an Article or a Demonstrative Adjective Before a Noun

**Source:** Adapted from ASD-STE100 Issue 9, Rule 4.5.

### Requirement

Articles (**the**, **a**, **an**) and demonstrative adjectives (**this**, **these**) show
the position of nouns and multi-word nouns in the sentence. Use them correctly; do not
omit them to make the text shorter.

- Do not use an article in a general statement or before an abstract concept
  (performance, scalability, error handling, concurrency, backward compatibility).
- In short sentences, use an article before each noun.
- In a long series of items, use the article only before the first noun. Repeat it
  before each item when an adjective applies to only one item (to avoid ambiguity).
- Do not use a definite article before a noun when a code identifier follows it —
  the identifier is a proper noun (function, class, variable, file, environment
  variable, error code, version tag).
- Use a demonstrative adjective (**this**, **these**) to connect a noun to the topic
  of the previous sentence. Always keep the noun after it; do not write "this"/"these" alone.

### Code-domain examples

Article before a noun in a short instruction:

> **Non-STE:** Call callback function. Pass response object to handler and set retry flag.
> **STE:** Call the callback function. Pass the response object to the handler. Then set the retry flag.

API reference sentence:

> **Non-STE:** Method reads configuration file and returns settings object.
> **STE:** The `load` method reads the configuration file and returns the settings object.

No article in a general statement; "the" for a specific item:

> **Non-STE:** The error handling is important for the production applications. A function throws the error when the input is not valid.
> **STE:** Error handling is important for production applications. The function throws an error when input is not valid.

Article only before the first noun in a long series:

> **STE:** Delete the temporary files, log files, cache entries, and lock files before you start the build.

Article before each noun when an adjective applies to only one item:

> **STE:** Register the new event listeners, the timers, the subscriptions, and the cleanup callbacks. (Only the event listeners are new.)

No article before a noun with a code identifier (proper noun):

> **Non-STE:** Call the function `validateInput` before you send the request.
> **STE:** Call function `validateInput` before you send the request.  — or —  Call the `validateInput` function before you send the request.
> **STE:** Configure module `AuthService` in the container.  /  Set variable `LOG_LEVEL` to `debug`.  /  Error `ERR_TIMEOUT_1042` shows in the console log.  /  Install version 3.2.1 of the package.

Demonstrative adjective for sentence linking:

> **Non-STE:** The function returns a configuration object. Configuration object has three fields: host, port, and timeout.
> **STE:** The function returns a configuration object. This object has three fields: `host`, `port`, and `timeout`.

Article use in commit messages and release notes:

> **STE:** Fix the race condition in the scheduler. The worker pool now waits for the queue to become empty.
> **STE:** Adds retry logic to the `HttpClient` class. Removes deprecated method `sendSync`.

Article use in an error message and a test description:

> **STE:** The input is not valid. The `name` field must be a string.
> **STE:** The test checks that the handler returns the status code 404 when the record is not in the database.

### Paradigm-specific guidance

- **Object-Oriented:** use an article to separate a class (type) from an instance (value) — "The `ConnectionPool` class manages a pool of database connections. Each instance keeps a list of open connections." No article directly before a bare identifier: "Call `connect`."
- **Functional:** separate a type constructor from a value — "The `Ok(value)` pattern shows a successful result. A `Result` value is either `Ok` or `Err`." Write concepts (immutability, referential transparency) with no article.
- **Procedural (C, Go, Bash):** separate a pointer from the value at the address — "The function receives a pointer to a buffer. The buffer must hold at least 512 bytes."
- **Declarative (SQL, Terraform, YAML, Kubernetes):** separate a resource type from an instance — "A `Deployment` resource manages a set of pods. The `web` deployment runs three replicas." No article before a named resource: "Apply manifest `web-deployment.yaml`."
- **Systems (Rust, C memory, embedded):** make ownership/lifetime clear — "The pointer must point to an initialized region of memory. A borrow of the value must not outlive the owner."

### Edge cases

- **Identifier vs concept:** `ConnectionPool` alone is a proper noun (no article). "The `ConnectionPool` class" takes "the" (noun is "class"). "Call `initialize`" no article; "The `initialize` function" takes "the".
- **"a" vs "an":** use "an" before a vowel sound (an SQL query, an HTML element, an XML parser, an ID, an API key); "a" before a consonant sound (a URL, a Unix system, a UUID, a JSON payload, a `User` record). Match the usual pronunciation.
- **Headings, titles, table cells, UI labels:** may omit the article; the first sentence below the heading must obey the rule.
- **Product/framework names starting with "The":** `TheMovieDB` is a proper noun; the leading "The" is part of the identifier, not an article.
- **Plural types as a general statement:** "Iterators are lazy in this library" takes no article; "The iterator stops at the end of the sequence" takes "the".
- **Code samples and command lines:** do not add an article inside a code block, command, or log line; the rule applies to prose only.
- **Acronyms:** choose the article for the spoken form — "an API" (ay-pee-eye), not "a API".
- **Uncountable technical nouns:** memory, throughput, latency, state take no indefinite article — "The function allocates memory", not "a memory".

### Grammar notes

- "A" = any instance of a type; "the" = one specific identifiable item; no article = the type or concept as a whole.
- First mention uses "a" ("The method throws a `ValidationError`"); later mentions use "the" ("The `ValidationError` contains a message field").
- Proper-noun exception: a code identifier is a proper noun — no definite article directly before it ("Call `connect`", not "Call the `connect`").
- Demonstrative adjectives keep their noun: "this object", "these headers" — never "this"/"these" alone.
- Multi-word nouns: put the article before the full noun ("the retry policy object"), not inside it.
- Possessive forms replace the article: "its return value" and "the return value of the method" are both correct; not "the its return value".

### Summary checklist

- [ ] Articles and demonstrative adjectives are used correctly and not removed to shorten the text.
- [ ] No article appears before a general statement or an abstract concept.
- [ ] Short sentences use an article before each noun.
- [ ] A long series uses the article only before the first noun, unless an adjective applies to one item only.
- [ ] No definite article appears directly before a code identifier used as a proper noun.
- [ ] "a" and "an" match the spoken sound of the term that follows.
- [ ] Each demonstrative adjective is followed by a noun and refers to one clear topic.

---

## Cross-References

- **Rule 1.1** — Use approved words from the STE-Code dictionary.
- **Rule 1.3** — Use words only with their approved meanings.
- **Rule 1.5** — Technical nouns from an approved category still take an article in prose.
- **Rule 1.6** — Non-approved words are permitted only as technical code nouns.
- **Rule 1.11** — Use one term per concept.
- **Rule 3.1** — Write one topic per sentence (simplify before you connect).
- **Rule 4.1** — One topic per sentence, no abstract text.
- **Rule 4.2** — Do not omit words or use contractions.
- **Rule 4.3** — Vertical lists for complex text.
- **Rule 4.4** — Connecting words and phrases.
- **Rule 4.5** — Articles / demonstrative adjectives before a noun.
- **Rule 5.1** — Active voice in procedural steps.
- **Section 5 (Procedural Writing)** — sentence structure for step-by-step instructions.
- **Section 6 (Descriptive Writing)** — sentence structure for descriptions and explanations.

---

<!-- rules-sec5.md -->

# Level 5 — Clarity Rules: Sentences & Instructions (Section 5)

This slice contains STE-Code Section 5, adapted for people who use LLMs to
generate code documentation. It covers five rules about how to write procedural
and descriptive sentences in software docs:

- Rule 5.1 — Short Sentences (Maximum 20 Words)
- Rule 5.2 — One Instruction Per Sentence
- Rule 5.3 — Imperative (Command) Form for Instructions
- Rule 5.4 — Descriptive Statement Before the Command
- Rule 5.5 — Notes Give Information Only, Not Instructions

STE-Code voice: plain, code-domain, command-form instructions. Word-count and
voice rules apply to *procedural text* (steps the reader executes). They do not
apply to code blocks, terminal output, string literals, or identifier names.
Inside backticks, a code token counts as one word regardless of length
(`Result<T, E>` = 1 word, `async fn` = 2 words).

## Rule 5.1 — Short Sentences (Maximum 20 Words)

**Core rule:** Every sentence in code-documentation *procedures* must be 20
words or fewer. Split long procedural sentences into shorter ones. Warnings and
cautions about security, data loss, or stability must also obey the 20-word limit.

**Notes** (supplementary, non-procedural text) may use up to 25 words per
sentence. Code blocks, command output, and string literals inside code fences
are excluded from the count.

### Why
Long sentences in install steps, setup checklists, debugging workflows, and API
usage guides are hard to follow when the reader is typing commands or writing
code while reading.

### Split long sentences with these techniques
1. **At coordinating conjunctions.** Replace "and/but/or" with a period. Start
   the next sentence with a transition: "Then," "After that," "Next."
2. **Extract conditions.** Move an "if X, then Y" clause into its own sentence
   that precedes or follows the main instruction.
3. **Separate action from purpose.** Put the instruction in one sentence, the
   reason/result in the next.
4. **Use lists.** Convert an enumerating sentence into bulleted/numbered items.
   List items are fragments, not sentences, but keep them short.

**Allowed (8 words):** Run the tests and check the output.
**Not allowed (28):** Run the full test suite with coverage enabled and check
the report for untested paths that might indicate gaps in the test plan.
**Allowed:** Run the full test suite with coverage enabled. Then, check the
report for untested code paths.

### Counting rules
- A sentence ends at `.`, `?`, or `!`. A comma does not end a sentence.
- Hyphenated compounds count as one word ("command-line" = 1).
- Numbers, symbols, parentheticals each count as one word: "(2)" = 1, "HTTP/2" = 1.
- Code tokens in backticks count as one word each. Generics/type params stay
  opaque: `pub async fn fetch_user(id: UserId) -> Result<User, Error>` is one word.

### Edge cases
- **Long proper nouns** (e.g. "Amazon Web Services Elastic Kubernetes Service"):
  use the shortest accepted form on first use, define an abbreviation, then use
  the abbreviation. The abbreviation counts as one word.
- **Generated docs** (Javadoc, Sphinx, rustdoc, TypeDoc): apply the limit to the
  *source docstrings/comments* the generator reads. Fix the source, not the output.
  If the source is third-party/legacy, apply the 25-word descriptive limit and
  document the exception in a style guide.
- **Legal text** (license headers, disclaimers): not procedural. Put it in a
  separate NOTE or "Legal" section, not inside a procedure.
- **Multi-line code mid-sentence:** the code block is excluded. The introducing
  and following sentences must each obey the limit independently.

### Worked example
```bash
# Non-STE (27 words): Set the environment variable HTTP_TIMEOUT to the value
# 30000 which represents the maximum number of milliseconds that the client
# will wait for a response from the upstream server.
# STE:
export HTTP_TIMEOUT=30000
# This value is the maximum wait time in milliseconds for a response.
```

### Cross-references
Rule 1.1 (approved words), Rule 1.2 (part of speech), Rule 1.4 (verb forms),
Rule 1.5 (technical nouns), Rule 1.7 (no technical-noun-as-verb), Rule 1.9
(short technical nouns), Rule 1.12 (technical verbs), Rule 5.2 (active voice),
Rule 5.3 (imperative), Rule 5.5 (notes), Rule 5.7 (lists), Section 8 (word count).

## Rule 5.2 — One Instruction Per Sentence

**Core rule:** Write exactly one instruction in each sentence. Use numbered or
bulleted lists to show step sequence. There is no limit on the number of steps
in a procedure.

**Exceptions — two instructions in one sentence are allowed only when:**
- both actions occur at the same time and cannot be separated (e.g. "Hold the
  Shift key and click Reload"), or
- a result or measurement follows the action immediately and splitting it would
  break the logical flow (e.g. "Measure the leakage. The leakage must not exceed
  0.5 cc/minute").

### Why
A sentence with multiple instructions lets the reader miss or skip an action,
causing config, deploy, or debug errors.

### Apply across doc types
- **README / quick-start:** each numbered step = one instruction.
- **API docs:** one sentence per endpoint operation, per parameter, per return
  field, per error code.
- **Docstrings:** first line = one-sentence summary. Body: one sentence per
  parameter, return value, raised exception, side effect, precondition.
- **Commit subject:** one imperative sentence describing one change. Multiple
  unrelated changes → split the commit (or use body bullets).
- **Error messages:** state exactly one problem; one recovery instruction if
  applicable. Do not combine failure paths with "or/and/also".

**Non-STE (5 instructions):** Open the config file and locate the database
section and change the connection string to staging and save the file and close
the editor.
**STE:** (1) Open `config/database.toml`. (2) Find the `[database]` section.
(3) Set `connection_string = "postgres://staging-db:5432/app"`. (4) Save the
file. (5) Close the editor.

### Grammar (single predicate)
Each imperative sentence has exactly one main verb in imperative mood.
- Correct: `Install the package.` (one predicate)
- Incorrect: `Install the package and configure the settings.` (two predicates)

**Compound objects are fine** (one verb, many objects):
`Remove the log files, cache files, and temporary directories.` — one instruction.
`Remove the log files and restart the server.` — two instructions (split).

**"-ing" forms as main verbs hide instructions:** "After installing, configuring,
and setting up, run the app" smuggles three instructions. Number them.

**Preconditions are instructions:** "Before you run the tests, set TEST_MODE" →
`(1) Set TEST_MODE to true. (2) Run the tests.`

### Edge cases
- **Framework CLI commands** (`docker compose up`, `kubectl apply`,
  `terraform destroy`) are one technical noun phrase. Do not split into
  "run docker. then compose." Use backticks.
- **Error messages with cascading symptoms:** state the *root cause* (one
  sentence); list consequences in a separate descriptive sentence.
- **Generated docs:** prefer annotation styles (JSDoc `@param` per item) that
  yield one sentence per item.
- **Test assertions:** one description/message per assertion.
- **Progress logs:** each log line reports one completed action/result.

### Cross-references
Rule 5.1 (short sentences), Rule 5.3 (imperative), Rule 1.1 (approved words),
Rule 1.12 (technical verbs), Rule 1.13 (no technical-verb-as-noun), Rule 5.5
(notes), STE-Code Dictionary (approved action verbs).

## Rule 5.3 — Imperative (Command) Form for Instructions

**Core rule:** Write every procedural instruction in the imperative (command)
form. Start each instruction with an imperative verb. The implied subject is
always the reader ("you"), which removes ambiguity about who acts.

**Imperative verbs common in code docs:** run, set, open, save, install,
configure, restart, execute, copy, delete, create, add, enter, select, click,
type, check, use, start, stop, send, show, get, make, remove, build.

**Do NOT use:**
- passive voice ("is executed", "are to be removed"),
- gerunds as commands ("Building the image..."),
- modal verbs (can, could, should, may, might) for instructions,
- "must" before the imperative in a *standard* instruction.

**Reserve "must"** for WARNING/CAUTION blocks about security, data loss, or
safety-critical conditions.

### What kind of text is imperative vs descriptive?
| Text type | Form |
|-----------|------|
| Install/setup/quick-start steps | Imperative |
| API "getting started"/auth walkthrough | Imperative |
| Endpoint *descriptions* (system behavior) | Descriptive ("Returns a list") |
| Docstring body (what code does) | Descriptive |
| Commit **subject line** | Imperative ("Fix the race condition") |
| Commit body (rationale) | Descriptive allowed |
| Error message — recovery instruction | Imperative (after the description) |
| Makefile/shell-script usage headers | Imperative |

### Examples
- Non-STE: The unit tests can be executed with `npm test`.
  STE: Run the unit tests with `npm test`.
- Non-STE: The configuration file should be validated before the app starts.
  STE: Check the configuration file against the schema before you start the app.
- Non-STE: It is recommended that you create a backup before the migration.
  STE: Create a backup of the database before you run the migration.
- Non-STE: The SSL certificate must be renewed and then the server must restart.
  STE: Renew the SSL certificate. Then, restart the web server to apply changes.
- WARNING (allowed "must"): IF YOU MUST STORE CREDENTIALS, ALWAYS USE AN
  ENCRYPTED SECRETS MANAGER. PLAIN-TEXT CREDENTIALS CAN CAUSE BREACHES.

### Grammar
- **Subject omission:** imperative drops "you" → reader knows the instruction is
  for them. Passive hides the agent ("The file is saved" = who?).
- **Modal elimination:** "can/should" let the reader read an action as optional.
  Imperative leaves no room for that.
- **Tense consistency:** base verb form, no inflection — simpler to translate and
  parse.
- **Coordinates with Rule 5.4:** a descriptive context sentence may precede the
  imperative command. Keep the two roles in separate sentences.
  `The Docker daemon must be running. Build the image with \`docker build\`.`

### Paradigm notes
- **OOP:** imperative for setup/config; descriptive for invariants/inheritance.
- **Functional:** imperative for build/REPL/setup; descriptive for what a
  function transforms.
- **Procedural (C/Go/Bash):** imperative dominates (build, compile, link, run).
- **Declarative (SQL/Terraform/K8s):** the spec is descriptive; the *tooling
  that applies it* (CLI, pipelines) is imperative.
- **Systems (Rust/C):** descriptive for invariants; imperative for "how to
  comply" (free memory, satisfy borrow checker).

### Edge cases
- **Framework name = verb** (React, Spring, Go, Make, Build): never start a
  sentence with the framework name as if it were a command. Prefix with an
  article or reword: "Use React to build the UI." Avoid "React to state changes."
- **Generated/tool output** (`--help`, changelogs, OpenAPI pages): fix the
  *template/source*, not the output. CLI help: `help="Write the output to this file"`.
- **Language keywords that are modals** (`try`, `await`, `yield`): use backticks;
  don't start an imperative sentence with the bare keyword. "Use `await` on the
  promise before you access the result."
- **Release notes:** imperative for upgrade/migration steps; past/perfect tense
  for feature/bug descriptions.
- **Interactive tutorials:** label instructional blocks ("Run this command") and
  system-response blocks ("You will see…") separately.

### Cross-references
Rule 1.1 (approved words), Rule 1.2 (part of speech), Rule 1.4 (verb forms),
Rule 1.7 (no technical-noun-as-verb), Rule 5.4 (descriptive before command),
Rule 7.1 (risk signal words), Rule 7.2 (safety instruction start), STE-Code
Dictionary (approved verbs: use > utilize, start > initiate, check > verify,
set > configure).

## Rule 5.4 — Descriptive Statement Before the Command

**Core rule:** When a step has a condition the reader must know first, write the
condition as a descriptive statement at the start of the sentence, follow it with
a **comma**, then give the imperative command. The comma is mandatory — it marks
where the condition ends and the instruction begins.

**Pattern:** `[condition clause] , [imperative verb] [object]`

- Non-STE: Run the migration after you set `DATABASE_URL` and confirmed the
  server accepts connections.
- STE: After you set the `DATABASE_URL` environment variable, run the migration
  script.

### Why the comma matters
Comma placement changes which verb an adverb modifies:
- `If the service does not start, automatically restart it.` (the restart is automatic)
- `If the service does not start automatically, restart it.` (you restart it manually)

In code, condition clauses often contain punctuation (backticks, dots,
parentheses). The comma after the clause is the only reliable boundary marker.

### Apply across doc types
- **README:** one condition-command pair per step. Don't bury the condition after
  the command.
- **API:** state the trigger/error condition before describing the response.
- **Docstrings:** precondition-before-behavior. "If the file does not exist, this
  function raises `FileNotFoundError`."
- **Commit:** context-before-action. "When the connection pool reaches capacity,
  add a mutex lock around pool access."
- **Error messages:** problem-before-resolution. "The config has invalid YAML on
  line 42. Fix the syntax error, then run the app again."

### Dependent clause types (condition first, comma, command)
1. **Time** (before, after, when, while, until): `Before you deploy, run the tests.`
2. **Conditional** (if, unless): `If the build fails, check the error log.`
3. **Reason** (because): prefer splitting — "The port is in use. Use a different port."
4. **Purpose** (to, in order to): `To see running containers, run \`docker ps\`.`
5. **Concessive** (although): `Although the server starts, check the health endpoint.`

Never reverse the order (command first, condition second) — the reader would act
before learning the condition.

### Multiple conditions in one step
- **A — separate sentences:** "Make sure the server is running. After it accepts
  connections, run the migration."
- **B — compound with 'and':** "If the server is running and the backup is
  complete, run the migration."
- **C — sequential pairs (preferred):** "Before you run the migration, make sure
  the server is running. After the server accepts connections, run the migration."

### Paradigm notes
- **OOP:** state preconditions before method-call/constructor instructions.
- **Functional:** state input guard/pattern before describing the transformation.
- **Procedural (C/Go/Bash):** state system-state condition before the action.
- **Declarative:** applies to the *operational wrapper* (how to apply/destroy),
  not the declarative spec itself.
- **Systems (Rust/C):** state safety condition before the operation; use WARNING/
  BREAKING when the consequence is severe.

### Edge cases
- **Framework name = common word** (Next.js, Express): still a technical noun;
  comma rule applies to the condition clause containing it.
- **Code keyword inside condition:** comma after the closing backtick. "When
  `response.status === 429`, wait for the `Retry-After` duration. Then, retry."
- **Condition clause has its own commas** (a list): restructure into a separate
  descriptive sentence + a simple condition clause, or use Strategy C. Don't pile
  commas.
- **Condition implied by tool output:** state the observable output as the
  condition. "If the terminal shows 'Connection refused', start the database."
- **Generated docs:** relaxed for output, but source docstrings/comments must
  follow the rule. For templates, place the condition placeholder first.

### Cross-references
Rule 1.1 (approved words), Rule 1.4 (verb forms), Rule 1.5 (technical nouns),
Rule 5.3 (imperative verb form), Rule 5.5 (notes), Rule 7.2 (safety instruction
start). Dictionary synonyms: verify → check, obtain → get, terminate → stop.

## Rule 5.5 — Notes Give Information Only, Not Instructions

**Core rule:** A NOTE gives descriptive information only. It must not contain
instructions, commands, step-by-step actions, requirements, limits, tolerances,
or expected results of a work step. A note must not use the imperative form.

Each sentence in a note may be up to 25 words. A note can have one or more
sentences.

### The "remove the notes" test
To check correct note usage: read the procedure *without* the notes. If the
reader can complete the procedure correctly, the notes are used correctly. If
important information is only in a note, move it into a numbered work step and
repeat the test.

### Move note content out when…
- it tells the reader to run a command → make it a numbered work step.
- it states a limit/tolerance/result → put it directly in the work step after the
  related action.
- it carries safety-critical info (data loss, security, system damage) → convert
  to a WARNING or CAUTION safety instruction. A note is never a substitute for a
  safety instruction.

**Non-STE:** NOTE: When you update dependencies, run `npm audit fix` to resolve
vulnerabilities. If you skip this, you may have security issues.
**STE:** (5) Run the command `npm audit fix` to resolve known vulnerabilities.

**Non-STE:** NOTE: Do not run the migration on production without a backup.
**STE:** WARNING: DO NOT RUN THE MIGRATION ON THE PRODUCTION DATABASE WITHOUT A
FULL BACKUP. RUNNING IT WITHOUT A BACKUP CAN CAUSE IRREVERSIBLE DATA LOSS.

### Apply across doc types
- **README:** notes give project context (why a dependency exists). Not install steps.
- **API docs:** notes explain behavior/side effects/constraints. "Call the
  /refresh endpoint first" is an instruction — move it to the endpoint description.
- **Docstrings:** describe behavior/constraints. "Call `initialize()` first" is a
  requirement — write it as a descriptive constraint in the function spec.
- **Commit body:** explain *why* a change was made. Not "run the migration" (that
  belongs in release notes / upgrade guide).
- **Error messages:** the fix guidance is part of the error text (descriptive +
  imperative), not a separate note the reader might skip.

### Paradigm notes
- **OOP:** note explains disposed-state constraint, not "call dispose() first."
- **Functional:** note states purity/performance, not "memoize it."
- **Procedural:** note states resource-leak behavior, not "close the fd."
- **Declarative:** note describes attribute behavior, not "always set this."
- **Systems:** note describes borrow/compiler behavior, not "don't mutate."

### Grammar of notes
- **Descriptive mood only.** Subject performs/experiences the action (system,
  code, environment). "The cache expires after 300 seconds." NOT "Run the build."
- **Modals:** "can/may/will" are fine when describing system behavior. "must" in
  a note is a red flag — it usually signals a requirement that belongs in a work
  step or WARNING.
- **Articles:** do not omit "the/a/an" in notes.
- **Technical nouns** (function/class/command names) follow Rule 1.5 — exempt from
  the dictionary, but surrounding words must use approved vocabulary.

### Edge cases
- **Framework name = verb** (React, Express): still a technical noun in a note;
  not an instruction. "The `React` component tree re-renders when state changes."
- **Generated docs:** fix the *source comment*, not the generator output.
- **Interactive tutorials:** exploratory "try this" notes are acceptable only in
  non-shipping tutorial material, never in reference/README/API docs.
- **Command referenced, not commanded:** "The `terraform plan` command shows the
  changes" is a note. "Run `terraform plan`" is an instruction — not a note.
- **Conditional in a note:** "if" alone doesn't make it an instruction. Test: does
  the clause describe system behavior (note) or tell the reader to do something
  (a step)? "The server returns 503 if upstream is slow" = note. "If you get 503,
  check /health" = step.

### Cross-references
Rule 1.1 (approved words), Rule 1.5 (technical nouns), Rule 1.7 (no
technical-noun-as-verb), Rule 5.3 (imperative vs descriptive), Rule 5.4
(descriptive-before-command — a note must not follow this pattern), Rule 5.6
(separate steps for separate actions), Rule 7.1 (risk signal words), Rule 9.1
(descriptive writing).

## Quick checklist for LLM code-doc generation

When generating install steps, API guides, READMEs, docstrings, commit messages,
or error text, apply Section 5 in this order:

1. **5.3 — Use imperative verbs** for every instruction. Drop passive voice,
   gerunds, and modals (can/should/may). Reserve "must" for WARNING/CAUTION.
2. **5.2 — One instruction per sentence.** Number steps. Split compound
   instructions. Don't put preconditions, results, or "and"-chained actions in one
   sentence unless they are simultaneous or an immediate result.
3. **5.1 — Keep each procedural sentence ≤ 20 words** (notes ≤ 25). Exclude code
   blocks and count backtick tokens as one word each. Split long sentences at
   conjunctions/conditions or into lists.
4. **5.4 — Put the condition before the command**, with a comma.
   `After you set DATABASE_URL, run the migration.` Never reverse the order.
5. **5.5 — Keep NOTES descriptive only.** No imperatives, no commands, no limits.
   If a note tells the reader to act, make it a work step (or a WARNING). A note
   sentence may be up to 25 words.

Defaults that are NOT instructions: code blocks, terminal output, string literals,
identifier names, and the words around a backticked technical noun.

---

<!-- rules-sec6.md -->

# Level 5 — Section 6: Sentence and Paragraph Structure (Rules 6.1–6.6)

This slice of the STE-Code standard governs how to organize sentences and
paragraphs in code documentation. It is part of the full standard (all rules +
extensions + dictionary + provenance) at Level 5.

## What this section is for

When an LLM generates code documentation (README, API docs, docstrings, inline
comments, commit messages, error messages, changelogs, config comments), apply
these six rules so the output is easy to read on the first pass:

- **Rule 6.1** — Give information gradually; one subject per sentence.
- **Rule 6.2** — Use key words and key phrases to give the text a logical structure.
- **Rule 6.3** — Write short sentences (max 25 words each).
- **Rule 6.4** — Use paragraphs to group related information (topic sentence first).
- **Rule 6.5** — Each paragraph has only one topic.
- **Rule 6.6** — No paragraph has more than six sentences.

The rules build on each other: 6.1 splits compound sentences → 6.2 links the
short sentences with repeated key words → 6.3 keeps each sentence short → 6.4
groups related sentences into paragraphs → 6.5 keeps each paragraph on one
topic → 6.6 caps paragraph length.

## Shared code-domain vocabulary

Across all six rules, prefer plain approved verbs and avoid unapproved synonyms:

- `make` (not "create"/"generate"), `start` (not "initiate"), `stop` (not
  "terminate"), `get` (not "retrieve"/"fetch"), `send` (not "transmit"),
  `show` (not "display"/"render"), `set` (not "configure"/"assign"),
  `check` (not "verify"/"ensure"), `use` (not "utilize"/"leverage").
- Approved connecting words: `and`, `but`, `then`, `thus`, `also`, `however`,
  `therefore`, `for example`, `as a result`, `at the same time`. Place them
  near the start of a sentence so the reader sees the signal first.
- Technical code nouns (class names, function names, library names, framework
  names) are allowed even when not in the approved dictionary (Rule 1.5). Do
  not use a technical noun as a verb.

---

## Rule 6.1 — Give Information Gradually

Adapted from ASD-STE100 Issue 9, Rule 6.1.

**Core rule.** In code documentation, give the reader one piece of information
at a time. Each sentence contains only one subject performing one action. Do
not combine multiple actions, multiple conditions, or multiple subjects in one
sentence. Applies to every form of documentation: README, API reference,
docstrings, inline comments, commit messages, error messages, log entries,
changelogs, config files.

**Why.** Human working memory holds ~4–7 items. A sentence with multiple
subjects and verbs forces the reader to hold all of them until the sentence
ends, raising cognitive load — especially when the reader is also parsing code.

**Single-subject constraint (grammar).**
- One subject + two verbs sharing that subject is OK: "The function validates
  the input and returns a result." (one subject "function").
- Two subjects is NOT OK: "The function validates the input and the middleware
  logs the result." → split: "The function validates the input. The middleware
  logs the result."

**Splitting rules.**
- Coordinating conjunction (`and`/`or`/`but`) joining two clauses, each with
  its own subject — split at the conjunction.
- Subordinating conjunction (`because`/`since`/`while`/`if`) — one main clause
  + one dependent clause is OK, unless the dependent clause introduces a new
  subject with its own chain of actions (then move it to its own sentence).
- Relative clause (`which`/`that`/`who`) describing the main subject is OK; one
  that introduces a new subject + new actions must be split.

**Code-domain example (auth middleware).**

Non-STE (one dense sentence, ~90 words):
> The authentication middleware validates bearer tokens from the authorization
> header by calling the `validateToken` function in the security module which
> decodes the JWT payload using the `HS256` algorithm from the `jwt-signer`
> library and checks the `exp` claim against the current server time before
> extracting the `sub` and `role` claims and attaching them as properties on
> the `request.auth` object, and if the token is expired or malformed the
> middleware returns a `401 Unauthorized` response with a JSON error body ...

STE (one subject per sentence):
> The authentication middleware validates each incoming request. The middleware
> reads the bearer token from the `Authorization` header. It sends the token to
> the `validateToken` function in the `security` module. The `validateToken`
> function decodes the JWT payload. It uses the `HS256` algorithm from the
> `jwt-signer` library. Then it compares the `exp` claim with the current
> server time. If the token is not expired and not malformed, the function gets
> the `sub` and `role` claims. It attaches these claims as properties on the
> `request.auth` object. If the token is expired, the middleware returns a
> `401 Unauthorized` response. The response body is a JSON object: the
> `message` field contains a description of the error; the `errorCode` field is
> set to `TOKEN_EXPIRED`. If the token is malformed, the middleware returns a
> `401 Unauthorized` response. The `errorCode` field in the response is set to
> `TOKEN_MALFORMED`. The middleware also logs each failure to the audit trail.
> It calls the `AuditLogger.log` static method. This method writes a record to
> the `audit_events` table in the primary database. The write uses an
> asynchronous pattern that does not block the response pipeline.

**Per-context guidance.**
- README: one concept per sentence. State the purpose, then the install
  command, then a usage example — each in its own sentence.
- API docs: one sentence for method+path, one per parameter, one per response
  field or status code. A reader who looks up one parameter must not read a
  paragraph about ten unrelated things.
- Docstrings/comments: one behavior per sentence. Each parameter and each
  return condition gets its own sentence.
- Commit messages: one logical change per sentence; use a summary line + bullet
  body, not "Add X, fix Y, update Z, refactor W" as one sentence.
- Error/log messages: one problem per message with a distinct error code; one
  event per log line.
- Changelogs: one change per entry; separate feature / fix / deprecation.

**Paradigm-specific.** Object-oriented: one method/behavior per sentence;
describe the override chain step by step. Functional: one transformation per
sentence; do not describe an entire `>>=` or pipe chain in one sentence.
Procedural: one step/branch per sentence — if/else and loop bodies stay separate
sentences. Declarative: one resource/constraint/column per sentence. Systems:
one ownership rule / lifetime constraint / memory operation per sentence.

**Edge cases.**
- A framework name combining multiple actions (e.g.
  `UserAuthenticationAndAuthorizationService`) is one technical noun — do not
  split it; keep the single-subject rule for the surrounding prose.
- Tool-generated docs (OpenAPI/JSDoc/Sphinx) may emit compound sentences. If
  you cannot change the output, add a one-subject-per-sentence summary above the
  generated block.
- Control-flow keywords (`if`/`else`/`while`/`try-catch`) naturally have
  multiple subjects — use one sentence per branch.
- CLI `--help`/error codes have limited space: still one subject per sentence;
  use fragments only when the display format enforces them.
- When rewriting existing compound docs, check for hidden logical dependency:
  if B depends on A, describe A first, then B.

**See also.** Rule 6.2, 6.3, 6.4, 6.5; Rule 1.1 (approved words); Rule 1.11
(one term per concept).

---

## Rule 6.2 — Use Key Words and Key Phrases to Give Your Text a Logical Structure

Adapted from ASD-STE100 Issue 9, Rule 6.2.

**Core rule.** Use key words (terms repeated across a documentation block) and
key phrases (multi-word expressions) to connect related ideas across sentences.
Key words are the threads that bind a block into one coherent unit. Do not change
the key word within a block — the same term must carry the same meaning
everywhere (links to Rule 1.11). Place approved connecting words near the start
of a sentence so the reader sees the signal before the content.

**Approved connecting words/phrases.** `and`, `but`, `then`, `thus`, `also`,
`however`, `therefore`, `for example`, `as a result`, `at the same time`. Do NOT
use `moreover`, `furthermore`, `nevertheless`, `subsequently`, or
`utilize`/`leverage` as connectors.

**How key words work (example chain).** Across the auth-middleware block:
> Sentence 1: The authentication middleware validates each incoming request.
> Sentence 2: The middleware reads the bearer token from the `Authorization` header. (repeats "middleware")
> Sentence 3: It sends the token to the `validateToken` function in the `security` module. (repeats "token")
> Sentence 4: The `validateToken` function decodes the JWT payload. (repeats "`validateToken` function")
> Sentence 9: The response body is a JSON object. (repeats "response")

Three groups form by key word: (1) token validation, (2) error responses +
`errorCode`, (3) audit trail. The reader follows the chain sentence to sentence
without manual reconstruction.

**Key word by documentation type.**
- README: repeat the project/library name and core concept ("middleware",
  "pipeline", "plugin") as the key word across sections. Do not switch to "the
  library"/"this tool".
- API docs: function names, parameter names, return-type names are the key
  words. Each sentence names the function or a pronoun referring to it.
- Docstrings: the function/class name is the key word; use parameter names and
  pronouns, not synonyms like "transmit"/"data"/"queue".
- Commit messages: the component name + action verb + affected module are the
  key words; do not switch to "pool"/"conn pool"/"connection manager".
- Error messages: the operation name + resource name are the key words; do not
  switch to "document"/"path".
- Cross-type consistency: the same key word means the same thing in README, API
  docs, docstrings, and commits (part of Rule 1.11).

**Paradigm-specific key words.**
- OOP: class names, method names, property names. For a builder/method chain,
  repeat the return type (e.g. "Stream") to show the flow.
- Functional: type names, function names, data constructors; the value flowing
  through transformations is the key word (e.g. "Result", the "changeset").
- Procedural: variable names, struct fields, error codes (e.g. "buffer").
- Declarative: resource names, column names, attribute names (e.g.
  "aws_instance").
- Systems: ownership terms, lifetime names, pointer names (e.g. "buffer",
  "borrow").

**Edge cases.**
- A framework name that is an unapproved word (e.g. a library named "Leverage")
  is a technical code noun — keep it as the key word; do not replace with a
  synonym.
- A short language keyword that carries little meaning (Go `go`, Rust `mut`) is
  not a good key word — use a descriptive key phrase that includes it (e.g.
  "goroutine").
- Generated code with verbose type names (e.g. `UserServiceClientImpl`) is the
  key word even though long — do not shorten to "client"/"stub"/"it".
- Multi-language repos: pick one key word for a cross-language concept (e.g.
  "map" for Python `dict` / Java `HashMap` / Go `map`) and note the
  language-specific names once.
- Multi-word key phrases ("connection pool", "rate limiter", "retry policy")
  stay intact — do not break them apart mid-document.

**Grammar notes.** Key-word repetition is lexical cohesion. Three cohesive ties:
(1) Repetition ("The middleware validates the request. The middleware reads the
token."); (2) Pronoun reference ("It reads the token.") — use sparingly, repeat
the full key word after two sentences; (3) Approved synonym/hypernym. Topic is
the subject of each sentence (topic-comment structure): keep the same key word in
subject position. A "dangling key word" (introduced once, never repeated) breaks
the structure. Use connecting words at the start of sentences, not buried.

**See also.** Rule 6.1, 6.3, 6.4, 6.5; Rule 1.5 (technical code nouns), Rule
1.8 (standard technical nouns), Rule 1.9 (short technical nouns), Rule 1.11 (one
term per concept).

---

## Rule 6.3 — Write Short Sentences. Maximum 25 Words per Sentence.

Adapted from ASD-STE100 Issue 9, Rule 6.3.

**Core rule.** In descriptive code documentation, the maximum sentence length is
25 words. Short sentences give clear structure and make information easier to
understand. This is a hard ceiling for descriptive text; procedures (imperative
steps) are naturally shorter.

**Why the limit.** A 25-word sentence can hold at most ~2 clauses with
connecting words — matching working-memory capacity. Most English clauses are
6–12 words, so the limit indirectly bounds clause density. Splitting one complex
sentence into several short ones improves clarity even when the original is under
25 words.

**Examples (code-domain).**
- Non-STE (32 w): "The configuration loader reads the YAML manifest file from
  the filesystem and parses it into an in-memory representation that other
  modules can query at runtime to determine their operational parameters."
  → STE: "The configuration loader reads the YAML manifest file from the
  filesystem. It parses the file into an in-memory representation. Other modules
  can query this representation at runtime. They use it to find their
  operational parameters." (20/8/7/8)
- Non-STE (34 w): "The cache invalidation strategy employs a time-to-live
  mechanism combined with a least-recently-used eviction policy to ensure that
  stale data is removed and memory consumption remains within the allocated heap
  budget."
  → STE: "The cache invalidation strategy uses a time-to-live mechanism. It also
  uses a least-recently-used eviction policy. Together, these mechanisms remove
  stale data. They also keep memory consumption within the allocated heap
  budget." (16/10/7/10)
- Non-STE (21 w): "This function provides the ability to run arbitrary software
  applications within a sandboxed execution environment that isolates system
  resources."
  → STE: "This function lets you run software applications in a sandbox. The
  sandbox isolates system resources." (8/5)

**Per-context guidance.**
- README: one sentence for the project, one for prerequisites, one for install.
- API docs: one short sentence each for path+method, each parameter, each
  response field, each error code.
- Docstrings: one sentence for purpose, one per parameter, one for return, one
  per exception — all under 25 words.
- Commit messages: subject line ≤72 chars; one short sentence per logical
  change in the body.
- Error messages: two short sentences — the problem, then the action. Log
  aggregation tools parse by line, so one sentence per line helps filtering.

**Paradigm-specific.**
- OOP: split inheritance + behavior into separate sentences ("The
  `AuthenticatedController` class extends `BaseController`. It implements the
  `Auditable` and `Loggable` interfaces.").
- Functional: split composition from error behavior.
- Procedural: each step = one sentence; for safety-critical code, split
  allocation from copy from return.
- Declarative: document each resource argument in its own sentence.
- Systems (Rust ownership, C memory): short sentences are safety-critical; split
  borrowing/lifetime explanation into discrete sentences.

**Edge cases.**
- Long technical terms ("single sign-on", "Hypertext Transfer Protocol Secure")
  count as one unit; if one still pushes over 25 words, introduce an acronym
  (SSO) after first mention to cut later counts.
- Verbose language keywords (`synchronized`, `__attribute__((constructor))`) count
  as one word — keep the rest of the sentence short.
- Compound type signatures (TypeScript/Rust generics) often exceed 25 words: one
  sentence for the type shape, one for constraints, one for behavior.
- Legal/license text (MIT, Apache, GPL, copyright) is exempt; the surrounding
  explanation still obeys the limit.
- Generated documentation (JSDoc/Sphinx/`go doc`) may exceed the limit — fix the
  source docstrings, not the generated output.

**Counting rules.** Hyphenated compounds count as one word ("least-recently-used"
= 1). Acronyms count as one word ("JSON" = 1). Code tokens count as one word
(`Result<Vec<T>>` = 1). Do not count parenthetical word counts in examples.

**Grammar notes.** Prefer coordination with separate sentences over heavy
subordination (e.g. "The `parse` function throws a `SyntaxError`. This error
occurs when the input string contains invalid JSON." rather than a 27-word
sentence with three levels of subordination). Code docs use implicit connectives
(order implies flow) rather than academic "therefore"/"furthermore".

**See also.** Rule 6.1, 6.2, 6.4, 6.5; Rule 1.1 (approved words); Rule 1.10 (no
slang/jargon).

---

## Rule 6.4 — Use Paragraphs to Show Related Information

Adapted from ASD-STE100 Issue 9, Rule 6.4.

**Core rule.** In code documentation, a paragraph starts with a topic sentence
that tells the developer the topic of that paragraph. The sentences that follow
explain it or add related information. A new paragraph signals a new topic or
different information. This applies to procedures (numbered steps) and
descriptive writing alike.

**Why.** Paragraphs group related sentences and give the text a logical
sequence. A paragraph that mixes unrelated topics (install steps + config
options + usage) is not compliant. Use section headings for major topics and
paragraph breaks for sub-topics.

**Examples (data pipeline split into topic-sentence-led paragraphs).**

Non-STE (one dense paragraph, mixed stages + error handling):
> The data pipeline processes incoming events through a sequence of stages. Each
> stage transforms the event payload and passes it to the next stage. The first
> stage is validation ... The second stage is enrichment ... The third stage is
> transformation ... The final stage is persistence ... Error handling is
> implemented at each stage ... If a stage fails, the pipeline logs the error and
> routes the event to the dead-letter queue ...

STE (each stage = its own paragraph with a topic sentence):
> **1. Data Pipeline Overview** — The data pipeline processes incoming events
> through a sequence of stages. Each stage transforms the event payload and
> passes it to the next stage. Error handling is implemented at each stage ...
> **2. Validation Stage** — The first stage is validation. This stage checks the
> event schema. It rejects events that are malformed.
> **3. Enrichment Stage** — The second stage is enrichment. This stage adds
> metadata to the event: Timestamps; Source identifiers; Geolocation data.
> **4. Transformation Stage** — The third stage is transformation. This stage
> converts the event into the target format. Downstream consumers use this
> format.
> **5. Persistence Stage** — The final stage is persistence. This stage writes
> the transformed event to the data store and to the event log for audit.

**Per-context guidance.**
- README: each section starts with a topic sentence. Separate Installation,
  Configuration, Dependencies, Usage into their own paragraphs.
- API docs: endpoint description = topic sentence first; give authentication its
  own paragraph (before endpoint details); separate request schema, response
  schema, and error descriptions with clear topic sentences.
- Docstrings/inline comments: start with a one-line topic sentence, then a blank
  line, then more paragraphs (parameters / returns / raises / side effects /
  usage). Each inline comment is a one-sentence paragraph stating the topic of
  the following code.
- Commit messages: the first line is the topic sentence; the body uses paragraphs
  to group the problem, the changes, and the monitoring separately.
- Error messages: a single sentence states the topic (what failed + why); a
  multi-line error uses paragraphs to separate the error description, the
  diagnostic checks, and the stack trace.

**Paradigm-specific.**
- OOP: separate class purpose, constructor details, public API, and internal
  design into paragraph groups; one paragraph per method description.
- Functional: separate the type signature explanation, the behavior, the
  purity/algebraic properties, and the internal composition.
- Procedural: separate initialization, main loop, and cleanup phases.
- Declarative: give each resource its own paragraph group (identity, spec,
  dependencies).
- Systems: separate the ownership model, lifetime annotations, and unsafe-code
  justifications.

**Edge cases.**
- Framework name = approved word (e.g. "Make" the build tool vs "make" the verb):
  capitalize the tool, use a topic sentence to establish meaning.
- Code keywords (`break`, `continue`, `return`, `yield`) are technical nouns
  (Rule 1.5), not verbs — set them in backticks and start the paragraph with a
  topic sentence naming the keyword.
- A long code block must sit in its own paragraph; start the preceding paragraph
  with a topic sentence that names what the code does, end it, insert the block,
  then start a new paragraph to explain important parts.
- Auto-generated docs (JSDoc/Sphinx/`go doc`): insert a blank comment line
  between topics so the tool emits separate paragraphs.
- Mixed-author documents: apply structural linting; flag paragraphs >5 sentences
  or lacking a topic sentence (a Vale `existence` rule works).

**Grammar notes.** The topic sentence is a declarative simple-present sentence
that names the topic in subject position with an approved verb — never start a
paragraph with a subordinate clause ("Because...", "When...", "If..."). A
paragraph of five sentences cannot exceed 125 words (due to Rule 6.3). Ideal
length: docstrings 1–3 sentences per topic, README 3–5, API endpoint 4–6, error
messages 1. Place a paragraph break before a new concept, a code example, a
warning, a list, or a change in abstraction level. Do NOT break between a topic
sentence and its supporting sentences.

**See also.** Rule 6.1, 6.2, 6.3, 6.5; Rule 1.1, 1.5, 1.11; Rule 7.1 (use lists
for three or more items).

---

## Rule 6.5 — Make Sure That Each Paragraph Has Only One Topic

Adapted from ASD-STE100 Issue 9, Rule 6.5.

**Core rule.** Each paragraph in descriptive code documentation has only one
topic. The topic sentence is the first and most important sentence; it gives new
information and makes a logical connection to previous information (via a key
word and/or connecting word). If you write down the topic sentences of a
document, you get a good outline of its content.

**Why.** The topic sentence lets the developer find applicable information
quickly. When a paragraph drifts to a second topic, the reader loses the thread.
Rule 6.4 tells you to use paragraphs; Rule 6.5 tells you each paragraph gets one
topic.

**Example (auth middleware — one function, three topics).**

Non-STE (five topics in one sentence):
> The authentication middleware validates each request and the logging system
> records all validation failures to the audit trail while the response pipeline
> returns JSON error bodies with error codes and the database connection pool
> maintains idle connections for reuse and the configuration module reloads
> settings when the manifest file changes on disk.

STE (three single-topic paragraphs; topic sentences form an outline):
> The authentication middleware validates each incoming request. The middleware
> reads the bearer token from the `Authorization` header. It sends the token to
> the `validateToken` function ... Then it compares the `exp` claim ...
> If the token is expired, the middleware returns a `401 Unauthorized` response.
> The response body is a JSON object ... If the token is malformed, the middleware
> returns a `401 Unauthorized` response ...
> The middleware also logs each failure to the audit trail. It calls the
> `AuditLogger.log` static method ...

Outline from topic sentences: "The authentication middleware validates each
incoming request." / "If the token is expired, the middleware returns a `401
Unauthorized` response." / "The middleware also logs each failure to the audit
trail."

**Per-context guidance.** The "topic" definition changes with format, but one
topic per paragraph is constant.
- README: "What it does", "How to install", "How to configure", "How to
  contribute" are separate paragraphs.
- API docs: one paragraph for endpoint purpose, one for request format, one per
  response status group (success / client error / server error), one for auth.
- Docstrings: the topic is the function's contract (inputs, outputs, behavior) —
  do not explain why the function exists, side effects of other functions, or
  list callers.
- Commit messages: one commit = one topic; split unrelated changes into separate
  commits.
- Error messages: a one-topic paragraph — what went wrong, why, how to fix; put
  stack traces in a log, not the message.

**Paradigm-specific.**
- OOP: one paragraph per concern — class purpose, constructor, public interface,
  inheritance/interface, thread-safety. Method implementation detail belongs in
  the method docstring.
- Functional: one paragraph for input shape, transformation logic, output shape,
  edge cases; document each pipeline stage in its own paragraph.
- Procedural: one paragraph per phase — init, main loop, cleanup, error handling.
- Declarative: one paragraph per table/view, per Terraform resource, per K8s
  object (Deployment and its Service are separate topics even if related).
- Systems: one paragraph per ownership relationship or memory lifecycle
  (allocation, transfer, deallocation, unsafe invariants).

**Edge cases.**
- Framework name = unapproved word (e.g. "Execute" library): it is a technical
  noun, allowed; but do not use it as a verb in the same paragraph ("Use the
  `Execute` library to run background jobs.", not "Execute background jobs with
  the `Execute` library.").
- Large multi-topic legacy functions: use the docstring as a bullet-point topic
  index; give each responsibility its own paragraph in module-level docs.
- Generated API docs: each individual docstring must still follow the one-topic
  rule because the tool only combines them.
- Cross-cutting concerns (security, performance, accessibility): give them their
  own document/section with a one-paragraph summary + link per module.
- Error-code reference tables: the table is one container; each description cell
  is a mini-paragraph describing only one error condition.

**Grammar notes.** Always use deductive paragraphs (topic sentence first) — a
topic sentence at the end is invisible to a scanning reader. Repeat the key word
(or approved synonym) from the topic sentence in supporting sentences; a new
unconnected key word means drift. Use connecting words in the topic sentence:
"Also" (same topic, new angle), "However" (contrast), "For example" (instance),
"Therefore" (result). A paragraph is 3–7 sentences; a 10+ sentence paragraph
almost always has multiple topics. Separate paragraphs with a blank line (not
indentation-only).

**See also.** Rule 6.1, 6.2, 6.3, 6.4; Rule 1.11 (one term per concept); Rule
3.6 (approved verb forms); Rule 5.1 (imperative instructions); Rule 6.6 (≤6
sentences per paragraph).

---

## Rule 6.6 — Make Sure That No Paragraph Has More Than Six Sentences

Adapted from ASD-STE100 Issue 9, Rule 6.6.

**Core rule.** In code documentation, no paragraph has more than six sentences.
Paragraphs divide a block into logical units and keep the reader's attention. If
a paragraph has more than six sentences, divide it into two smaller paragraphs.
The six-sentence limit is a practical ceiling, not a target — most good
paragraphs use two to four sentences.

**Relationship to 6.4 and 6.5.** Rule 6.4 says use paragraphs; Rule 6.5 says
each paragraph has one topic; Rule 6.6 says don't let a paragraph grow past six
sentences. The three together produce short, single-topic paragraphs.

**When to split a paragraph.**
- It has more than six sentences.
- It covers two or more topics (Rule 6.5).
- A sentence introduces a new key word the earlier sentences don't use (Rule 6.2).
When splitting, group sentences that share a key word in the first paragraph;
start the new paragraph with a topic sentence that names the new key word.

**Code-domain examples.**
- ConnectionPool docstring: the Non-STE version packs four components (socket
  connections, reaper thread, bounded queue, metrics collector) into one 5-sentence
  paragraph; the STE version uses one outline paragraph + four short paragraphs,
  each under six sentences.
- POST /orders handler: the Non-STE version crams the whole lifecycle into one
  one-paragraph sentence; the STE version uses four paragraphs (parse, authorize,
  act, fail), each two to four sentences.
- AuthModule: five responsibilities in one paragraph → six paragraphs, each under
  six sentences, one topic per paragraph.
- Migration `upgrade()`: seven changes in one sentence/paragraph → six short
  paragraphs.
- Changelog v3.1.0: five unrelated changes in one paragraph → one short paragraph
  per change type; mark the API removal with DEPRECATED.

**Per-context guidance.**
- README: keep each feature description to a short paragraph; split
  install/configure/verify into separate paragraphs.
- API docs: keep each endpoint description short — purpose, request, response,
  errors each in its own paragraph under six sentences.
- Docstrings: keep the summary paragraph short; one short paragraph per concern
  (params, returns, raises); move a long parameter list to a bulleted list.
- Error/log diagnostics: a multi-line diagnostic block stays to six lines or
  fewer, or splits into a cause paragraph and a recovery paragraph.

**Paradigm-specific.** OOP: one responsibility per paragraph (e.g. each phase of
the order lifecycle). Functional: one pipeline stage per paragraph. Procedural:
one phase per paragraph (build/rollout/verify/fail). Declarative: one
resource/block per paragraph. Systems: one ownership rule per paragraph (memory
contracts are easy to bury in a long one).

**Edge cases.**
- A topic that needs >6 sentences: keep each paragraph under six sentences and
  continue the same topic in a second paragraph, starting it with "Also," or "In
  addition," (e.g. the garbage-collector description spans two paragraphs).
- A bulleted/numbered list is ONE paragraph regardless of item count. Rule 6.6
  limits the surrounding prose sentences, not the number of list items. Keep the
  intro sentence short; don't add a long closing sentence restating every item.
- Generated docs that emit one long paragraph per symbol: if you can't change the
  generator, add a short human-written summary above the block; the generated
  block is exempt only if you don't edit its source annotations.
- A short paragraph can still violate 6.5 by mixing two topics (e.g. three
  sentences covering both "cache" and "queue") — Rule 6.6 (sentence count) and
  6.5 (topic count) are independent; split even if under the limit.

**Grammar notes.** The six-sentence limit comes from reading psychology: the
topic fades from working memory after ~6 sentences, causing re-reading. Rule 6.6
counts sentences, not words — a paragraph can have six long or six short
sentences and still pass, but six 25-word sentences is at the edge of
readability; prefer 2–4 sentences. Lists/tables inside a paragraph don't add to
the surrounding prose sentence count. In procedural writing each step is its own
paragraph by convention, so 6.6 rarely applies — except when a step has a long
note/rationale (keep it under six sentences or move it to a note paragraph).

**See also.** Rule 6.4, 6.5, 6.1, 6.2, 6.3.

---

## Quick reference for LLM documentation generation

Apply this checklist to any code documentation you produce:

1. **6.1 Gradual** — one subject per sentence; split compound sentences at
   coordinating/subordinating conjunctions and relative clauses.
2. **6.2 Key words** — repeat the same technical noun/term as the key word
   across sentences; use approved connectors (`and`, `but`, `then`, `thus`,
   `also`, `however`, `therefore`, `for example`) at sentence start.
3. **6.3 Short** — every descriptive sentence ≤ 25 words (hyphenated terms,
   acronyms, and code tokens each count as one word).
4. **6.4 Paragraphs** — start each paragraph with a topic sentence; group
   related sentences; separate Installation/Config/Usage/API/etc.
5. **6.5 One topic** — each paragraph covers exactly one topic; topic sentences
   alone should outline the document.
6. **6.6 ≤6 sentences** — no paragraph exceeds six sentences; prefer 2–4; a list
   is one paragraph.

Cross-links within the standard: Section 1 (Vocabulary: approved words, technical
nouns, one term per concept), Section 3 (Verb forms), Section 5 (Imperative
instructions), Section 7 (Lists for three or more items). These six rules form
the sentence-and-paragraph backbone of STE-Code; they are necessary but not
sufficient — pair them with the vocabulary and writing-style rules for full
compliance.

---

<!-- rules-sec7.md -->

<!-- a-sec7-rule7.1.md -->

# Rule 7.1 — Use an Applicable Word (for Example, "Warning" or "Caution") to Identify the Level of Risk

> **Source:** Adapted from ASD-STE100 Issue 9, Rule 7.1

> **Source:** [master.md#sec7-rule7.1](ste-code/grouped/)

## Original Rule

**Rule 7.1** Use a word (for example, "warning" or "caution") or, when applicable, a symbol, to immediately show your reader the level of the related risk.

- If there is a risk of injury or death, use a "warning."
- If there is a risk of damage to machines, tools, or equipment, use a "caution."
- If there are the two levels of risk together, use a "warning."

In the non-STE example that follows, the safety instruction is a caution. But if you know about oxygen systems, you also know that oxygen mixed with other materials can cause explosions. Because there is a risk of injury or death here, you must identify this safety instruction as a warning.

Compare the wording in the two safety instructions. The non-STE safety instruction is an abstract sentence and only makes a general statement. The warning in STE gives clear and correct information about how to decrease the risk of explosion. The warning contains the words "explosion," "injury," and "death" to make the reader clearly understand how important this safety instruction is.

**Spec example:**

> **Non-STE:** CAUTION: EXTREME CLEANLINESS OF OXYGEN TUBES IS IMPERATIVE.
>
> **STE:** WARNING: BEFORE YOU FILL THE LIQUID OXYGEN SYSTEM, PUT ON A FACE MASK AND PROTECTIVE CLOTHING. LIQUID OXYGEN CAN CAUSE IRRITATION OF THE RESPIRATORY TRACT AND EYE IRRITATION.

## STE-Code Adaptation

**Rule 7.1** In code documentation, use a signal word (for example, "WARNING" or "CAUTION") to immediately show your reader the level of the related risk.

- If there is a risk of security vulnerabilities, data loss, or system corruption, use a "WARNING."
- If there is a risk of unexpected behavior, performance degradation, or incorrect results, use a "CAUTION."
- If there are the two levels of risk together, use a "WARNING."

Severity mapping: This rule teaches the WARNING and CAUTION safety signal words for code documentation. For release-note and changelog severity, map the same levels as follows: WARNING to BREAKING, CAUTION to DEPRECATED, NOTE to NOTE.

In the non-STE example that follows, the safety instruction is a caution. But if you know about data validation in software systems, you also know that unvalidated input can cause security breaches and data loss. Because there is a risk of security vulnerabilities and data loss here, you must identify this safety instruction as a warning.

Compare the wording in the two code-documentation safety instructions. The non-STE safety instruction is an abstract statement and only makes a general claim. The warning in STE-Code gives clear and correct information about how to decrease the risk of security breaches. The warning contains the words "security breach" and "data loss" to make the reader clearly understand how important this safety instruction is.

### Examples

> *Adapted from spec pair:* Non-STE: `CAUTION: EXTREME CLEANLINESS OF OXYGEN TUBES IS IMPERATIVE.`  |  STE: `WARNING: BEFORE YOU FILL THE LIQUID OXYGEN SYSTEM, PUT ON A FACE MASK AND PROTECTIVE CLOTHING. LIQUID OXYGEN CAN CAUSE IRRITATION OF THE RESPIRATORY TRACT AND EYE IRRITATION.` (ASD-STE100 Issue 9, Rule 7.1, page 99 — escalated from CAUTION to WARNING because the true risk is injury or death.)

> **Non-STE:** CAUTION: ALWAYS VALIDATE INPUT DATA.
>
> **STE:** WARNING: BEFORE YOU PROCESS INPUT DATA, MAKE SURE THAT YOU SANITIZE AND VALIDATE THE DATA. UNSANITIZED INPUT CAN CAUSE SECURITY BREACHES AND DATA LOSS.
>
> *Adapted from the spec pair shown in the Original Rule above: an abstract caution about cleanliness is escalated to a specific warning when the true risk level (injury or death) is higher. The code-domain pair below applies the same escalation. A vague caution about input becomes a warning that names the security breach and data loss risk.*

> **Non-STE:** CAUTION: THE CONFIGURATION FILE MAY CONTAIN OUTDATED SETTINGS.
>
> **STE:** CAUTION: BEFORE YOU DEPLOY THE APPLICATION, COMPARE THE CONFIGURATION FILE AGAINST THE REFERENCE CONFIGURATION. OUTDATED SETTINGS CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.
>
> *Code-domain CAUTION example — risk of unexpected behavior and incorrect results, not security or data loss.*

> **See also:** Rule 5.3 — Imperative (Command) Form for Instructions; Rule 7.2 — Start a Safety Instruction with a Clear and Accurate Command or Condition

---

## Code-Domain Explanation

This rule applies to all code documentation types. Each type has a different level of exposure to security risks, data loss, and unexpected behavior. Use the correct signal word for the risk level. Do not let the signal word become routine noise.

### README Files

README files are the first document a user reads. Use WARNING for security-critical setup steps. Use CAUTION for configuration steps that can cause incorrect behavior. Place signal words at the top of the relevant section. Do not bury them in a paragraph.

**WARNING in a README setup section:**

> **Non-STE:** Note: you should be careful with the API key and not commit it to version control.
>
> **STE:** WARNING: DO NOT COMMIT THE API KEY TO VERSION CONTROL. AN EXPOSED API KEY CAN CAUSE UNAUTHORIZED ACCESS AND DATA LOSS.
>
> *Principles applied: P1, P2 — "warning" for security risk, imperative command, specific consequence*

**CAUTION in a README configuration section:**

> **Non-STE:** Make sure the port number does not conflict with other services or the app won't start.
>
> **STE:** CAUTION: BEFORE YOU START THE APPLICATION, CHECK THAT THE PORT NUMBER DOES NOT CONFLICT WITH OTHER SERVICES. A PORT CONFLICT CAN CAUSE THE APPLICATION TO FAIL.
>
> *Principles applied: P9, P11 — clear signal word, specific condition, specific consequence*

### API Documentation

API documentation describes functions that external callers use. Use WARNING for endpoints that handle sensitive data, authentication, or destructive operations. Use CAUTION for endpoints that have side effects or rate limits.

**WARNING for a destructive API endpoint:**

> **Non-STE:** DELETE /users/:id removes the user and all associated data, this cannot be undone.
>
> **STE:** WARNING: DELETE /users/:id REMOVES THE USER AND ALL RELATED DATA PERMANENTLY. THIS OPERATION CANNOT BE UNDONE. VERIFY THE USER ID BEFORE YOU SEND THE REQUEST.
>
> *Principles applied: P1, P5 — warning for irreversible data loss, technical noun preserved in backticks, specific pre-action instruction*

**CAUTION for a rate-limited endpoint:**

> **Non-STE:** This endpoint allows 100 requests per minute, exceeding this will return 429 errors.
>
> **STE:** CAUTION: THE ENDPOINT ALLOWS A MAXIMUM OF 100 REQUESTS PER MINUTE. IF YOU EXCEED THE LIMIT, THE ENDPOINT RETURNS A 429 ERROR. MONITOR THE `X-RateLimit-Remaining` HEADER.
>
> *Principles applied: P1, P12 — caution for incorrect results (429 errors), technical verb "monitor" is allowed*

### Docstrings and Inline Comments

Docstrings describe function contracts. Use WARNING in docstrings when a function can cause security vulnerabilities or data corruption if used incorrectly. Use CAUTION when a function has performance pitfalls or non-obvious side effects.

**WARNING in a Python docstring:**

```python
def execute_sql(query: str, params: tuple = ()) -> list:
    """Run a raw SQL query.

    WARNING: THIS FUNCTION EXECUTES THE QUERY DIRECTLY. SANITIZE ALL
    USER INPUT BEFORE YOU PASS IT TO THIS FUNCTION. UNSANITIZED INPUT
    CAN CAUSE SQL INJECTION ATTACKS AND DATA LOSS.

    Parameters:
        query: The raw SQL query string.
        params: The query parameters. The default is an empty tuple.

    Returns:
        A list of result rows.
    """
```

*Principles applied: P1, P7 — warning for security risk, "sanitize" used as a verb, specific consequence named*

**CAUTION in a JavaScript JSDoc comment:**

```javascript
/**
 * Caches the result of an expensive computation.
 *
 * CAUTION: THE CACHE USES MEMORY PROPORTIONAL TO THE NUMBER OF
 * UNIQUE ARGUMENTS. FOR UNBOUNDED INPUT SETS, USE A CACHE WITH
 * A SIZE LIMIT. AN UNLIMITED CACHE CAN CAUSE MEMORY EXHAUSTION.
 *
 * @param {Function} fn - The function to cache.
 * @returns {Function} A cached version of the function.
 */
function memoize(fn) {
  const cache = new Map();
  return function (...args) {
    const key = JSON.stringify(args);
    if (cache.has(key)) {
      return cache.get(key);
    }
    const result = fn.apply(this, args);
    cache.set(key, result);
    return result;
  };
}
```

*Principles applied: P1, P13 — caution for performance degradation (memory exhaustion), "cache" used as noun not verb*

### Commit Messages

Commit messages can use WARNING or CAUTION as the commit type prefix. Use `WARNING:` for commits that fix security vulnerabilities or prevent data loss. Use `CAUTION:` for commits that change behavior in a way that downstream consumers must know about. This convention helps automated changelog tools group commits by severity.

> **Non-STE:** fix: patch SQL injection in login form
>
> **STE:** WARNING: Prevent SQL injection in the login form. The previous code did not sanitize the `username` parameter. This vulnerability could permit unauthorized database access.
>
> *Principles applied: P1, P14 — warning for security breach risk, American English spelling*

> **Non-STE:** change: update default timeout from 30s to 10s
>
> **STE:** CAUTION: Change the default timeout from 30 seconds to 10 seconds. Update all callers that rely on the previous default. The shorter timeout can cause connection failures in high-latency environments.
>
> *Principles applied: P1 — caution for unexpected behavior, specific instruction for callers*

### Error Messages

Error messages are read during incidents. Use WARNING in error messages when the system detects a condition that can lead to security compromise or data corruption. Use CAUTION when the system detects a condition that can lead to incorrect results. Error messages must be actionable.

**WARNING in an error message:**

> **Non-STE:** Error: invalid signature
>
> **STE:** WARNING: THE REQUEST SIGNATURE IS NOT VALID. THE REQUEST MAY HAVE BEEN TAMPERED WITH. REJECT THE REQUEST. CHECK YOUR SIGNING KEY AND ALGORITHM.
>
> *Principles applied: P1, P9 — warning for security risk, short clear sentences, actionable instruction*

**CAUTION in an error message:**

> **Non-STE:** The configuration value for max_connections must be less than database pool size.
>
> **STE:** CAUTION: THE `max_connections` VALUE IS GREATER THAN THE `pool_size` VALUE. THIS CONFIGURATION CAN CAUSE CONNECTION FAILURES. SET `max_connections` TO A VALUE THAT IS NOT MORE THAN `pool_size`.
>
> *Principles applied: P1, P11 — caution for incorrect results, one term per concept, actionable correction*

---

## Paradigm-Specific Guidance

### Object-Oriented (Java, C++, C#, Python Classes)

Object-oriented documentation describes class contracts, inheritance hierarchies, and mutable state. Use WARNING when a subclass override can break a security invariant. Use CAUTION when a method mutates shared state.

**WARNING for a security-sensitive override (Java):**

> **Non-STE:** Subclasses should be careful to call super.validate() before performing custom validation.
>
> **STE:** WARNING: OVERRIDE THE `validate` METHOD WITH CARE. CALL `super.validate()` BEFORE YOU ADD CUSTOM VALIDATION LOGIC. IF YOU SKIP THE BASE VALIDATION, UNTRUSTED DATA CAN BYPASS SECURITY CHECKS.
>
> *Principles applied: P1, P7 — warning for security risk, "call" used as imperative verb, specific consequence*

```java
abstract class RequestValidator {
    /** Base security checks that apply to all request types. */
    void validate(Request request) {
        if (request.getUser() == null) {
            throw new SecurityException("Missing user context");
        }
        if (!request.isAuthenticated()) {
            throw new SecurityException("Request is not authenticated");
        }
    }
}

class PaymentRequestValidator extends RequestValidator {
    @Override
    void validate(Request request) {
        // WARNING: CALL super.validate() BEFORE YOU ADD CUSTOM LOGIC.
        super.validate();
        PaymentRequest payment = (PaymentRequest) request;
        if (payment.getAmount() <= 0) {
            throw new IllegalArgumentException("Amount must be greater than zero");
        }
    }
}
```

*The `PaymentRequestValidator.validate` method shows the correct override: it calls `super.validate()` first, so the base security checks (user context and authentication) still run. If a developer removes that call, an untrusted request can bypass the checks and reach the payment logic.*

**CAUTION for mutable shared state (C++):**

> **Non-STE:** Note that this method modifies the internal cache which may affect other threads.
>
> **STE:** CAUTION: THE `invalidateCache` METHOD MODIFIES THE INTERNAL CACHE. THIS CHANGE AFFECTS ALL THREADS THAT USE THE CACHE. USE A LOCK BEFORE YOU CALL THIS METHOD.
>
> *Principles applied: P1, P5 — caution for unexpected behavior in concurrent contexts, technical noun "thread" allowed, specific guard instruction*

### Functional (Haskell, Elixir, Clojure, Rust)

Functional documentation describes pure functions, effect types, and immutable data. Use WARNING when an unsafe escape hatch breaks referential transparency. Use CAUTION when a lazy operation can cause space leaks.

**WARNING for unsafe escape hatches (Haskell):**

> **Non-STE:** Use unsafePerformIO with caution as it breaks purity.
>
> **STE:** WARNING: `unsafePerformIO` BYPASSES THE IO TYPE SYSTEM. THIS FUNCTION HIDES SIDE EFFECTS IN PURE CODE. INCORRECT USE CAN CAUSE NONDETERMINISTIC BEHAVIOR AND DATA CORRUPTION. USE THIS FUNCTION ONLY WHEN NO SAFE ALTERNATIVE EXISTS.
>
> *Principles applied: P1, P8 — warning for data corruption risk, standard technical noun preserved, clear prohibition*

**CAUTION for space leaks (Haskell):**

> **Non-STE:** foldl is strict, but if you accumulate large thunks you might run out of memory.
>
> **STE:** CAUTION: `foldl` ACCUMULATES UNEVALUATED EXPRESSIONS (THUNKS). A LARGE ACCUMULATOR CAN CAUSE A SPACE LEAK AND MEMORY EXHAUSTION. USE `foldl'` FOR STRICT ACCUMULATION.
>
> *Principles applied: P1, P9 — caution for performance degradation, alternative provided, short clear sentences*

### Procedural (C, Go, Bash)

Procedural documentation describes memory management, buffer handling, and system calls. Use WARNING for buffer overflows, use-after-free, and undefined behavior. Use CAUTION for platform-specific behavior or resource limits.

**WARNING for buffer overflow (C):**

> **Non-STE:** Make sure the destination buffer is at least as large as the source string when using strcpy.
>
> **STE:** WARNING: `strcpy` DOES NOT CHECK THE SIZE OF THE DESTINATION BUFFER. IF THE SOURCE STRING IS LARGER THAN THE DESTINATION BUFFER, THE FUNCTION WRITES PAST THE BUFFER BOUNDARY. THIS BUFFER OVERFLOW CAN CAUSE SECURITY VULNERABILITIES AND SYSTEM CRASHES. USE `strncpy` WITH A SIZE LIMIT.
>
> *Principles applied: P1, P8 — warning for security risk and system corruption, standard technical noun, alternative provided*

**CAUTION for platform-specific behavior (Go):**

> **Non-STE:** On Windows, filepath separator is backslash, be careful with cross-platform paths.
>
> **STE:** CAUTION: THE `filepath` PACKAGE USES THE OPERATING SYSTEM PATH SEPARATOR. ON WINDOWS, THE SEPARATOR IS `\\`. ON UNIX, THE SEPARATOR IS `/`. USE `filepath.Join` OR `filepath.FromSlash` TO BUILD CROSS-PLATFORM PATHS. HARDCODED SEPARATORS CAUSE INCORRECT PATHS.
>
> *Principles applied: P1, P11 — caution for incorrect results, one term per concept, specific code examples*

### Declarative (SQL, Terraform, Kubernetes YAML)

Declarative documentation describes desired state, resource specifications, and destructive operations. Use WARNING for operations that destroy data or expose resources publicly. Use CAUTION for configuration values that have subtle effects on behavior.

**WARNING for destructive SQL operations:**

> **Non-STE:** Caution: this migration drops the users table.
>
> **STE:** WARNING: THIS MIGRATION DROPS THE `users` TABLE. ALL USER DATA IS DELETED PERMANENTLY. BACK UP THE DATABASE BEFORE YOU RUN THIS MIGRATION. VERIFY THAT YOU RUN THE MIGRATION AGAINST THE CORRECT DATABASE.
>
> *Principles applied: P1, P5 — warning for irreversible data loss, technical noun in backticks, multiple pre-action checks*

**CAUTION for Terraform resource recreation:**

> **Non-STE:** Changing the subnet_id will cause the EC2 instance to be recreated, which may cause downtime.
>
> **STE:** CAUTION: IF YOU CHANGE THE `subnet_id` ARGUMENT, TERRAFORM DESTROYS THE EXISTING EC2 INSTANCE AND CREATES A NEW ONE. THIS RECREATION CAUSES DOWNTIME. THE INSTANCE PUBLIC IP ADDRESS CHANGES. PLAN THE CHANGE DURING A MAINTENANCE WINDOW.
>
> *Principles applied: P1, P12 — caution for unexpected behavior and downtime, "plan" used as approved verb, specific consequences listed*

**WARNING for public Kubernetes exposure:**

> **Non-STE:** Be careful with LoadBalancer type services as they expose your app to the internet.
>
> **STE:** WARNING: A SERVICE OF TYPE `LoadBalancer` EXPOSES THE APPLICATION TO THE PUBLIC INTERNET. UNAUTHORIZED USERS CAN SEND REQUESTS TO THE APPLICATION. MAKE SURE THAT AUTHENTICATION AND NETWORK POLICIES ARE IN PLACE BEFORE YOU APPLY THIS CONFIGURATION.
>
> *Principles applied: P1, P7 — warning for security risk, "apply" used as imperative verb, specific pre-condition check*

### Systems (Rust Ownership, C Memory)

Systems documentation describes ownership, unsafe blocks, and memory layout. Use WARNING for undefined behavior, data races, and memory corruption. Use CAUTION for performance characteristics of unsafe optimizations.

**WARNING for undefined behavior (Rust):**

> **Non-STE:** Dereferencing a raw pointer is unsafe and may cause undefined behavior if the pointer is invalid.
>
> **STE:** WARNING: DEREFERENCING A RAW POINTER CAN CAUSE UNDEFINED BEHAVIOR. UNDEFINED BEHAVIOR CAN CORRUPT MEMORY, CAUSE SECURITY VULNERABILITIES, AND CRASH THE PROGRAM. BEFORE YOU DEREFERENCE A RAW POINTER, CHECK THAT: (1) THE POINTER IS NOT NULL. (2) THE POINTER IS CORRECTLY ALIGNED. (3) THE POINTER POINTS TO VALID, INITIALIZED MEMORY.
>
> *Principles applied: P1, P4 — warning for system corruption and security, vertical list for preconditions, explicit checklist*

**CAUTION for unsafe optimization tradeoffs:**

> **Non-STE:** Using MaybeUninit can improve performance but be careful about initialization.
>
> **STE:** CAUTION: `MaybeUninit` SKIPS INITIALIZATION TO IMPROVE PERFORMANCE. IF YOU READ UNINITIALIZED MEMORY, THE PROGRAM BEHAVIOR IS UNDEFINED. MAKE SURE THAT YOU INITIALIZE THE VALUE BEFORE YOU READ IT. MEASURE THE PERFORMANCE GAIN BEFORE YOU USE THIS TYPE.
>
> *Principles applied: P1, P9 — caution for incorrect results (undefined behavior is also a WARNING-level risk, but the primary risk here is the subtlety of the contract), specific guard instruction*

---

## Extended Examples

### Example 1 — Misclassified Risk Level in API Key Documentation

> **Non-STE:** CAUTION: Store the API key in an environment variable.
>
> **STE:** WARNING: STORE THE API KEY IN AN ENVIRONMENT VARIABLE. DO NOT HARDCODE THE API KEY IN THE SOURCE CODE. AN EXPOSED API KEY CAN CAUSE UNAUTHORIZED ACCESS, DATA THEFT, AND SERVICE ABUSE. ADD THE `.env` FILE TO `.gitignore`.
>
> *Principles applied: P1 — the original used CAUTION for a security risk (exposed credentials). Escalated to WARNING. Specific consequences named. Actionable prevention steps.*

### Example 2 — Missing Consequence in Database Migration Documentation

> **Non-STE:** WARNING: Run this migration carefully.
>
> **STE:** WARNING: BEFORE YOU RUN THIS MIGRATION, BACK UP THE `transactions` TABLE. THE MIGRATION REMOVES ALL RECORDS OLDER THAN 90 DAYS. THE DATA CANNOT BE RECOVERED AFTER THE MIGRATION COMPLETES. VERIFY THE DATE THRESHOLD AGAINST YOUR RETENTION POLICY.
>
> *Principles applied: P1, P9 — the original warning has no specific consequence and no actionable instruction. The STE version names the consequence (irrecoverable data loss), gives a pre-action check, and links to a policy reference.*

### Example 3 — Abstract Caution in a Library README

> **Non-STE:** CAUTION: Be mindful of thread safety when using this library.
>
> **STE:** CAUTION: THE `Cache` CLASS IS NOT THREAD-SAFE. IF YOU SHARE A `Cache` INSTANCE ACROSS THREADS, RACE CONDITIONS CAN CAUSE INCORRECT CACHE ENTRIES AND APPLICATION CRASHES. USE `ConcurrentCache` FOR MULTI-THREADED APPLICATIONS. USE A MUTEX FOR MANUAL SYNCHRONIZATION.
>
> *Principles applied: P1, P8 — the original caution is abstract and does not give a specific risk or a fix. The STE version names the class, explains the risk, and gives two alternatives.*

### Example 4 — Wrong Signal Word for Performance Degradation

> **Non-STE:** WARNING: This function is slow for large inputs.
>
> **STE:** CAUTION: THIS FUNCTION HAS O(N²) TIME COMPLEXITY. FOR INPUTS LARGER THAN 10,000 ITEMS, THE FUNCTION CAN TAKE SEVERAL MINUTES TO COMPLETE. USE `fastSort` FOR LARGE INPUTS. `fastSort` HAS O(N LOG N) TIME COMPLEXITY.
>
> *Principles applied: P1, P9 — performance degradation is a CAUTION-level risk, not a WARNING. The original used WARNING incorrectly. The STE version downgrades to CAUTION, explains the complexity, gives a threshold, and provides an alternative.*

### Example 5 — Missing Signal Word in Environment Variable Documentation

> **Non-STE:** The DEBUG_MODE environment variable controls verbose logging. Setting it to true in production will leak sensitive information.
>
> **STE:** WARNING: DO NOT SET `DEBUG_MODE=true` IN A PRODUCTION ENVIRONMENT. DEBUG MODE WRITES SENSITIVE DATA TO THE LOG OUTPUT. THIS DATA INCLUDES REQUEST BODIES, AUTHENTICATION TOKENS, AND DATABASE QUERIES. AN ATTACKER WITH LOG ACCESS CAN STEAL USER CREDENTIALS.
>
> *Principles applied: P1 — the original has no signal word at all. The risk (data leak, credential theft) is a security vulnerability. A WARNING is required. The STE version adds the signal word, explains the data at risk, and names the attacker threat.*

### Example 6 — Mixed Risk Levels in a Single Callout

> **Non-STE:** CAUTION: The reset method clears the database and disables authentication, only use in development.
>
> **STE:** WARNING: THE `reset` METHOD CLEARS THE DATABASE AND DISABLES AUTHENTICATION. IF YOU CALL THIS METHOD IN A PRODUCTION ENVIRONMENT, ALL USER DATA IS DELETED AND ALL REQUESTS BYPASS AUTHENTICATION. THIS METHOD IS FOR DEVELOPMENT USE ONLY. CHECK THE `NODE_ENV` VARIABLE BEFORE YOU CALL THIS METHOD.
>
> *Principles applied: P1 — the original has two risks together: data loss (WARNING level) and disabled auth (WARNING level). When two WARNING-level risks exist together, use WARNING. The original used CAUTION incorrectly. The STE version escalates to WARNING, names both consequences, and adds an environment check.*

---

## Edge Cases

### Edge Case 1 — When a Framework or Language Feature Uses "Warning" as a Name

Some programming languages and frameworks use "Warning" as a type or module name (for example, Python's `warnings` module, Rust's `#[allow(warnings)]`, JavaScript's `console.warn()`). When the word "Warning" appears as a technical code noun, put it in backticks. When it appears as a risk signal word, use uppercase WARNING without backticks.

> **Non-STE:** Warning: the warnings module suppresses warnings by default.
>
> **STE:** CAUTION: THE `warnings` MODULE SUPPRESSES WARNINGS BY DEFAULT. THE OUTPUT FROM `warn()` CALLS IS NOT SHOWN. CALL `warnings.simplefilter('always')` TO SHOW ALL WARNINGS.
>
> *The risk is unexpected behavior (suppressed output), so CAUTION is the correct signal word. The `warnings` module name is in backticks. The signal word WARNING is not used here because that would conflict with the module name and cause confusion.*

### Edge Case 2 — When a Third-Party Library Uses a Different Risk Convention

Third-party libraries may use their own signal word conventions (for example, `DANGER`, `CRITICAL`, `IMPORTANT`, `NOTE`). When you document a third-party API in your project, translate their convention to STE-Code signal words. Do not replicate the third-party convention directly.

> **Third-party convention:** DANGER: This operation is irreversible.
>
> **STE-Code translation:** WARNING: THIS OPERATION IS IRREVERSIBLE. THE DATA CANNOT BE RECOVERED AFTER THE OPERATION COMPLETES. BACK UP THE DATA BEFORE YOU START.
>
> *The third party uses DANGER. STE-Code uses WARNING for irreversible data loss. Translate the signal word and add the specific consequence and pre-action instruction.*

### Edge Case 3 — Generated Code with Auto-Inserted Warnings

Generated code (from tools such as `protoc`, `graphql-codegen`, or OpenAPI generators) may insert WARNING or CAUTION comments automatically. These generated comments are not under your control. For generated code:

- Do not modify the generated comments. The generator may overwrite your changes.
- Add your own STE-Code WARNING or CAUTION in the documentation that wraps the generated code.
- If the generated warning misclassifies the risk level, open an issue with the generator project.

> **Generated (leave as-is):** // CAUTION: This method is deprecated.
>
> **Your wrapper documentation:** WARNING: THE `legacy/client.go` FILE CONTAINS DEPRECATED METHODS. DEPRECATED METHODS MAY BE REMOVED IN A FUTURE VERSION. THE REMOVAL OF THESE METHODS CAN BREAK YOUR APPLICATION. MIGRATE TO THE `v2/client.go` API.
>
> *The generated comment remains. Your documentation adds the correct signal word (WARNING, because removal of used methods is a BREAKING risk).*

### Edge Case 4 — When a BREAKING Change Overlaps with a WARNING

BREAKING changes and WARNING-level risks often occur together. When a breaking change also introduces a security risk or data loss risk, use WARNING and mention the breaking nature in the body. Do not use two signal words.

> **Non-STE:** BREAKING: WARNING: The encrypt function now requires a key parameter.
>
> **STE:** WARNING: THE `encrypt` FUNCTION NOW REQUIRES A `key` PARAMETER. THIS IS A BREAKING CHANGE. UPDATE ALL CALLERS TO PASS A KEY ARGUMENT. IF YOU DO NOT PASS A KEY, THE FUNCTION THROWS AN ERROR AND THE DATA IS NOT ENCRYPTED.
>
> *WARNING is used because unencrypted data is a security risk. The breaking nature is mentioned in the body, not as a competing signal word. The consequence of ignoring the warning is stated explicitly.*

### Edge Case 5 — Internationalization of Warning and Caution Strings

When your documentation is translated to other languages, the signal words WARNING and CAUTION must also be translated. Use the standard translation for these words in each target language. Do not invent new signal words per language. Maintain a glossary of translated signal words.

The signal word must remain visually distinct. Use the same formatting rules across all languages:

- Uppercase letters for the signal word.
- A colon (:) after the signal word.
- A space before the instruction text.

**STE-Code signal word glossary (example):**

| Language | WARNING | CAUTION |
|----------|---------|---------|
| English | WARNING | CAUTION |
| Spanish | ADVERTENCIA | PRECAUCIÓN |
| French | AVERTISSEMENT | ATTENTION |
| German | WARNUNG | VORSICHT |
| Japanese | 警告 | 注意 |

*For each new language, add the translation to the glossary. Use the same signal word consistently across all documentation in that language.*

---

## Cross-References

- **Rule 1.1** — Use approved words from the STE-Code dictionary. "Warning" and "caution" are approved signal words. Do not invent new signal words.
- **Rule 1.4** — Use only approved verb forms and adjective forms. A safety instruction must start with an approved verb (for example, "check," "make sure," "do not").
- **Rule 1.6** — Non-approved words are not permitted. Do not use non-approved words inside a WARNING or CAUTION instruction.
- **Rule 1.10** — No slang, jargon, or regional terms. Use standard signal words. Do not use slang signal words (for example, "heads up," "watch out").
- **Rule 1.11** — One term per concept. Use WARNING and CAUTION consistently across all documentation. Do not mix signal word conventions from different sources.
- **Rule 4.1** — Write short and clear sentences. Each WARNING or CAUTION instruction must be a short, clear imperative sentence.
- **Rule 4.2** — Use the active voice. Safety instructions must use the active voice to give clear commands.
- **Rule 5.3** — Use the imperative (command) form for instructions. A WARNING or CAUTION is a safety instruction. The body must use the imperative mood.
- **Rule 5.4** — Write each step as a command. Each action inside a WARNING or CAUTION is a step. Write each step as a command.
- **Rule 7.2** — Start a safety instruction with a clear and accurate command or condition. The sentence that follows the signal word must give a clear command or state a clear condition.
- **Rule 7.3** — Give a clear consequence in the safety instruction. The consequence must use the words that name the risk level (for example, "security breach," "data loss," "unexpected behavior").
- **Section 1 (Vocabulary)** — All words used in WARNING and CAUTION instructions must come from the approved vocabulary unless they are technical code nouns.
- **Section 5 (Procedural Writing)** — WARNING and CAUTION instructions are procedural. Follow all procedural writing rules.

---

## Grammar Notes

### Signal Word Placement

The signal word (WARNING or CAUTION) must be the first word of the safety instruction. Put the signal word at the start of the line. Do not indent the signal word. Do not put text before the signal word.

> **Correct placement:** WARNING: DO NOT SHARE THE PRIVATE KEY.
>
> **Incorrect placement:** Important: WARNING: DO NOT SHARE THE PRIVATE KEY.

The signal word is followed by a colon (:) and a single space. The instruction text starts after the space. The colon is part of the signal word format, not part of the instruction sentence.

### Uppercase Convention

Write the signal word in uppercase letters. This convention makes the signal word visually distinct from the body text. The uppercase is part of the signal, not emphasis. Do not write the signal word in lowercase or title case.

> **Correct:** WARNING: The operation is destructive.
> **Incorrect:** Warning: The operation is destructive.
> **Incorrect:** warning: The operation is destructive.

The instruction text after the signal word can use standard sentence case. The first word of the instruction is uppercase (as the start of a sentence). The rest of the instruction uses standard capitalization.

### Sentence Structure After the Signal Word

The sentence that follows the signal word must include three parts:

1. **A clear command or condition** — What the reader must do or must check.
2. **A clear consequence** — What happens if the reader ignores the instruction.
3. **A clear risk escalation** — How the consequence maps to the risk level (security, data loss, unexpected behavior).

These three parts can be in one sentence or across multiple sentences. The parts must appear in this order. The reader must understand the risk before acting.

> **Structure:** WARNING: [COMMAND/CONDITION]. [CONSEQUENCE]. [RISK ESCALATION].
>
> **Example:** WARNING: DO NOT COMMIT THE API KEY TO VERSION CONTROL. AN EXPOSED API KEY CAN CAUSE UNAUTHORIZED ACCESS AND DATA LOSS. ADD THE `.env` FILE TO `.gitignore`.

### Verb Form in WARNING and CAUTION Instructions

Use the imperative mood for the command part of the instruction. Use "do not" for prohibitions. Do not use "should," "must," or "needs to."

> **Correct (imperative):** CHECK THE INPUT DATA BEFORE YOU PROCESS IT.
> **Correct (prohibition):** DO NOT USE THIS FUNCTION IN PRODUCTION.
> **Incorrect:** You should check the input data before processing.
> **Incorrect:** The input data must be checked before processing.

For technical verbs that have specific meanings in the code domain (for example, "sanitize," "validate," "encrypt," "back up"), use them as verbs in the imperative mood. These are approved technical verbs under Rule 1.12.

### Risk Escalation Vocabulary

Use these approved nouns to describe the risk consequence in WARNING instructions:

- Security breach
- Data loss
- System corruption
- Unauthorized access
- Credential theft
- Data leak
- Privilege escalation

Use these approved nouns to describe the risk consequence in CAUTION instructions:

- Unexpected behavior
- Performance degradation
- Incorrect results
- Connection failure
- Memory exhaustion
- Application crash
- Configuration drift

Do not use vague nouns such as "problems," "issues," or "trouble." Name the specific risk.

### Visual Distinction

In rendered documentation (HTML, PDF, Markdown), the signal word must be visually distinct. Use bold formatting, color, or a border to make the signal word stand out. Do not rely only on the uppercase text. Some readers scan visually. The formatting must catch the eye before the text is read.

```
> **WARNING:** Do not expose the private key. An exposed key can cause unauthorized access.
```

*In Markdown, use a blockquote with bold formatting for the signal word. In HTML, use a `<div>` with a CSS class. In reStructuredText, use an admonition directive (`.. WARNING::`). Choose the format that your documentation generator supports.*

---

## Summary Checklist

Before you publish code documentation that contains WARNING or CAUTION instructions, check each safety instruction:

- [ ] The signal word (WARNING or CAUTION) is correct for the risk level.
- [ ] Security, data loss, or system corruption risks use WARNING.
- [ ] Unexpected behavior, performance, or incorrect result risks use CAUTION.
- [ ] Mixed risk levels with one WARNING-level risk use WARNING.
- [ ] The signal word is the first word of the instruction.
- [ ] The signal word is in uppercase.
- [ ] The signal word is followed by a colon and a space.
- [ ] The instruction gives a clear command or condition.
- [ ] The instruction gives a clear consequence.
- [ ] The consequence names the specific risk (not "problems" or "issues").
- [ ] The instruction uses the imperative mood (not "you should").
- [ ] The instruction is not abstract. It gives concrete actions.
- [ ] Technical code nouns are in backticks.
- [ ] No non-approved words are used in the instruction.
- [ ] No competing signal words from third-party conventions are mixed in.
- [ ] The signal word is visually distinct from body text.

---

<!-- a-sec7-rule7.2.md -->

# Rule 7.2 — Start a Safety Instruction with a Clear and Accurate Command or Condition

> **Source:** Adapted from ASD-STE100 Issue 9, Rule 7.2

> **Source:** [master.md#sec7-rule7.2](ste-code/grouped/)

## Original Rule

**Rule 7.2** Start a safety instruction with a clear and accurate command or condition. Your reader must know how to prevent accidents and keep a high level of safety.

If your reader must know about a condition before the start of a procedure or work step, give this condition first.

**Spec examples:**

(Refer to the underlined command.)

> **WARNING:** DO NOT SWALLOW THE SOLVENT. ALWAYS MAKE SURE THAT YOU KNOW THE SAFETY PRECAUTIONS AND FIRST AID INSTRUCTIONS FOR SOLVENTS. SOLVENTS ARE POISONOUS AND CAN CAUSE INJURY OR DEATH.

> **CAUTION:** DO NOT USE BLEACH OR CLEANSERS THAT CONTAIN CHLORINE TO CLEAN THE UNIT. THESE CLEANING AGENTS CAN CAUSE CORROSION.

(Refer to the underlined condition.)

> IF THEY FALL, PERMANENT DAMAGE TO THE PARTS CAN OCCUR.

## STE-Code Adaptation

**Rule 7.2** In code documentation, start a safety instruction with a clear and accurate command or condition. Your reader must know how to prevent security vulnerabilities, data loss, and system failures.

If your reader must know about a condition before they use a function, method, or API, give this condition first.

Severity mapping: The command or condition in a safety instruction carries the severity from Rule 7.1. In release notes and changelogs, the same levels map as follows: WARNING to BREAKING, CAUTION to DEPRECATED, NOTE to NOTE.

### Examples

> *Adapted from spec pair:* Non-STE: `STORING API KEYS IN THE SOURCE CODE IS NOT RECOMMENDED.`  |  STE: `DO NOT STORE API KEYS IN THE SOURCE CODE. ALWAYS USE ENVIRONMENT VARIABLES OR A SECRETS MANAGER TO STORE API KEYS. API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.` (ASD-STE100 Issue 9, Rule 7.2, page 99–100 — the safety instruction starts with a clear command, not a description of the risk.)

> **Non-STE:** WARNING: STORING API KEYS IN THE SOURCE CODE IS NOT RECOMMENDED.

> **STE:** WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. ALWAYS USE ENVIRONMENT VARIABLES OR A SECRETS MANAGER TO STORE API KEYS. API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.

> *Adapted from spec pair: "WARNING: DO NOT SWALLOW THE SOLVENT. ALWAYS MAKE SURE THAT YOU KNOW THE SAFETY PRECAUTIONS AND FIRST AID INSTRUCTIONS FOR SOLVENTS. SOLVENTS ARE POISONOUS AND CAN CAUSE INJURY OR DEATH." — the safety instruction starts with a clear command ("DO NOT STORE") and explains the risk.*

Full runnable form — a Python module that reads credentials from the environment:

```python
import os

# WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. ALWAYS USE
# ENVIRONMENT VARIABLES OR A SECRETS MANAGER TO STORE API KEYS.
# API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND
# DATA BREACHES.
def get_api_client() -> "Client":
    api_key = os.environ.get("PAYMENT_API_KEY")
    if api_key is None:
        raise RuntimeError("PAYMENT_API_KEY is not set in the environment")
    return Client(api_key=api_key)
```

The non-STE version describes an attitude ("is not recommended"). The STE version starts with the command "DO NOT STORE", gives the required alternative, and names the consequence (data breaches).

> **Non-STE:** CAUTION: THE CODEBASE CONTAINS DEPRECATED FUNCTIONS.

> **STE:** CAUTION: DO NOT USE DEPRECATED FUNCTIONS OR METHODS THAT HAVE KNOWN ISSUES. USE THE APPROVED REPLACEMENT FUNCTIONS SPECIFIED IN THE MIGRATION GUIDE. DEPRECATED FUNCTIONS CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.

> *Adapted from spec pair: "CAUTION: DO NOT USE BLEACH OR CLEANSERS THAT CONTAIN CHLORINE TO CLEAN THE UNIT. THESE CLEANING AGENTS CAN CAUSE CORROSION." — the safety instruction starts with a clear command ("DO NOT USE") and explains the risk.*

Full runnable form — a Python deprecation shim that warns and points to the replacement:

```python
import warnings

# CAUTION: DO NOT USE DEPRECATED FUNCTIONS OR METHODS THAT HAVE
# KNOWN ISSUES. USE THE APPROVED REPLACEMENT FUNCTIONS SPECIFIED
# IN THE MIGRATION GUIDE. DEPRECATED FUNCTIONS CAN CAUSE UNEXPECTED
# BEHAVIOR AND INCORRECT RESULTS.
def legacy_send_email(address: str, body: str) -> None:
    warnings.warn(
        "legacy_send_email is deprecated; use send_message() instead",
        DeprecationWarning,
        stacklevel=2,
    )
    send_message(address, body)
```

The non-STE version only reports the presence of deprecated code. The STE version starts with the prohibition "DO NOT USE", names the replacement, and states the consequence (incorrect results).

> **Non-STE:** PERMANENT DATA LOSS CAN OCCUR.

> **STE:** IF YOU DO NOT SET THE CONNECTION TIMEOUT, THE APPLICATION CAN BECOME UNAVAILABLE AND PERMANENT DATA LOSS CAN OCCUR.

> *Adapted from spec pair: "IF THEY FALL, PERMANENT DAMAGE TO THE PARTS CAN OCCUR." — the safety instruction starts with a clear condition ("IF YOU DO NOT SET...") before stating the risk.*

Full runnable form — a Go database client that requires a timeout:

```go
// WARNING: IF YOU DO NOT SET THE CONNECTION TIMEOUT, THE APPLICATION
// CAN BECOME UNAVAILABLE AND PERMANENT DATA LOSS CAN OCCUR.
func NewClient(dsn string) (*Client, error) {
    db, err := sql.Open("postgres", dsn)
    if err != nil {
        return nil, err
    }
    // A zero value means "wait forever"; set a bound.
    db.SetConnMaxLifetime(0)
    db.SetMaxOpenConns(10)
    // Without a timeout the next call can block until the TCP
    // connection is silently dropped, and buffered writes are lost.
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    if err := db.PingContext(ctx); err != nil {
        return nil, err
    }
    return &Client{db: db}, nil
}
```

The non-STE version states only the consequence. The STE version starts with the condition "IF YOU DO NOT SET THE CONNECTION TIMEOUT" so the reader learns when the risk applies.

> **See also:** Rule 5.3 — Imperative (Command) Form for Instructions; Rule 5.4 — Descriptive Statement Before the Command; Rule 7.1 — Use an Applicable Word to Identify the Level of Risk

---

## Code-Domain Explanation

This rule defines the structure of every safety instruction in code documentation. A safety instruction has two parts: a signal word (WARNING or CAUTION, per Rule 7.1) and a body. The body must start with either a clear command or a clear condition. The reader must understand what action to take (or not take) within the first few words.

A safety instruction is complete only when it has all three of these parts:

1. **Signal word** — WARNING or CAUTION (Rule 7.1).
2. **Command or condition** — the first sentence after the colon. This tells the reader what to do, what not to do, or under what condition the risk applies.
3. **Consequence** — the explanation that shows the risk (Rule 7.3). This is what makes the command or condition "accurate": the reader understands why the instruction matters.

If you write the consequence but not the command, the instruction is not actionable. If you write the command but not the consequence, the reader does not know why the command matters. Both the command or condition and the consequence are required.

### Command-First Structure

A command-first safety instruction starts with an imperative verb. The most common command forms in code documentation are:

- **DO NOT [action]** — Prohibit a dangerous action. Example: "DO NOT COMMIT THE `.env` FILE."
- **ALWAYS [action]** — Require a mandatory action. Example: "ALWAYS SANITIZE THE INPUT BEFORE YOU PROCESS IT."
- **[imperative verb]** — Direct the reader to take a specific action (for example, "CHECK," "MAKE SURE," "BACK UP," "SANITIZE," "VALIDATE," "VERIFY").

The command must appear immediately after the signal word and colon. The reader must not read through background information before learning what to do. Use approved verbs: prefer "use," "check," "make," "get," "set," "send," "remove," "keep," "start," "stop," "show," "do" over "utilize," "leverage," "employ," "commence," "terminate," "initiate."

**Command-first WARNING — README file:**

> **Non-STE:** WARNING: It is important to consider that hardcoding database credentials in the configuration file can lead to serious security issues if the file is committed to version control.

> **STE:** WARNING: DO NOT HARDCODE DATABASE CREDENTIALS IN THE CONFIGURATION FILE. STORE CREDENTIALS IN A SECRETS MANAGER OR ENVIRONMENT VARIABLES. HARDCODED CREDENTIALS IN VERSION CONTROL CAN CAUSE UNAUTHORIZED DATABASE ACCESS.

> *Principles applied: P1, P9 — the command "DO NOT HARDCODE" starts the instruction. The reader knows the prohibition in the first three words.*

Full runnable form — a `.env.example` and a load step:

```bash
# .env.example  (copy to .env and fill in real values)
# WARNING: DO NOT HARDCODE DATABASE CREDENTIALS IN THE CONFIGURATION
# FILE. STORE CREDENTIALS IN A SECRETS MANAGER OR ENVIRONMENT VARIABLES.
# HARDCODED CREDENTIALS IN VERSION CONTROL CAN CAUSE UNAUTHORIZED
# DATABASE ACCESS.
DATABASE_URL=postgres://user:password@localhost:5432/app
```

```python
import os
# Reads DATABASE_URL from the environment, never from a committed file.
db = connect(os.environ["DATABASE_URL"])
```

**Command-first CAUTION — API documentation:**

> **Non-STE:** CAUTION: The `/search` endpoint returns results from a cache that is updated every 5 minutes, so recent changes may not be reflected immediately.

> **STE:** CAUTION: BEFORE YOU USE THE `/search` ENDPOINT, READ THE CACHE STALENESS NOTE. THE CACHE IS UPDATED EVERY 5 MINUTES. RECENT CHANGES ARE NOT VISIBLE UNTIL THE NEXT CACHE UPDATE. DO NOT USE THIS ENDPOINT FOR REAL-TIME DATA.

> *Principles applied: P1, P2 — the condition "BEFORE YOU USE" starts the instruction. The reader knows the prerequisite before the explanation.*

Full runnable form — an OpenAPI operation object:

```yaml
/search:
  get:
    summary: Search the catalog
    # CAUTION: BEFORE YOU USE THE `/search` ENDPOINT, READ THE CACHE
    # STALENESS NOTE. THE CACHE IS UPDATED EVERY 5 MINUTES. RECENT
    # CHANGES ARE NOT VISIBLE UNTIL THE NEXT CACHE UPDATE. DO NOT USE
    # THIS ENDPOINT FOR REAL-TIME DATA.
    description: >
      Results come from a cache that refreshes on a 5-minute interval.
      Do not poll this endpoint for live status; subscribe to the
      webhook stream instead.
    responses:
      '200':
        description: Cached search results
```

### Condition-First Structure

A condition-first safety instruction starts with a subordinate clause that describes the prerequisite the reader must know. The most common condition forms are:

- **IF [condition]...** — State the unsafe condition before the consequence. Example: "IF YOU DISABLE TLS, THE TRAFFIC IS IN CLEAR TEXT."
- **BEFORE YOU [action]...** — Require a pre-action check. Example: "BEFORE YOU RUN THE MIGRATION, BACK UP THE DATABASE."
- **WHEN [condition]...** — Describe a scenario that triggers the risk. Example: "WHEN THE QUEUE IS FULL, THE PUBLISH CALL BLOCKS."

The condition must come first. The consequence comes second. The reader must understand the context before learning the result. Use the active voice in the condition: "IF YOU DO NOT SET..." not "IF THE TIMEOUT IS NOT SET..."

**Condition-first WARNING — docstring:**

> **Non-STE:** WARNING: The database connection may not be initialized if you call this function before `connect()` has completed.

> **STE:** WARNING: IF YOU CALL THIS FUNCTION BEFORE `connect()` COMPLETES, THE DATABASE CONNECTION IS NOT INITIALIZED. THE FUNCTION RETURNS `null` AND YOUR APPLICATION CAN CRASH. CALL `connect()` AND WAIT FOR THE PROMISE BEFORE YOU USE THIS FUNCTION.

> *Principles applied: P1, P10 — the condition "IF YOU CALL THIS FUNCTION BEFORE" starts the instruction. The reader learns the prerequisite scenario first. The consequence follows.*

Full runnable form — a JavaScript class with an explicit precondition:

```javascript
class Repository {
  /**
   * WARNING: IF YOU CALL THIS FUNCTION BEFORE `connect()` COMPLETES,
   * THE DATABASE CONNECTION IS NOT INITIALIZED. THE FUNCTION RETURNS
   * `null` AND YOUR APPLICATION CAN CRASH. CALL `connect()` AND WAIT
   * FOR THE PROMISE BEFORE YOU USE THIS FUNCTION.
   *
   * @param {number} id
   * @returns {Promise<Row|null>}
   */
  async getById(id) {
    if (!this.db) return null; // connection not ready
    return this.db.query("SELECT * FROM rows WHERE id = $1", [id]);
  }

  async connect() {
    this.db = await createPool();
  }
}
```

**Condition-first CAUTION — commit message:**

> **Non-STE:** CAUTION: The CI pipeline will fail if the `NODE_ENV` variable is not set to `production` during the release build.

> **STE:** CAUTION: WHEN YOU RUN THE RELEASE BUILD, SET `NODE_ENV=production`. IF YOU DO NOT SET THIS VARIABLE, THE CI PIPELINE FAILS. THE DEPLOYMENT STOPS UNTIL THE VARIABLE IS SET.

> *Principles applied: P1, P12 — the condition "WHEN YOU RUN THE RELEASE BUILD" starts the instruction. The command follows. The consequence is explained.*

Full runnable form — a commit body that changelog tools can parse:

```text
CAUTION: Change the build to require NODE_ENV in the release job.

WHEN YOU RUN THE RELEASE BUILD, SET NODE_ENV=production. IF YOU DO
NOT SET THIS VARIABLE, THE CI PIPELINE FAILS. THE DEPLOYMENT STOPS
UNTIL THE VARIABLE IS SET.

- Add NODE_ENV=production to .github/workflows/release.yml
- Add a guard that fails fast when the variable is missing
```

### Documentation Type Differences

**README files:** Safety instructions in README files are read before the user sets up the project. Use command-first for prohibitions (for example, "DO NOT COMMIT"). Use condition-first for prerequisites (for example, "BEFORE YOU RUN THE BUILD").

**API documentation:** Safety instructions in API docs are read by external consumers. Use command-first for destructive operations. Use condition-first for preconditions that depend on application state.

**Docstrings:** Safety instructions in docstrings are read by developers who use the function. Use command-first for function contract violations. Use condition-first for argument preconditions that are not enforced by the type system.

**Commit messages:** Safety instructions in commit messages are read during code review and changelog generation. The command or condition must be the first sentence of the commit body after the signal word. Use command-first for behavioral changes. Use condition-first for conditional breakage.

**Error messages:** Safety instructions in error messages are read during incidents. Use command-first to tell the operator what to do. Use condition-first to explain the system state that caused the error.

**Error message with command-first:**

> **Non-STE:** WARNING: Rate limit exceeded, try again after the reset window.

> **STE:** WARNING: THE RATE LIMIT IS EXCEEDED. DO NOT SEND MORE REQUESTS UNTIL THE RESET WINDOW OPENS. SENDING MORE REQUESTS CAN CAUSE YOUR API KEY TO BE TEMPORARILY BLOCKED. CHECK THE `Retry-After` HEADER FOR THE RESET TIME.

> *Principles applied: P1, P9 — the command "DO NOT SEND MORE REQUESTS" tells the operator what to stop doing. The consequence of ignoring the command is stated.*

Full runnable form — a handler that returns an actionable error:

```python
from http import HTTPStatus

def handle_request(req):
    if rate_limiter.is_exceeded(req.api_key):
        # WARNING: THE RATE LIMIT IS EXCEEDED. DO NOT SEND MORE REQUESTS
        # UNTIL THE RESET WINDOW OPENS. SENDING MORE REQUESTS CAN CAUSE
        # YOUR API KEY TO BE TEMPORARILY BLOCKED. CHECK THE `Retry-After`
        # HEADER FOR THE RESET TIME.
        headers = {"Retry-After": str(rate_limiter.seconds_to_reset(req.api_key))}
        return HTTPStatus.TOO_MANY_REQUESTS, headers, b"rate limit exceeded"
    return process(req)
```

---

## Paradigm-Specific Guidance

### Object-Oriented (Java, C++, C#, Python Classes)

Object-oriented documentation describes class invariants, method contracts, and inheritance rules. Use command-first for prohibitions on subclass overrides. Use condition-first when the state of the object affects the safety of a method call.

**Command-first WARNING for subclass override (Java):**

> **Non-STE:** WARNING: Subclasses of `Authenticator` need to ensure that the `authenticate` method always calls `super.authenticate()` first.

> **STE:** WARNING: DO NOT OVERRIDE THE `authenticate` METHOD WITHOUT CALLING `super.authenticate()` FIRST. IF YOU BYPASS THE BASE AUTHENTICATION, UNTRUSTED REQUESTS CAN ACCESS PROTECTED RESOURCES. ALWAYS PUT `super.authenticate()` AS THE FIRST LINE OF YOUR OVERRIDE.

> *Principles applied: P1, P7 — the command "DO NOT OVERRIDE..." starts the instruction. The prohibition is clear in the first sentence. The required action ("ALWAYS PUT...") follows.*

Full runnable form — a base class and a compliant subclass:

```java
abstract class Authenticator {
    // WARNING: DO NOT OVERRIDE THE `authenticate` METHOD WITHOUT
    // CALLING `super.authenticate()` FIRST. IF YOU BYPASS THE BASE
    // AUTHENTICATION, UNTRUSTED REQUESTS CAN ACCESS PROTECTED
    // RESOURCES. ALWAYS PUT `super.authenticate()` AS THE FIRST LINE
    // OF YOUR OVERRIDE.
    void authenticate(Request req) {
        if (!req.isSigned()) throw new SecurityException("missing signature");
    }
}

class TokenAuthenticator extends Authenticator {
    @Override
    void authenticate(Request req) {
        super.authenticate(); // required: keeps the base checks
        verifyToken(req.token());
    }
}
```

**Condition-first CAUTION for mutable state (Python):**

> **Non-STE:** CAUTION: The `logger` object is shared across modules, be careful about changing the log level at runtime.

> **STE:** CAUTION: BEFORE YOU CHANGE THE `logger.level` AT RUNTIME, CHECK THAT NO OTHER MODULE USES THE SAME LOGGER. IF ANOTHER MODULE EXPECTS A DIFFERENT LOG LEVEL, THE APPLICATION LOGS CAN BECOME INCOMPLETE. SET THE LOG LEVEL IN THE INITIALIZATION FUNCTION. DO NOT CHANGE IT DURING RUNTIME.

> *Principles applied: P1, P11 — the condition "BEFORE YOU CHANGE..." starts the instruction. The reader checks the precondition before acting.*

Full runnable form — a shared logger configured once at startup:

```python
import logging

logger = logging.getLogger("app")  # shared singleton

# CAUTION: BEFORE YOU CHANGE THE `logger.level` AT RUNTIME, CHECK THAT
# NO OTHER MODULE USES THE SAME LOGGER. IF ANOTHER MODULE EXPECTS A
# DIFFERENT LOG LEVEL, THE APPLICATION LOGS CAN BECOME INCOMPLETE.
# SET THE LOG LEVEL IN THE INITIALIZATION FUNCTION. DO NOT CHANGE IT
# DURING RUNTIME.
def configure_logging(level: int) -> None:
    logger.setLevel(level)  # called once, at startup only
```

### Functional (Haskell, Elixir, Clojure, Rust)

Functional documentation describes pure functions, effect types, and referential transparency. Use command-first when an unsafe function can break purity. Use condition-first when laziness or non-strict evaluation creates a hidden precondition.

**Command-first WARNING for unsafe code (Rust):**

> **Non-STE:** WARNING: `unsafe` blocks require the programmer to manually uphold invariants that the compiler does not check.

> **STE:** WARNING: DO NOT ADD AN `unsafe` BLOCK WITHOUT DOCUMENTING THE SAFETY INVARIANTS. AN `unsafe` BLOCK WITHOUT DOCUMENTED INVARIANTS CAN CAUSE UNDEFINED BEHAVIOR, MEMORY CORRUPTION, AND SECURITY VULNERABILITIES. WRITE A `// SAFETY:` COMMENT THAT LISTS EACH INVARIANT AND THE REASON IT HOLDS.

> *Principles applied: P1, P8 — the command "DO NOT ADD AN `unsafe` BLOCK WITHOUT..." starts the instruction. The required action ("WRITE A `// SAFETY:` COMMENT") follows.*

Full runnable form — a safe wrapper over an unsafe raw pointer read:

```rust
/// WARNING: DO NOT ADD AN `unsafe` BLOCK WITHOUT DOCUMENTING THE
/// SAFETY INVARIANTS. AN `unsafe` BLOCK WITHOUT DOCUMENTED
/// INVARIANTS CAN CAUSE UNDEFINED BEHAVIOR, MEMORY CORRUPTION, AND
/// SECURITY VULNERABILITIES. WRITE A `// SAFETY:` COMMENT THAT LISTS
/// EACH INVARIANT AND THE REASON IT HOLDS.
pub unsafe fn read_u32(ptr: *const u32) -> u32 {
    // SAFETY: `ptr` is non-null, 4-byte aligned, and points to
    // initialized memory for the lifetime of this call.
    ptr.read_unaligned()
}
```

**Condition-first CAUTION for lazy evaluation (Haskell):**

> **Non-STE:** CAUTION: Using `foldl` on infinite lists will not terminate.

> **STE:** CAUTION: IF YOU USE `foldl` ON AN INFINITE LIST, THE FUNCTION DOES NOT TERMINATE. THE PROGRAM HANGS INDEFINITELY. USE `foldr` FOR OPERATIONS THAT CAN SHORT-CIRCUIT ON LAZY LISTS. CHECK THAT YOUR LIST IS FINITE BEFORE YOU USE `foldl`.

> *Principles applied: P1, P3 — the condition "IF YOU USE `foldl` ON AN INFINITE LIST" starts the instruction. The consequence (hang) is explained.*

Full runnable form — a GHCi session that shows the difference:

```haskell
-- CAUTION: IF YOU USE `foldl` ON AN INFINITE LIST, THE FUNCTION DOES
-- NOT TERMINATE. THE PROGRAM HANGS INDEFINITELY. USE `foldr` FOR
-- OPERATIONS THAT CAN SHORT-CIRCUIT ON LAZY LISTS. CHECK THAT YOUR
-- LIST IS FINITE BEFORE YOU USE `foldl`.
import Data.List (foldl')

sumFinite :: Num a => [a] -> a
sumFinite = foldl' (+) 0   -- strict: safe on finite lists

-- This never returns; `foldl` builds a thunk chain:
-- sumInfinite = foldl (+) 0 [1..]
```

### Procedural (C, Go, Bash)

Procedural documentation describes memory management, buffer handling, and system calls. Use command-first for memory safety violations. Use condition-first when the program state determines whether a call is safe.

**Command-first WARNING for buffer handling (C):**

> **Non-STE:** WARNING: `gets` reads input without bounds checking and should never be used.

> **STE:** WARNING: DO NOT USE `gets()` IN ANY C PROGRAM. `gets()` READS INPUT WITHOUT BOUNDS CHECKING. A BUFFER OVERFLOW CAN CAUSE ARBITRARY CODE EXECUTION AND SYSTEM COMPROMISE. USE `fgets()` WITH A SIZE LIMIT.

> *Principles applied: P1, P8 — the command "DO NOT USE `gets()`" starts the instruction. The prohibition is absolute ("IN ANY C PROGRAM"). The consequence (arbitrary code execution) justifies the command.*

Full runnable form — a safe read replacement:

```c
/* WARNING: DO NOT USE `gets()` IN ANY C PROGRAM. `gets()` READS INPUT
 * WITHOUT BOUNDS CHECKING. A BUFFER OVERFLOW CAN CAUSE ARBITRARY CODE
 * EXECUTION AND SYSTEM COMPROMISE. USE `fgets()` WITH A SIZE LIMIT. */
char name[64];
if (fgets(name, sizeof(name), stdin) == NULL) {
    /* handle EOF or read error */
}
name[strcspn(name, "\n")] = '\0'; /* remove trailing newline */
```

**Condition-first CAUTION for file descriptors (Go):**

> **Non-STE:** CAUTION: Closing a file descriptor that has already been closed causes a panic.

> **STE:** CAUTION: BEFORE YOU CALL `file.Close()`, CHECK THAT THE FILE IS OPEN. IF YOU CLOSE A FILE THAT IS ALREADY CLOSED, THE PROGRAM PANICS. USE `defer file.Close()` IMMEDIATELY AFTER YOU OPEN THE FILE. THIS PATTERN PREVENTS DOUBLE-CLOSE ERRORS.

> *Principles applied: P1, P12 — the condition "BEFORE YOU CALL `file.Close()`" starts the instruction. The precondition check is stated first. The safe pattern follows.*

Full runnable form — the recommended `defer` pattern:

```go
// CAUTION: BEFORE YOU CALL `file.Close()`, CHECK THAT THE FILE IS
// OPEN. IF YOU CLOSE A FILE THAT IS ALREADY CLOSED, THE PROGRAM
// PANICS. USE `defer file.Close()` IMMEDIATELY AFTER YOU OPEN THE
// FILE. THIS PATTERN PREVENTS DOUBLE-CLOSE ERRORS.
f, err := os.Open("data.csv")
if err != nil {
    return err
}
defer f.Close() // single owner; no second Close() anywhere
```

### Declarative (SQL, Terraform, Kubernetes YAML)

Declarative documentation describes desired state, resource specifications, and destructive operations. Use command-first for destructive state changes. Use condition-first when a configuration value depends on infrastructure state.

**Command-first WARNING for destructive SQL:**

> **Non-STE:** WARNING: This migration truncates the audit log table.

> **STE:** WARNING: DO NOT RUN THIS MIGRATION WITHOUT A FULL DATABASE BACKUP. THE MIGRATION TRUNCATES THE `audit_log` TABLE. ALL AUDIT RECORDS ARE DELETED PERMANENTLY. THE DATA CANNOT BE RECOVERED. RUN THE BACKUP COMMAND: `pg_dump audit_log > audit_log_backup.sql`. VERIFY THE BACKUP BEFORE YOU CONTINUE.

> *Principles applied: P1, P5 — the command "DO NOT RUN THIS MIGRATION WITHOUT A FULL DATABASE BACKUP" starts the instruction. The precondition command is stated first. The consequence clarifies why.*

Full runnable form — a migration file with a guard:

```sql
-- WARNING: DO NOT RUN THIS MIGRATION WITHOUT A FULL DATABASE BACKUP.
-- THE MIGRATION TRUNCATES THE `audit_log` TABLE. ALL AUDIT RECORDS ARE
-- DELETED PERMANENTLY. THE DATA CANNOT BE RECOVERED. RUN THE BACKUP
-- COMMAND: `pg_dump audit_log > audit_log_backup.sql`. VERIFY THE
-- BACKUP BEFORE YOU CONTINUE.
--
-- Safe pre-check: fail the migration if the table is unexpectedly large
-- and no backup marker exists.
DO $$
BEGIN
  IF NOT EXISTS (SELECT 1 FROM backup_markers WHERE table_name = 'audit_log')
     AND (SELECT count(*) FROM audit_log) > 0
  THEN
    RAISE EXCEPTION 'audit_log backup missing; abort migration';
  END IF;
END $$;

TRUNCATE TABLE audit_log;
```

**Condition-first CAUTION for Kubernetes resource limits:**

> **Non-STE:** CAUTION: Setting resource limits too low causes OOMKilled errors.

> **STE:** CAUTION: IF YOU SET THE `memory.limits` VALUE TOO LOW, THE POD IS KILLED WITH AN OOMKILLED ERROR. THE APPLICATION RESTARTS. REQUESTS TO THE APPLICATION FAIL DURING THE RESTART. MONITOR THE ACTUAL MEMORY USAGE IN STAGING BEFORE YOU SET THE LIMIT IN PRODUCTION. USE A LIMIT THAT IS AT LEAST 50 PERCENT ABOVE THE AVERAGE USAGE.

> *Principles applied: P1, P11 — the condition "IF YOU SET THE `memory.limits` VALUE TOO LOW" starts the instruction. The cascade of consequences follows. The corrective action is specific.*

Full runnable form — a manifest with a measured limit:

```yaml
# CAUTION: IF YOU SET THE `memory.limits` VALUE TOO LOW, THE POD IS
# KILLED WITH AN OOMKILLED ERROR. THE APPLICATION RESTARTS. REQUESTS
# TO THE APPLICATION FAIL DURING THE RESTART. MONITOR THE ACTUAL
# MEMORY USAGE IN STAGING BEFORE YOU SET THE LIMIT IN PRODUCTION.
# USE A LIMIT THAT IS AT LEAST 50 PERCENT ABOVE THE AVERAGE USAGE.
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: web
          resources:
            requests:
              memory: "256Mi"
            limits:
              memory: "768Mi"   # avg usage 512Mi + 50% headroom
```

### Systems (Rust Ownership, C Memory)

Systems documentation describes ownership, unsafe blocks, and memory layout. Use command-first when an operation can cause undefined behavior. Use condition-first when the safety of an operation depends on a property that the compiler cannot verify.

**Command-first WARNING for pointer alignment (Rust):**

> **Non-STE:** WARNING: Reading from a misaligned pointer is undefined behavior on most platforms.

> **STE:** WARNING: DO NOT READ FROM A POINTER THAT IS NOT CORRECTLY ALIGNED. A MISALIGNED READ CAN CAUSE UNDEFINED BEHAVIOR. UNDEFINED BEHAVIOR CAN CORRUPT MEMORY, CAUSE SECURITY VULNERABILITIES, AND CRASH THE PROGRAM. USE `std::ptr::read_unaligned` FOR UNALIGNED MEMORY. CHECK THE ALIGNMENT WITH `std::mem::align_of` BEFORE YOU READ.

> *Principles applied: P1, P8 — the command "DO NOT READ FROM A POINTER THAT IS NOT CORRECTLY ALIGNED" starts the instruction. The safe alternative is given. The check instruction follows.*

Full runnable form — aligned and unaligned read paths:

```rust
use std::mem::align_of;
use std::ptr;

/// WARNING: DO NOT READ FROM A POINTER THAT IS NOT CORRECTLY ALIGNED.
/// A MISALIGNED READ CAN CAUSE UNDEFINED BEHAVIOR. UNDEFINED BEHAVIOR
/// CAN CORRUPT MEMORY, CAUSE SECURITY VULNERABILITIES, AND CRASH THE
/// PROGRAM. USE `std::ptr::read_unaligned` FOR UNALIGNED MEMORY. CHECK
/// THE ALIGNMENT WITH `std::mem::align_of` BEFORE YOU READ.
unsafe fn load_u64(buf: *const u8, aligned: bool) -> u64 {
    if aligned && (buf as usize) % align_of::<u64>() == 0 {
        ptr::read(buf as *const u64)          // safe when aligned
    } else {
        ptr::read_unaligned(buf as *const u64) // required when not aligned
    }
}
```

**Condition-first CAUTION for manual allocators:**

> **Non-STE:** CAUTION: Custom allocators must return memory with at least the requested alignment or the allocator API contract is violated.

> **STE:** CAUTION: WHEN YOU IMPLEMENT A CUSTOM ALLOCATOR, MAKE SURE THAT THE RETURNED POINTER SATISFIES THE REQUESTED ALIGNMENT. IF THE ALIGNMENT IS NOT SATISFIED, THE ALLOCATOR CONTRACT IS VIOLATED. CODE THAT USES THE ALLOCATOR CAN PRODUCE INCORRECT RESULTS OR CRASH. CALL `std::alloc::Layout::align()` TO GET THE REQUIRED ALIGNMENT.

> *Principles applied: P1, P12 — the condition "WHEN YOU IMPLEMENT A CUSTOM ALLOCATOR" starts the instruction. The precondition (alignment) is stated. The consequence of violation is explained.*

Full runnable form — an allocator that rounds up to the alignment:

```rust
use std::alloc::{Layout, alloc};

/// CAUTION: WHEN YOU IMPLEMENT A CUSTOM ALLOCATOR, MAKE SURE THAT THE
/// RETURNED POINTER SATISFIES THE REQUESTED ALIGNMENT. IF THE ALIGNMENT
/// IS NOT SATISFIED, THE ALLOCATOR CONTRACT IS VIOLATED. CODE THAT USES
/// THE ALLOCATOR CAN PRODUCE INCORRECT RESULTS OR CRASH. CALL
/// `std::alloc::Layout::align()` TO GET THE REQUIRED ALIGNMENT.
unsafe fn alloc_aligned(size: usize, align: usize) -> *mut u8 {
    let layout = Layout::from_size_align(size, align).unwrap();
    let ptr = alloc(layout);
    // `alloc` guarantees `ptr` is a multiple of `layout.align()`.
    assert!(ptr as usize % align == 0, "allocator contract violated");
    ptr
}
```

---

## Extended Examples

### Example 1 — Missing Command (Abstract Description Only)

> **Non-STE:** WARNING: API keys stored in plaintext configuration files are a major security risk.

> **STE:** WARNING: DO NOT STORE API KEYS IN PLAINTEXT CONFIGURATION FILES. STORE API KEYS IN ENVIRONMENT VARIABLES OR A SECRETS MANAGER. PLAINTEXT API KEYS IN VERSION CONTROL CAN CAUSE UNAUTHORIZED ACCESS AND DATA THEFT.

> *Principles applied: P1, P9 — the non-STE version describes the risk but gives no command. The STE version starts with "DO NOT STORE," gives an alternative, and explains the consequence. The reader learns the action in the first four words.*

Full runnable form — a test that fails on a committed secret:

```python
# WARNING: DO NOT STORE API KEYS IN PLAINTEXT CONFIGURATION FILES.
# STORE API KEYS IN ENVIRONMENT VARIABLES OR A SECRETS MANAGER.
# PLAINTEXT API KEYS IN VERSION CONTROL CAN CAUSE UNAUTHORIZED ACCESS
# AND DATA THEFT.
def test_no_secret_in_config(config_path):
    text = config_path.read_text()
    assert "sk_live_" not in text, "plaintext API key found in config"
```

### Example 2 — Missing Condition (Consequence Only)

> **Non-STE:** WARNING: THE DATABASE TRANSACTION CAN FAIL SILENTLY.

> **STE:** WARNING: IF YOU DO NOT CHECK THE RETURN VALUE OF `transaction.commit()`, THE TRANSACTION CAN FAIL SILENTLY. DATA THAT YOU THINK IS SAVED IS NOT SAVED. THIS SILENT DATA LOSS CAN CAUSE APPLICATION INCONSISTENCY. CHECK THE RETURN VALUE AND HANDLE THE `RollbackError` CASE.

> *Principles applied: P1, P4 — the non-STE version states only the risk. The STE version adds the condition ("IF YOU DO NOT CHECK...") before the consequence. The reader learns when the risk applies, not just that it exists.*

Full runnable form — a commit that checks the result:

```python
# WARNING: IF YOU DO NOT CHECK THE RETURN VALUE OF
# `transaction.commit()`, THE TRANSACTION CAN FAIL SILENTLY. DATA THAT
# YOU THINK IS SAVED IS NOT SAVED. THIS SILENT DATA LOSS CAN CAUSE
# APPLICATION INCONSISTENCY. CHECK THE RETURN VALUE AND HANDLE THE
# `RollbackError` CASE.
try:
    transaction.commit()
except RollbackError as exc:
    logger.error("commit failed: %s", exc)
    raise
```

### Example 3 — Command Buried in Background Information

> **Non-STE:** WARNING: Configuration drift between environments is a common cause of production incidents and represents a significant operational risk to the platform's availability, with the remedy being to always use the same configuration templates across all environments and verify them before each deployment.

> **STE:** WARNING: DO NOT USE DIFFERENT CONFIGURATION TEMPLATES FOR EACH ENVIRONMENT. USE THE SAME TEMPLATE FOR ALL ENVIRONMENTS. VERIFY THE CONFIGURATION BEFORE EACH DEPLOYMENT. CONFIGURATION DRIFT CAN CAUSE PRODUCTION INCIDENTS AND SERVICE UNAVAILABILITY.

> *Principles applied: P1, P9 — the non-STE version buries the command 30 words into the sentence. The STE version puts "DO NOT USE" at the start. The reader knows the prohibition immediately. The consequence follows.*

Full runnable form — a CI check that diffs configs:

```bash
# WARNING: DO NOT USE DIFFERENT CONFIGURATION TEMPLATES FOR EACH
# ENVIRONMENT. USE THE SAME TEMPLATE FOR ALL ENVIRONMENTS. VERIFY THE
# CONFIGURATION BEFORE EACH DEPLOYMENT. CONFIGURATION DRIFT CAN CAUSE
# PRODUCTION INCIDENTS AND SERVICE UNAVAILABILITY.
diff -q config/base.yaml config/staging.yaml || exit 1
diff -q config/base.yaml config/prod.yaml    || exit 1
```

### Example 4 — Wrong Condition Order (Consequence Before Condition)

> **Non-STE:** WARNING: PERMANENT DATA LOSS CAN OCCUR IF YOU DO NOT EXPORT THE DATA BEFORE YOU RUN THE CLEANUP SCRIPT.

> **STE:** WARNING: BEFORE YOU RUN THE CLEANUP SCRIPT, EXPORT THE DATA. IF YOU DO NOT EXPORT THE DATA, THE SCRIPT REMOVES THE DATA PERMANENTLY. THE DATA CANNOT BE RECOVERED. RUN `export-data --output backup.json` AND VERIFY THE FILE BEFORE YOU RUN THE CLEANUP SCRIPT.

> *Principles applied: P1, P3 — the non-STE version puts the consequence before the condition. The reader learns the risk before learning when it applies. The STE version puts the condition first ("BEFORE YOU RUN..."). The reader learns the context, then the risk.*

Full runnable form — a guarded cleanup script:

```bash
# WARNING: BEFORE YOU RUN THE CLEANUP SCRIPT, EXPORT THE DATA. IF YOU
# DO NOT EXPORT THE DATA, THE SCRIPT REMOVES THE DATA PERMANENTLY.
# THE DATA CANNOT BE RECOVERED. RUN `export-data --output backup.json`
# AND VERIFY THE FILE BEFORE YOU RUN THE CLEANUP SCRIPT.
export-data --output backup.json
test -s backup.json || { echo "backup empty; abort"; exit 1; }
./cleanup.sh
```

### Example 5 — Passive Voice Instead of Command

> **Non-STE:** CAUTION: The input data should be validated before it is processed by the pipeline.

> **STE:** CAUTION: VALIDATE THE INPUT DATA BEFORE THE PIPELINE PROCESSES IT. IF THE PIPELINE PROCESSES INVALID DATA, THE OUTPUT CAN BE INCORRECT. THE INCORRECT OUTPUT CAN PROPAGATE TO DOWNSTREAM SYSTEMS. USE THE `validateSchema` FUNCTION TO CHECK THE DATA STRUCTURE AND TYPES.

> *Principles applied: P1, P9 — the non-STE version uses passive voice ("should be validated"). The STE version uses an imperative command ("VALIDATE THE INPUT DATA"). The command is the first word after the colon. The consequence explains why validation matters.*

Full runnable form — a validation step in a pipeline:

```python
# CAUTION: VALIDATE THE INPUT DATA BEFORE THE PIPELINE PROCESSES IT.
# IF THE PIPELINE PROCESSES INVALID DATA, THE OUTPUT CAN BE INCORRECT.
# THE INCORRECT OUTPUT CAN PROPAGATE TO DOWNSTREAM SYSTEMS. USE THE
# `validateSchema` FUNCTION TO CHECK THE DATA STRUCTURE AND TYPES.
def run_pipeline(raw):
    validateSchema(raw)        # imperative: validate first
    return transform(raw)
```

### Example 6 — Multiple Commands Without Hierarchy

> **Non-STE:** WARNING: You need to sanitize inputs, escape SQL queries, validate return types, and check authentication tokens before processing the request, or data breaches can occur.

> **STE:** WARNING: BEFORE YOU PROCESS THE REQUEST, COMPLETE THESE CHECKS: (1) SANITIZE ALL INPUT DATA. (2) USE PARAMETERIZED SQL QUERIES. (3) VALIDATE THE RETURN TYPES. (4) VERIFY THE AUTHENTICATION TOKEN. IF YOU SKIP ANY CHECK, A SECURITY BREACH OR DATA LOSS CAN OCCUR.

> *Principles applied: P1, P4 — the non-STE version lists four commands in one run-on sentence. The STE version uses a numbered list with one command per item. The condition ("BEFORE YOU PROCESS") starts the instruction. Each command is imperative and self-contained.*

Full runnable form — a request handler that runs each check as a step:

```python
# WARNING: BEFORE YOU PROCESS THE REQUEST, COMPLETE THESE CHECKS:
# (1) SANITIZE ALL INPUT DATA. (2) USE PARAMETERIZED SQL QUERIES.
# (3) VALIDATE THE RETURN TYPES. (4) VERIFY THE AUTHENTICATION TOKEN.
# IF YOU SKIP ANY CHECK, A SECURITY BREACH OR DATA LOSS CAN OCCUR.
def process_request(req):
    data = sanitize(req.body)                       # (1)
    rows = db.query("SELECT * FROM u WHERE id=%s",  # (2) parameterized
                    (data["id"],))
    result = validate_return_type(rows)            # (3)
    verify_token(req.headers["Authorization"])      # (4)
    return result
```

---

## Edge Cases

### Edge Case 1 — When a Framework Method Name Conflicts with a Command Word

Some frameworks use method names that are the same as STE-Code command words (for example, `check`, `set`, `get`, `do`). When the command in the safety instruction is also a framework method name, use the method name in backticks only when referring to the method. Use the plain word as the command.

> **Non-STE:** WARNING: Check that you check the `check()` return value before proceeding.

> **STE:** WARNING: CHECK THE RETURN VALUE OF THE `check()` METHOD BEFORE YOU CONTINUE. IF `check()` RETURNS `false`, THE AUTHENTICATION IS NOT VALID. DO NOT PROCESS THE REQUEST. AN INVALID AUTHENTICATION CAN PERMIT UNAUTHORIZED ACCESS.

> *Principles applied: P1, P5 — the command word "CHECK" is plain uppercase. The method name `check()` is in backticks. The reader distinguishes the instruction from the method reference.*

Full runnable form — an auth guard that calls `check()`:

```python
# WARNING: CHECK THE RETURN VALUE OF THE `check()` METHOD BEFORE YOU
# CONTINUE. IF `check()` RETURNS `false`, THE AUTHENTICATION IS NOT
# VALID. DO NOT PROCESS THE REQUEST. AN INVALID AUTHENTICATION CAN
# PERMIT UNAUTHORIZED ACCESS.
def guard(req):
    if authenticator.check(req.token) is False:  # check() return value
        raise PermissionError("invalid authentication")
    return handle(req)
```

### Edge Case 2 — When the Condition Is Always True for a Subset of Users

Some conditions apply only to a specific deployment configuration, operating system, or library version. When the condition is not universal, use an "IF" clause that names the specific scenario. Do not write a command that is wrong for the other users.

> **Non-STE:** WARNING: DO NOT USE THE `fetch` API IN NODE.JS BEFORE VERSION 18.

> **STE:** WARNING: IF YOU USE NODE.JS BEFORE VERSION 18, DO NOT USE THE `fetch` API. THE `fetch` API IS NOT AVAILABLE IN NODE.JS BEFORE VERSION 18. YOUR APPLICATION CRASHES WITH A `ReferenceError`. USE `node-fetch` OR UPGRADE TO NODE.JS 18 OR LATER.

> *Principles applied: P1, P10 — the condition "IF YOU USE NODE.JS BEFORE VERSION 18" scopes the prohibition. Users on Node.js 18 or later know the command does not apply to them. The alternative is given.*

Full runnable form — a version-gated import:

```javascript
// WARNING: IF YOU USE NODE.JS BEFORE VERSION 18, DO NOT USE THE
// `fetch` API. THE `fetch` API IS NOT AVAILABLE IN NODE.JS BEFORE
// VERSION 18. YOUR APPLICATION CRASHES WITH A `ReferenceError`. USE
// `node-fetch` OR UPGRADE TO NODE.JS 18 OR LATER.
let fetchImpl;
if (process.versions.node.startsWith("18") ||
    Number(process.versions.node.split(".")[0]) >= 18) {
  fetchImpl = fetch;                 // global since Node 18
} else {
  fetchImpl = require("node-fetch"); // polyfill for older runtimes
}
```

### Edge Case 3 — When a Command and a Condition Are Both Required

Some safety instructions need both a command and a condition. When both are required, put the condition first (per the rule: "give this condition first"). The condition tells the reader when the command applies. The command tells the reader what to do.

> **Non-STE:** WARNING: Always run the database migration tool and make sure you are connected to the correct database before running the schema update.

> **STE:** WARNING: BEFORE YOU RUN THE SCHEMA UPDATE, CONNECT TO THE CORRECT DATABASE. RUN THE MIGRATION TOOL WITH THE `--check` FLAG. IF YOU RUN THE SCHEMA UPDATE ON THE WRONG DATABASE, THE SCHEMA IS CORRUPTED AND THE APPLICATION CANNOT START.

> *Principles applied: P1, P9 — the condition "BEFORE YOU RUN THE SCHEMA UPDATE" comes first. The command "CONNECT TO THE CORRECT DATABASE" follows. The reader knows the sequence: check the condition, then execute the command.*

Full runnable form — a migration runner with a pre-check:

```bash
# WARNING: BEFORE YOU RUN THE SCHEMA UPDATE, CONNECT TO THE CORRECT
# DATABASE. RUN THE MIGRATION TOOL WITH THE `--check` FLAG. IF YOU RUN
# THE SCHEMA UPDATE ON THE WRONG DATABASE, THE SCHEMA IS CORRUPTED AND
# THE APPLICATION CANNOT START.
export DATABASE_URL="postgres://app@staging:5432/app"
migrate --check        # fails fast if the connection is wrong
migrate up             # only reaches here on the correct database
```

### Edge Case 4 — When a Safety Instruction References Generated Code

Generated files (from tools such as `protoc`, `graphql-codegen`, or `terraform plan`) may contain auto-generated comments that look like safety instructions. These generated comments break the command-first or condition-first rule. For generated code:

- Do not modify the generated comments. The generator overwrites your changes.
- Add your own STE-Code WARNING or CAUTION above the generated block. Your instruction follows the command-first or condition-first rule.
- If the generated code has a safety concern that is not documented, open an issue with the generator project.

> **Generated comment (leave as-is):** // Note: This method is generated. Do not edit.

> **Your wrapper with command-first:** WARNING: DO NOT EDIT THE `generated/` DIRECTORY MANUALLY. THE GENERATOR OVERWRITES YOUR CHANGES ON THE NEXT BUILD. IF YOU CHANGE THE GENERATED CODE, YOUR CHANGES ARE LOST. EDIT THE `.proto` SOURCE FILE AND RUN THE GENERATOR AGAIN.

> *Principles applied: P1, P7 — the command "DO NOT EDIT" starts the instruction. The consequence (lost changes) follows. The correct workflow is explained.*

Full runnable form — a build step that regenerates from source:

```makefile
# WARNING: DO NOT EDIT THE `generated/` DIRECTORY MANUALLY. THE
# GENERATOR OVERWRITES YOUR CHANGES ON THE NEXT BUILD. IF YOU CHANGE
# THE GENERATED CODE, YOUR CHANGES ARE LOST. EDIT THE `.proto` SOURCE
# FILE AND RUN THE GENERATOR AGAIN.
generated/:
	protoc --python_out=generated/ api.proto   # regenerates from source
```

### Edge Case 5 — Internationalization of Command and Condition Words

When your documentation is translated, the command words (DO NOT, ALWAYS, CHECK, MAKE SURE) and condition words (IF, BEFORE, WHEN) must also be translated. Use the standard translation for these words. Maintain a glossary of translated command and condition words.

The command or condition must remain the first element after the translated signal word:

| Language | DO NOT | ALWAYS | IF | BEFORE YOU |
|----------|--------|--------|----|------------|
| English | DO NOT | ALWAYS | IF | BEFORE YOU |
| Spanish | NO | SIEMPRE | SI | ANTES DE |
| French | NE PAS | TOUJOURS | SI | AVANT DE |
| German | NICHT | IMMER | WENN | BEVOR SIE |
| Japanese | 禁止 | 必ず | 場合 | 前に |

The word order rules are the same in all languages. The command or condition comes first. The consequence comes after. Do not change the structure for any language.

Full runnable form — a localized warning (Spanish) in a docstring:

```python
# ADVERTENCIA: NO GUARDE CLAVES DE API EN EL CÓDIGO FUENTE. SIEMPRE
# USE VARIABLES DE ENTORNO O UN GESTOR DE SECRETOS. LAS CLAVES EN EL
# CÓDIGO FUENTE PUEDEN CAUSAR ACCESO NO AUTORIZADO Y FUGAS DE DATOS.
def get_client():
    return Client(os.environ["API_KEY"])
```

---

## Cross-References

- **Rule 1.4** — Use only approved verb forms and adjective forms. The command in a safety instruction must use an approved verb (for example, "check," "make sure," "use," "do not").
- **Rule 1.11** — One term per concept. Use the same command words across all safety instructions. Do not use "check" in one instruction and "verify" in another for the same action.
- **Rule 1.12** — Technical verbs (build, deploy, test, lint) are allowed. Use technical verbs in commands when they are the correct term (for example, "DO NOT DEPLOY," "ALWAYS SANITIZE").
- **Rule 4.1** — Write short and clear sentences. The command or condition must be a short sentence. The reader must understand it in one reading.
- **Rule 4.2** — Use the active voice. Commands are inherently active. Conditions must also use the active voice (for example, "IF YOU DO NOT SET..." not "IF THE TIMEOUT IS NOT SET...").
- **Rule 5.3** — Use the imperative (command) form for instructions. Every WARNING or CAUTION instruction uses the imperative mood for the command part.
- **Rule 5.4** — Write each step as a command. When a safety instruction has multiple actions, write each action as a separate command.
- **Rule 7.1** — Use an applicable word to identify the level of risk. The signal word (WARNING or CAUTION) comes before the command or condition. Choose the correct signal word before you write the command.
- **Rule 7.3** — Give an explanation to show the risk or possible result. The command or condition tells the reader what to do. The explanation tells the reader why. Both are required in a complete safety instruction.
- **Section 1 (Vocabulary)** — All words used in commands and conditions must come from the approved vocabulary unless they are technical code nouns.
- **Section 5 (Procedural Writing)** — Safety instructions are procedural sentences. Follow all procedural writing rules for the command and condition parts.

---

## Grammar Notes

### Imperative Mood in Commands

Commands in safety instructions use the imperative mood. The imperative mood addresses the reader directly and tells them what to do (or not do). The subject "you" is implied and not written.

The four imperative forms used in code documentation safety instructions:

1. **Positive imperative:** CHECK THE RETURN VALUE. MAKE SURE THAT THE FILE EXISTS. BACK UP THE DATABASE.
2. **Negative imperative (prohibition):** DO NOT COMMIT THE API KEY. DO NOT USE THIS FUNCTION. DO NOT SKIP THE VALIDATION STEP.
3. **Emphatic positive imperative:** ALWAYS SANITIZE THE INPUT. ALWAYS VERIFY THE SIGNATURE. ALWAYS USE PARAMETERIZED QUERIES.
4. **Sequence imperative:** BEFORE YOU [ACTION], [COMMAND].

Do not use modal verbs in commands. Modal verbs weaken the instruction:

> **Correct:** CHECK THE RETURN VALUE BEFORE YOU CONTINUE.
> **Incorrect:** You should check the return value before continuing.
> **Incorrect:** The return value must be checked before continuing.

### Condition Clause Grammar

Condition clauses use subordinating conjunctions (IF, BEFORE, WHEN, UNLESS). The condition clause is a dependent clause. It must be attached to an independent clause that contains the consequence or the command.

**Correct condition-first structure:** IF [condition], [consequence/command]. [Explanation].

**Incorrect (consequence first):** [Consequence] IF [condition]. [Explanation].

The condition clause uses the present tense, even when referring to a future action:

> **Correct:** IF YOU DO NOT SET THE TIMEOUT, THE APPLICATION HANGS.
> **Incorrect:** IF YOU WILL NOT SET THE TIMEOUT, THE APPLICATION WILL HANG.

### Sentence Length for Commands and Conditions

The command or condition sentence must not be more than 20 words. This limit makes sure the reader understands the instruction quickly. If the full safety instruction needs more words, use multiple sentences. The first sentence is the command or condition. The following sentences give the explanation and consequence.

> **Correct (19 words):** DO NOT USE THE `eval()` FUNCTION WITH DATA THAT COMES FROM AN UNTRUSTED SOURCE. EVAL() CAN EXECUTE ARBITRARY CODE.
>
> **Correct (split across sentences):** DO NOT USE THE `eval()` FUNCTION WITH UNTRUSTED DATA. EVAL() CAN EXECUTE ARBITRARY CODE. ARBITRARY CODE EXECUTION CAN CAUSE A COMPLETE SYSTEM COMPROMISE.

The condition sentence can also be split:

> **Correct (condition first, then consequence):** IF YOU DO NOT SANITIZE THE INPUT DATA, THE QUERY CAN FAIL. THE FAILURE CAN CAUSE DATA CORRUPTION. SANITIZE ALL INPUT WITH THE `cleanInput` FUNCTION.

### Punctuation After the Signal Word

The signal word is followed by a colon (:) and a single space. The command or condition sentence starts with an uppercase letter. Use a period (.) at the end of each sentence. Do not use semicolons to join the command and the consequence.

> **Correct:** WARNING: DO NOT STORE THE PRIVATE KEY IN THE REPOSITORY. THE PRIVATE KEY CAN BE ACCESSED BY UNAUTHORIZED USERS.
>
> **Incorrect:** WARNING: do not store the private key in the repository; the private key can be accessed by unauthorized users.

### Parallel Structure in Multi-Command Instructions

When a safety instruction contains multiple commands, use parallel grammatical structure. Each command must use the same verb form. Use a numbered list for clarity.

> **Correct:**
> WARNING: BEFORE YOU DEPLOY, COMPLETE THESE STEPS:
> (1) BACK UP THE DATABASE.
> (2) RUN THE MIGRATION SCRIPTS.
> (3) VERIFY THE APPLICATION HEALTH CHECK.
>
> **Incorrect:**
> WARNING: Before deploying you should back up the database, running migration scripts must be done, and the health check is verified.

### "Make Sure" as a Command Pattern

"Make sure" is a special command pattern in STE-Code. It is used when the reader must verify a condition before acting. "Make sure" is followed by a "that" clause that describes the condition to verify.

> **Correct:** MAKE SURE THAT THE DATABASE CONNECTION IS OPEN BEFORE YOU RUN THE QUERY.
> **Correct:** MAKE SURE THAT THE INPUT DATA IS SANITIZED BEFORE THE PIPELINE PROCESSES IT.

Do not use "make sure" when a direct imperative verb is clearer:

> **Better:** SANITIZE THE INPUT DATA BEFORE THE PIPELINE PROCESSES IT.
> **Acceptable:** MAKE SURE THAT THE INPUT DATA IS SANITIZED BEFORE THE PIPELINE PROCESSES IT.

Use "make sure" for verification of existing state. Use direct imperatives for actions the reader must perform.

---

<!-- a-sec7-rule7.3.md -->

# Rule 7.3 — Give an Explanation to Show the Risk or Possible Result

> **Source:** Adapted from ASD-STE100 Issue 9, Rule 7.3

> **Source:** [master.md#sec7-rule7.3](ste-code/grouped/)

## Original Rule

**Rule 7.3** If it is possible, always tell your reader about the problems that can occur if the reader does not obey the safety instruction. If there is a clear and specified risk, the person who does the task will understand the risk and be more careful.

**Spec examples:**

(Refer to the underlined risk or possible result.)

> **WARNING:** DO NOT SWALLOW THE SOLVENT. ALWAYS MAKE SURE THAT YOU KNOW THE SAFETY PRECAUTIONS AND FIRST AID INSTRUCTIONS FOR SOLVENTS. SOLVENTS ARE POISONOUS AND CAN CAUSE INJURY OR DEATH.

> **CAUTION:** DO NOT USE BLEACH OR CLEANSERS THAT CONTAIN CHLORINE TO CLEAN THE UNIT. THESE CLEANING AGENTS CAN CAUSE CORROSION.

> IF THEY FALL, PERMANENT DAMAGE TO THE PARTS CAN OCCUR.

## STE-Code Adaptation

**Rule 7.3** In code documentation, if it is possible, always tell your reader about the problems that can occur if the reader does not obey the safety instruction. If there is a clear and specified risk, the developer who uses the code will understand the risk and be more careful.

Severity mapping: The risk explanation must match the severity from Rule 7.1. For release-note and changelog severity, map the levels as follows: WARNING to BREAKING, CAUTION to DEPRECATED, NOTE to NOTE.

A risk explanation has three parts: (1) the violation or failure to obey the instruction, (2) the immediate consequence, and (3) the cascading or final harm. Write the chain in cause-first order: "If you do X, Y can happen." Do not stop at "Y must not happen" without naming what Y is. An instruction without a risk explanation is a prohibition the reader can dismiss. A risk explanation turns the prohibition into a reason.

### Examples

> *Adapted from spec pair:* Non-STE: `WARNING: DO NOT SWALLOW THE SOLVENT. ... SOLVENTS ARE POISONOUS AND CAN CAUSE INJURY OR DEATH.`  |  STE: `WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.` (ASD-STE100 Issue 9, Rule 7.3, page 100 — the WARNING names the poison and the injury or death; the code-domain pair names the exposure and the breach.)

> **Non-STE:** WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE.
>
> **STE:** WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE. API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.
>
> *Adapted from spec pattern: WARNING with risk explanation — "SOLVENTS ARE POISONOUS AND CAN CAUSE INJURY OR DEATH."*

A complete README section that uses this pair, with the risk explanation written in context:

```markdown
## Security Setup

WARNING: DO NOT STORE API KEYS IN THE SOURCE CODE.
API KEYS IN SOURCE CODE CAN CAUSE UNAUTHORIZED ACCESS AND DATA BREACHES.

Store the key in an environment variable named `PAYMENTS_API_KEY`.
Add the `.env` file to `.gitignore`. A committed key stays in the
repository history after you remove it, so rotate the key after a leak.
```

> **Non-STE:** CAUTION: DO NOT USE DEPRECATED FUNCTIONS.
>
> **STE:** CAUTION: DO NOT USE DEPRECATED FUNCTIONS. DEPRECATED FUNCTIONS CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.
>
> *Adapted from spec pattern: CAUTION with risk explanation — "THESE CLEANING AGENTS CAN CAUSE CORROSION."*

A JSDoc comment that uses this pair, with the specific deprecated function named:

```javascript
/**
 * CAUTION: DO NOT USE THE `formatDate` FUNCTION.
 * DEPRECATED FUNCTIONS CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.
 *
 * `formatDate` uses the host time zone. The output changes between
 * servers, so two users can see two different dates for the same event.
 * Use `formatDateUTC` instead.
 *
 * @deprecated since v3.2.0
 */
function formatDate(value) { /* ... */ }
```

> **Non-STE:** MAKE SURE THAT YOU SET THE CONNECTION TIMEOUT.
>
> **STE:** IF YOU DO NOT SET THE CONNECTION TIMEOUT, THE APPLICATION CAN BECOME UNAVAILABLE AND PERMANENT DATA LOSS CAN OCCUR.
>
> *Adapted from spec pattern: consequence statement — "IF THEY FALL, PERMANENT DAMAGE TO THE PARTS CAN OCCUR."*

A configuration file and the docstring that explain the timeout risk:

```python
def connect(host: str, port: int, timeout: float | None = None) -> Socket:
    """Open a TCP connection to the server.

    IF YOU DO NOT SET THE CONNECTION TIMEOUT, THE APPLICATION CAN
    BECOME UNAVAILABLE AND PERMANENT DATA LOSS CAN OCCUR.

    Without a timeout, a connection that never answers keeps the calling
    thread blocked. Blocked threads fill the worker pool. When the pool
    is full, the application stops accepting new requests. Writes that
    wait for a blocked connection are not committed, so the data is lost.

    Parameters:
        timeout: Seconds to wait before the connect fails. The default is
            None, which means wait forever. Always pass a value.
    """
```

> **See also:** Rule 7.1 — Use an Applicable Word (for Example, "Warning" or "Caution") to Identify the Level of Risk; Rule 7.2 — Start a Safety Instruction with a Clear and Accurate Command or Condition; Rule 7.4 — Use Imperative Mood for Instructions

---

## Code-Domain Explanation

Rule 7.3 addresses a fundamental gap in software documentation: instructions that tell the reader _what_ to avoid but not _why_ the avoidance matters. In aerospace, a mechanic who understands that a solvent is poisonous will handle it more carefully. In code, a developer who understands that an omitted timeout causes data loss will take the instruction seriously.

The rule applies differently across documentation types:

**README files.** README files give setup instructions and usage warnings. A README that says "do not use Node.js versions below 18" without explanation leaves new contributors vulnerable. The README must add: "Node.js versions below 18 do not include the `fetch` API. The application uses `fetch` for all network requests. If you use a version below 18, the requests will fail without an error message." The risk explanation connects the prohibition to a specific, observable failure.

```markdown
## Requirements

CAUTION: USE NODE.JS VERSION 18 OR HIGHER.
NODE.JS VERSIONS BELOW 18 DO NOT INCLUDE THE `fetch` API.
THE APPLICATION USES `fetch` FOR ALL NETWORK REQUESTS.
IF YOU USE A VERSION BELOW 18, THE REQUESTS WILL FAIL WITHOUT AN ERROR MESSAGE.

Run `node --version` before you run `npm install`.
```

**API documentation.** API docs describe function contracts. A docstring that says "do not pass null" is incomplete. It must also say: "If you pass null, the function throws a `NullPointerException` and the transaction is not committed. Uncommitted transactions can cause database lock contention." The reader now understands the cascading effect, not just the immediate error.

```java
/**
 * CAUTION: DO NOT PASS NULL FOR THE `orderId` PARAMETER.
 * A NULL `orderId` CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.
 *
 * If you pass null, the method throws NullPointerException and the
 * transaction is not committed. An uncommitted transaction holds a row
 * lock. Locked rows can block other requests and cause database
 * contention for all users of the table.
 */
Order loadOrder(String orderId) { /* ... */ }
```

**Docstrings and inline comments.** Docstrings carry both usage notes and warnings. A docstring that says "this function is not thread-safe" without explanation is ignored. The docstring must add: "If two goroutines call this function at the same time, the internal map can become corrupt. Map corruption causes silent data loss because no error is returned." The risk explanation transforms an abstract property into a concrete hazard.

```go
// CAUTION: THE `Counter` TYPE IS NOT THREAD-SAFE.
// THE `Counter` TYPE CAN CAUSE UNEXPECTED BEHAVIOR AND INCORRECT RESULTS.
//
// If two goroutines call Add at the same time, the internal map can
// become corrupt. Map corruption causes silent data loss because no
// error is returned. Use CounterSafe, which uses a mutex, for concurrent
// code.
type Counter struct { values map[string]int }
```

**Commit messages.** Commit messages serve as historical records and review context. A commit that says "remove the `--force` flag from the deploy script" documents a change. The body must add: "If the `--force` flag is used, the deploy script overwrites the production database without confirmation. Overwriting the production database can cause permanent loss of user data." Future readers who consider reintroducing the flag will see the recorded risk.

```
WARNING: Remove the --force flag from the deploy script.

The --force flag made the deploy script overwrite the production
database without confirmation. A wrong branch name then destroyed
all user data. Overwriting the production database can cause
permanent loss of user data.

The script now fails if the target is the production database unless
you set DEPLOY_TO_PROD=true. Keep this guard. Do not add --force back.
```

**Error messages.** Error messages are the last line of defense. An error that says "configuration not found" tells the user a fact. A better error says: "The configuration file `config.toml` was not found. The application cannot start without this file. If the application starts without configuration, it uses unsafe default values that can expose sensitive data in logs." The risk explanation turns a missing-file notice into an actionable security warning.

```
WARNING: THE CONFIGURATION FILE config.toml WAS NOT FOUND.
THE APPLICATION CANNOT START WITHOUT THIS FILE.
IF THE APPLICATION STARTS WITHOUT CONFIGURATION, IT USES UNSAFE
DEFAULT VALUES THAT CAN EXPOSE SENSITIVE DATA IN LOGS.

Check that config.toml is in the working directory. Set the
CONFIG_PATH environment variable to the file location.
```

**Changelogs and release notes.** A changelog entry that says "BREAKING: removed the `legacy_auth` module" tells users about a deletion. It must also say: "If your code imports `legacy_auth`, the build will fail. You must replace all imports with the `auth_v2` module. A build failure can delay your deployment and cause service downtime." The risk explanation helps users plan their migration. A changelog without risk explanations is a list of facts. A changelog with risk explanations is a migration guide.

```markdown
## [4.0.0] - 2026-08-01

### BREAKING
- Removed the `legacy_auth` module.

  WARNING: IF YOUR CODE IMPORTS `legacy_auth`, THE BUILD WILL FAIL.
  YOU MUST REPLACE ALL IMPORTS WITH THE `auth_v2` MODULE.
  A BUILD FAILURE CAN DELAY YOUR DEPLOYMENT AND CAUSE SERVICE DOWNTIME.

  Run `grep -r legacy_auth src/` to find every import. The `auth_v2`
  module uses token scopes instead of the old role list. See the
  migration guide before you upgrade.
```

**The risk explanation must match the signal word level.** The original ASD-STE100 defines two severity levels: WARNING (risk of injury or death) and CAUTION (risk of equipment damage). In code documentation, WARNING maps to data loss, security breach, or system unavailability. CAUTION maps to incorrect results, degraded performance, or build failures. A risk explanation under a WARNING must describe a severe outcome. A risk explanation under a CAUTION must describe a moderate outcome. Do not use WARNING for a build failure. Do not use CAUTION for a data breach. Mismatched severity erodes trust in all safety instructions in the document.

## Paradigm-Specific Guidance

**Object-Oriented (Java, C++, C#, Python classes).** In OOP, risk explanations often involve state corruption and inheritance contracts. A warning about a mutable field must explain that subclasses can modify the field in unexpected ways. A caution about a non-final method must explain that overriding can violate the base class invariant.

> **Non-STE:** CAUTION: DO NOT OVERRIDE THE `initialize()` METHOD.
>
> **STE:** CAUTION: DO NOT OVERRIDE THE `initialize()` METHOD. IF YOU OVERRIDE `initialize()`, THE BASE CLASS CONNECTION POOL IS NOT SET. CONNECTIONS WITHOUT A POOL CAN CAUSE RESOURCE EXHAUSTION AND APPLICATION CRASHES.
>
> *Principles applied: P3 (get → is not set), P7 (initialize as verb, not noun). Risk connects override to pool state to crash.*

```python
class Database:
    def __init__(self):
        self._pool = self._build_pool()

    def initialize(self):
        """CAUTION: DO NOT OVERRIDE THE `initialize()` METHOD.
        IF YOU OVERRIDE `initialize()`, THE BASE CLASS CONNECTION POOL IS
        NOT SET. CONNECTIONS WITHOUT A POOL CAN CAUSE RESOURCE EXHAUSTION
        AND APPLICATION CRASHES.

        Subclasses that override initialize must call super().initialize()
        first, or the pool stays None and every query fails open."""
        self._ready = True
```

**Functional (Haskell, Elixir, Clojure, Rust).** In functional paradigms, risk explanations often involve purity violations and lazy evaluation surprises. A warning about an impure function must explain that referential transparency is broken. A caution about an unsafe IO operation must explain that laziness delays the side effect beyond the expected execution point.

> **Non-STE:** WARNING: `unsafePerformIO` IS DANGEROUS.
>
> **STE:** WARNING: DO NOT USE `unsafePerformIO` IN PRODUCTION CODE. `unsafePerformIO` REMOVES THE IO TYPE SAFETY GUARANTEE. WITHOUT THE IO GUARANTEE, SIDE EFFECTS CAN RUN AT UNEXPECTED TIMES. SIDE EFFECTS AT UNEXPECTED TIMES CAN CAUSE RACE CONDITIONS AND SILENT DATA CORRUPTION.
>
> *Principles applied: P10 (no slang: "dangerous" → specific risk), P4 (approved adjective forms). Risk traces from type-safety removal to corruption.*

```haskell
-- WARNING: DO NOT USE `unsafePerformIO` IN PRODUCTION CODE.
-- `unsafePerformIO` REMOVES THE IO TYPE SAFETY GUARANTEE.
-- WITHOUT THE IO GUARANTEE, SIDE EFFECTS CAN RUN AT UNEXPECTED TIMES.
-- SIDE EFFECTS AT UNEXPECTED TIMES CAN CAUSE RACE CONDITIONS AND
-- SILENT DATA CORRUPTION.
--
-- cacheLookup reads a file inside a pure function. Two calls with the
-- same key can return different values because the file changes between
-- them. Referential transparency is broken.
secret :: Key -> Value
secret k = unsafePerformIO (readSecretFromFile k)
```

**Procedural (C, Go, Bash).** In procedural code, risk explanations often involve resource lifetimes and error-code neglect. A warning about a `malloc` without `free` must explain the leak's cumulative effect. A caution about an ignored return code must explain the silent failure path.

> **Non-STE:** WARNING: YOU MUST FREE THE BUFFER.
>
> **STE:** WARNING: YOU MUST FREE THE BUFFER AFTER EACH `malloc` CALL. EACH UNFREED BUFFER STAYS IN MEMORY UNTIL THE PROCESS STOPS. IN A LONG-RUNNING PROCESS, UNFREED BUFFERS CAN USE ALL AVAILABLE MEMORY. MEMORY EXHAUSTION CAN CAUSE THE OPERATING SYSTEM TO STOP THE PROCESS.
>
> *Principles applied: P1 (use → after each call), P9 (short, clear nouns). Risk traces from unfreed buffer to OS termination.*

```c
/* WARNING: YOU MUST FREE THE BUFFER AFTER EACH `malloc` CALL.
   EACH UNFREED BUFFER STAYS IN MEMORY UNTIL THE PROCESS STOPS.
   IN A LONG-RUNNING PROCESS, UNFREED BUFFERS CAN USE ALL AVAILABLE
   MEMORY. MEMORY EXHAUSTION CAN CAUSE THE OPERATING SYSTEM TO STOP
   THE PROCESS. */
char *buf = malloc(1024);
if (buf == NULL) { return ERR_NOMEM; }
parse(buf);
free(buf);   /* without this line, the leak grows every call */
```

**Declarative (SQL, Terraform, Kubernetes YAML).** In declarative configurations, risk explanations often involve cascading side effects from a single declaration. A Terraform resource change can destroy and recreate infrastructure. A Kubernetes manifest misconfiguration can expose internal services.

> **Non-STE:** CAUTION: DO NOT CHANGE THE `family` FIELD.
>
> **STE:** CAUTION: DO NOT CHANGE THE `family` FIELD IN THE `aws_db_instance` RESOURCE. TERRAFORM INTERPRETS A CHANGE TO `family` AS A DESTROY-AND-RECREATE OPERATION. A DESTROY-AND-RECREATE OPERATION REMOVES THE CURRENT DATABASE AND ALL ITS DATA. THE REMOVED DATA CANNOT BE RECOVERED.
>
> *Principles applied: P3 (show → interprets), P11 (one term: destroy-and-recreate). Risk explains the interpreter behavior behind the field change.*

```hcl
resource "aws_db_instance" "main" {
  # CAUTION: DO NOT CHANGE THE `family` FIELD IN THIS RESOURCE.
  # TERRAFORM INTERPRETS A CHANGE TO `family` AS A DESTROY-AND-RECREATE
  # OPERATION. A DESTROY-AND-RECREATE OPERATION REMOVES THE CURRENT
  # DATABASE AND ALL ITS DATA. THE REMOVED DATA CANNOT BE RECOVERED.
  family = "postgres16"
}
```

**Systems (Rust ownership, C memory, kernel documentation).** Systems documentation carries the highest-risk instructions. A warning about undefined behavior in C must explain the practical consequence, not just cite the standard. A Rust `unsafe` block documentation must explain which safety invariant the caller must uphold and what happens if it is not.

> **Non-STE:** WARNING: THIS FUNCTION IS UNSAFE. THE CALLER MUST NOT ALIAS THE POINTER.
>
> **STE:** WARNING: THIS FUNCTION IS UNSAFE. THE CALLER MUST MAKE SURE THAT NO OTHER POINTER REFERS TO THE SAME MEMORY. IF TWO POINTERS REFER TO THE SAME MEMORY, THE COMPILER CAN REMOVE LOADS AND STORES THAT THE PROGRAM NEEDS. REMOVED LOADS AND STORES CAN CAUSE VALUES TO APPEAR FROM DIFFERENT EXECUTION TIMELINES, WHICH IS UNDEFINED BEHAVIOR.
>
> *Principles applied: P2 (alias → refer to, specified part of speech), P8 (standard technical nouns: undefined behavior). Risk connects aliasing to compiler optimization to undefined behavior.*

```rust
/// WARNING: THIS FUNCTION IS UNSAFE.
/// THE CALLER MUST MAKE SURE THAT NO OTHER POINTER REFERS TO THE SAME MEMORY.
/// IF TWO POINTERS REFER TO THE SAME MEMORY, THE COMPILER CAN REMOVE
/// LOADS AND STORES THAT THE PROGRAM NEEDS. REMOVED LOADS AND STORES CAN
/// CAUSE VALUES TO APPEAR FROM DIFFERENT EXECUTION TIMELINES, WHICH IS
/// UNDEFINED BEHAVIOR.
///
/// `write_volatile` writes through `ptr` with no aliasing check. Keep the
/// pointed-to memory exclusive to this call while it runs.
pub unsafe fn write_volatile(ptr: *mut u32, value: u32) { /* ... */ }
```

## Extended Examples

> **Non-STE:** WARNING: DO NOT USE `eval()`.
>
> **STE:** WARNING: DO NOT USE `eval()` WITH DATA FROM EXTERNAL SOURCES. `eval()` RUNS THE INPUT AS CODE WITH THE SAME PRIVILEGES AS THE APPLICATION. A MALICIOUS INPUT CAN RUN ARBITRARY COMMANDS ON THE HOST SYSTEM. ARBITRARY COMMANDS CAN CAUSE DATA THEFT, DATA DESTRUCTION, OR SYSTEM COMPROMISE.
>
> *Principles applied: P5 (technical code noun: `eval`), P3 (use → runs, approved meaning). Risk traces from eval to full system compromise.*

```javascript
// WARNING: DO NOT USE `eval()` WITH DATA FROM EXTERNAL SOURCES.
// `eval()` RUNS THE INPUT AS CODE WITH THE SAME PRIVILEGES AS THE APPLICATION.
// A MALICIOUS INPUT CAN RUN ARBITRARY COMMANDS ON THE HOST SYSTEM.
// ARBITRARY COMMANDS CAN CAUSE DATA THEFT, DATA DESTRUCTION, OR SYSTEM COMPROMISE.
function runFilter(userInput) {
  // Bad: eval(userInput)
  return JSON.parse(userInput); // Safe: parse only, no code execution
}
```

> **Non-STE:** CAUTION: PAGINATION IS MANDATORY.
>
> **STE:** CAUTION: YOU MUST USE PAGINATION FOR ALL LIST ENDPOINTS. WITHOUT PAGINATION, A SINGLE REQUEST CAN RETURN EVERY RECORD IN THE DATABASE. A LARGE RESULT SET CAN CAUSE MEMORY EXHAUSTION ON THE SERVER. MEMORY EXHAUSTION CAN CAUSE THE SERVER TO STOP AND ALL CONNECTED CLIENTS TO DISCONNECT.
>
> *Principles applied: P9 (short, clear: pagination), P1 (use → use). Risk traces from missing pagination to server crash.*

```python
@app.get("/users")
def list_users(page: int = 1, per_page: int = 50):
    """CAUTION: YOU MUST USE PAGINATION FOR ALL LIST ENDPOINTS.
    WITHOUT PAGINATION, A SINGLE REQUEST CAN RETURN EVERY RECORD IN THE
    DATABASE. A LARGE RESULT SET CAN CAUSE MEMORY EXHAUSTION ON THE SERVER.
    MEMORY EXHAUSTION CAN CAUSE THE SERVER TO STOP AND ALL CONNECTED
    CLIENTS TO DISCONNECT.

    Reject requests where per_page is above 100. Use keyset pagination on
    the `id` column for stable ordering."""
    return db.paginate(page, per_page)
```

> **Non-STE:** WARNING: CORS IS NOT CONFIGURED PROPERLY.
>
> **STE:** WARNING: THE CORS CONFIGURATION USES A WILDCARD ORIGIN (`*`). A WILDCARD ORIGIN LETS ANY WEBSITE SEND REQUESTS WITH THE USER'S CREDENTIALS. AN ATTACKER CAN MAKE AN AUTHENTICATED REQUEST FROM A MALICIOUS WEBSITE. AUTHENTICATED REQUESTS FROM A MALICIOUS ORIGIN CAN CAUSE DATA THEFT AND ACCOUNT TAKEOVER.
>
> *Principles applied: P5 (CORS, wildcard as technical nouns), P6 (non-approved word as technical noun). Risk traces from wildcard to account takeover.*

```javascript
// WARNING: THE CORS CONFIGURATION USES A WILDCARD ORIGIN (`*`).
// A WILDCARD ORIGIN LETS ANY WEBSITE SEND REQUESTS WITH THE USER'S
// CREDENTIALS. AN ATTACKER CAN MAKE AN AUTHENTICATED REQUEST FROM A
// MALICIOUS WEBSITE. AUTHENTICATED REQUESTS FROM A MALICIOUS ORIGIN CAN
// CAUSE DATA THEFT AND ACCOUNT TAKEOVER.
app.use(cors({
  origin: ["https://app.example.com"], // not "*"
  credentials: true,
}));
```

> **Non-STE:** WARNING: RACE CONDITION.
>
> **STE:** WARNING: TWO GOROUTINES CAN WRITE TO THE `counter` VARIABLE AT THE SAME TIME. CONCURRENT WRITES TO A GO VARIABLE WITHOUT A MUTEX CAUSE A DATA RACE. DATA RACES CAN MAKE THE COUNTER VALUE INCORRECT. AN INCORRECT COUNTER CAN CAUSE BILLING ERRORS AND FINANCIAL LOSS.
>
> *Principles applied: P7 (no technical noun as verb: "race" is a noun here), P3 (make → cause). Risk traces from data race to financial loss.*

```go
// WARNING: TWO GOROUTINES CAN WRITE TO THE `counter` VARIABLE AT THE SAME
// TIME. CONCURRENT WRITES TO A GO VARIABLE WITHOUT A MUTEX CAUSE A DATA
// RACE. DATA RACES CAN MAKE THE COUNTER VALUE INCORRECT. AN INCORRECT
// COUNTER CAN CAUSE BILLING ERRORS AND FINANCIAL LOSS.
var counter int
var mu sync.Mutex

func increment() {
    mu.Lock()
    defer mu.Unlock()
    counter++ // protected: no data race
}
```

> **Non-STE:** CAUTION: DO NOT SKIP MIGRATIONS.
>
> **STE:** CAUTION: DO NOT SKIP DATABASE MIGRATIONS. EACH PENDING MIGRATION CAN ADD, REMOVE, OR CHANGE COLUMNS. IF THE APPLICATION STARTS WITHOUT APPLYING ALL MIGRATIONS, THE APPLICATION SCHEMA DOES NOT MATCH THE DATABASE SCHEMA. SCHEMA MISMATCHES CAN CAUSE QUERY FAILURES, SILENT DATA LOSS, AND APPLICATION CRASHES.
>
> *Principles applied: P1 (skip → skip), P4 (approved adjective: pending). Risk traces from skipped migration to crashes.*

```sql
-- CAUTION: DO NOT SKIP DATABASE MIGRATIONS.
-- EACH PENDING MIGRATION CAN ADD, REMOVE, OR CHANGE COLUMNS.
-- IF THE APPLICATION STARTS WITHOUT APPLYING ALL MIGRATIONS, THE
-- APPLICATION SCHEMA DOES NOT MATCH THE DATABASE SCHEMA. SCHEMA
-- MISMATCHES CAN CAUSE QUERY FAILURES, SILENT DATA LOSS, AND CRASHES.
--
-- Run this before you start the application after a deploy:
--   alembic upgrade head
SELECT version_num FROM alembic_version;
```

> **Non-STE:** WARNING: HARDCODED SECRETS.
>
> **STE:** WARNING: THE CONFIGURATION FILE CONTAINS HARDCODED SECRETS. HARDCODED SECRETS BECOME PART OF THE SOURCE CODE HISTORY. ANY PERSON WITH ACCESS TO THE REPOSITORY CAN READ THE SECRETS. AN ATTACKER WITH REPOSITORY ACCESS CAN USE THE SECRETS TO ACCESS PRODUCTION SYSTEMS, DATABASES, AND THIRD-PARTY SERVICES.
>
> *Principles applied: P5 (secrets as technical noun), P3 (part of → become part of). Risk traces from hardcoded secrets to full infrastructure access.*

```yaml
# WARNING: THE CONFIGURATION FILE CONTAINS HARDCODED SECRETS.
# HARDCODED SECRETS BECOME PART OF THE SOURCE CODE HISTORY. ANY PERSON
# WITH ACCESS TO THE REPOSITORY CAN READ THE SECRETS. AN ATTACKER WITH
# REPOSITORY ACCESS CAN USE THE SECRETS TO ACCESS PRODUCTION SYSTEMS,
# DATABASES, AND THIRD-PARTY SERVICES.
#
# Replace the literal value with ${DATABASE_PASSWORD} and load it from
# the secret store. Then rotate the exposed password and remove the file
# from history with `git filter-repo`.
database:
  password: "s3cr3t-password"   # remove this line
```

## Edge Cases

**When a framework name is also an "unapproved" word.** Some framework names overlap with everyday English words that STE restricts. For example, the React framework `Suspense` is both a technical noun and an ordinary English word. A warning that says "DO NOT NEST SUSPENSE BOUNDARIES" could confuse readers who interpret Suspense as an emotion, not a component. The risk explanation must anchor the word in its technical meaning: "IF YOU NEST `Suspense` COMPONENTS, THE INNER SUSPENSE BOUNDARY CAN CAPTURE THE FALLBACK OF THE OUTER BOUNDARY. CAPTURED FALLBACKS CAN CAUSE INFINITE LOADING STATES AND UNRESPONSIVE PAGES." The code-formatted backticks and the repeated technical context disambiguate the term.

```jsx
// CAUTION: DO NOT NEST `Suspense` COMPONENTS.
// IF YOU NEST `Suspense` COMPONENTS, THE INNER SUSPENSE BOUNDARY CAN
// CAPTURE THE FALLBACK OF THE OUTER BOUNDARY. CAPTURED FALLBACKS CAN
// CAUSE INFINITE LOADING STATES AND UNRESPONSIVE PAGES.
function Page() {
  return (
    <Suspense fallback={<Spinner />}>
      <Suspense fallback={<Spinner />}>  {/* nested: captures fallback */}
        <Comments />
      </Suspense>
    </Suspense>
  );
}
```

**When a code keyword conflicts with the rule.** Keywords like `break`, `continue`, `return`, and `throw` carry control-flow meaning that risk explanations must address precisely. A warning that says "DO NOT USE `return` INSIDE A `finally` BLOCK" must explain the interaction: "IF YOU USE `return` IN A `finally` BLOCK, THE `return` REPLACES ANY EXCEPTION THAT WAS THROWN IN THE `try` BLOCK. THE REPLACED EXCEPTION IS LOST AND CANNOT BE CAUGHT BY CALLERS. SILENTLY LOST EXCEPTIONS CAN HIDE ERRORS THAT CAUSE INCORRECT PROGRAM BEHAVIOR." The risk explanation addresses the language-level semantic collision, not the word itself.

```java
// CAUTION: DO NOT USE `return` INSIDE A `finally` BLOCK.
// IF YOU USE `return` IN A `finally` BLOCK, THE `return` REPLACES ANY
// EXCEPTION THAT WAS THROWN IN THE `try` BLOCK. THE REPLACED EXCEPTION IS
// LOST AND CANNOT BE CAUGHT BY CALLERS. SILENTLY LOST EXCEPTIONS CAN HIDE
// ERRORS THAT CAUSE INCORRECT PROGRAM BEHAVIOR.
try {
  doWork();
} finally {
  cleanup();
  // return result;  // removes any exception from doWork()
}
```

**When the rule should be relaxed for generated code.** Generated code (protobuf stubs, OpenAPI clients, database ORM models) often contains instructions that violate Rule 7.3 because the generator produces terse, repetitive output. A generated file comment that says "DO NOT EDIT" without explanation is acceptable only if a companion document or the code generator's documentation explains the risk. If the generated code is the sole artifact the developer sees, the risk must still be explained: "DO NOT EDIT THIS FILE. THIS FILE IS REGENERATED EACH TIME YOU RUN `make generate`. IF YOU EDIT THE FILE, YOUR CHANGES ARE LOST THE NEXT TIME `make generate` RUNS. LOST CHANGES CAN CAUSE BUILD FAILURES AND REGRESSION BUGS."

```go
// Code generated by protoc-gen-go. DO NOT EDIT.
// DO NOT EDIT THIS FILE. THIS FILE IS REGENERATED EACH TIME YOU RUN
// `make generate`. IF YOU EDIT THE FILE, YOUR CHANGES ARE LOST THE NEXT
// TIME `make generate` RUNS. LOST CHANGES CAN CAUSE BUILD FAILURES AND
// REGRESSION BUGS.
package pb
```

**When the risk is probabilistic, not guaranteed.** Many software risks are not deterministic: a race condition may manifest only under load, a memory leak may exhaust resources only after days. Rule 7.3 still applies. Use "can" instead of "will" for probabilistic risks: "IF TWO THREADS WRITE TO THE MAP AT THE SAME TIME, A DATA RACE CAN OCCUR. THE DATA RACE CAN CAUSE INCORRECT MAP CONTENTS. INCORRECT MAP CONTENTS CAN CAUSE WRONG QUERY RESULTS AND SILENT DATA CORRUPTION." The word "can" communicates uncertainty without diminishing the severity.

```java
// CAUTION: THE CACHE IS NOT THREAD-SAFE.
// IF TWO THREADS WRITE TO THE MAP AT THE SAME TIME, A DATA RACE CAN OCCUR.
// THE DATA RACE CAN CAUSE INCORRECT MAP CONTENTS. INCORRECT MAP CONTENTS
// CAN CAUSE WRONG QUERY RESULTS AND SILENT DATA CORRUPTION.
// (A race may not happen on every run. Under load, it can.)
Map<String, Object> cache = new HashMap<>();
```

**When multiple risks share one instruction.** A single "DO NOT" instruction may prevent several different problems. List the risks in order of severity, from most severe to least severe: "DO NOT DISABLE TLS VERIFICATION. WITHOUT TLS VERIFICATION, A MAN-IN-THE-MIDDLE ATTACKER CAN DECRYPT AND CHANGE THE TRAFFIC. CHANGED TRAFFIC CAN CAUSE DATA THEFT, CREDENTIAL LEAKAGE, AND UNAUTHORIZED TRANSACTIONS." Each risk is a separate "can cause" clause that builds the cumulative case for the instruction.

```python
# WARNING: DO NOT DISABLE TLS VERIFICATION.
# WITHOUT TLS VERIFICATION, A MAN-IN-THE-MIDDLE ATTACKER CAN DECRYPT AND
# CHANGE THE TRAFFIC. CHANGED TRAFFIC CAN CAUSE DATA THEFT, CREDENTIAL
# LEAKAGE, AND UNAUTHORIZED TRANSACTIONS.
import urllib3
urllib3.disable_warnings()  # remove this line
```

**When the risk is a cascading chain with no single owner.** Distributed systems failures often involve emergent behavior where no single component is at fault. A warning about removing a circuit breaker must explain the cascading effect across services: "IF YOU REMOVE THE CIRCUIT BREAKER FROM THE PAYMENT SERVICE, A SLOWDOWN IN THE INVENTORY SERVICE CAN PROPAGATE TO THE PAYMENT SERVICE. THE PROPAGATED SLOWDOWN CAN CAUSE TIMEOUTS IN THE ORDER SERVICE. ORDER SERVICE TIMEOUTS CAN CAUSE CUSTOMERS TO PLACE DUPLICATE ORDERS. DUPLICATE ORDERS CAN CAUSE INCORRECT CHARGES AND FINANCIAL LOSS." The risk explanation traces the chain across three services without blaming any single component.

```yaml
# WARNING: DO NOT REMOVE THE CIRCUIT BREAKER FROM THE PAYMENT SERVICE.
# IF YOU REMOVE THE CIRCUIT BREAKER, A SLOWDOWN IN THE INVENTORY SERVICE
# CAN PROPAGATE TO THE PAYMENT SERVICE. THE PROPAGATED SLOWDOWN CAN CAUSE
# TIMEOUTS IN THE ORDER SERVICE. ORDER SERVICE TIMEOUTS CAN CAUSE
# CUSTOMERS TO PLACE DUPLICATE ORDERS. DUPLICATE ORDERS CAN CAUSE
# INCORRECT CHARGES AND FINANCIAL LOSS.
payment_service:
  circuit_breaker:
    enabled: true   # keep true
```

**When the risk affects a different team than the reader.** In large organizations, the person who reads the documentation is often not the person who suffers the consequence. An infrastructure engineer reading an application warning may not feel the urgency. The risk explanation must bridge the organizational gap: "DO NOT DEPLOY WITHOUT CONTACTING THE DATABASE TEAM FIRST. THE DATABASE TEAM MUST LOCK THE SCHEMA BEFORE DEPLOYMENT. IF YOU DEPLOY WITHOUT A SCHEMA LOCK, THE MIGRATION CAN CONFLICT WITH ANOTHER DEPLOYMENT. SCHEMA CONFLICTS CAN CAUSE DATA CORRUPTION THAT AFFECTS ALL TEAMS USING THE DATABASE." The phrase "affects all teams using the database" connects the reader's action to consequences beyond their immediate team.

```markdown
## Deploy Checklist

WARNING: DO NOT DEPLOY WITHOUT CONTACTING THE DATABASE TEAM FIRST.
THE DATABASE TEAM MUST LOCK THE SCHEMA BEFORE DEPLOYMENT.
IF YOU DEPLOY WITHOUT A SCHEMA LOCK, THE MIGRATION CAN CONFLICT WITH
ANOTHER DEPLOYMENT. SCHEMA CONFLICTS CAN CAUSE DATA CORRUPTION THAT
AFFECTS ALL TEAMS USING THE DATABASE.

Open the #db-deploys channel and request a lock before you run the
migration. Wait for the lock confirmation before you continue.
```

## Cross-References

- **Rule 1.1 (Use approved words):** The words in your risk explanation must come from the STE-Code dictionary. See the Canonical Synonym Table for substitutes (for example, replace non-approved verbs with their approved general-purpose equivalents such as use, set, check, make, get, remove, keep).
- **Rule 1.6 (Non-approved words only as technical nouns):** When a risk explanation must include a non-approved word (for example, `deadlock`, `thrashing`, `replay attack`), present it as a technical code noun and define it on first use.
- **Rule 1.10 (No slang, jargon, or regional terms):** A risk explanation that says "this will brick your deployment" fails Rule 1.10 and Rule 7.3 simultaneously. Replace "brick" with the specific consequence: "THIS WILL MAKE THE DEPLOYMENT PERMANENTLY UNAVAILABLE."
- **Rule 7.1 (Use clear, specific safety signal words):** The signal word (WARNING or CAUTION) sets the severity level. Rule 7.3 connects the signal word to the concrete consequence. A WARNING demands a risk of injury or data loss. A CAUTION demands a risk of incorrect results or system damage.
- **Rule 7.2 (Place safety instructions before the related step):** The instruction must come before the risky action. The risk explanation in Rule 7.3 comes immediately after the instruction, before the reader proceeds. The order is: signal word → instruction → risk explanation → action.
- **Rule 7.4 (Use imperative mood for instructions):** The instruction part of a Rule 7.3 warning must use imperative mood ("DO NOT USE"), not descriptive ("using this is not recommended"). The risk explanation part may use declarative mood to state the consequence.
- **Section 1 (Words):** All words in risk explanations follow the noun-verb-adjective rules of Section 1. A risk sentence like "This initiates a cascade failure" violates Rule 1.2 (initiate → start) and Rule 1.3 (cascade as unapproved modifier). The STE version: "This can start a sequence of failures."

> **See also:** Rule 7.1 — Use an Applicable Word (for Example, "Warning" or "Caution") to Identify the Level of Risk; Rule 7.2 — Start a Safety Instruction with a Clear and Accurate Command or Condition; Rule 7.4 — Use Imperative Mood for Instructions

## Grammar Notes

The original ASD-STE100 Rule 7.3 carries grammatical justification that adapts directly to code documentation.

**Causal connective "IF...THEN" structure.** The original spec uses "IF THEY FALL, PERMANENT DAMAGE TO THE PARTS CAN OCCUR." The "IF" clause states the violation (not obeying the instruction). The main clause states the consequence. This structure is mandatory for risk explanations in code documentation. Always state the violation first, then the consequence. Do not reverse the order: "PERMANENT DATA LOSS CAN OCCUR IF YOU DO NOT SET THE TIMEOUT" is grammatically correct but less effective because the reader processes the gravity before knowing the cause. The STE pattern puts cause before effect so the reader follows the logical chain.

**Modal verb "can" versus "will."** Use "can" for risks that are possible but not certain. Use "will" only for risks that are guaranteed. "A data race can cause incorrect results" (possible). "A build will fail if a required dependency is not declared" (guaranteed). Never use "may" — it introduces ambiguity about permission versus possibility, and STE restricts "may" to permission contexts only. Never use "might" — it is less direct than "can" and is listed as an unapproved word in the STE dictionary.

**Active voice in risk explanations.** The subject of a risk sentence must be the thing that causes harm, not an abstract noun. "Data loss can occur" identifies the concrete harm. "There can be a loss of data" is passive and indirect. The active form makes the risk tangible. For systemic risks where no single agent exists, use the system or component as the subject: "The database can reject inconsistent writes." "Inconsistent writes can be rejected" is passive and hides the agent.

**Article usage in risk statements.** Do not omit articles from risk explanations. "Buffer overflow can cause crash" is incorrect. Write: "A buffer overflow can cause a crash." The indefinite article "a" before "buffer overflow" establishes that any single overflow triggers the risk. The indefinite article before "crash" establishes the type of failure. Omitting articles makes the risk sound like a headline, not an explanation.

**Sentence length constraint.** Risk explanations can chain consequences, but each link in the chain must stay within the 20-word procedural limit. Break long causal chains into separate sentences: "WITHOUT A TIMEOUT, THE CONNECTION CAN HANG FOREVER. A HANGING CONNECTION CAN USE ALL AVAILABLE THREADS. EXHAUSTED THREADS CAN CAUSE THE SERVER TO REJECT NEW REQUESTS." Each sentence states one causal link. The cumulative effect is a multi-step risk chain that the reader can process incrementally.

**Avoid "ing" forms as main verbs in risk explanations.** Do not write: "Not setting the timeout causing the connection to hang." Write: "If you do not set the timeout, the connection can hang." The "-ing" form "causing" is a participle, not a main verb. The risk explanation requires a finite verb ("can hang") to form a complete clause that assigns the consequence to the violation.

**Avoid semicolons and nested clauses.** The causal relationship between violation and consequence must not depend on semicolons or deeply nested subordinate clauses. Write two simple sentences joined by the logical chain: "If you skip the migration, the schema does not match. A schema mismatch can cause query failures." Do not write: "If you skip the migration, which creates a schema mismatch that can cause query failures, the deployment will fail." The nested version buries the risk chain and exceeds the 2-level clause depth limit.

**Definite versus indefinite articles in multi-risk chains.** When a risk chain involves a series of consequences, use the indefinite article "a" for the first mention of each consequence and the definite article "the" for subsequent references to the same consequence: "An unhandled promise rejection can cause a memory leak. The memory leak can cause the process to use more memory over time." The shift from "a" to "the" signals to the reader that "the memory leak" refers back to the consequence just introduced. Do not use "this" as a determiner in risk chains ("This memory leak can cause...") — STE treats "this" without an explicit noun as potentially ambiguous. Always pair "this" with the noun it modifies: "This type of memory leak."

**Imperative versus declarative mood in compound warnings.** A complete Rule 7.3 instruction has two grammatical moods. The instruction is imperative: "DO NOT DISABLE TLS VERIFICATION." The risk explanation is declarative: "Without TLS verification, an attacker can decrypt the traffic." Do not mix moods within a single sentence. Do not write: "Do not disable TLS verification because an attacker can decrypt the traffic." The conjunction "because" weakens the imperative by making the instruction sound like a suggestion. Use a period and start a new sentence for the risk explanation. The pause between the command and the consequence gives the reader a moment to register the instruction before processing its justification.

## Practical Application

Apply Rule 7.3 during documentation review with this checklist:

1. Find every WARNING and CAUTION in the document.
2. For each, ask: "What happens if the reader ignores this?"
3. If the answer is not written after the instruction, add it.
4. Check that the risk explanation uses "can" (probabilistic) or "will" (guaranteed) correctly.
5. Verify the risk matches the signal word severity (WARNING = data loss/security, CAUTION = incorrect results/build failures).
6. Confirm the risk chain reads cause-first: "If you do X, Y can happen." Not effect-first: "Y can happen if you do X."
7. Break any risk explanation over 20 words into separate causal-link sentences.
8. Replace any "-ing" participles with finite verbs ("causing" → "can cause").
9. Replace "may" and "might" with "can" or "will."
10. Check that technical nouns in code formatting are defined on first use in the risk chain.

A document where every safety instruction carries a clear, specific risk explanation is a document developers trust. A document where instructions carry unexplained prohibitions is a document developers ignore. The difference is Rule 7.3.

---

<!-- rules-sec8.md -->

# Level 5 — Punctuation and Word Count (Section 8)

Section 8 of STE-Code governs punctuation and word-count mechanics in code
documentation. It contains seven rules: 8.1 (no semicolon), 8.2 (hyphens),
8.3 (parentheses usage), 8.4 (colon in vertical lists), 8.5 (parentheses and
word count), 8.6 (elements that count as one word), and 8.7 (hyphenated words
count as one word).

This is the full-standard (Level 5) slice. Use it when an LLM generates or
revises code documentation: README files, API reference docs, docstrings, inline
comments, commit messages, error messages, configuration comments, and
specification documents. All guidance below is faithful to the STE-Code
standard and uses code-domain examples only.

Quick reference — the seven rules:

- 8.1 No semicolon (;) in documentation prose.
- 8.2 Hyphenate directly related words (compound adjectives / technical nouns).
- 8.3 Parentheses: references, abbreviations, item IDs, alternatives, singular/plural, explanations.
- 8.4 A colon before a vertical list acts as a period (sentence boundary) with word-count limits.
- 8.5 Parenthetical text counts as one word in the enclosing sentence but is its own separate sentence.
- 8.6 Numbers, units, abbreviations, identifiers, quoted text, titles/labels, and proper nouns each count as one word.
- 8.7 A hyphenated word group counts as one word.

## Rule 8.1 — No semicolon (;)

You may use all standard English punctuation marks in code documentation except
the semicolon (;). The semicolon is forbidden because it lets you pack two
independent clauses into one sentence, which is hard to read — especially for
non-native English readers — and because the semicolon is a statement terminator
in many languages (C, C++, Java, JavaScript, Rust, Go), causing cognitive
interference in documentation prose.

Fix every violation the same way: split the semicolon-separated sentence into two
or more independent sentences. Each new sentence stands alone with its own
subject and verb. This aligns with Rule 3.1 (simple sentences) and Rule 4.1
(short sentences).

Applies to: README, API reference docs, docstrings, inline comments, commit
messages, error messages, configuration comments, and specification documents.
Does NOT apply to source code (where the semicolon is syntax) or to code shown
inside code blocks / inline backticks.

### Examples

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

Non-STE: The cache is invalid after a write operation; you must flush it before the next read.
STE:    The cache is invalid after a write operation. You must flush it before the next read.

Non-STE: The server supports WebSocket connections; these use a persistent channel instead of the standard request-response cycle.
STE:    The server supports WebSocket connections. These connections use a persistent channel instead of the standard request-response cycle.

Non-STE: POST /sessions creates a new session and returns a token; the token must be included in the Authorization header of subsequent requests.
STE:    A POST request to /sessions makes a new session and returns a token. You must include the token in the Authorization header of all later requests.

Non-STE: Invalid port number; specify a value between 1024 and 65535.
STE:    The port number is not valid. Specify a value between 1024 and 65535.

Non-STE: The authentication middleware now checks token expiry before decoding; expired tokens return a 401 before reaching the route handler.
STE:    The authentication middleware now checks token expiry before decoding. Expired tokens return a 401 status code before they reach the route handler.

### Paradigm notes
- Object-oriented: split constructor initialization from post-condition; for getter/setter pairs, write each method's description as its own sentence.
- Functional: describe the happy path as one sentence, the error path as a second sentence. Do not reinforce the `|>` / `>>` / `.` pipe with a semicolon in prose.
- Procedural (C, Go, Bash): write each step as its own sentence; use "then" at the start of the second sentence for tight sequences.
- Declarative (SQL, Terraform, Kubernetes): write each property and each effect as its own sentence.
- Systems (Rust ownership, C memory): write the safety rule as one sentence and the consequence as a second sentence introduced with "thus" or "as a result." For Undefined Behavior, never use a semicolon — the consequence must be a standalone sentence.

### Edge cases
1. Semicolons inside code blocks / inline backticks are language syntax, not prose. Keep them. The rule governs surrounding prose only.
2. Generator-inserted semicolons in auto-generated docs (OpenAPI, JSDoc, protobuf) are not your violation; apply 8.1 to the source comments you author.
3. Semicolons inside quoted strings (error output, logs) are quoted material — keep them; prose around must obey 8.1.
4. Do not use a semicolon as a "super-comma" in a complex list. Use a bullet list or table instead.
5. Chat / informal PR-thread messages: 8.1 is optional. Commit messages are permanent history and must follow 8.1.
6. A semicolon inside a regex, CSV row, or data string is data, not prose — keep it in the code span.

### Cross-references
Rule 1.1 (approved words for connecting clauses), Rule 3.1 (simple sentences),
Rule 4.1 (short sentences), Rule 4.4 (connecting words replace the semicolon),
Rule 8.2 (hyphen versus semicolon).

## Rule 8.2 — Use hyphens (-) to connect directly related words

Use a hyphen to connect two or more words that function as one concept, most
often a compound adjective before a noun. The hyphen signals to the reader that
the words form a single unit and removes ambiguity about which word modifies
which. A hyphen joins words; a semicolon/colon joins clauses. Keep the two
distinct.

The five code-domain hyphenation categories:

1. Compound adjectives before a noun: high-priority task, read-only file,
   thread-safe method, event-driven architecture, type-safe interface,
   run-time error, end-to-end test, point-to-point connection,
   server-side rendering, client-side validation, just-in-time compilation,
   fire-and-forget pattern.
2. Two-word fractions / numbers: seventy-two, three-fourths, one hundred and
   sixty-two.
3. Uppercase-or-number + noun giving shape/configuration: L-shaped bracket,
   T-shaped connector, 64-bit register, 8-byte alignment, 128-bit value,
   3-prong connector.
4. Verbs whose first part is a noun or different part of speech: dry-run,
   hot-reload, cold-start, hard-code, soft-delete, short-circuit.
5. Prefix ending in a vowel + root starting with a vowel: pre-initialized,
   re-entrant, de-allocated, anti-aliasing, re-indexed.

### Examples

Non-STE: The high priority task must acquire the write lock before it can modify the shared data structure.
STE:    The high-priority task must get the write lock before it can change the shared data structure.

Non-STE: A read only file descriptor to open the configuration for parsing.
STE:    A read-only file descriptor to open the configuration for parsing.

Non-STE: A non negative integer that sets the buffer size. / A read only reference to the internal cache.
STE:    A non-negative integer that sets the buffer size. / A read-only reference to the internal cache.

Non-STE: The thread safe singleton uses lazy initialization to defer object creation until the first access.
STE:    The thread-safe singleton uses lazy initialization to defer object creation until the first access.

Non-STE: The left joined table uses a fully qualified column name from the user provided input.
STE:    The left-joined table uses a fully-qualified column name from the user-provided input.

Non-STE: The memory mapped file uses a copy on write page that is atomically reference counted.
STE:    The memory-mapped file uses a copy-on-write page that is atomically-reference-counted.

### Paradigm key terms
- OO: read-only property, write-only field, lazy-initialized singleton, reference-counted pointer, thread-safe collection, lock-free algorithm.
- Functional: pure-function semantics, side-effect-free computation, higher-order function, copy-on-write map, lazily-evaluated sequence, lock-free CAS loop.
- Procedural: null-terminated string, zero-initialized struct, stack-allocated array, const-qualified parameter, short-circuit evaluation, newline-delimited output.
- Declarative: left-joined table, fully-qualified column name, read-only attribute, base64-encoded value, cluster-scoped resource, blue-green deployment.
- Systems: move-semantics transfer, borrow-checked reference, memory-mapped I/O, copy-on-write page, lock-free stack, use-after-free bug.

### Edge cases
1. Keep hyphenated tool/library names as-is (create-react-app). Do not add a second hyphen (correct: "the create-react-app template"; wrong: "create-react-app-template").
2. In prose, hyphenate code keywords used as compound adjectives ("the type-of operator", "a full-outer-join operation"); in code spans, reproduce exactly (`typeof x`, `FULL OUTER JOIN`).
3. Leave generated output as-is; add a NOTE in surrounding prose if the generator omits hyphens.
4. An established unhyphenated compound (codebase, filename, namespace) may stay if it is unambiguous and consistent project-wide; otherwise hyphenate.
5. API endpoints / URL paths use kebab-case as proper nouns — keep hyphens in the path (`/api/read-only-access`); prose hyphenation follows 8.2 separately.

### Grammar notes
- Attributive (before noun) takes a hyphen; predicative (after a linking verb) does not: "the thread-safe collection" vs "the collection is thread safe."
- Adverbs ending in "-ly" do NOT take a hyphen: "a fully qualified name", not "fully-qualified".
- "self-" prefix always takes a hyphen (self-contained, self-signed).
- Do not insert hyphens into code identifiers (`getUserProfile`, not "get-user-profile"); use the identifier verbatim in backticks.

### Cross-references
Rule 1.1 (approved words), Rule 1.5 (technical nouns as first element),
Rule 1.9 (shorten long compounds), Rule 1.11 (consistent form), Rule 8.1,
Rule 8.6 (hyphenated term counts as one word), Rule 8.7.

## Rule 8.3 — Use of parentheses

You may use parentheses in code documentation for seven purposes:

1. References to modules, diagrams, or text: "Call the request handler (Figure 3, Module A)." / "Deploy the service (refer to sections 2 thru 5)."
2. Letters or numbers that identify diagram or text items: "Disconnect the endpoints (2) and (12) from the load balancer (8)."
3. Work-step identification in a procedure: "(1) Install the dependency package (4) in the project directory (8)."
4. Abbreviations, placed immediately after the full term: "A Command Line Interface (CLI) is a text-based interface…"
5. Singular and plural at once: "Before you run the test(s), set the environment variable(s)."
6. Explanations of words or part of a sentence: "Increase the timeout slowly (not more than 1000 ms each step)."
7. An alternative: "Use the left (right) API key for the staging (production) environment."

Square brackets [ ] are reserved for optional parameters in code syntax. Parentheses are the only permitted brackets for parenthetical information in prose. Do not use commas before an opening parenthesis except when the parenthetical is an alternative at the end of a list.

### Examples by doc type

README: This project provides a Command Line Interface (CLI) for managing your deployment pipeline. Follow the setup guide (refer to docs/getting-started.md) before you run the server.

API docs: The timeout parameter accepts an integer in milliseconds (ms). To use seconds, set the unit flag to "s" (available in version 2.1 and later). If the request fails, the server returns a 404 (Not Found) status.

Docstrings: timeout: milliseconds to wait (1 to 30000). / "Calculate the factorial of n (a non-negative integer)."

Commit messages: feat(auth): add PKCE support (issue #482). / fix(ui): correct z-index conflict between dropdown and modal (regression from v2.3).

Error messages: Cannot find the configuration file (searched: /etc/myapp/config.yaml, ~/.config/myapp/config.yaml, ./config.yaml). / Invalid value for --workers: 0 (valid range: 1 to 64).

### Paradigm notes
- OO: parentheses show method parameters, constructors, type parameters; "the `process` method (inherited from `BasePipeline`, which implements `core.Pipeline`)". Default values in tables: "milliseconds to wait before failure (default: 5000)."
- Functional: group type parameters; "the `State` monad passes an immutable state value… Use `StateT` (the transformer variant) to combine it with another monad."
- Procedural: return codes — "0 (success), -1 (I/O error), -2 (malformed input), -3 (timeout)"; ownership — "the caller must free the returned buffer (allocated by this function)."
- Declarative: enumeration values — "set the `provider` field to one of: "aws", "gcp", "azure" (lowercase only)"; "set `replicas` to the number of pod copies (range: 1 to 100, production minimum: 1)."
- Systems: ownership transfer — "this function takes ownership of the value (the caller cannot use it after the call)"; SAFETY invariants — "(invariant enforced by caller)."

### Edge cases
1. Framework/library names that are common words: clarify with a parenthetical on first use — "Use Flask (the Python web framework)…", "React (a JavaScript UI library)…".
2. Code keywords that are punctuation (Rust `()`, `<T>`): keep code literals distinct; explain in a separate sentence, do not nest.
3. Auto-generated docs (JSDoc, Sphinx, rustdoc): leave generated signatures untouched; apply 8.3 to human-written description fields.
4. Never nest parentheses. Restructure or split: "Set the cache TTL to 3600 (one hour). For production, set the cache TTL to 86400 (one day)." / "JWT is an abbreviation for JSON Web Token."
5. CLI help text: use parentheses sparingly — alternative or explanation patterns only; long descriptions belong in a man page.

### Cross-references
Rule 1.1 (abbreviation words), Rule 1.3 (approved meanings in explanations),
Rule 1.9 (short technical nouns), Rule 5.1 (parenthetical counts toward sentence
length), Rule 6.3 (one step per numbered line), Rule 8.2 (hyphens are not
parentheses). Period goes outside the closing parenthesis unless the
parenthetical is a complete sentence (then it becomes its own sentence).

## Rule 8.4 — Colon in a vertical list

In a vertical list, the colon (:) before the list acts as a period (full stop).
The introductory text before the colon is a complete sentence and must obey the
sentence-length limits: maximum 20 words for procedural text, 25 words for
descriptive text. Each list item after the colon is a new sentence with its own
limit (20 procedural / 25 descriptive).

The colon always ends the introductory sentence. Enumerated items must be
vertical (bullets or numbered), never inline. Em-dashes are not a substitute;
only the colon introduces a vertical list.

### Examples

Non-STE: To handle all possible error conditions, the following exception types must be caught and processed by the error handler: database connection timeouts which occur when the primary node is unreachable, authentication failures caused by expired or invalid tokens, and validation errors due to malformed request payloads.
STE:
To handle possible error conditions, the error handler catches these exception types:
- Database connection timeout
- Authentication failure
- Validation error.

Non-STE: ...supports these environment profiles that you can use for deployment: a development profile for local testing..., a staging profile..., and a production profile...
STE:
The configuration file supports these environment profiles:
- Development
- Staging
- Production.

Non-STE: A successful request to the GET /users/{id} endpoint returns a JSON response body that contains the following fields which describe the user account...: an id field..., a username field..., an email field..., a created_at field..., and a status field...
STE:
A GET request to /users/{id} returns a JSON response with these fields:
- `id` — The unique user identifier (UUID string)
- `username` — The display name
- `email` — The verified email address
- `created_at` — The account creation timestamp (ISO 8601)
- `status` — The account status (`active`, `suspended`, or `pending_verification`).

### Guidance by doc type
- README: keep the introduction to the category only; move version numbers, caveats, and compatibility notes into list items or a prior sentence.
- API docs: name the endpoint/resource and what the list enumerates; put type, default, and validation in each item (Args:/Returns:/Raises: sections align naturally).
- Docstrings: "This function handles these edge cases: - Empty input strings - Input with only whitespace…".
- Commit messages: the subject line is a standalone summary, not a list introduction; the body's intro must be short.
- Error messages: use a short intro ("The database migration failed for one of these reasons:") then one item per cause or recovery step.

### Paradigm notes
- OO: "The ConnectionPool constructor accepts these arguments: - url — A valid JDBC connection string… - maxConnections — The largest number of concurrent connections."
- Functional: "The ParseResult enum represents the result of parsing a configuration file. The enum has these variants: - Ok(Config) — … - Err(ParseError::Io) — …"
- Procedural: state the goal, then imperative steps — "Make sure that Go 1.21 or later is installed. … Then do these steps: - Clone the repository. - Run `go mod download`."
- Declarative: "The instance_type variable sets the EC2 instance size. The variable accepts these values: - t3.micro - t3.small - t3.medium." Put exclusions in a NOTE after the list.
- Systems: enumerate every precondition as its own bulleted item — "The caller must obey these safety conditions: - The pointer must not be null. - The pointer must be aligned to a 4-byte boundary. - …"

### Edge cases
1. Code tokens in backticks inside the introduction count as one word each, but prefer introductions with few code tokens and fewer than 15 total words.
2. Limit nested lists to one level; the parent item is a short category heading with its own colon.
3. A code block inside a list item is exempt from word count; keep the surrounding prose short.
4. Long framework/resource names belong in the list items, not the introduction.
5. Generator-produced colon-lists (OpenAPI, `--help`): obey 8.4 in source comments; accept the generator's boilerplate.

### Cross-references
Rule 1.1 (approved words in items), Rule 3.1 (one subject-verb-object per item),
Rule 3.3 (lists satisfy paragraph brevity), Rule 4.1 (limits apply at two
points: intro and each item), Rule 6.3 (procedural lists), Rule 8.1 (the colon
replaces semicolon-joined enumerations). The colon before a vertical list is the
approved replacement for semicolon-joined clause lists.

## Rule 8.5 — Parentheses and word count

When you put text in parentheses, it counts as ONE WORD in the enclosing
sentence. But the words inside the parentheses also form a separate sentence
with its own word-count limit (20 procedural / 25 descriptive). An identifier in
parentheses (a number, letter, or alphanumeric identifier) and an abbreviation
in parentheses each count as one word and do not need to obey the sentence-length
limit, because they are not prose.

Two types of parentheticals:
- Identifier parentheticals: (10), (EACCES), (CI/CD), (v2.1) — one word, no sentence limit.
- Explanatory parentheticals: (the DEBUG flag is off), (the worker runs every 60 seconds) — one word in the main sentence, but a complete separate sentence that must obey the limit.

Do not use parentheses to hide safety conditions, required steps, or warnings
the reader must act on. If the information is important enough to include, it is
important enough to be a main sentence.

### Examples

Non-STE: Make sure that the DEBUG environment variable is set to false before you run the deployment script in the production cluster (the DEBUG flag must be explicitly disabled for all production workloads to prevent accidental log leakage).
STE:    Make sure that the DEBUG environment variable is set to false (the DEBUG flag is off).

Non-STE: Remove the health check flag number ten from the deployment configuration.
STE:    Remove the health check flag (10).

Non-STE: Installation and Configuration of a Continuous Integration and Continuous Deployment Pipeline for the Application
STE:    Configuration of a Continuous Integration/Continuous Deployment (CI/CD) Pipeline

Non-STE: The timeout parameter sets the request timeout in seconds (this parameter is optional and defaults to 30 if not provided, but if you set retries greater than zero you should increase the timeout accordingly to account for the cumulative wait time across all retry attempts).
STE:    The timeout parameter sets the request timeout in seconds. The default value is 30. This parameter is optional. NOTE: If you set retries to a value larger than zero, increase the timeout to account for the cumulative wait time.

### Guidance by doc type
- README: do not bury conditional instructions in parentheses; split long asides into their own sentences.
- API docs: identifiers (200, 404, application/json, optional) count as one word; do not embed full conditional logic in a parameter description.
- Docstrings: short parentheticals ((int, optional), (default: 30)) are fine; move algorithmic explanations out.
- Commit messages: issue refs ((#1234)), (breaking), (auth) count as one word; put justification in the body, not in parentheses.
- Error messages: keep error codes and recovery hints short ((Error code: EACCES), (try: chmod 600)); never put the whole recovery procedure in parentheses — use a list.

### Paradigm notes
- OO: (User), (abstract), (Factory pattern) are identifier parentheticals, one word each; move inheritance rationale to its own paragraph.
- Functional: (Eq a), (when x > 0), (:else) are short; move transformation-chain descriptions to a list.
- Procedural: (exit code 1), (-v), (if root) are identifier parentheticals; promote error-branch logic to separate sentences.
- Declarative: (PostgreSQL 14+), (required), (default: true) are short; move migration/back-compat history out of parentheses into a NOTE/BREAKING block.
- Systems (stricter): never put safety-critical information in parentheses. Use the main sentence or a `# Safety` section — "The caller must obey these conditions: - The pointer must be valid for writes. - …"

### Edge cases
1. Function-call notation in backticks (`authenticate()`, `parse(input)`) is one atomic word; its internal parentheses are not Rule 8.5 parentheticals.
2. A URL in parentheses is an identifier (one word); if the parenthetical adds explanatory text after the URL, that text forms a separate sentence.
3. Never nest parentheses. Use an em-dash for the inner aside or split into a sentence.
4. Library/method names with parentheses as part of the canonical spelling (`expect()`) stay in backticks and count as one word.
5. Generator-inserted parentheticals (type hints, defaults) are accepted; follow 8.5 for any you write manually.

### Cross-references
Rule 1.5 (code nouns in parentheses), Rule 1.6 (non-approved words only as
technical nouns — parentheses are not a loophole), Rule 3.1 (the parenthetical
is a sentence), Rule 3.3 (long parentheticals signal a restructure), Rule 4.1
(word limits apply to the parenthetical sentence), Rule 8.1 (a semicolon inside
a parenthetical is still forbidden), Rule 8.4 (a parenthetical can hold a nested
list).

## Rule 8.6 — Elements that count as one word

For sentence-length counting, count each of these as ONE WORD:

1. Numbers: "Do steps 13 thru 16 a minimum of three times." / "The configuration file has twenty-one keys." Do NOT count numbers that identify paragraphs or work steps (document numbering).
2. Numbers with units of measurement: "Make sure that the timeout is 10 ms." / "The payload is 20 MB." / "The latency must be 10 μs." ("10 ms" is one word).
3. Abbreviations (acronyms and initialisms): "For remote access, use the VPN." / "During this security check, obey OWASP guidelines." / "a.m." with its number is one word.
4. Alphanumeric identifiers: "Tag error code E36L7." / "Examine the No. 1 handler installation." / `user_preferences`, `ERR_PG_TIMEOUT_0099`, `OrderPaymentFailed`.
5. Quoted text: words between quotation marks, backticks, or `<code>` tags count as one word — `"Service Overview"`, `C = (A - B) - 0.063 mm` (a formula is one word), `useUserProfile(userId)`.
6. Titles, headings, and text on UI elements / labels: "refer to the Operations Runbook for the applicable safety procedures." / "refer to Error Handling and Recovery, page block 1001." / dialog warnings quoted verbatim count as one word.
7. Proper nouns of individuals, groups, organizations, and geopolitical entities: "The creator of Linux was Linus Torvalds." / "the Apache Software Foundation."

Applying 8.6 collapses many seemingly-long sentences into compliance. A README
sentence that looks like 17 words may count as 12 once "GitHub Actions" (proper
noun), "CI/CD" (abbreviation), "AWS Lambda" (proper noun), and "Serverless
Framework" (proper noun) each become one word.

### Examples

Non-STE: ...validate the signature of each incoming request using the public key obtained from the OpenID Connect identity provider, and the token must have an expiry time of not more than three hundred and sixty seconds...
STE:    The JWT authentication middleware must validate the signature of each incoming request. The token must have an expiry time of not more than 360 seconds to be valid for processing. ("JWT" = 1 word; "360 seconds" = 1 word.)

Non-STE: ...set the property called http.client.retry.max.attempts to a numeric value of five and also set the property http.client.retry.backoff.millis to a numeric value of one thousand...
STE:    In `application.properties`, set `http.client.retry.max.attempts` to 5. Set `http.client.retry.backoff.millis` to 1000. (file path = 1; each prop name = 1; "5", "1000" = 1 each.)

Non-STE: ...freeze the checkout container to two hundred and fifty millicores of CPU and five hundred and twelve mebibytes of memory...
STE:    In the Kubernetes manifest, set the `checkout` container to 250m CPU and 512Mi memory. Set the limit to 500m CPU and 1Gi memory. ("checkout" = 1; "250m CPU", "512Mi", "500m CPU", "1Gi" = 1 each.)

### Paradigm notes
- OO: class/method/interface/package names are proper nouns or identifiers (1 word each); "Abstract Factory Pattern" is one word.
- Functional: type signatures and monad stacks quoted count as one word — `validate :: Config -> Either ValidationError Config`, `ReaderT Env (ExceptT AppError IO) a`.
- Procedural: `pthread_mutex_lock(&mtx)` (quoted, 1 word), `EAGAIN` (identifier, 1 word), `context.Context` (proper noun, 1 word).
- Declarative: `users(email_address, created_at)` (quoted, 1 word), `aws_lambda_function.main` (identifier, 1 word), `readinessProbe.httpGet.path` (identifier, 1 word).
- Systems: `fn process<'a>(data: &'a [u8]) -> Cow<'a, str>` (quoted, 1 word), `0x7fff5fbff8c0` (identifier, 1 word).

### Edge cases
1. Framework names with "unapproved" words (Express, Swift, React) are proper nouns (1 word); do not rewrite them to obey word rules.
2. Code keywords quoted in docs (`class`, `return`, `async`) count as one word; do not replace them with synonyms. When used in your own prose, apply the dictionary normally.
3. Generated text you cannot change (Javadoc `@see`, auto-generated OpenAPI descriptions) counts as one word (category 6).
4. Nested quoted text: the outer backtick/`<code>` boundary defines the unit; everything inside counts as one word.
5. Semantic versions (`1.2.3-alpha.1+build.456`), Git hashes (`a1b2c3d`), image digests (`sha256:abc123...`) are alphanumeric identifiers (1 word). "Version 1.2.3" = two words ("Version" + "1.2.3").
6. Document part numbers (rule/section numbers in cross-refs, step numbers, issue IDs as references) are structural and not counted as quantities.

### Cross-references
Rule 1.1 (proper nouns/identifiers exempt from approved-word rule), Rule 1.5
(framework/library names are technical nouns and proper nouns), Rule 1.6
(non-approved words inside proper nouns/identifiers allowed), Rule 1.14
(American spelling exemptions for proper nouns), Rule 8.7 (hyphenated words also
count as one), Rule 4.1 (the 20/25 limits these counts serve).

## Rule 8.7 — Hyphenated words count as one word

A hyphenated group of words counts as ONE WORD when you count sentence length.
The hyphen joins two or more words into a single unit the reader processes as one
concept, so the 20-word (procedural) / 25-word (descriptive) limits measure the
unit as one word, not as the number of words inside it.

Two cases:

Case 1 — Hyphenated compound adjectives (attributive, before a noun):
- `read-only file descriptor` — "read-only" is one word.
- `thread-safe singleton`, `event-driven architecture`, `low-latency cache`,
  `client-side rendering pipeline`, `end-to-end test suite`,
  `backward-compatible API`.
- After a linking verb / after the noun, do NOT hyphenate and count each word:
  "The singleton is thread safe" (5 words: "thread" and "safe" are separate).

Case 2 — Long hyphenated technical nouns:
- `cutoff-switch power connection` (3 words: `cutoff-switch` / `power` / `connection`)
- `main-gear-door retraction-winch handle` (3 words: `main-gear-door` / `retraction-winch` / `handle`)
- Code-domain: `build-time environment variable` (3 words), `client-side rendering pipeline` (3 words), `end-to-end test suite` (3 words), `check-out request handler` (3 words), `sign-in error message` (3 words), `look-up table index` (3 words). Words after the hyphenated unit are separate.

### Examples

Non-STE: The open function returns a read only file descriptor.
STE:    The open function returns a read-only file descriptor. ("read-only" = 1 word)

Non-STE: To calibrate the retry interval, use the try and error method.
STE:    To calibrate the retry interval, use the trial-and-error method. ("trial-and-error" = 1 word)

Non-STE: Set the build time environment variable to the path of the staging cluster...
STE:    Set the build-time environment variable to the path of the staging cluster... ("build-time" = 1 word)

Non-STE: The client side rendering pipeline builds the page in the browser.
STE:    The client-side rendering pipeline builds the page in the browser. ("client-side" = 1 word)

Non-STE: Use a thread safe singleton for the cache.
STE:    Use a thread-safe singleton for the cache. ("thread-safe" = 1 word)

Word-count proof: "The build-time environment variable must point to the staging cluster." = 10 words. `build-time` is one word, not two.

### Interaction with other rules
- With Rule 8.2: hyphenate per 8.2, then count the hyphenated unit as one word per 8.7. ("open-source" hyphenated per 8.2; counts as one word per 8.7. "JSON" is an abbreviation, one word per 8.6.)
- With Rule 8.6: a hyphenated term is a separate case — it is not an abbreviation or identifier, but still counts as one word. Do not double-count.
- Exception: a hyphen in a spelled-out numeral (twenty-one, forty-seven) or a range (pages 10-15) is covered by Rule 8.6 (numbers count as one word), not 8.7.

### Common code-domain hyphenated terms (each = one word before a noun)

| Term | Type |
|------|------|
| read-only, write-only, thread-safe, event-driven | compound adjective |
| client-side, server-side, end-to-end, backward-compatible, low-latency | compound adjective |
| build-time, run-time, sign-in, check-out, request-response | technical noun |

When a term in this table follows the noun or a linking verb, write it as separate words and count each word.

### Cross-references
Rule 8.2 (when to use hyphens), Rule 8.6 (other one-word elements),
Rule 4.1 (sentence-length limit), Rule 4.2 (do not omit words / use contractions).

---

### How an LLM should apply Section 8 when generating code documentation
1. Never write a semicolon in prose; split into sentences (8.1).
2. Hyphenate compound adjectives before nouns; keep predicates separate (8.2, 8.7).
3. Use parentheses only for the seven allowed purposes; never nest them; never hide safety info in them (8.3, 8.5).
4. Introduce vertical lists with a short colon sentence; each item is its own sentence under 20/25 words (8.4).
5. When counting length, collapse numbers+units, abbreviations, identifiers, quoted code, titles, and proper nouns to one word each, and hyphenated groups to one word (8.6, 8.7).

---

<!-- rules-sec9.md -->

# Level 5 — Section 9: Sentence Construction & Word Usage (Rules 9.1–9.4)

This sub-document distills the four "writing-level" rules of STE-Code for use by an
LLM that generates or revises code documentation. It covers how to restructure
sentences when a word-for-word replacement fails (9.1), how to use each approved
word with its exact meaning and part of speech (9.2), why phrasal verbs are
prohibited (9.3), and why consistent terminology across a document or project is
mandatory (9.4).

These four rules sit at the top of the STE-Code writing stack. When a candidate
word is not in the controlled terminology, try a word-for-word replacement (9.2).
If no same-part-of-speech alternative keeps the meaning, restructure the sentence
(9.1). Never reach the meaning through a phrasal verb (9.3), and never vary the
term you picked (9.4).

All examples are code-domain. Code symbols (keywords, framework names, function
and variable names) are technical nouns and never change — only surrounding prose
is edited.

---

## Rule 9.1 — Restructure When a Word-for-Word Replacement Is Not Sufficient

**Core instruction.** Use a different sentence construction when you cannot replace
an unapproved word with an approved word of the same part of speech without
changing the meaning.

**When restructuring is required:**
1. You must change the grammatical structure to use the approved alternative.
2. A word-for-word replacement gives a meaningless or unclear result.
3. The approved alternative would change the meaning.
4. The word to replace is not in the controlled terminology at all.

**Procedure when a replacement fails:**
- Think about the *purpose* of the sentence, then select different words.
- Frequently you must: select different words, use a different verb form, write
  shorter sentences, remove unnecessary information, or get more detail from a
  developer.
- Keep code symbols unchanged (Rule 1.5). Only the prose around them changes.

**Code-domain examples (Non-STE → STE):**

| Non-STE | STE | Why |
|---|---|---|
| A timeout value of 5000 ms is **acceptable** for this endpoint. | A timeout value of 5000 ms is **permitted** for this endpoint. | "acceptable" not approved; "permitted" is same part of speech and keeps meaning → word-for-word replacement is enough, no restructure. |
| The stack trace in the console must be **visible** during the debugging session. | During the debugging session, **make sure that you can see** the stack trace in the console. | "visible" (adj) → "see" (verb); restructure around the agent "you." |
| **Loop** the function twice to remove null values from the array. | **Run** the function for two iterations to remove null values from the array. | "loop" not approved; "iteration" (noun) + "run" (verb) replace it; "twice" → "two" (technical). |
| Without this change, the behavior of the function can be **uncertain**. | Without this change, it is possible that the function will not behave as expected. | "uncertain" not in terminology; word-for-word fails → new sentence. |
| **Just** add a single log statement to the method. | **Only** add a single log statement to the method. | "just" → "only"; do NOT use "immediately" here (changes meaning). |

**Restructuring patterns (reuse these):**

- *Adjective → verb:* "X is visible/configurable/accessible" → "make sure that you
  can see/set/open X." Example: "The configuration panel is accessible only to
  administrators." → "Only administrators can open the configuration panel."
- *Noun → verb:* nominalizations ("retrieval", "validation", "execution") pair with
  light verbs ("perform", "carry out"). Drop the light verb: "perform the retrieval
  of X" → "get X." Example: "The service performs the validation of each request"
  → "The service checks each request."
- *Split long sentences* before a conjunction ("and", "or", "but"), a conditional
  ("if", "when"), or between cause/effect. After splitting, each sentence must
  stand alone.

**Per documentation type:**

- *README:* replace passive with active instructions; move complex detail to a
  separate doc; use bullets; drop marketing language.
  Non-STE: "This library leverages asynchronous I/O to facilitate high-throughput
  data processing." → STE: "This library uses async I/O. It can process large
  quantities of data quickly."
- *API docs:* keep parameter names unchanged (Rule 1.5); restructure the
  description around the approved word; use a different subject if the original
  subject depends on an unapproved word; split compound descriptions.
  Non-STE: "This endpoint facilitates the retrieval of user profiles." →
  STE: "This endpoint gets user profiles."
- *Docstrings/comments:* use the approved verb form even if longer; move complex
  detail out; never change a code symbol.
  Non-STE: `"""Computes the aggregate of the supplied metrics and persists them."""`
  → STE: `"""Gets the total of the metrics and saves them."""`
- *Commit messages:* imperative summary ("Add feature"); put detail in the PR.
  Non-STE: "Implemented utilization of the cached connection pool to expedite
  request handling." → STE: "Use the cached connection pool to make requests
  faster."
- *Error messages:* state what happened and what to do; keep stack traces/symbols
  unchanged.
  Non-STE: "The application encountered an unrecoverable exception while attempting
  to instantiate the connection pool." → STE: "The application cannot start the
  connection pool. Look at the log for more data."

**Paradigm-specific notes:**

- *OOP (Java/C#/C++/Python classes):* "provides an abstraction that facilitates"
  → restructure to the concrete purpose. Non-STE:
  "The `BaseRepository` class provides an abstraction that facilitates data access
  operations across multiple database backends." → STE: "The `BaseRepository`
  class lets you use the same data access methods with different databases."
- *Functional (Haskell/Elixir/Rust):* type signatures stay unchanged; "maps over"/
  "folds" are technical verbs only when naming an op — in general prose use
  "applies a function to each element."
- *Procedural (C/Go/Bash):* "deallocate" → "free" or "release"; "pipe command A to
  command B" → "send the output of command A to command B" unless "pipe" is a
  keyword in context.
- *Declarative (SQL/Terraform/K8s):* naturally passive/stative — split and use
  active: Non-STE: "This Deployment manifest orchestrates the rollout of three
  replicated Pods, ensuring high availability through automated rescheduling." →
  STE: "This Deployment makes three copies of the Pod. If a Pod stops, the system
  starts a new Pod automatically."
- *Systems (Rust ownership/C memory):* keywords (`move`, `borrow`) keep their
  technical meaning in code font; in prose, "borrow" → "get a reference to", "own"
  → "has".

**Edge cases:**

- *Framework name = English word* (Flask, Vite, Express, Tailwind): keep the name
  unchanged; never use it as a verb. "Flask your application" → "Use Flask with
  your application."
- *Keyword = approved word* (Rust `use`, `move`; `return`; `break`): code font =
  technical noun; prose = approved meaning. "You must move the value with the
  `move` keyword, then give it back from the function."
- *Generated code symbols* with unapproved words (e.g. `utilizeData()`): keep the
  symbol; describe it with approved words — "The `utilizeData()` function uses the
  data to make a report."
- *Quoted log/error text:* keep verbatim (it is data); explain it with approved
  prose.
- *Restructuring loses precision* (e.g. security audit): (1) split + clarifying
  note, (2) keep the term in code font with a glossary definition, or (3) for an
  internal expert audience keep it as a technical noun with an approved-word
  definition on first use.
- *Algorithm names* (QuickSort, Two-Phase Commit): technical nouns, keep unchanged;
  describe behavior with approved words.

---

## Rule 9.2 — Use Each Approved Word Correctly

**Core instruction.** Use each approved word with its approved meaning and its
approved part of speech. In STE-Code, an approved word usually has exactly one
approved meaning; other standard-English meanings are not approved.

**Key facts:**
- Before using a word, check the STE-Code dictionary's approved-meaning column.
- A word may be approved for one meaning only (e.g. "wear" = "become damaged by
  friction", not "have on body"). Pick a different word for the other meaning.
- A small set of words is approved as more than one part of speech — each with a
  restricted meaning (see "Multiple parts of speech" below).
- Code symbols (keywords, framework/library names, function/var names) are
  technical nouns (Rule 1.5) and exempt from this rule — but your *prose* about
  them must follow it.

**Code-domain examples (Non-STE → STE):**

| Non-STE | STE | Why |
|---|---|---|
| Execute the initialization script before you start the server. | **Run** the initialization script before you start the server. | "execute" not approved; "run" is the one approved verb for "run a program". |
| When the error count goes down, restart the service. | When the error count **decreases**, restart the service. | "goes down" (physical movement) → "decreases" (number). |
| **Log** the exception details to the output stream. | **Write** the exception details to the log. | "log" approved as noun only, not verb. |
| The config **help** shows all command-line options. | The configuration **help text** shows all command-line options. | "help" approved as verb only, not noun. |
| The recursive call **damaged** the call stack. | The recursive call **caused damage** to the call stack. | "damage" approved as noun only, not verb. |
| This configuration option **governs** whether the linter enforces the rule set. | This configuration option **sets** how the linter applies the rules. | "governs"/"enforces" not approved; restructure around "sets". |
| The `render` method leverages a virtual DOM diffing algorithm to minimize expensive DOM manipulations. | The `render` method **uses** a virtual DOM diff algorithm. This algorithm **decreases** the number of DOM changes. | "leverages"→"uses"; "minimize"→split; "expensive"→restate; "manipulations"→"changes". |

**Words approved as multiple parts of speech** (restricted meaning each):

- **build** — verb: "construct software from source" (technical verb, Rule 1.12);
  noun: "the result of a build" or "a version". Be specific: "the build output"
  not "the build" when you mean the artifact.
- **run** — verb: "start and operate software"; noun only in compounds "test run",
  "dry run". Never "do a run" — "run the tests" or "do a test run".
- **set** — verb: "put into a specified state"; noun: "a group of related items".
  Avoid "the set timeout" (looks like an adjective) → "the timeout value that you
  set".
- **check** — verb: "make sure something is correct"; noun only in compounds
  "type check", "health check", "lint check". Never "do a check" — "check" or "do a
  health check".
- **flush** — verb: "remove remaining data from a buffer"; adjective: "where one
  surface fully touches a different surface". Primary spec example.
- **free** — verb: "release"; adjective: "not restricted".
- **close** — verb: "shut"; adjective: "near" (avoid the adjective in technical
  contexts; use "nearest port").

**Per documentation type:**

- *README:* every verb an approved verb in its approved meaning ("leverage"→"use",
  "facilitate"→"help"); every concept noun approved ("functionality"→"feature",
  "capability"→"can"); "build"/"run" handled per the table above.
- *API docs:* `GET` (uppercase, HTTP method) is a technical noun; "get" (verb) is
  approved. "Send a GET request to this endpoint to get the user data." "return" is
  a verb; "the return value" is allowed (noun adjunct) but "the return of the
  function" is not.
- *Docstrings:* "do" only for general actions (else specific verb); "make" = "create"
  (not "make a call"→"call", not "make a request"→"send a request", but "make a
  copy" ok); `using` keyword in code font = technical noun, prose "use" = verb.
- *Commit messages:* imperative approved verb ("Implement feature"→"Add feature",
  "Introduce breaking change"→"Add breaking change"); "fix" verb ok, "a fix" noun
  not; "update" verb only.
- *Error messages:* "cannot" not "unable to"/"failed to"; "must" only when the user
  must act to continue (else state the state: "The file does not exist" not "The
  file must exist"); "if" for conditional action.

**Paradigm-specific notes:**

- *OOP:* `extend`/`implements`/`override`/`abstract` are keywords in code font; in
  prose use "is a child of", "uses the interface", "replaces the parent method",
  "is a base class. You cannot make an instance of it." Non-STE: "This class
  implements the `Serializable` interface." → STE: "This class uses the
  `Serializable` interface."
- *Functional:* `map`/`reduce`/`filter`/`apply` are function names (technical
  nouns); in prose use "apply the function to each element", "combine the elements
  into a single value", "remove elements that do not match", "use the function on
  the value" — never the verb forms.
- *Procedural (C/Go):* `free()`/`open()`/`close()`/`read()` are function names;
  prose: "free the memory", "open the file", "the port is available" (not "open"),
  "read the data from the buffer" (not "do a read").
- *Declarative:* `CREATE`/`SELECT`/`DROP` are SQL keywords; in prose "make a table",
  "get rows from the table", "remove the table"; `terraform apply` stays in code
  font, prose "use `terraform apply` to make the changes".
- *Systems (Rust):* `move` as technical verb ok ("when you move a value"); `borrow`
  → "get a reference to"; `drop` as technical verb ok ("the value drops when it
  goes out of scope"); `own` → "has". "ownership" is a technical noun.

**Edge cases:**

- *Framework name = unapproved word* (Express, Flask, Fresh, FastAPI): technical
  noun, keep unchanged, never as a verb. "Express your API routes" → "Use the
  `Express` framework to write your API routes."
- *Keyword = approved word* (Rust `use`, `move`; `return`; `break`): code font =
  keyword; prose = approved meaning. "Do not break the API contract" → "Do not
  change the API contract."
- *Generated code:* keep unapproved symbol names; describe with approved words. If
  public API, wrap with an approved name that calls the generated function. If you
  own the generator, template approved symbol names from the start.
- *Quoted error/log text:* keep verbatim; explain with approved prose.

**Cross-references:** Rule 1.1 (approved words), 1.2 (part of speech), 1.3 (approved
meanings), 1.4 (approved forms), 1.5 (technical nouns), 1.7 (no technical-noun
verbs), 1.12 (technical verbs), 9.1, 9.3, 9.4, and the STE-Code Dictionary (source
of truth).

---

## Rule 9.3 — Do Not Make Phrasal Verbs

**Core instruction.** When you use two words together, do not make a phrasal verb.
A phrasal verb = an approved verb + a particle/preposition whose combined meaning
differs from the parts (e.g. "put out", "give off", "carry out"). Replace it with a
single approved verb of the same meaning. Only a small number of phrasal verbs are
approved, each with a restricted meaning (see below).

**Why it matters in code docs:** phrasal verbs are ambiguous (one phrase, many
meanings), hard for non-native readers, and unsearchable ("remove" won't match
"take off" or "strip out"). One approved verb is always preferred.

**Code-domain examples (Non-STE → STE):**

| Non-STE | STE | Why |
|---|---|---|
| The compiler **puts out** a warning. | The compiler **emits** a warning. | "put out" phrasal → single verb "emit". |
| The function **gives off** an error code. | The function **returns** an error code. | "give off" phrasal → "return". |
| The cleanup task **carries out** the deallocation. | The cleanup task **does** the deallocation. | "carry out" → "do". |
| The test runner **runs through** all suites and **prints out** a report. | The test runner **executes** all suites and **prints** a report. | "run through"→"execute"; "prints out"→"prints" ("out" adds nothing). |
| The framework **sets up** the routing table. | The framework **configures** the routing table. | "set up" → "configure" (or "install"/"create" by context). |
| The middleware **looks at** headers and **filters out** fields. | The middleware **examines** headers and **removes** fields. | "look at"→"examine"; "filter out"→"remove" (note: "filter" alone is an approved verb). |
| The cleanup job **kicks in** and **clears out** sessions. | The cleanup job **starts** and **removes** sessions. | "kick in"/"clear out" informal → "start"/"remove". |
| The compiler **breaks down** the source, then **goes on** to generate IR. | The compiler **divides** the source, then **continues** to generate IR. | "break down"→"divides"; "go on"→"continues". |
| The plugin lets you **hook into** the pipeline and **tap into** the stream. | The plugin lets you **connect to** the pipeline and **subscribe to** the stream. | "hook into"/"tap into" slang → "connect"/"subscribe". |

**README / type-specific replacements:**

- README: "set up"→"configure"/"install"; "run through"→"complete"; "check out"→
  "examine"; "go through"→"read"; "pick up where you left off"→"continue"; "break
  down the architecture"→"describe the architecture".
- API docs: verb must match the operation exactly — GET "gets", POST "creates"/
  "sends"; "looks up"→"finds", "hands off"→"sends", "takes in"→"receives", "spits
  out"→"returns", "fills in"→"completes".
- Commit messages: clean up→remove/delete/tidy; fix up→correct/repair; speed
  up→accelerate/make faster; cut down→reduce; rip out/strip out→remove; wire up→
  connect; flesh out→complete/expand.
- Error messages: "could not hook up"→"could not connect"; "blew up"→"failed";
  "out of whack"→"not consistent".
- Changelogs: "did away with"→"removed"; "added back"→"restored"; "ironed out"→
  "corrected"; "phased out"→"ended".

**Paradigm-specific notes:**

- *OOP:* "sets up the state"→"initializes"; "tears down"→"releases"; "hands off
  ownership"→"transfers ownership"; "looks up the dependency"→"finds"; "wraps up
  the transaction"→"completes".
- *Functional:* "maps over"→"applies a transformation to each element"; "pipes
  through"→"sends through"; "folds down"→"combines"; "reaches out to"→"sends a
  request to".
- *Procedural:* "reach out to the API"→"send a request"; "pull down"→"get"; "go
  through each record"→"examine"; "put together"→"make". C: "free up"→"release"/
  "free"; "hands back"→"returns".
- *Declarative:* "brings up instances"→"creates"; "spins up pods"→"starts"; "tears
  down"→"removes"; "joins together"→"joins ... with".
- *Systems:* "hands off ownership"→"transfers"; "holds onto"→"keeps a reference";
  "gives up the lock"→"releases"; "carves out"→"allocates".

**Approved phrasal verbs (restricted meaning — the only ones allowed):**

| Phrasal verb | Meaning | Example |
|---|---|---|
| log in / log out | start/end an authenticated session | "The user must log in before they can access the dashboard." |
| follow up | take further action after an initial step | "Follow up the installation with the configuration step." |
| back up | make a copy for safekeeping | "Back up the database before you apply the migration." |
| roll back | return to a previous state | "Roll back the deployment if the health check fails." |

Do not use "sign in/out", "log on/off". "Back up" (two words) means only "make a
copy" — not movement or support.

**Edge cases:**

- *Framework name contains a phrasal verb* (`setuptools`, `cleanup`, `rollback`):
  the name is a technical noun — keep it. But describe its behavior with an
  approved verb: "`setuptools` configures the package metadata" (not "sets up").
- *Code keyword = phrasal component* (`break`, `continue`, `throw`, `catch`): as a
  keyword/noun or technical verb it is fine ("the `break` statement exits the
  loop"); as a phrasal verb it is not ("breaks out of the loop"→"exits the loop";
  "catches up with the stream"→"synchronizes with the stream").
- *Not every verb+preposition is a phrasal verb.* If the preposition is a normal
  prepositional phrase (location/direction/target) and the verb keeps its meaning,
  it is allowed: "runs on the server", "flows from input to output", "write the
  configuration to the file". Test: remove the preposition — if the meaning stays
  roughly the same, it is allowed; if the meaning changes completely, it is a
  phrasal verb. ("write up the report" = compose formally → not allowed.)
- *Generated docs:* fix the source doc comments (JSDoc/Sphinx/rustdoc) so the
  published output is compliant. Third-party docs you cannot edit need not be
  corrected.
- *No single verb exists:* apply Rule 9.1. "calls back the caller with the result"
  → "sends the result to the caller through a callback". "warms up"→"loads the
  data"; "flags up"→"reports"/"marks"; "churns through"→"processes".

**Cross-references:** Rule 1.1 (dictionary), 1.2 (part of speech — the particle is
not a preposition of direction), 1.4 (approved forms), 1.11 (one term per concept —
mixing "set up" and "configure" violates consistency), 1.12 (technical verbs — do
not replace "serialize" with "turn into a string"), 9.1 (escape hatch), 9.2 (each
non-phrasal word must carry its approved meaning).

---

## Rule 9.4 — Always Use a Consistent Style

**Core instruction.** When you select terminology or wording, always use a
consistent style: the same term for the same thing, the same verb for the same
action, and the same sentence structure for the same type of instruction. Variation
is a defect, not a stylistic virtue.

**Why:** every synonym forces the reader to ask "is this the same thing or a
different thing?" — a cognitive tax that causes misidentification and bugs. In code
docs this means a parameter called "retry count" in one section and "max attempts"
in another gets misconfigured at runtime.

**Three consistency domains (each maintained independently):**

1. *Lexical* — one term per concept. Audit with grep. Pick one noun for one file
   ("configuration file", never alternating with "settings file"/"config").
2. *Syntactic* — same structure for the same action. All setup steps share one
   template (imperative verb + purpose clause); do not switch to passive/conditional
   for some steps.
3. *Semantic* — same meaning across files/modules/types. If "build" = "compile and
   link" in the README, it must not mean "compile, link, and package" in CI docs.

**Per documentation type:**

- *README:* one term for the artifact ("library" not "package" mid-doc).
- *API docs:* one name for each endpoint/method/parameter; prose must match the
  schema field name (`createdAt`, not "creation date"/"timestamp").
- *Docstrings:* use the parameter name from the signature (`max_retries`, not
  "maximum attempts"/"retry limit").
- *Commit messages:* one imperative verb per change category ("Add" for new
  features — not "Introduce"/"Insert"/"Create"; "Fix" — not "Resolve"/"Correct"/
  "Patch").
- *Error messages:* the same failure mode must produce identical text every time
  (`E_CONNECT_FAIL` = "Cannot connect to the remote host" in every module).
- *CLI help:* same template for every flag ("Enables/Disables [adjective] output").

**Code-domain examples (Non-STE → STE):**

- Setup verbs: "Install the dependencies. Then fetch the source. After that set up
  the environment. Finally get the database running." → "Install the dependencies.
  Then download the source. After that set the environment variables. Finally start
  the database." (one verb per action)
- Noun across docs: README "auth package" / API "auth package" / error "auth
  module" → all "authentication library".
- API reference: "Retrieves all items" / "Use this to create" / "Gets item by ID" /
  "Removes the specified item" → all third-person singular: "Returns all items" /
  "Creates a new item" / "Returns the item with the specified ID" / "Removes the
  item with the specified ID".
- Commit log: "Add" / "Introduce" / "Insert" / "Create" → all "Add".
- Error messages: "Connection refused by peer" / "Cannot establish link to remote"
  / "Failed to connect to upstream server" → all "Cannot connect to the remote
  host".
- CLI flags: "--verbose Enable verbose output / --quiet Suppress all logging /
  --debug Turns on debug-level messages" → "--verbose Enables verbose output /
  --quiet Disables all output / --debug Enables debug output".

**Paradigm-specific notes:**

- *OOP:* reuse the base-class docstring template in every subclass; don't abbreviate
  class names inconsistently (`UserRepository`, not `UserRepo`/"user repo").
- *Functional:* one anchor phrase for pure functions ("returns a new list"); don't
  mix "produces a result"/"yields output"; keep the monad metaphor constant.
- *Procedural:* predictable I/O step pattern; same error-check phrasing for every
  `if err != nil`.
- *Declarative:* same phrasing per resource type (`aws_instance` = "a virtual machine
  in AWS EC2" everywhere); Kubernetes resource names are proper nouns — `ConfigMap`,
  `Pod`, never "config map"/"configuration map".
- *Systems:* consistency is a safety property. Rust terms "ownership"/"move"/
  "borrow"/"lifetime" are precise — never substitute synonyms ("takes possession"/
  "relinquishes control" → "takes ownership"/"moves").

**Edge cases:**

- *Framework-mandated terminology* (React "props", "hooks"): the framework is the
  authority — use its term everywhere, never translate to an STE-Code synonym.
- *Generated docs:* fix the source docstrings; don't post-process output. For
  conventional-commits changelogs, enforce an allowed-verb convention and reject
  non-standard verbs in CI.
- *Cross-project (monorepo):* per-service docs follow the service glossary;
  system-level docs define a system-wide glossary mapping each system term to its
  service-level term.
- *Multiple valid industry names* (e.g. "GitHub Actions workflow" vs "pipeline"):
  pick one, document it in the project glossary, never alternate.
- *Version renames* ("packages" ↔ "workspaces"): each version's docs use that
  version's canonical name; migration guides must state the rename explicitly.

**Canonical synonym table — pick the preferred term and use it everywhere:**

| Preferred | Do NOT alternate with |
|---|---|
| use | utilize, leverage, employ |
| start | initiate, commence, bootstrap |
| show | display, render, present |
| make | create, generate, produce |
| get | retrieve, fetch, obtain |
| set | configure, assign, establish |
| check | verify, validate, ensure |
| remove | delete, eliminate, purge |
| keep | retain, preserve, maintain |
| send | transmit, dispatch, forward |

**Cross-references:** Rule 1.1 (approved words — consistency needs one approved
term), 1.3 (approved meanings — "set" can't mean both "configure" and "collection"),
1.5 (technical nouns must also be consistent), 1.11 (one term per concept — the
lexical foundation of 9.4), 9.1 (restructure rather than introduce a synonym), 9.2
(incorrect usage in one place breaks the chain).

---

*Section 9 covers the four writing-level rules. For the controlled terminology
(dictionary A–Z), the full rule set (Sections 1–8, 10+), extensions, and the
provenance catalogue, see the other Level 5 sub-documents.*
