Repository navigation
OKF schema: dedicated cluster field + controlled topic vocabulary - #4
Merged
Merged
Conversation
…ulary Groundwork for a bundle viewer, fixing two data-model problems in the cards. Phase 1 — promote the thematic cluster out of the tags[0] positional hack into a dedicated `cluster:` frontmatter field across all 426 cards. Extract the card schema from CLAUDE.md into docs/schema.md. Update validate_okf.py to key card<->synthesis correspondence off `cluster`, and reword README, the web-resource-crawler agent, and the /sync + /ask skills. Phase 2 — consolidate 1255 free-form, LLM-generated topic tags (77% used once) into a 222-slug controlled vocabulary in docs/topics.md. Rewrite every card's `tags` through the mapping and have validate_okf.py reject any tag outside the vocabulary. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`rust` was its own heading with only one slug; move it under the broader languages heading. Vocabulary unchanged (222 slugs); no card changes. Co-Authored-By: Claude Opus 4.8 <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.
Data-model cleanup of the OKF bundle, as groundwork for a planned local viewer. Two independent problems fixed; no card content changed beyond frontmatter.
Phase 1 — cluster is now a dedicated field
The thematic cluster was previously smuggled into
tags[0](a fragile positional overload). It's now a dedicatedcluster:frontmatter field on all 426 cards (396 concept + 30 synthesis). Per-cluster counts are identical before/after.docs/schema.md— the house-style schema, extracted fromCLAUDE.md(which now links to it), mirroring the Repodo monorepo'sdocs/schema.md.validate_okf.pykeys card↔synthesis correspondence offclusterand requires it non-empty.tags[0]reference inREADME.md, theweb-resource-crawleragent, and the/sync+/askskills.Phase 2 — topic tags are now a controlled vocabulary
tags[1:]were free-form LLM output: 1255 distinct tags, 77% used exactly once, with heavy overlap. Consolidated to a 222-slug controlled vocabulary indocs/topics.md(13 themes).tagsrewritten through the mapping (avg 5.07 → 3.8 tags/card; no card left tagless).validate_okf.pynow rejects any card tag not present indocs/topics.md, so the sprawl can't return;/syncand the crawler draw tags from the list or propose additions.Notes
docs/topics.md(a few instance→category folds, e.g.money/currency→value-objects);crudandserverlesswere kept as their own topics per review (cards taggedcrudalso carrydatabases).python3 scripts/validate_okf.py→ OK — all invariants satisfied.🤖 Generated with Claude Code