Extract the glossary to a root CONTEXT.md - #10
Merged
Conversation
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
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.
Why
docs/agents/domain.mdtells every skill to read aCONTEXT.mdthat does notexist. The glossary it describes does exist, but as a section inside
CLAUDE.md,which no skill looks in. The consequence is not a missing file: it is that the
first
/domain-modelingrun to resolve a term would create a second glossarynext to the first, and this repo has already been burned by exactly that shape
once, which is why
architecture/was deleted.This is the same move #9 made for decisions, one layer down: the content was
never the problem, only its address.
Design
Move the seven terms to a root
CONTEXT.mdand leaveCLAUDE.md's## Vocabularyheading in place carrying a pointer. The heading stays becauseplanning/README.md's deviation 2 links to it andjust check-linksvalidatesanchors; a signpost is not a duplicated fact.
Native structure, local content. The file uses the
## Language/**Term**:/_Avoid_:shape from the skill'sCONTEXT-FORMAT.md, so thatwhen
/domain-modelingappends a term later it writes in the same style and thefile does not drift into two formats. What does not change is the definitions,
which move word for word, and the admission rule above them: a term is listed
only when there is a synonym to reject, or a meaning subtle enough that code and
docs must agree on it.
One deliberate deviation from the stock format.
CONTEXT-FORMAT.mdsays adefinition must be one or two sentences and "totally devoid of implementation
details". Ours name
direct_key,last_read_message_idandGREATEST. That isnot an oversight: this repo's admission rule turns on a term's meaning being
subtle enough that code and docs must agree, and the mechanism is usually where
that subtlety lives. Strip
direct_keyfrom Direct chat and what remains is"a chat between two users", which no longer explains why opening one twice is an
upsert rather than a read-then-race. The precision is the reason the entry
exists.
planning/README.md's deviation 2 is repointed from../CLAUDE.md's Vocabularysection to
../CONTEXT.md.Non-goals
definitions and the same
Avoidlists. Only the container changed.docs/agents/domain.md. It already namesCONTEXT.mdanddocs/adr/; with Convert planning/decisions to numbered ADRs in docs/adr #9 merged and this PR, both finally exist, so its consumerrules describe the repo as it now is rather than as it was planned to be.
CONTEXT-MAP.md. This repo is single-context, which iswhat
docs/agents/domain.mdstates.about where a record lives, so this body is where it belongs.
Verification
Docs only: no Python, no configuration, no migration, no test is touched.
just lintpasses (ruff format: 100 files unchanged;ruff checkandty check: all checks passed).just check-linkspasses (links: OK) — the gate that matters here, sincethe change is one new file and two repointed cross-references, one of which is
an anchor into a heading that had to survive.
just check-adrspasses (adr: OK),just check-planningpasses (planning: OK).grepconfirms no "Vocabulary section" reference remains anywhere.just testandjust test-migrationswere not run: this diff contains noPython and nothing either of them reads. Both passed on
mainat Convert planning/decisions to numbered ADRs in docs/adr #9(109 and 4 tests, 100% coverage) and nothing here can affect them.