# Explanatory Standard

Andrew established this explanatory contract for the Rhythm 2.0 specification corpus on 2026-10-23. [`CONVENTIONS.md`](CONVENTIONS.md) specifies the artifact kinds, their fields, and the sources that support their facts. This document specifies what each kind must *explain*, the required depth, where explanations belong, and how reviewers assess them. Use the documents together. When they conflict, CONVENTIONS governs structure, and this document governs explanatory depth.

## 1. Why This Standard Exists

The corpus started as an inventory of identifiers, relationships, rule rows, test bindings, and provenance. That information remains necessary, but it does not explain the product. Someone could read an entire feature document without learning what the feature does, why Rhythm needs it, who uses it, what the complete experience involves, how it operates, why it operates that way, or what happens when it fails. Describing a feature as "this feature groups the following capabilities" turns it into an index entry rather than an explanation.

**We are not documenting software. We are preserving an understandable model of the product.** A technical inventory identifies what exists. A business rule states what must happen. A test checks behavior. An architecture document describes the system's organization. A useful product specification explains why functionality exists, the problem it addresses, how it should work, and why its behavior matters. The corpus must fulfill all these roles.

The measure of success is whether readers understand the product. A new product manager, engineer, implementation consultant, or architect who knows nothing about Rhythm should be able to read the library and understand what Rhythm does; why its applications and modules exist; the business problems and concepts they address; its users and workflows; connections between features; capabilities and their rules; design choices; integrations and boundaries; verification; and where authoritative rules and evidence live. Understanding a feature's purpose should not require source code. When Forge changes a feature months later, it should understand the intent and reasoning as well as the routes and tables.

## 2. Three Audiences, One Library

| Audience | What they need from the same document |
|---|---|
| Product owners and product managers | An understandable account of behavior that helps them question design choices, compare tradeoffs, and decide whether we are building the right product. |
| Developers and AI agents (Forge) | The intent, business model, invariants, boundaries, and expected behavior they need to modify and extend the product safely. |
| Implementation consultants and future employees | Business-language explanations supported by technical detail where that detail improves understanding. |

Narrative sections address all three audiences. The formal contract, including rule rows, scenarios, permissions, and test specifications, addresses the second audience while giving the first precise statements to evaluate. Neither form replaces the other.

## 3. Explanatory Responsibility by Kind

Each kind is responsible for a different question. A section that answers a question belonging to another kind duplicates information and risks contradictions.

| Kind | Explains |
|---|---|
| Product Area (`AREA`) | The application's business domain, purpose, users, supported business processes, and place in Rhythm. |
| Module (`MODULE.md`) | The bounded business problem it addresses, who uses it, how its features share the work, and the limits of its responsibility. |
| Feature (`FEAT`) | Its problem, purpose, users, complete experience, ownership, exclusions, and results. |
| Capability (`CAP`) | The behavior it delivers, how that behavior works, the rules that govern it, the reasoning behind important rules, and its connections to related functionality. |
| Key Concept (`CON`) | A business concept's meaning and purpose, its representation and use in Rhythm, its lifecycle and relationships, and the ideas readers often confuse with it. |
| Journey (`JNY`) | A person's complete business process, its alternate paths, and the conditions that are true when it ends. |

Design kinds (Domain Object, State Model, Workflow, Service Contract, Screen Design, Component Design) require the depth of Tribal's specifications (Andrew, 2026-10-23, after reading the Entities design: "the screen designs look naked; the domain object should have its key properties; where is my permission model"). Their sections appear in §6.7. Decision Records and Inference Operations keep their existing sections. CONVENTIONS §9 applies: explain what something is for before explaining what it is.

## 4. One Home per Fact, Still, and No History Yet

