finos/morphir-scala / .claude/skills/kb
Manages the Morphir knowledge base under kb/ — OKF bundles and concept documents. Use when adding content to a bundle, creating a new bundle, checking the knowledge base for conformance or provenance drift, building or querying its SQLite index, managing intent through its lifecycle, recording or reading architectural decisions as Decision Records, or navigating, searching and listing its bundles, concepts and links.
| File | Kind | Size |
|---|---|---|
| .gitignore | other | 180 B |
| .mill-version | other | 19 B |
| KbCheck.scala | other | 19.7 KB |
| KbDecision.scala | other | 12.6 KB |
| KbIndex.scala | other | 21.9 KB |
| KbIntent.scala | other | 14.0 KB |
| KbIntentEdit.scala | other | 10.9 KB |
| KbModel.scala | other | 11.7 KB |
| KbRefresh.scala | other | 8.9 KB |
| KbRender.scala | other | 9.0 KB |
| KbScaffold.scala | other | 9.5 KB |
| KbStore.scala | other | 12.0 KB |
| KbSync.scala | other | 46.9 KB |
| KbTests.scala | other | 71.5 KB |
| SKILL.md | skill md | 10.8 KB |
| kbexecutable | script | 459 B |
| kb.bat | script | 485 B |
| kb.scala | other | 43.3 KB |
| millexecutable | script | 6.5 KB |
| mill.bat | script | 9.7 KB |
| references/authoring.md | markdown | 4.7 KB |
| references/checks.md | markdown | 12.0 KB |
| references/commands.md | markdown | 12.8 KB |
| references/decisions.md | markdown | 7.4 KB |
| references/divergence.md | markdown | 3.4 KB |
| references/index-db.md | markdown | 5.2 KB |
| references/sync.md | markdown | 16.7 KB |
| test-resources/META-INF/services/kyo.test.Test | other | 503 B |
references/divergence.md
View on GitHub# Detecting Content Divergence
`kb check` finds mechanical inconsistency — broken links, missing fields, index drift, stale pins. It cannot find the
kind of divergence that actually degrades a knowledge base: two concepts that assert incompatible things, or a
concept that no longer matches the source it claims to summarize.
That needs reading. This is the procedure.
## Start from the mechanical signal
`check` narrows where to look even though it cannot judge content.
```bash
.claude/skills/kb/kb check --verbose --json
```
| Finding | What it suggests reading |
| ------- | ------------------------ |
| `source-commit-drift` | The source moved. Diff it against what the concept claims |
| `source-path-missing` | The source was moved or deleted. The concept may describe something that no longer exists |
| `stale-after-passed` | The author expected churn by now. Assume the content is suspect until re-read |
| `index-description-drift` | Someone edited one of the two and not the other — often a sign of a half-finished revision nearby |
## Diff a concept against its source
For each concept with drift, compare the pinned commit to the checkout's HEAD:
```bash
.claude/skills/kb/kb show --path /naming.md --bundle morphir-ir-v3 --json | jq -r '.sources[]'
```
```bash
git -C .refs/finos/morphir diff <pinned-sha>..HEAD -- docs/spec/ir/morphir-ir-specification.md
```
An empty diff means the pin is merely old, not wrong — re-pin and move on. A non-empty diff needs reading against the
concept's claims.
## Find cross-concept contradictions
There is no command for this; it is a reading task, and these are the shapes worth looking for.
**The same subject in two bundles.** A concept in a specification bundle and one in an implementation bundle
describing the same construct are the most likely pair to drift apart.
```bash
.claude/skills/kb/kb search --query "format version"
```
**The same `type` across bundles.** Concepts sharing a type usually make the same *kind* of claim, which makes
conflicting claims easier to spot.
```bash
.claude/skills/kb/kb search --type "Specification Section" --json | jq -r '.results[] | "\(.bundle)\(.path) \(.description)"'
```
**Version-pair claims.** Anywhere one concept says "unchanged in vN" and another documents a change.
**Divergence notes that have gone stale.** A recorded divergence is a claim with a shelf life — the upstream may have
reconciled it since.
```bash
.claude/skills/kb/kb search --query divergence --body
```
## What to do with what you find
**Record it; do not silently reconcile it.** If two sources genuinely disagree, that disagreement *is* knowledge, and
flattening it destroys information. Write it into the relevant concept with both positions and, if there is one, the
tiebreak.
**Say which source is authoritative.** Often the rule already exists — for the Morphir bundles, `finos/morphir`
`docs/` is authoritative for the specification and `finos/morphir-elm` for how v3 actually behaves. The group's
`README.md` records constraints like these.
**Do not let an implementation rewrite a specification concept, or vice versa.** When the code and the spec disagree,
that is a finding about the project, not an error in the knowledge base.
**Log it.** A divergence discovered and recorded is an `**Update**` entry in the bundle's `log.md`.
## After reconciling
```bash
.claude/skills/kb/kb check
```
Re-pin any sources you re-read, so the next drift report starts from where you actually looked.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |