LabDataStorageEvaluation/docs/rules/meta-rules-naming.md

Meta / Rule file naming

Binding for files inside docs/rules/. Adding, renaming, or splitting a rule file follows this document.

Layout

• docs/rules/ - binding rules (this folder): reproducible conventions on HOW work is done. Reference content that supports a rule also lives here, named <rule>-reference.md.
• docs/specs/ - the pipeline task specifications (WHAT to build: tasks 01-11, their inputs, outputs, and dependencies). Binding for scope and deliverables, but conventions that span tasks are codified in docs/rules/.
• docs/examples/ - imported reference materials (master plan, ontology). Descriptive, not binding.

Files live flat at the top level of docs/rules/. No subfolders.

Naming

<domain>-<subdomain>-<topic>[-<aspect>].md

• Lowercase, dashes between segments. No underscores, no CamelCase.
• Max 4 segments. Most general first.
• Reading the filename should answer: category -> subcategory -> topic.

Approved domain prefixes

Prefix	Covers
bench-	Benchmark execution, resource measurement, extrapolation, reporting methodology
build-	Pipeline task orchestration: the ./out/ tree, .done markers, task order
code-	General code style across languages (Python, SQL, PowerShell): comments, formatting, error handling, configuration
data-	The simulated dataset: determinism, identifiers, units, column naming
db-	SQLite / PostgreSQL benchmark target schemas, loading, indexing
meta-	Rules about the rules system and working conventions
obs-	Observability and logging
test-	Validation gates, checksums, pytest conventions

Don't invent a new prefix without adding it to this table in the same commit.

Subdomains (second / third segment)

Within a domain, the second segment is a recognised tool, subsystem, or concern; the third is the concrete topic. Established families:

• db-sql-* - relational benchmark targets (SQLite, PostgreSQL): schema, loading, indexing.
• data-* - dataset conventions (data-determinism, data-naming-units).
• bench-* - measurement methodology (bench-methodology).
• build-pipeline-* - task orchestration and artifact layout.
• code-* - general code style (comments, formatting, error handling, config, Python style).
• meta-* - rules about the rules system and working conventions.
• obs-* - observability and logging (obs-python-logging).
• test-* - validation and testing (test-pipeline-validation).

Examples

Good	Reads as
data-determinism.md	Data -> deterministic generation
db-sql-schema.md	DB -> SQL -> schema conventions
bench-methodology.md	Benchmarks -> measurement methodology
code-python-style.md	Code -> Python -> style
obs-python-logging.md	Observability -> Python logging
meta-rules-naming.md	Meta -> rules system -> naming

Bad	Why
BenchMethodology.md	CamelCase forbidden
data_determinism.md	Underscores forbidden
sqlite-loading-conventions.md	Use db- prefix, drop redundant conventions
bench-execution-measurement-rules-doc.md	5+ segments + redundant rules suffix

Adding a rule

1. Pick the domain prefix; add new ones to the table above first.
2. Check ls docs/rules/ - extend a sibling rule before creating a new one.
3. Create the file with binding content, examples, and exceptions.
4. Add a row for the new file to the rule-trigger table in the root CLAUDE.md in the same commit.
5. If replacing an older doc, git mv to preserve history and Grep the repo for the old path.

Rules vs specs vs memory files

Three homes for a statement; pick by its kind:

Source	Stores
docs/rules/<name>.md	A reproducible, mandatory behaviour - the same answer for every contributor on every task within the topic.
docs/specs/NN_<task>.md	The definition of one pipeline task: scope, inputs, outputs, dependencies.
memory/<name>.md	A fact about this user, this project, or the current moment - preferences, ongoing initiatives, locked decisions, infra specifics.

• A convention that must hold across several tasks -> docs/rules/.
• A deliverable of one task -> its spec in docs/specs/.
• A fact about the user or the present state of things -> memory/.

A rule file may reference a spec or a memory note for context, but the binding convention lives in the rule file. When a rule and a spec disagree on a convention (naming, formats, thresholds), the rule wins and the spec is updated to match.

Anti-patterns

• Duplicating rule content across rule files - pick one canonical location and cross-link from siblings instead of copying.
• Restating a whole spec inside a rule - the rule codifies the reusable convention and links the spec for task detail.
• Adding rules to the body of CLAUDE.md instead of creating a rule file - CLAUDE.md carries only the trigger table, the project preamble, and the canonical-source-of-truth note.
• Naming a file after the implementation instead of the domain (oxigraph-loading.md vs db-rdf-loading.md) - the implementation may be replaced; the topic endures.