**No history during reverse engineering** (Andrew, 2026-10-23). The corpus represents the current product at one milestone and one timestamp. Delete artifacts that are incorrect, misplaced, or do not represent real concepts, and remove references to them. Do not keep artifacts as `superseded`, build a `supersedes` chain, raise `revision` above 1, or record change history. Readers never encounter a page whose only message is "superseded by". Versioning, including revision increases, change fields, and superseded chains, begins only after Andrew locks and approves the corpus. Repository and test links required by CONVENTIONS §15 are not history and stay in place.

Narrative explains rules but never establishes them. Each authoritative business rule has exactly one home: a `rules[]` row in one capability. Acceptance scenarios prove that rule by id. Narrative may summarize a rule in plain language, show an example, and explain its purpose. It may not create a rule absent from the capability, contradict an existing rule, or introduce a condition absent from its rule row. If writing exposes behavior without a supporting rule, the author adds a rule row with provenance and source or files a finding. Behavior never lives only in prose.

Repeating a rule statement word for word in a narrative sentence is a defect rejected by the conformance check. Summarize the rule or direct readers to the formal contract ("the rules below specify exactly which declarations are refused").

## 5. Six Kinds of Knowing

Reverse engineering can establish behavior reliably, but it cannot reliably establish intent. Prose must make that distinction clear, and frontmatter must record it. There are Six tiers:

| Tier | Meaning | How the prose says it | How the frontmatter records it |
|---|---|---|---|
| Verified intent | A product record, such as a milestone decision, approved plan, standard, or Andrew's ruling, confirms that the behavior is intended. | Use "Product decided …" or "Rhythm requires …", or state the fact directly. | Set `provenance: documented`; put the record and decision id in `source`, and record the rule's `origin`. |
| Verified implementation | Pinned code or a test establishes the product's current behavior. | Use "Today Rhythm …" or "When a coordinator saves …", or describe the behavior directly in present tense. | Set `provenance: observed` or `test`, and name the symbol or test title. |
| Documented motivation | A record, design document, or architecture chapter gives the reason. | Use "The milestone record explains that …" or "The design was chosen because …" | Set `provenance: documented` and cite the heading containing the reason. |
| Interpreted rationale | No written reason exists; the author derives a possible explanation from behavior, invariants, and domain knowledge. | Use "Our reading is that …" or "The most likely reason is …"; never assign the reasoning to a person. | Set `provenance: inferred` and add a `note` that explains the reasoning. |
| Proposed behaviour | The author recommends behavior that the product does not currently support. | Use "The product should …" | Set `product_intent: proposed` on the artifact, and add an open question when the choice is material. |
| Unknown | The author cannot establish the fact. | Use "It is not established whether …; this is an open question." | Set `provenance: unknown` and put the `FND-` or `OQ-` id in `source`. |

These tiers require the following:

- Never fabricate past deliberations. Never assign a motive to anyone without a supporting record.
- Never describe an interpretation as a decision. Writing narrative does not change `status`, `product_intent`, or `design_intent`.
- Useful interpretations are welcome when clearly labeled. An unlabeled, confident explanation is worse than a shorter explanation that is honest about its limits.
- Every motivation and rationale section identifies its evidence in `narrative_sources[]` (§7). If the entire section is interpretive, say so in its first sentence.

## 6. The Sections, Kind by Kind

Use H2 section headings in the required order and include every required section. Add an optional section only when it contributes something true and useful; otherwise, leave it out. Never populate a section with "None" or "Not applicable". The subject's complexity determines the depth. A simple capability may need a few hundred words altogether. Payments, eligibility, overlapping memberships, audit recovery, or concurrent edits may require several times as much. The conformance check requires sections in order and at least forty words in every required section. This floor prevents empty headings; it is not a writing target.

