Skip to content

docs(conventions): group thousands with a comma (phaze-xp9nx) - #543

Merged
SimplicityGuy merged 1 commit into
mainfrom
wt/bead/issue/phaze-xp9nx
Aug 26, 2026
Merged

docs(conventions): group thousands with a comma (phaze-xp9nx)#543
SimplicityGuy merged 1 commit into
mainfrom
wt/bead/issue/phaze-xp9nx

Conversation

@SimplicityGuy

Copy link
Copy Markdown
Owner

Summary

Adds a new section to CONVENTIONS.md, next to "Replace identifiers, never quantities", stating the number-grouping convention for tracked prose: comma grouping (4,383), never space grouping β€” including four-digit numbers.

What it covers

  • The rule: comma groups the integer part; four-digit numbers are grouped too (4,383, never 4383); decimals keep the comma on the integer part and the period as the decimal point (4,761.835).
  • What is never grouped: years, ports, bead ids, version numbers, line numbers, SHAs β€” any identifier that merely looks numeric. Cites the PERF-02 200K false positive in .planning/milestones/2026.7.5-ROADMAP.md to show this is a judgement call about meaning, not a mechanical pattern (and why no grep/lint guard is added).
  • Scope: tracked prose (docs/**, root-level *.md, spike/design docs, planning notes, commit messages, PR bodies) β€” not source code.
  • The measured evidence for why the rule is needed: the corpus already splits by genre (measurement spikes space-grouped, diagnosis spikes and everything else comma-grouped), and how phaze-zaf2l's spike forked because it matched space-grouped exemplars with no written rule to check against.
  • The operator decision (question-as-put, answer-as-given, durable record) that authorizes writing the rule down, and why the answer is comma grouping.
  • A note that the existing space-grouped corpus (~440 matches across 44 files) is being converted under the companion bead phaze-3x7xt, not silently left inconsistent.

Out of scope (deliberately)

  • No existing document's numbers are converted here β€” that's phaze-3x7xt.
  • No mechanical grep/lint guard is added β€” an automated rewrite-on-pattern-match would reproduce the PERF-02 200K false positive.

Validation

just check-fast β€” green: ruff clean, mypy clean, docs-selector correctly picked the 11 prose-guard modules touching CONVENTIONS.md (including tests/shared/test_adr_citation_resolution.py and tests/shared/test_operator_attribution_citations.py), 194 passed.

Bead: phaze-xp9nx

πŸ€– Generated with Claude Code

Adds a new section to CONVENTIONS.md next to 'Replace identifiers,
never quantities' stating the number-grouping rule: comma grouping
(4,383), never space grouping, including four-digit numbers.
Documents the measured genre-split evidence (measurement spikes
space-grouped, everything else comma-grouped), the PERF-02 false-
positive that shows this is a judgement call rather than a mechanical
pattern, and points at the companion backfill bead (phaze-3x7xt)
converting the existing corpus.

Operator decision 2026-08-26 (durable record: phaze-xp9nx): write the
convention into CONVENTIONS.md, with comma grouping as the standard.
@SimplicityGuy
SimplicityGuy merged commit ce5c0c7 into main Aug 26, 2026
11 checks passed
@SimplicityGuy
SimplicityGuy deleted the wt/bead/issue/phaze-xp9nx branch August 26, 2026 05:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant