Skip to content

ANNOTATIONS.md

Latest commit

 

History

History
269 lines (186 loc) · 8.16 KB

ANNOTATIONS.md

File metadata and controls

269 lines (186 loc) · 8.16 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 file (.editorconfig)

# REQ.UNIVERSAL: All professional repositories MUST include .editorconfig.
# WHY: Establish cross-editor baseline so diffs stay clean.
# ALT: Omit ONLY if formatting enforced equivalently by CI.
# CUSTOM: Adjust indent_size if organizational standards differ.

root = true

[*]
# WHY: Normalize line endings across Windows, macOS, and Linux.
end_of_line = lf
charset = utf-8

# WHY: Newline at EOF avoids noisy diffs and tool warnings.
insert_final_newline = true

Build configuration (pyproject.toml)

# REQ.PYTHON: Python projects MUST include pyproject.toml as single source of truth.
# WHY: Centralizes metadata and configuration for reproducibility.

[project]
name = "example"  # CUSTOM: Update to match your package.
version = "0.1.0" # CUSTOM: Update as needed.

[tool.ruff.lint]
select = [
  "E",   # REQ: Basic syntax and structural correctness
  "F",   # REQ: Undefined names and unused imports
  # "N", # ALT: Naming conventions (enable if enforcing naming policy)
]

Source code (Python)

# WHY-FILE: Adapter for EU transparency register data.
# OBS: Schema version 2.3, last updated 2025-01.

# WHY: Deferred import avoids circular dependency.
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from cee.core import Evolution

def validate(record: dict) -> bool:
    # REQ: All records must include source jurisdiction.
    # EVIDENCE: See EP Section 4.2 for provenance requirements.
    return "jurisdiction" in record

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.