**Typical depth.** The first authoring pass on CRM Entities (2026-10-23) included every section but remained thin: eight sections in 550 words, each containing a paragraph of abstractions. Complete understanding is the standard. In practice, achieving it has required these ranges: a feature 900 to 1,800 words; a capability 500 to 1,200 (more for money, eligibility, overlapping periods, audit recovery or concurrency); a key concept 500 to 1,200; a journey 300 to 700; a module charter's prose sections 600 to 1,200 before its tables; a screen contract, domain object or state model 600 to 1,500 of prose alongside its structured fields. Merely naming things ("the milestone records a common meaning for current membership") does not explain them. An explanation says what the thing is, what problem it addresses, and what happens in concrete terms, as §9 demonstrates. A reviewer treats a document substantially below these ranges, or a `Why It Exists` without a concrete problem, as `needs-revision` unless the document explains why less is sufficient.

### 6.1 Feature

A feature explains a cohesive part of the product. It presents the whole story; its capabilities provide the details.

| Section | Required | Must answer | Must not |
|---|---|---|---|
| `## Overview` | yes | Describe the feature and its place in the product for a knowledgeable business reader who does not know it. Use Two to four paragraphs. | Substitute a one-sentence definition or capability-title list for an explanation. |
| `## Why It Exists` | yes | Describe the real-world problem, operational need, technical limitation, or opportunity; what happens without the feature; and what organizations did previously, when that history is known. | Fabricate history. Include a `narrative_sources` row for each claim. |
| `## Who Uses It` | yes | Name each relevant audience using its actor name in words and explain its goals. Include members, staff, administrators, finance, HQ, consultants, developers, automated systems, and agents only when relevant. | Invent a persona. |
| `## How It Works` | yes | Describe the conceptual solution: the product model, its value, and the connections between its main parts. Follow with normal operation as a continuous sequence of triggers, actions, decisions, stored or changed information, visible behavior, and results. Give readers a practical mental model. | Copy rule rows into the narrative. |
| `## Examples` | yes | Present One or more realistic business situations that demonstrate meaningful behavior and comply with verified rules. Use association situations for association functionality and realistic engineering or operations situations for internal platform functionality. | Replace the example with a generic consumer-software situation or break a rule. |
| `## Decisions and Tradeoffs` | optional | Explain significant choices, such as multiple affiliations instead of one employer field, immutable historical prices, overlapping memberships, or workflow approval. Discuss alternatives and tradeoffs where evidence supports them, and label interpretations. | Give unsupported or unlabeled reasoning, or assign motives to people. |
| `## Scope and Boundaries` | yes | State what the feature owns and excludes, identify adjacent features and modules, and explain how responsibilities are divided. This is especially important as macroservices form around business capabilities. | Repeat the full module boundary. |
| `## Outcomes` | yes | Describe what the feature enables, its business or operational result, and how success is established. Name the feature acceptance suite in words. | Invent numerical targets. |
| `## Its Capabilities` | yes | Provide One sentence for each child capability that includes its title and explains its contribution. Name existing journeys in words. | Treat a title alone as a sentence. |

### 6.2 Capability

A capability owns detailed behavior. Its narrative explains the behavior's purpose and operation. The formal contract in frontmatter specifies that behavior precisely and is displayed after the narrative.

| Section | Required | Must answer | Must not |
|---|---|---|---|
| `## Purpose` | yes | Describe the specific problem this capability solves and why its feature needs it. | Simply repeat the title. |
| `## How It Works` | yes | Explain the operating model in connected prose, including objects, inputs, outputs, state changes, workflows, and side effects. Readers should not have to assemble twenty rule rows to understand the operation. | Present a rule list. |
| `## Example` | yes | Provide One realistic walkthrough showing the sequence and result. Choose an example that makes behavior clear rather than restating a rule. | Leave the explanation abstract. |
| `## Variations` | optional | Cover only relevant variations: roles and permissions, starting states, absent or invalid information, concurrency, duplicates, retries, rollbacks, exceptions, boundary values, and historical versus current records. Select categories from the capability test specification's coverage map. | Add categories that do not apply. |
| `## Why It Works This Way` | yes | For every significant rule or constraint, explain the invariant it preserves, the business risk it prevents, and why an apparently simpler approach would be wrong. Address future engineers who may modify the rule. Label interpretations and record evidence in `narrative_sources`. | Describe an interpretation as a decision. |
| `## Relationships` | yes | Describe interactions with other capabilities and modules, the location of authority, and the distinction between service contracts, events, registries, and direct dependencies. | Suggest a direct dependency when communication goes through a contract. |

