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
2026-07-11 13:39:13 -04:00
parent d8353953b0
commit b173ac82a9
55 changed files with 3755 additions and 9 deletions

View File

@@ -0,0 +1,61 @@
# Code comments - write WHY, not WHAT
**Binding** for all source files: Python, SQL, SPARQL, PowerShell, YAML, shell.
## Rule
Default to **no comment**. Add one only when the *why* is non-obvious from
the code. If removing the comment wouldn't confuse a future reader, delete it.
A comment earns its place when it captures something the code can't:
hidden constraint, ordering invariant, workaround for a named bug, vendor
quirk, cross-file invariant the type system can't enforce.
## Delete on sight
```python
# Read the manifest file
manifest = read_manifest(csv_root) # function name says it
```
```python
# Increment counter
counter += 1 # pure restatement
```
```python
# Added for the benchmark rework (see task 09)
def run_cell(...): # belongs in commit message, rots in code
```
```python
# TODO: refactor later
# no owner, no trigger - decoration
```
## Keep
```python
# Q5 must scan raw friction_cycles - track_summary is forbidden for this
# query in every format (spec 08); do not "optimize" this into the summary.
```
Cross-file invariant a refactor must preserve.
```python
# Column order matches MANIFEST.csv writer in generate_data.py - keep in sync.
```
Cross-file invariant the type system can't enforce.
```sql
-- BRIN, not b-tree: cycle values are physically ordered within each
-- partition, so BRIN gives the same pruning at ~1% of the index size.
```
Non-obvious engineering decision with a reason.
## Length
Inline: one line. Block: 1-4 lines. If you need more than a paragraph,
the right home is a rule or spec doc - link it from a one-line comment.
Stale comments are worse than missing ones. When you touch a file, fix or
delete comments whose *why* no longer holds.