Skip to content

ANNOTATIONS.md

Latest commit

 

History

History
218 lines (148 loc) · 6.78 KB

ANNOTATIONS.md

File metadata and controls

218 lines (148 loc) · 6.78 KB

Structural Explainability Annotation Standard

Structured annotations document decisions, constraints, alternatives, and observations directly alongside code and configuration.

Annotations are human-readable, machine-scannable, and non-enforcing by default. They explain why something is the way it is without turning comments into executable policy.

Core Vocabulary

Five annotations cover the majority of use cases.

Annotation Purpose Use
WHY Rationale Explain intent or trade-offs
OBS Observable fact State current state or measurements
REQ Requirement or constraint Declare invariants
ALT Alternative Document other viable options
CUSTOM Customization point Flag values expected to change

REQ documents intent. It does not imply enforcement unless paired with tooling.

Extended Vocabulary

Three additional annotations support governance-heavy or analytical contexts.

Annotation Purpose Use
MODEL Decision framework Attribute reasoning to a method or model
EVIDENCE Supporting data Cite data underlying a decision
ATTEST Verification Record that validation occurred

Extended annotations are optional. Most repositories need only the core five.

Scoping

Annotations apply at different scopes.

Default Scope

Without qualification, an annotation applies to the immediate next item (line or block).

# WHY: Avoids circular import at module level.
from typing import TYPE_CHECKING

Section Scope

Use === SECTION NAME === markers to define logical boundaries within a file.

# === Environment variables and secrets ===

# WHY: Never commit credentials or environment-specific configuration.
.env
.env.*
*.env

# === LaTeX papers ===

# WHY: LaTeX build artifacts are regenerated on each compile.
*.aux
*.bbl

Annotations apply until the next section marker unless scoped more narrowly.

Use the -SECTION suffix to make section scope explicit:

# WHY-SECTION: All patterns below prevent committing generated artifacts.

Section markers are visual and semantic. The === ... === pattern is conventional but not enforced; any consistent delimiter works.

File Scope

Use the -FILE suffix to apply an annotation to the entire document.

# WHY-FILE: Configuration for explainability and accountability tracking.
# OBS-FILE: Auto-generated; do not edit manually.

Domain Scope

Use dot notation to scope requirements to a domain.

# REQ.PYTHON: Use src/ layout for all packages.
# REQ.UNIVERSAL: Include .gitignore in all repositories.

Common domain scopes:

Scope Applies to
UNIVERSAL All professional repositories
PROJECT This specific project
PYTHON Python projects
RUST Rust projects
LATEX LaTeX documents
CI Continuous integration workflows

Dot notation is syntactic sugar. REQ.PYTHON is equivalent to REQ[scope=python].

Arbitrary Scope

Use bracket notation for scopes not covered by dot sugar.

# REQ[scope=nwmsu-courses]: All student repos must include acknowledgement when generative AI tools are used.
# REQ[scope=civic-interconnect]: Adapters must not define new entity kinds.

General form: ANNOTATION[key=value] or ANNOTATION[value] (shorthand for scope=value).

Scope Precedence

Narrower scope overrides broader scope. REQ.PROJECT overrides REQ.UNIVERSAL for the same concern.

Syntax by Language

Annotations use the same keywords across file types. Only comment syntax differs.

File Type Syntax
Python, YAML, TOML, shell # WHY: Explanation
HTML, Markdown, XML <!-- WHY: Explanation -->
JavaScript, TypeScript, C, Rust, Go // WHY: Explanation
CSS /* WHY: Explanation */
LaTeX % WHY: Explanation

Machine Readability

Annotations are designed to be scannable by tooling.

Core Pattern

(WHY|OBS|REQ|ALT|CUSTOM|MODEL|EVIDENCE|ATTEST)

With Scope

(WHY|OBS|REQ|ALT|CUSTOM)(\.[A-Z]+|\[[^\]]+\])?(-FILE)?:\s*(.+)

By Comment Style

# Python / YAML / TOML / shell
r'#\s*(WHY|OBS|REQ|ALT|CUSTOM)(\.[A-Z_]+|\[[^\]]+\])?(-FILE)?:\s*(.+)'

# HTML / Markdown / XML
r'<!--\s*(WHY|OBS|REQ|ALT|CUSTOM)(\.[A-Z_]+|\[[^\]]+\])?(-FILE)?:\s*(.+?)\s*-->'

# JavaScript / C-style
r'//\s*(WHY|OBS|REQ|ALT|CUSTOM)(\.[A-Z_]+|\[[^\]]+\])?(-FILE)?:\s*(.+)'

Tooling is optional. Annotations work without it.

Theoretical Basis

This standard implements concepts from the Structural Explainability framework.

Annotation CEE Concept
WHY Explanation
OBS Observation
EVIDENCE Evidence set
MODEL Decision model
ATTEST Verification

REQ, ALT, and CUSTOM are pragmatic extensions for engineering use. They document constraints and variation points that support explainability but do not map directly to CEE's formal structure.

Examples

  • Configuration files (e.g., .editorconfig)
  • Build configuration files (e.g., pyproject.toml)
  • Source code (e.g., Python files)

Adoption

When to annotate

  • When a decision matters and future readers might ask why
  • When alternatives exist and the choice is non-obvious
  • When constraints are intentional, not accidental
  • When customization is expected

When not to annotate

  • To restate what the code obviously does
  • To replace proper documentation
  • To enforce style (use linters)
  • On every line (annotations are signal; overuse is noise)

Value lies in clarity, not quantity.

Governance

This standard is maintained at: https://github.com/structural-explainability/.github/blob/main/ANNOTATIONS.md

Changes to the core vocabulary require consideration of downstream adopters. Extended vocabulary and scoping mechanisms may evolve with use.