9.0 KiB
The analyst's domain knowledge: one source per kind
2026-11-16. Approved by the user on 2026-11-16.
Why
Since precedents.py (the RAG over labeling/auto/), the analyst gets the same knowledge twice: as cases cited inside label-map.md and as cases retrieved by the RAG. The user no longer knows which file to maintain, nor which one prevails. label-map.md is frozen: it was regenerated by /labels-map in Support-Agent (obsolete), partly from manual/, which no process may read any more. knowledge/ mixes data formats, domain knowledge, project history and an outdated note (thermal-cycle.md contradicts D-117).
Success: for each kind of knowledge, one file (or the labels), maintained by hand by the user, and the analyst reads exactly those. Nothing derived, nothing written twice.
Goals, non-goals, anti-goals
- Goal: one source per kind of knowledge; the analyst's mandatory reading shrinks, and nothing it relied on is lost.
- Non-goal: feeding the gaps reported by analyses (section 3: the "comb", a jolt inside a thermal cycle…) back into the rules. Later, separate work.
- Non-goal: changing
precedents.py. It already refreshes its index on each call (new or changed labels embedded, removed ones dropped): no hook needed. - Anti-goal: a file generated from labels (the old
label-map.mdpattern), or the same rule in two files. - Anti-goal: a station-specific rule.
stations.mddescribes installations; it states no rule.
Constraints
- Runs after the English migration (
Diagnostic-App/docs/superpowers/plans/2026-11-16-english-renames.md) is committed; names below are the English ones; new text in English. manual/stays unread by any process.- tools: "a tool returns values: no threshold, no category, no 'normal'". So tools holds what the data are, labeling what they mean.
- Commits by path, never
git add -A; one commit per repository.
Approaches considered for the phenomenon cards (decided by the user: B)
- A. Drop them, rely on the RAG. Least upkeep; the analyst only finds the right cases if it already describes what it sees with the right words; rare phenomena get lost.
- B. A short catalogue, one line per phenomenon (name, signature, how to tell it from its neighbours), the RAG for the detailed cases. Gives the analyst its list of hypotheses for ~40 lines.
- C. Keep the full cards, maintained by hand. Richest; 120 KB largely redundant with the labels.
Target layout
| Kind of knowledge | Source | Read by the analyst |
|---|---|---|
| Cases | labeling/auto/*.jsonl, through precedents.py |
on demand |
| Families, boundaries, phenomenon catalogue | labeling/families.md |
in full |
| How to write a label | labeling/labeling-rules.md (unchanged) |
in full |
| What the data mean: measurement chain, gaps, reading rules, false friends, lessons of cases | labeling/reading-rules.md (new) |
in full |
| Installation of each station | labeling/stations.md (new) |
in full (short) |
| What the data are: export formats, columns, quality metrics, IRON/DIFF images | tools/DATA.md (new) |
in full, with GUIDE.md |
labeling/families.md
Unchanged, plus a section "Phenomena": per family, one line per phenomenon of the old map's table of contents (sections A to G): name; what is seen (signature, from the card's "what is seen"); how to tell it from its neighbours (from the card and the false friends). Phenomena whose family is that of their cause (a reference set aside, two references lost) go in a short last group, "Family of the cause". No case citations in this section: cases come from the RAG.
Note: Optimizer's /improve (upgrader, validator) also reads families.md (FAMILIES:); the catalogue is useful to them too.
labeling/reading-rules.md
Compiled from:
knowledge/measurement-chain.md: how a measurement is made (section 1), where each cause enters and what it touches (section 2), the three thermal effects (section 3);knowledge/gaps.md;label-map.mdsections 2 (reading rules: the expert's, then those established by labels) and 3 (false friends);- the non-negotiable rules (end of
displacement-columns.md, section 4 ofmeasurement-chain.md), once; - the lessons of
barcelona-incident.mdandexpert-annotated-cases.md(neighbouring prisms interfering, vegetation growing over weeks, masked references giving a 24 h cycle on pan/tilt, compensation instability falsifying the amplitude of a real movement), without the case narratives.
Removed: what families.md or labeling-rules.md already say; [H] hypotheses not confirmed by labels; sources and paths of Support-Agent; the "open questions" sections.
Citations: a label key STATION DD.MM HH:MM becomes the label's id (NORDEND-80), found in auto/<STATION>.jsonl by station and start (the sensor or family in parentheses disambiguates). A key with no match in auto/ (an expert label of manual/) becomes [expert], without a key. Events [E-xxx] are dropped (the events base is in Support-Agent).
labeling/stations.md
From label-map.md section 4, one row per station: structure (bridge, rock face, tunnel, building…), camera (measurement interval, shelter, power), references (number, twins, local references read as targets), neighbouring cameras. The column "what recurs in its labels" is dropped: that is the RAG's job. Header: context for reading, not a rule; the expert rule "the kind of structure says whether a thermal movement is possible" depends on it.
tools/DATA.md
Compiled from displacement-columns.md, quality-metrics.md, camera-images.md: the export formats and the meaning of each column, the unit of corr_x/corr_y, the camera pose and the sign of tilt, the six quality metrics and their reading, IRON vs DIFF. Removed: pumping history, the LENZSPITZE conversion (keep one line: its x/y are rewritten in image pixels by the extraction), the to-do list for the detectors, Support-Agent sources. Maintained by hand, beside GUIDE.md (which stays the tool-builder's).
Archived to labeling/docs/archive/
label-map.md and all of knowledge/ (thermal-cycle.md outdated; the others once compiled). Git history keeps the rest.
Consumers to update
agents/agents/analyst.md: reading list (families.md,labeling-rules.md,reading-rules.md,stations.md,tools/GUIDE.md+tools/DATA.md, the RAG,auto/<STATION>.jsonlaround the range); step 2 of the procedure ("look up the phenomenon in the map") becomes: the catalogue gives the hypotheses, the RAG the cases; the analysis template's "Phenomenon of the map" becomes "Phenomenon of the catalogue".tools/GUIDE.md("Read first"), docstrings and messages oftools/scripts/data.py,inventory.py,quality.py: point totools/DATA.mdandlabeling/reading-rules.md(gaps).labeling/README.md,labeling/CLAUDE.md: the target layout table, who maintains what (the user, by hand).Diagnostic-App/consignes(or its English name) if it cites the map;Diagnostic-App/app/server/station.py:221andanalysis.py:31,Optimizer/README.md:29citefamilies.mdonly: unchanged.
Last step: the scripts in labeling/scripts/ (asked by the user)
Done after the knowledge layout is verified, as its own commit.
git mv validate.py ids.py precedents.py scripts/.- Paths: each script finds
auto/from its own location (validate.py:19,ids.py:14AUTO;precedents.py:29HERE): go up one more level. The index stays atlabeling/.index/(already embedded vectors kept, still ignored by git). - Callers:
python3 labeling/<script>.pybecomespython3 labeling/scripts/<script>.pyinagents/agents/analyst.md(lines 33, 60), the scripts' own docstrings and messages,labeling/README.md,labeling/CLAUDE.md,labeling/.claude/settings.json(permissions),Diagnostic-App/README.mdand the comment ofDiagnostic-App/app/server/station.py:266; then agrep -rover the seven repositories (outside archives anddocs/superpowers/). - Check:
python3 scripts/validate.py(same errors as before),python3 scripts/ids.py(changes nothing),python3 scripts/precedents.py --check, and one real query (the index is found, nothing re-embedded).
Verification
python3 validate.py(expected errors unchanged),python3 precedents.py --check.grep -rforlabel-map,knowledge/across the seven repositories (outside archives anddocs/superpowers/): nothing left.- Load check:
claude -p "<short question>" --plugin-dir ~/agents --agent agents:analyst --model haiku. - A real run on an already analysed range, NORDEND 2026-11-05 06:00 → 12:00, from Diagnostic-App: compare its labels with the previous analysis, and read its section 3 ("documentation") for anything it now misses.
- Mandatory reading size before and after (bytes of the files read in full).
Calls made by Claude (to check)
- Catalogue inside
families.mdrather than a separate file (fewer files; already read in full; it has a "Phenomena" column). reading-rules.mddrops unconfirmed[H]hypotheses and[E-xxx]events.- Citations converted to label ids; unmatched keys become
[expert]. - Everything in
knowledge/archived; nothing kept there.