docs(ste): finish Simplified Technical English — the whole workspace is at zero - #57
Merged
Conversation
The crate had no prior STE commits, so its vocabulary was undeclared. Adds a "Read mapping" section to the dictionary (CIGAR, mapper, mate, minimizer, part, preset, template), SAM under formats, and two -ing Technical Names: chaining, the middle step of minimap2's published seed-chain-align method, and pairing, the step that makes two mapped ends into one template. Both also go into ING_OK in the checker, because the -ing rule reads that set and never the dictionary. Same pass fixes one checker false positive: "sibling" matched as an -ing verb. That is 19 of the 557 before a line of prose changed. The other 538 are the eleven files, each carried to zero: pe.rs 119, map.rs 87, output.rs 74, batch.rs 72, index.rs 51, map/tests.rs 38, pe/tests.rs 31, lib.rs 29, preset.rs 21, error.rs 8, examples/map_profile.rs 8. Every measured number survives: the 99.74% parity against the C implementation, the 19.2 and 11.7 GiB index peaks, the 8.93 GB .mmi, the 549 GB of dirtied memory and the 1.4x write-back overshoot, the 332,653-against-332,722 lockstep mismatch, 404 million secondary records at 86.6% of the file, ~26% pool use over a 3 h 40 m stage, and the 9223372036854 Mbase sentinel. Also refreshes "Where the work stands" in the dictionary, which still listed five finished crates as not started. Repo 3,277 -> 2,714. Eight of ten crates at zero; navigator-ui and navigator-domain remain. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SequryftjcFkLnjQRMKCx3
Thirty-one files, 844 -> 0. The dictionary grows by three Technical Names that the crate needs and did not have: `clustering` (the statistical method, under Statistics), `inbreeding` (the population-genetics term that names the F coefficient, same section), and `grounding` (the LLM term for the facts that hold a model to the data, under Local LLM). All three end in -ing, so each also goes into ING_OK in the checker, which reads that set and never the dictionary. Same pass fixes a second checker false positive of the "sibling" kind: "substring" matched as an -ing verb. Nothing else was declared. `sizing`, `weighting`, `voting`, `templating`, `formatting`, `leading` and `trailing` are ordinary English used as gerunds, not domain nouns, and they are rewritten rather than declared. Every fact survives, including the ones the conversion had to carry across a sentence split: the 332,653-against-332,722 style figures in filetype.rs (404 million secondary records at 86.6%, 266 matched of ~260k), the private-Y QC range (~3-39 novel calls per WGS sample), F_ROH ~0.008 for the ground-truth sample, the 61-of-6,218 HTML-entity count in the MDKA corpus, the ~600-700k chip marker count, and the 16,569 bp rCRS window. Two run-together doc comments turned up, both of the shape the dictionary's recipe describes: `roh_brief` in brief.rs and `impute_state` in consensus.rs each have their documentation sitting on the *next* item. This commit only separates the paragraphs so the checker can read them; the relocation is its own commit, because a doc that moves to a different item is a different review. Repo 2,714 -> 1,869. Nine of ten crates at zero; only navigator-ui remains (1,869 in 21 files). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SequryftjcFkLnjQRMKCx3
The STE conversion of navigator-domain surfaced two doc blocks that documented the *next* item, which is the first shape the dictionary's recipe names. `brief.rs`: the documentation of `roh_brief` sat on `ArchaicBrief`, so the struct read as though it also put the wording on a runs-of-homozygosity verdict, and `roh_brief` had none. `consensus.rs`: the documentation of `impute_state` sat on the `INDEL_DERIVED` constant, so a one-line sentinel carried a paragraph about strand-complement matching, and `impute_state` — the canonical base-to-state projection — had none. Both are pure moves. No prose word changes in either file; the only difference is one `///` line in each, the paragraph separator that a merged block needed and two separate blocks do not. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SequryftjcFkLnjQRMKCx3
Twenty-one files, 1,869 -> 0. The dictionary gains a "Desktop UI" section for
the nouns of the egui shell (chip, frame, modal, scroll area, tab, tooltip,
viewport, widget) and `coding` as a genetics -ing Technical Name, with a note
that it is the protein-coding sense and never *colour coding*, which is a colour
code.
This crate was the largest and the most mechanical: the biggest three files
(worker.rs 374, ui/mod.rs 323, cli.rs 188) are nearly half of it, and most of
that is one-line field documentation with an em-dash aside.
Four checker behaviours only show up at this volume, and they are recorded here
because each one cost time:
* `in flight` (17 hits), `cheap` (15) and `expensive` (9) are on the idiom
list. They become "in progress", "the cost is low" and "costs a lot".
* "gets Advanced" trips the passive rule, because "Advanced" ends in `ed`. So
does "are Markdown", on `own`. Reword; do not fight the rule.
* A UI string quoted inside a comment is prose to the checker. `Building your
brief…` and `via Atmosphere` go in backticks, which is honest: they are
literals.
* The sentence splitter needs a capital after the full stop, so a sentence
that starts with a digit, an emoji, or a lower-case crate name silently
merges with the one before it and reports a length that is not there.
Every measured fact survives: the ~60 GB `mapped.bam`, the 1.2M-site autosomal
panel, the ~1,900 catalog strings and the eight undrawable characters they hid,
the 404-million-vs-62-million secondary-record ratio, the 24 folded branches and
1,763 SNPs of the R-Z290 backbone, the 1,200 cM and 200 cM relationship floors,
and the 64 MiB worker stacks with both recursion sources that need them.
Seven run-together doc comments turned up here, of both shapes the dictionary
names. This commit only separates the paragraphs so the checker can read them;
moving them is its own commit.
Repo 1,869 -> 0. **Every crate in the workspace is at zero.**
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SequryftjcFkLnjQRMKCx3
The STE conversion of navigator-ui surfaced seven run-together doc blocks, of
both shapes the dictionary's recipe names.
Stranded docs, moved to the item each one describes:
detail.rs `ystr_sequence_section` carried four docs. Three belong to
`str_section`, `str_consensus_section` and `ystr_report_section`,
all of which had none.
detail.rs `sample_pca` carried the donor-level ancestry summary, which
belongs to `donor_ancestry_summary`.
central.rs `sub_bar` carried "The Subjects work area", which belongs to
`subjects_central`.
worker.rs `reload_genealogy` carried the doc of `handle`, the command-to-
event map itself.
worker.rs `run_chore_streaming` carried the doc of
`deep_analyze_project_streaming`.
Those five are pure moves. No prose word changes in central.rs, and the only
difference in the other two files is the paragraph separator a merged block
needed and two separate blocks do not.
Two summaries of one item, merged:
charts.rs `draw_color_donut` carried both a "generic donut … labels the hole
with the largest slice's share" summary and the pie summary that
replaced it. The function calls `draw_pie` and ignores
`_center_pct`, so the donut text described behaviour that no
longer exists. The pie summary stands, with the two call sites it
serves named.
worker.rs `Command::LoadYProfile` carried two summaries of the same load.
Merged into one.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SequryftjcFkLnjQRMKCx3
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Completes the ASD-STE100 conversion started in #56. The three crates that were
left —
navigator-align,navigator-domainandnavigator-ui— are now atzero, and so is every other crate.
python3 scripts/ste-check.pyover the reporeports 0.
Progress
navigator-alignnavigator-domainnavigator-uiCommits
navigator-alignto zero, and the read-mapping dictionary — 557 → 0 over11 files.
navigator-domainto zero — 844 → 0 over 31 files.roh_briefandimpute_state.navigator-uito zero — 1,869 → 0 over 21 files.Dictionary
Each crate with no prior STE commits needed its vocabulary declared first, so
documents/STE-dictionary.mdgrows three sections and six Technical Names:template, plus the
-ingnameschainingandpairing.viewport · widget.
-ingnames in existing sections:clusteringandinbreeding(Statistics),
grounding(Local LLM), andcoding(Genetics, theprotein-coding sense and never colour coding).
An
-ingTechnical Name has to go in both the dictionary andING_OKinthe checker, because the
-ingrule never reads the dictionary.scripts/ste-check.pyalso gains two false-positive fixes:
siblingandsubstringwere matching as-ingverbs.Declaring was kept deliberately tight.
sizing,weighting,voting,templating,formatting,leadingandtrailingare ordinary English usedas gerunds, so they were rewritten rather than declared.
Facts preserved
The rewrite keeps every measured number, date and sample id — that is the value
of these comments and the point of the exercise. Spot-checked across the diff:
the 99.74% minimap2 parity and its zero disagreements at MAPQ > 0, the 19.2 and
11.7 GiB index peaks, the 549 GB of dirtied memory behind the WindowServer
teardown, the 332,653-against-332,722 lockstep mismatch, 404 million secondary
records at 86.6%, the ~3–39 private-Y QC range, F_ROH ~0.008, 61 of 6,218 MDKA
names carrying HTML entities, the 24 folded branches and 1,763 SNPs of R-Z290,
the 1,200 cM and 200 cM relationship floors, and the 64 MiB worker stacks with
both recursion sources that need them.
Doc comments that were documenting the wrong item
The conversion is how these get found: a block that changes topic in the middle
is obvious once you rewrite it. Nine turned up across the three crates, and they
are moved in two commits of their own — relocating a doc changes the API
documentation, which is a different review from a change to the English. The
word-level proof for each move is in those commit messages.
Gates
cargo clippy --all-targets -- -D warningsclean across the workspace.cargo fmt --all --checkclean.cargo test -p navigator-align48 passed,-p navigator-domain172 passed,-p navigator-ui49 passed. Thenavigator-uiglyph tests, which parse everysource literal, are included.
cargo docproduces no new warnings fornavigator-alignornavigator-domain(compared against a stashed baseline). The same check wasnot run for
navigator-ui:cargo docthere resolves to a differenttoolchain fingerprint and rebuilds the whole dependency graph, so it was
abandoned after 25 minutes.
clippy::doc_lazy_continuation, which is the doclint that actually breaks this build, is covered by the clippy gate above.
🤖 Generated with Claude Code
https://claude.ai/code/session_01SequryftjcFkLnjQRMKCx3