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

104 lines
9.0 KiB
Markdown

# 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.