Skip to content

Record why H6 reads no title by shape before a family comma - #724

Merged
derek73 merged 3 commits into
masterfrom
docs/h6-abbreviated-surname-rationale
Oct 19, 2026
Merged

derek73 merged 3 commits into
masterfrom
docs/h6-abbreviated-surname-rationale

Conversation

@derek73

@derek73 derek73 commented Oct 19, 2026 •

Copy link
Copy Markdown
Owner

Summary

H6 (a title before a family comma) decided in #701 that only the title vocabulary claims a word before a family comma, never H2's period shape, so Xyz. Smith, John keeps family Xyz. Smith. The decisions entry gave two reasons, the doctrine (the slot is a surname's slot, as at H5) and the absence of need, and named no surname the shape would break. Closing #710 raised the question again ("surnames don't end in periods"). It turns out there is a cost:

  • A surname can open with an abbreviated word. Filipino records write Santa and Santo as Sta. and Sto., and H2's shape (two or more letters, one trailing period) claims both.
  • Sta. Maria, Juan reads family Sta. Maria today. With the shape rule it would read title Sta., family Maria.
  • US Census 2010 surname bearers (tools/name_usage.py, 2026-10-18): Sta. Ana 408, Sta. Maria 376, Sto. Domingo 163, Sta. Cruz 110.
  • ste is a particle and no title, so Ste. Marie, Jean never enters H6's run. sta and sto are in no vocabulary set.
  • The Census strips punctuation, but Santa Maria is its own entry (12,375 bearers), so these counts are the people recorded with the abbreviation.

H6 stays as decided. This PR records the reason so it isn't asked a third time:

  • decisions/H6: a 2026-10-18 entry with the counts and the recompute command. It also records a gap this rule doesn't close: the comma-less Juan Sta. Maria already splits the surname (middle 'Sta.', family 'Maria'). Listing sta/sto as particles fixes that (measured). As never-given particles, they'd make P1's fold take a bare leading Sta (Sta Juan → family 'Sta Juan'). Listed as ambiguous, they keep given 'Sta' and add a report. Neither listing is decided here; that question is Should Juan Sta. Maria read family Sta. Maria? Today it reads middle Sta., family Maria #725.
  • rules/H6: the rationale names the abbreviated-surname class, and "Sta. Maria, Juan" → family="Sta. Maria" joins the boundary examples, so the reading is now an executable pin.
  • corpus_rules.jsonl and snapshot.jsonl each gain the one new example name. No other reading moves.

No parser code changes.

Review

The design-docs review found four inaccuracies in the first draft of the decisions entry, all fixed in 7d8be67: the Juan Sta. Maria example, the Ste. reason, how to read the Census counts, and the unmeasured Mt./Ft. counts. Its review of that fix commit came back clean, and ba7a3ba states the one condition it flagged.

Test plan

  • uv run pytest: 21,314 passed
  • The snapshot diff is the one new name (Sta. Maria, Juan)

🤖 Generated with Claude Code

decisions/H6 point (1) gave only the doctrine and the absence of need for
skipping H2's shape before a family comma. #710's close-out asked again
whether `Xyz. Smith, John` could read title 'Xyz.'. There is a cost: a
surname can open with an abbreviated word, and Filipino records write
Santa and Santo as `Sta.` and `Sto.`, which the shape would take as
titles (`Sta. Maria, Juan` -> title 'Sta.'). The decisions entry records
the Census counts and what reopening would need. rules/H6's rationale
names the class, and gains `Sta. Maria, Juan` as a boundary example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@derek73 derek73 added docs Documentation fixes and updates design labels Oct 19, 2026
@derek73 derek73 self-assigned this Oct 19, 2026
derek73 and others added 2 commits October 18, 2026 18:17
The Juan Sta. Maria example presented a fix as a risk: today it already
splits the surname (middle 'Sta.'), and particle status fixes it. The
real open cost is P1's fold on a bare leading Sta, which the ambiguous
listing avoids (both measured). Ste. Marie, Jean stays whole because
ste is no title, not because of point (3)'s stop. The Census counts are
bearers recorded with the abbreviation (Santa Maria is a separate
12,375-bearer entry). Mt./Ft. counts recorded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A shape peel gets a stop from a particle listing only if it keeps point
(3)'s particle stop, which H2's comma-less head does not have
(Ste. Marie Jean reads title 'Ste.').

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Oct 19, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.04%. Comparing base (16ee285) to head (ba7a3ba).

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #724   +/-   ##
=======================================
  Coverage   99.04%   99.04%           
=======================================
  Files          46       46           
  Lines        4585     4585           
=======================================
  Hits         4541     4541           
  Misses         44       44           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@derek73
derek73 merged commit c726650 into master Oct 19, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

design docs Documentation fixes and updates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant