Two project skills for the procedures this repo keeps getting wrong - #26
Merged
Conversation
…rong
Adds .claude/skills/measure-corpus and .claude/skills/widen-language, plus a
pointer to both from CLAUDE.md. No source changes.
These are not summaries of CLAUDE.md. They encode the step order, the traps, and
the checks that say whether a check actually ran -- the things this project has
had to rediscover by measurement rather than by reading.
measure-corpus is the freeze -> pin -> vary-only-dist/ -> per-row-diff loop. It
leads with the failures rather than the happy path, because the failures are what
cost time here:
- build the comparison engine with an src-only tsconfig, because npm run build
typechecks test/, fails on a branch whose new tests reference new APIs, emits
nothing, and leaves the previous dist/ in place -- so the measurement compares
an engine against itself and reports a perfect match, which is exactly what a
real match looks like
- key rows on corpusPath, assert the row count, and assert the compared fields
exist, because a diff keyed on a field the harness does not emit collapsed 594
rows onto one undefined key and reported "differing: 0"
- byte-identical is not the same as inert (§56). A real fix moved 0 of 576 rows
because 0 of 45 Python corpus files contained the shape it fixes. Count the
occurrences before concluding a change does nothing.
- check line endings after any scripted edit. The repo is uniformly CRLF and
prose files are themselves corpus; a Python rewrite in default text mode
silently flattens a file to LF, which is §45's defect arriving through the
editing tool rather than through git.
widen-language is the extractSymbols -> validator -> region scanner order, with
the §56 measurement showing why the intuitive order is wrong. Scanner-first does
not produce the visible zero the docs promised: a struct or import manufactures a
symbol that body elision cannot destroy, so the drift gate passes with
astMeasured true and S_k 0.0000 having witnessed nothing. On the CLI, where
elision is irreversible, that is silent data loss. The skill carries the step-1
negative control, the requirement to validate the instrument before believing its
output, and the language-choice reasoning that puts Go first.
Committed rather than kept local because they are process knowledge for anyone
working on this repo, and the failures they describe are not ones a newcomer
would predict.
669 tests, typecheck, lint and build green.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.
Adds
.claude/skills/measure-corpusand.claude/skills/widen-language, plus a pointer fromCLAUDE.md. Docs only; no source changes.These aren't summaries of
CLAUDE.md. They encode the step order, the traps, and the checks that say whether a check actually ran — the things this project has had to rediscover by measurement rather than by reading.measure-corpusThe freeze → pin → vary-only-
dist/→ per-row-diff loop, led by the failures rather than the happy path:npm run buildtypecheckstest/, fails on a branch whose new tests reference new APIs, emits nothing, and leaves the previousdist/in place — so the measurement compares an engine against itself and reports a perfect match. A perfect match is exactly what a real match looks like.corpusPath, assert the row count, assert the compared fields exist. A diff keyed on a field the harness doesn't emit collapsed 594 rows onto oneundefinedkey and reporteddiffering: 0.widen-languageThe
extractSymbols→ validator → region scanner order, with the §56 measurement showing why the intuitive order is wrong. Scanner-first doesn't produce the visible zero the docs promised: a struct or import manufactures a symbol that body elision cannot destroy, so the drift gate passes withastMeasured: trueandS_k = 0.0000having witnessed nothing. On the CLI, where elision is irreversible, that's silent data loss.Carries the step-1 negative control, the instrument-validation requirement, and the language-choice reasoning that puts Go first.
Why committed rather than kept local
They're process knowledge for anyone working on this repo, and the failures they describe aren't ones a newcomer would predict. Both loaded and appear in the skills list.
677 tests, typecheck, lint and build green.
🤖 Generated with Claude Code