Files
aimsight-labeling/docs/superpowers/specs/2026-11-16-analyst-knowledge-design.md

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.md pattern), or the same rule in two files.
  • Anti-goal: a station-specific rule. stations.md describes 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.md sections 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 of measurement-chain.md), once;
  • the lessons of barcelona-incident.md and expert-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>.jsonl around 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 of tools/scripts/data.py, inventory.py, quality.py: point to tools/DATA.md and labeling/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:221 and analysis.py:31, Optimizer/README.md:29 cite families.md only: 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:14 AUTO; precedents.py:29 HERE): go up one more level. The index stays at labeling/.index/ (already embedded vectors kept, still ignored by git).
  • Callers: python3 labeling/<script>.py becomes python3 labeling/scripts/<script>.py in agents/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.md and the comment of Diagnostic-App/app/server/station.py:266; then a grep -r over the seven repositories (outside archives and docs/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 -r for label-map, knowledge/ across the seven repositories (outside archives and docs/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.md rather than a separate file (fewer files; already read in full; it has a "Phenomena" column).
  • reading-rules.md drops unconfirmed [H] hypotheses and [E-xxx] events.
  • Citations converted to label ids; unmatched keys become [expert].
  • Everything in knowledge/ archived; nothing kept there.