Keep the formal contract in frontmatter unchanged, including rules, scenarios, edge cases, permissions, preconditions, postconditions, dependencies, journeys, open questions, controls, and evidence. The reader displays that contract after the narrative, below a visible divider.

### 6.3 Key Concept

A concept teaches the business domain. An Affiliation concept explains how association management views connections between people and organizations, not a table's structure. A Contact Type concept explains the type's purpose and what changes in the product when a contact has that type. A Key Concept is every business idea a reader must understand to use the module (Andrew, 2026-10-23). It includes broad nouns, classification types, roles, statuses, policies, and settings that influence behavior or display. A storage row or mechanism inside a concept is a facet, not a separate concept. A noun owned by another module is not this module's concept. Custom field definitions and values, page layouts, forms, files, users, and email templates belong to Platform. Name the owning module's concept in words. If that concept does not exist, file a finding in the owning module.

| Section | Required | Must answer |
|---|---|---|
| `## What It Is` | yes | Describe what the thing means to customer staff, how it is created, what it contains, and how it is identified. Compare it with Rhythm 1.0 or a common system when useful. |
| `## Why It Exists` | yes | Describe the business need it meets and the problems that arise without it. |
| `## What It Is Not` | yes | Separate it from related ideas readers may confuse with it, and address common misunderstandings. |
| `## What It Controls` | yes | Describe the behavior, display, and rules it determines, including the effects of setting, selecting, or changing it. Teach readers what it changes in the system. |
| `## How It Is Used` | yes | Describe who uses it and when, name relevant capabilities and journeys in words, and explain good use and potential problems. |
| `## Example` | yes | Present a specific instance in a realistic situation. |
| `## Its Facets` | optional | When the concept has subparts, explain each facet's meaning and purpose in a short paragraph. |
| `## Its Lifecycle` | optional | When the concept has a lifecycle, explain its states in product language and what triggers transitions. Keep the formal state model in Design. |
| `## How It Relates` | yes | Explain its connections to concepts in this module and other modules in words. When another module owns a related idea, name that module's concept. |
| `## What It Could Become` | optional | Describe unsettled behavior, likely extensions, and questions Product may want to answer. |

A type, role, or setting generally needs 400 to 1,000 words; a broad noun generally needs 600 to 1,200.

### 6.4 Journey

A journey explains a business process from start to finish. Frontmatter records its steps, alternates, failures, and assertions. Narrative turns those details into a story readers can follow.

| Section | Required | Must answer |
|---|---|---|
| `## Story` | yes | Describe the entire process from the actor's viewpoint, including the goal and how the actor achieves it. |
| `## Before It Starts` | optional | Describe who starts the process, what triggers it, and the conditions that must already hold. |
| `## What Can Go Differently` | optional | Explain alternate paths and exceptions in prose, including how each is resolved. |
| `## What Is True Afterwards` | yes | Describe the final state, the people affected, and what the person or system can do next. |

### 6.5 Module Charter

| Section | Required | Must answer |
|---|---|---|
| `## Purpose` | yes | Introduce the domain, business problem, users, and supported processes to a first-time reader in 200 to 500 words. |
| `## Who Uses It` | yes | Name the module's actors in words and describe each actor's work here. |
| `## How It Is Organized` | yes | Provide One paragraph for each feature describing its purpose and when readers should open it. |
| `## Boundary` | yes | Describe what the module owns and what it intentionally delegates to other modules, naming those modules. |
| `## Features`, `## Capabilities`, `## Journeys` | yes | Leave the tables required by CONVENTIONS §5.4 unchanged. |

### 6.6 Product Area Overview and Architecture

