fix(docs): fix formatting issues in README.md
- adapt meta-/code-/obs- rules to the local Python benchmark pipeline - replace db-sql-ddl, code-config-env-scope, test-e2e-pytest with pipeline equivalents - add code-python-style, data-determinism, data-naming-units, bench-methodology, build-pipeline-tasks - normalize specs and README typography to ASCII per code-data-formatting - rewrite root CLAUDE.md trigger table; add .cursorrules and .gitignore - specs: pipeline plan and task specs 00-11 - rules: 19 binding rule files adapted for this project - docs: CLAUDE.md rule-trigger table - config: .cursorrules commit convention, .gitignore excluding out/ and .venv/ - docs: rewrite README.md with pipeline diagrams, setup guide, result placeholders - config: requirements.txt for the closed dependency list - datagen: make_lab_config.py writes out/config/lab_config.yaml and .done marker
This commit is contained in:
administrator
119
docs/rules/meta-rules-naming.md
Normal file
119
docs/rules/meta-rules-naming.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# Meta / Rule file naming
|
||||
|
||||
**Binding** for files inside [`docs/rules/`](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`](../../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.
|
||||
Reference in New Issue
Block a user