From 1ce863f76cefc42da8e69ff7d00b6386a969a19e Mon Sep 17 00:00:00 2001 From: Brummel Date: Sun, 31 May 2026 18:17:53 +0200 Subject: [PATCH] chore: add project profile + bootstrap glossary Add .claude/dev-cycle-profile.yml (skills-plugin profile) with paths.glossary pointing at the new docs/glossary.md, so the glossary becomes standing reading for every role. The glossary pins 19 canonical terms bootstrapped from the design spec and source doc comments; canonical forms are English (repo-English rule), German spec-prose forms listed under Avoid. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/dev-cycle-profile.yml | 50 +++++++++++++++++++++ docs/glossary.md | 85 +++++++++++++++++++++++++++++++++++ 2 files changed, 135 insertions(+) create mode 100644 .claude/dev-cycle-profile.yml create mode 100644 docs/glossary.md diff --git a/.claude/dev-cycle-profile.yml b/.claude/dev-cycle-profile.yml new file mode 100644 index 0000000..80808a4 --- /dev/null +++ b/.claude/dev-cycle-profile.yml @@ -0,0 +1,50 @@ +# Project profile for the skills plugin. +# See ~/dev/skills/docs/profile-schema.md for the full schema. + +paths: + spec_dir: docs/specs + plan_dir: docs/plans + glossary: docs/glossary.md # standing reading for every role + code_roots: [src] + +naming: + counter_dirs: [] + policy: date_prefix # specs use YYYY-MM-DD-slug.md + slug_separator: "-" + +commands: + build: "cargo build" + test: "cargo test" + regression: [] + architect_sweeps: [] + +vocabulary: + cycle: cycle + subcycle: iteration + milestone: milestone + ledger_entry: contract + +standing_reading: + always: + - CLAUDE.md + - "git log -10 --format=full" + by_role: {} + +git: + main_sacrosanct: true + only_orchestrator_commits: true + protected_branches: [main] + issue_tracker: + kind: gitea + close_marker: "closes #N" + url: "http://192.168.178.103:3000/Brummel/alpha-id/issues" + list_cmd: "tea issues ls --repo Brummel/alpha-id --state open" + +notifications: + +pipeline: + brainstorm: { gates: [planner] } + planner: { gates: [implement] } + implement: {} + audit: { mandatory_at: cycle_close } + debug: { trigger: bug, red_first: true } diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..68af861 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,85 @@ +# Glossary + +Canonical nomenclature for alpha-id. This file is the source of truth for +the project's terminology: where any other document names a concept +differently, the canonical entry here — and its **Avoid** list — wins. +Each block is a canonical term, an **Avoid** line of synonyms not to use, +and a definition of at most two sentences. (Canonical terms are English, +per the repo-English rule; the spec's German prose forms appear as +synonyms to avoid.) + +### alpha-id +**Avoid:** — +The Rust tool and CLI binary that turns caller-extracted diagnostic phrases into a ranked list of ICD-10-GM code suggestions. Distinct from Alpha-ID, the upstream data source it consumes. + +### Alpha-ID +**Avoid:** — +The BfArM Alpha-ID dataset mapping free-text diagnosis phrases to ICD-10-GM codes; the source of the match corpus. Distinct from alpha-id, the tool that consumes it. + +### extracted phrase +**Avoid:** segment, unit, Einheit, Formulierung +One caller-extracted diagnostic phrase (one input line) — the unit that is matched and ranked. In source code this concept is carried by the identifier `segment` (e.g. `split_segments`, `source_segments`), which is retained as a code term only. + +### Mode C +**Avoid:** Modus C +The lexical-baseline retrieval mode: BM25 over the corpus plus tag filtering, with no IONOS calls. Also the degrade target for Mode A. + +### Mode A +**Avoid:** Modus A, semantic mode +The hybrid retrieval mode: lexical and semantic (IONOS embedding) pools fused via RRF, then cross-encoder reranked. Degrades to Mode C on any IONOS failure. + +### billable +**Avoid:** abrechenbar, Abrechenbarkeit +An ICD code marked `Para295 == "P"` in ClaML, i.e. valid as a standalone billing diagnosis. The `--billable-only` filter and the BillableRecall@10 metric key off this tag. + +### ClaML +**Avoid:** — +The Classification Markup Language XML distribution of ICD-10-GM, parsed for code metadata (chapter, billability, descriptions) and for modifier expansion. + +### modifier expansion +**Avoid:** subclassification, Subklassifikation +The ClaML process of generating terminal sub-digit codes (e.g. `E11.90`) by applying `` definitions, referenced via ``, to a parent category. Produces the synthesized billable leaf codes the corpus matches against. + +### RRF +**Avoid:** — +Reciprocal Rank Fusion: the rank-based method that merges the lexical and semantic candidate lists into one fused pool in Mode A. + +### rerank +**Avoid:** — +The Mode A cross-encoder step that rescores the fused candidate pool against the query phrase, using the IONOS reranker model. + +### corpus +**Avoid:** Korpus, match corpus +The set of Alpha-ID phrase entries that retrieval matches against. + +### embedding store +**Avoid:** embedding cache +The per-phrase, content-hash-keyed persistent store of corpus embeddings under `index/`. Resumable, so an interrupted full embedding run can be continued. + +### vector index +**Avoid:** ANN index +The in-RAM matrix of corpus embeddings searched by exact cosine similarity for the semantic pool. Built only when every corpus entry has a cached embedding; otherwise Mode A degrades. + +### degrade +**Avoid:** — +Mode A falling back to Mode C when any IONOS step fails (embed, rerank, or a missing vector index); the request is still answered and `degraded` is set in diagnostics. Distinct from the 5-char-parent lookup fallback in `meta_lookup`. + +### tag filter +**Avoid:** — +The predicate that drops suggestions by their tags — `billable_only`, `valid_only`, `exclude_exotic`, and `chapters` — applied after ranking and before truncating to the top-k. + +### eval harness +**Avoid:** — +The offline evaluation that injects transcription errors into known billable phrases and measures whether the true code returns in the top-10. + +### exotic +**Avoid:** — +An ICD code tagged `Meta == "J"` in ClaML, marking a rare/exotic code; removable via `--exclude-exotic`. + +### chapter +**Avoid:** — +The ICD-10-GM chapter, stored as a zero-padded two-digit string ("01".."22") derived from the ClaML Roman-numeral chapter code. The `--chapters` filter matches against this value. + +### BillableRecall@10 +**Avoid:** — +The project's lead metric: the share of billable-code eval cases whose true code appears in the top-10 suggestions.