The area page is the product area's final architecture document (Andrew, 2026-10-23). Before opening a module, readers begin there to learn the area's purpose, users, business processes, organization, construction, and the reasons for that construction. The deep architecture artifacts decided in Claude belong in this page, combined with the overview as one document. Architecture records under `architecture/` remain unchanged as sources and supporting evidence.

| Section | Required | Must answer |
|---|---|---|
| `## Purpose and Outcomes` | yes | Describe what the area provides to a customer and why it exists in 200 to 500 words. |
| `## Who Uses It` | yes | Name the area's actors in words and describe what each achieves here. |
| `## Key Business Processes` | yes | Describe the area's principal workflows and refer in words to the product acceptance suites that prove them. |
| `## Scope and Boundaries`, `## How the Area Is Divided` | yes | Follow CONVENTIONS §5.0c. |
| Architecture chapters (free H2 titles) | when records exist | Develop the architecture from the architecture portions of the records: principles, domain model, functional architecture, services and contracts, lifecycles and safeguards, console and portal experience, data operations, security and privacy, cross-application contracts, and a separate chapter for each topic architecture (households, enrichment). Label every statement built, decided, or proposed. Each chapter's `narrative_sources` row names the record parts that support it. Keep research, evidence, review, gap, and roadmap portions in the records. |
| `## Area-Level Invariants` | yes | Follow CONVENTIONS §5.0c. |
| `## Decisions` | when records exist | Identify standing decisions, recorded decisions, and decisions that still require Andrew. Explain their results and origins. |
| `## Open Ownership Questions` | optional | Explain ownership questions that remain unresolved. |

### 6.7 Design Kinds

Design explains the product's construction in enough detail for an engineer to extend it and a product owner to question it. The permission model has one authoritative home per area: the authorization model. It also appears where readers expect to find it: the module charter's `## Permissions`, each domain object's `## Permissions`, each screen's `## Who Can Reach It`, and each service's `## Permissions`.

| Kind | Required sections | Must answer |
|---|---|---|
| Domain Object | `## What It Models`, `## Identity and Attributes`, `## Relationships`, `## Invariants`, `## Permissions`, `## How It Is Stored and Shared`; optional sections: `## Lifecycle`, `## Open Design Questions` | Explain every key property's business meaning, who sets it, its rules, and an example. Explain each relationship's cardinality, ownership, and behavior on archive or delete. Describe what each invariant preserves and who can read, create, change, archive, and delete the object. |
| State Model | `## Purpose`, `## Ownership and Authority`, `## The Lifecycle`, `## States`, `## Transitions Explained`, `## What Cannot Happen`, `## Concurrency and Timing`; optional sections: `## Permissions by State`, `## Invariants` | Describe each state's meaning, permitted behavior, and visible experience; who or what can move the object and whether a model can; each transition's trigger, guard, effects, and record; every rejected transition and the response; two actors acting simultaneously; and automatic transitions and their timing. |
| Workflow | `## What It Does`, `## What Starts It`, `## The Flow`, `## Hop by Hop`, `## When Something Fails`, `## Repeats and Races`, `## What Is Observable`; optional section: `## Open Design Questions` | For each hop, describe the actor, action, seam crossed, and information written. Explain failures, retries or compensation, what the person sees, and who notices at each hop. Address idempotency, concurrency, and what the person and operator can observe. |
| Service Contract | `## What This Service Is For`, `## Boundary`, `## What It Owns`, `## Operations in Words`, `## Permissions`, `## Events and Jobs`, `## Consistency Guarantees` | Describe each owned object and the implications of that ownership for callers. For every operation, explain who calls it, its action, what it rejects and why, the permission checked, and who holds that permission. |
| Screen Design | `## What the Screen Is For`, `## Who Can Reach It`, `## Navigation and Entry Points`, `## Layout and Information Hierarchy`, `## What It Shows`, `## What People Can Do`, `## Business Rules on This Screen`, `## States and Errors`, `## Sensitive Display and Refusals`, `## Patterns It Must Respect`, `## Components It Uses`, `## Acceptance Criteria`; optional sections: `## Accessibility and Responsive Behavior`, `## Open Questions and Approval` (the navigation, rules, components and acceptance sections are required once the module carries `screen_standard`, CONVENTIONS §9.6) | Explain who can reach the screen and its entry permission, making clear that screen access is not authorization. Explain where the screen sits, how people arrive, where Back, Cancel and each completed action lead, and what happens to unsaved work. Describe regions in reading order; each field's meaning, source, format, control, editability and conditions; and each action's actor, preconditions, result, permission treatment (hidden, disabled with a reason, offered and refused), confirmation, success, failure and side effects. Name each rule the screen enforces in words and say how it shows up here, never restating it. Describe what the person sees in every state; what is displayed, withheld, never rendered, confirmed, or re-authenticated; and what a refused person sees. Name the components reused, the new reusable components the design calls for, and the local elements. State the acceptance criteria a screen acceptance scenario can prove. A Screen Design holds no v0 prompt and no user-interface code. |
| Component Design | `## What It Is For`, `## Where It Is Used`, `## How It Behaves`, `## Its Contract`, `## States`, `## Accessibility`; optional sections: `## Rules It Enforces`, `## Open Design Questions` | Explain the job the component does for the person and for the screens that reuse it, where it is used and where it must not be, how it behaves visually and interactively, what a consumer supplies and gets back (the props and events in words), what the person sees in each state, which rules it enforces or displays (named, living in their capabilities), and how it is operated by keyboard and read by a screen reader. |

Describe an existing console screen as built; never redesign it. Design prose may identify components, operations, and tables, but explains their purpose before describing what they are. The implementation kinds that describe a screen's prompt and its built form (Screen v0 Prompt, Screen Implementation, Component Implementation; CONVENTIONS §10.1 to §10.3) explain what was generated or built and how it differs from the design; they never restate the design.

## 7. Frontmatter for Explanation

Three fields capture explanatory state so the corpus can be checked and inventoried.

```yaml
narrative:
  status: enriched            # enriched | verified | needs-revision | stale
  review: NARRATIVE-REVIEW-2026-10-24   # the review report that last judged it, once one exists
  stale_since: RS-123         # only when a dependency changed and the prose has not been revisited
narrative_sources:
  - section: Why It Exists
    provenance: documented
    source: 'services-platform:docs/milestones/PLAT-M1-ai-usage-metered-and-visible.md#D-03'
  - section: Why It Works This Way
    provenance: inferred
    source: 'BR-CAP-PFM-LLM-005-04; services-platform:modules/llm/db/llm-model-rate-versions.table.ts'
    note: Immutability follows from requests naming their rate version; no record states the reason.
```

- `narrative.status` (the only field during reverse engineering of the corpus; no revision counter, see §4): set `enriched` after the author job writes the sections; `verified` after review checks evidence and confirms §8 compliance; `needs-revision` when the artifact fails, with reasons recorded in the review report; and `stale` when a capability, concept, or rule discussed in the narrative changes without narrative review. For a stale artifact, `stale_since` names the ticket or commit.
- `narrative_sources[]`: add a row for every section containing claims that need evidence. Always include rows for `Why It Exists`, `Decisions and Tradeoffs`, and `Why It Works This Way`. Every `inferred` row contains a `note`.
- `explanatory_standard: 1` on `MODULE.md`: indicates that a module meets this standard. The conformance check then applies §6 to the charter and all its features, capabilities, concepts, and journeys. Landing the module's narrative stage sets this field; never set it by hand.

## 8. How Explanatory Quality Is Judged

Valid frontmatter, functioning links, and all required headings do not by themselves make a document useful. Quality requires Two checks, performed in this order.

### 8.1 Deterministic (the conformance check)

Under `explanatory_standard`, the check requires all required sections in the prescribed order and at least forty words in each. It confirms that `## Its Capabilities` includes every child capability's title; narrative sentences do not repeat rule statements; prose contains no identifier, repository path, or file name; motivation and rationale sections include `narrative_sources` rows; and every `inferred` row contains a `note`. It rejects the filler phrases listed below, requires a recognized `narrative.status`, and reports `stale` or `needs-revision` status. These checks find empty or mechanical writing but cannot judge the effectiveness of an explanation.

The check rejects these filler phrases: "form one product grouping", "their individual specifications define", "this feature groups", "as described above", "it is important to note", "in order to", "a wide range of", "plays a crucial role", "seamlessly".

### 8.2 Semantic (the OpenAI review pass)

A reviewer other than the author reads the document alongside pinned code, records, and the formal contract. The reviewer answers the questions below. Every "no" produces a finding with the reason and location. The document passes only when every answer is "yes".

A **feature** passes when a knowledgeable reader unfamiliar with the implementation can explain what it is, why it exists, the problem it solves, who needs it, and how it works. That reader can describe practical use, major choices and tradeoffs, ownership and exclusions, the outcome delivered, and where authoritative capabilities and rules can be found.

A **capability** passes when the reader can explain its purpose, operation, trigger, and effects on state or data. The reader can identify constraints, significant alternate conditions, failure behavior, the reasoning behind important invariants, dependencies, effects on other functionality, and the means of verifying behavior.

A **concept** passes when the reader can explain its business meaning and purpose, its representation in Rhythm, its use, ideas commonly confused with it, relationships with nearby concepts, and decisions that remain unresolved.

A **journey** passes when the reader can recount the process from beginning to end, identify who starts it and why, explain possible variations, and describe the conditions at its conclusion.

A **module** or **area** passes when a first-time reader understands the problem, users, organization, and boundaries and can select the next feature or module to read.

For each document, the reviewer also evaluates the following dimensions and identifies the weakest:

| Dimension | The question |
|---|---|
| Explanatory completeness | Does it answer every question required for this artifact kind? |
| Business relevance | Does it emphasize customer staff's needs and work rather than tables and routes? |
| Clarity and readability | Can all three audiences understand the document in a single reading? |
| Correctness | Are all substantive claims consistent with pinned code, records, and the formal contract? |
| Evidence support | Is every motivation or rationale claim supported by a source or labeled as an interpretation? |
| Appropriate examples | Are examples specific, realistic, and compliant with the rules? |
| Design rationale | Does it explain the reasons for significant rules? |
| Consistency with authoritative rules | Does the narrative avoid introducing, contradicting, or narrowing rules? |
| Consistency with related artifacts | Is it consistent with its parent, children, and related artifacts? |
| No speculation as fact | Is every interpretation clearly labeled? |
| No generic filler | Does each sentence contribute to explaining the subject? |
| Traceability | Can readers connect the explanation to the formal contract and its supporting evidence? |
| Technical accuracy | Are mechanisms described accurately in technical terms? |

The reviewer verifies factual claims against evidence, not the author's confidence. A document that "reads well" fails if its facts are wrong.

## 9. Inadequate and Adequate, Side by Side

The adequate examples below show the required **form**. They demonstrate writing, not verified product facts. The verified text is the artifact itself, created by the authoring pipeline against pinned code.

### 9.1 A feature's Overview and Why It Exists

**Inadequate** (the entire feature body as it stood on 2026-10-23):

> Group operation definitions, historical routing and prices, and deliberate model verification. These capabilities form one product grouping; their individual specifications define behavior, evidence and remaining questions.

**Adequate** (the form):

> Several Rhythm applications provide AI functionality. Their language models vary in capability, price, and usage limits. As AI use spreads across features, Rhythm needs a shared method for defining an operation's AI use, calculating consumption, and later explaining what it did and what it cost. AI Catalog and Pricing provides that common record. It stores published AI operation definitions and model prices for individual requests to reference instead of choosing them independently.
>
> Without common definitions, it becomes hard to reconstruct the model, instructions, and cost assumptions behind an operation. A price update could make last month's usage look as though it cost something different from the original calculation. Engineers would need to pay for live-model calls to check AI behavior. The milestone record for metered AI usage identifies visibility into cost per request as the AI program's first requirement. Our interpretation of behavior enforced by the code supplies the remaining motivation in this explanation.

The adequate version describes the functionality, its problem, the consequences of its absence, and which explanations come from records rather than interpretation.

### 9.2 A capability's Example and Why It Works This Way

**Inadequate**:

> Reverting a declaration creates another historical version rather than erasing the intervening one. Requests retain the versions under which they run.

**Adequate** (the form):

> Rhythm publishes an operation with model rates, and thousands of requests use it over the following month. After the provider changes its prices, an engineer updates the catalog and publishes a revised declaration. New requests reference the new pricing version. Completed requests keep their references to the earlier version, preserving the basis of last month's usage. If the engineer finds an error in the new rate and republishes the earlier content, that publication produces a third version instead of deleting the second. HQ staff investigating a discrepancy can inspect all three versions and the requests associated with them.
>
> Published versions cannot change because each request identifies the version it used. Modifying that version could change a request's recorded cost without modifying the request. The explanation of the customer's charge would then disagree with the ledger. Our interpretation is that the same concern explains why rollback publishes a new version rather than deleting an existing version: deletion would orphan requests referencing it. No record gives that reason. The database constraint and persistence tests establish the behavior.

### 9.3 A concept's Why It Exists

**Inadequate**: a concept body centered on explaining table columns.

**Adequate** (the form): "A person's connection to an association is rarely singular or permanent. Someone may work for a member firm, sit on a committee, and later retire while retaining a chapter affiliation. A single employer field cannot preserve all those connections over time; staff have to overwrite earlier information to display the present. Affiliations store each connection as its own dated fact. Connections can coexist, and changes in circumstances do not erase the person's history."

## 10. Keeping Explanations True When Rules Change

Unmaintained narrative becomes an outdated contract that competes with the authoritative contract. Maintenance is part of every change, not work deferred to later cleanup.

- When capability rules change, the impact tool (`node tools/narrative-impact.mjs --since <sha>`) finds the owning feature, journeys using the capability, concepts it acts on, its test specification, and its feature acceptance suite. The same ticket updates those narratives or marks them `stale` with `stale_since`. The conformance check reports all stale artifacts.
- When a feature adds a capability, reread `## Its Capabilities` and `## How It Works`, and check the module's `## How It Is Organized`.
- When a module adds a feature, check the area's `## How the Area Is Divided`.
- When implementation or QA discovers incorrect planning artifacts, fix them through a planning delta (CONVENTIONS §11), not a test note.
- Every ticket-delta, planning, design, and examination brief includes this standard as its authoring contract. Use it from the beginning for every new artifact.

## 11. Who Writes

OpenAI writes every sentence intended for human readers (CONVENTIONS §6 rule 7). In the pipeline's narrative stage, a Claude job collects and organizes sourced evidence into a machine-shaped dossier of motivation records, decisions, observed mechanics, tests, uncertainties, and candidate examples. An OpenAI job uses the dossier, artifacts, and code to write every narrative section. It records `narrative_sources` and files findings and open questions for anything it cannot establish. A second OpenAI job reviews each artifact in fresh context against §8 and the evidence, makes corrections where it can, and records verdicts. Only this review can mark a document `verified`. Claude never replaces the author.

## 12. What Done Means

A module operates under this standard once its narrative stage has landed, its charter includes `explanatory_standard: 1`, every feature, capability, concept, and journey has `narrative.status: verified`, and the conformance check passes. The corpus meets the standard once every registered module meets it. The inventory (`node tools/narrative-inventory.mjs`) reports status by module and kind, and the reverse-engineering dashboard shows those results. The retrofit remains incomplete until every module is shown as verified.