This commit is contained in:
maxime committed 2026-11-18 10:51:31 +01:00
1 parent 8e4ebca342
commit 58b630f2d5
112 files changed
+3172 -295

No files matched your search

@@ -0,0 +1,134 @@
# Cases: the labels generalized, for the agents
2026-11-18. Status: draft, for the user's approval.
## Intent
A label is an atomic fact: one station, some sensors, two dates, one conclusion. It is too specific for an analyst to reuse: in the 50 analyses so far, the label search (`precedents.py`) was called in 20, cited from another station for about one label in five, and then mostly "for the wording"; once (MICHIGAN) a validated precedent made the analyst keep two labels below the threshold. What transfers is the general knowledge under the labels: the signature of a phenomenon, its cause, how to tell it from its neighbours, what to tell the client.
That layer exists today in thin form, maintained by hand: the catalogue of phenomena in `families.md` (about 40 lines), the false friends (`reading-rules.md` §6, 12) and the lessons from cases outside the labels (§8, 6). This project turns it into **cases**: one JSON file per case in `auto/cases/`, built and refreshed from the labels by a skill, read by the agents through a RAG that replaces the label search.
## Decided by the user
- Cases are stored in `auto/cases/`, one JSON instance per case.
- A RAG gives access to the cases.
- A skill builds the cases and refreshes them.
- The phenomena and the other domain knowledge are extracted into the cases (they leave the markdown).
- Approach A (below): one skill, the labels split by family across subagents.
- ~~The agents can no longer read the labels through a RAG~~ (reversed by the user the same day): the agents keep the label search (`precedents.py`) next to the case search (`cases.py`), and use either or both.
- The user validates a case by editing its JSON (`review`); the skill never writes it.
## Goals
- Every phenomenon, false friend and lesson of the knowledge files becomes a case, with its provenance.
- The labels of `auto/` feed the cases: each label is attached to the case it illustrates, or proposes a new one.
- A refresh only reads what changed since the last run.
- The analyst (and any agent) finds the cases that fit what it sees, and can list them all to weigh the neighbours.
## Non-goals
- No page for the cases in aimsight-app (later, if wanted).
- No change to the label format, to `ids.py`, `client.py`, or to what aimsight-app calls (`validate.check`, `ids.assign`, `client.message`, `client.action`).
- No use of `manual/`.
- No change to the detectors; in Optimizer, only the pointer below.
## Anti-goals (a failure even if it works)
- A case that is one label reworded: a case is general or it does not exist.
- A rule specific to a station, a target or a date inside a case (the project rule). Where a case was seen is in its sources, not in its text.
- The same knowledge in two places: once a section is in the cases, it leaves the markdown.
- A case search that hides the alternatives: the agent must be able to see every neighbour of a case.
## Constraints
- Standard library only for the scripts (the repo rule); the RAG keeps the bge-m3 model of the `ollama-bge-m3` container and the `.index/` cache, out of git.
- English, UTC, descriptions in words without numeric values (the labels' rule, kept for cases).
- aimsight-app writes in `auto/` at the same time: the skill touches only `auto/cases/`; it never commits (the user commits by path).
- The agents are a read-only plugin (`~/aimsight-agents`): changing the analyst means editing its file there, with that repo's rules (commit by path, check with `claude -p … --agent agents:analyst --model haiku`).
## Approaches
- **A. One skill, the labels split by family** (picked). The skill seeds the cases from the markdown, then one subagent per family reads that family's labels and attaches each to a case or proposes one; the main session merges, writes, checks. Simple, cheap after the first run, incremental. Its weakness, no independent judge of the generalizations, is covered by a guard (below); a judge can be added later.
- **B. Optimizer's upgrader + validator.** Strongest guard against overfitting and circularity, but two agents per run and a commit per change, and both agents were made for targets checked by scripts, where a case is checked by judgment. Not picked.
- **C. Group the labels by their embeddings, then write one case per group.** Dropped: it groups by wording, not by cause (a one-measurement bump reads the same in Visibility, Obstruction and Displacement), which works against the purpose.
## Design
### A case
`auto/cases/<id>.json`, one object, indented for readable diffs:
```json
{
"id": "reference-dropped-base-changes",
"kind": "phenomenon",
"name": "A reference dropped: the base changes",
"family": null,
"signature": "One reference crosses its threshold and is dropped by the compensation: all the targets jump together at that measurement, without any movement of their raw positions; the reprojection error falls to zero.",
"checks": [
"inventory.py with --start/--end: the retained references at that instant",
"overview.py --rigid: the raw positions of the targets do not move"
],
"neighbours": [
{"case": "two-references-lost", "tell_apart": "two of the references dropped one after the other: every point of the range is invalid, not a common jump"}
],
"client": "The family is that of what hindered the reference; the targets moved together because of it, not the structure.",
"sources": ["WYOMING-17", "NIEDERHORN-126", "expert"],
"review": "2026-11-20"
}
```
- `id`: a short English slug, equal to the file name; it never changes (as a label id).
- `kind`: `phenomenon` (what happens), `false friend` (what looks like something it is not), `lesson` (learnt from a case outside the labels).
- `family`: a key of `families.md`, or `null` when the family is that of the cause (the current "Family of the cause" section) or when the case is not a family (most false friends).
- `signature`: what is seen, in the columns and the images: what moves, what does not. For a false friend, what misleads.
- `checks`: how to confirm it with the reading tools (`tools/GUIDE.md`) or the images.
- `neighbours`: the cases it can be mistaken for, each with how to tell them apart; ids of existing cases.
- `client`: what the client is told, when it differs from the family's line in `families.md`; omitted otherwise.
- `sources`: label ids of `auto/` that illustrate it, and the non-label sources: `user` (written by hand by the user in the knowledge files, before the cases), `expert`, `client report`. Never empty. A label may illustrate several cases (a rain label can also show "A reference dropped" and a false friend). [builder check; my call]
- `review`: the date the user validated the case, written by the user by editing the JSON [the user]; the skill never writes it. The skill removes it only when it changes the text of a case (`kind`, `family`, `name`, `signature`, `checks`, a `tell_apart`, `client`); adding a label to `sources` or a neighbour link keeps it, otherwise the most illustrated cases would never stay validated. [my call]
The stations where a case was seen are derived from its label sources; no field for them.
### What moves into the cases, and what stays
- **Moves** (first run): `families.md` "The phenomena" (every bullet, with its section giving `family`), `reading-rules.md` §6 "False friends" and §8 "Lessons from cases outside the labels". Every seeded case gets `user` in its `sources` (none of the phenomena carries a bracketed source; the false friends and lessons are the user's text too), plus its bracketed sources (`[NORDEND-169]` → `NORDEND-169`, `[expert]` → `expert`, `[client report]` → `client report`). [builder check; my call] Each section is then replaced by one line pointing to the cases and to the search.
- **Stays**: in `families.md`, the families table with its "For the client" columns (`client.py` reads them), the varieties table, the boundaries, "What is not labeled"; `labeling-rules.md`; `reading-rules.md` §1 to §5 and §7 (the measurement chain and the reading rules: mechanics, not cases); `stations.md` (installations).
### The skill
`.claude/skills/cases/SKILL.md` in this repo, run by the user in a Claude session here: `/cases`. One procedure; on an empty `auto/cases/` it starts with the seed.
1. **Seed** (only when `auto/cases/` is empty): the main session turns the three markdown sections into cases, links their neighbours, writes them, then removes the sections from the markdown as said above.
2. **What to read**: `auto/cases/.read.json` keeps, per label id, the hash of the text it was read with and the cases it went to (a list, possibly empty). New labels, labels whose text changed, and labels attached to no case are read again; deleted labels are removed from every case's `sources`, and a case left without any source is deleted. A case with a non-label source (`user`, `expert`, `client report`) is never deleted by the skill: hand-written knowledge leaves only by the user's hand. [builder check; my call]
3. **One subagent per family** with labels to read (six at most, in parallel; the largest family is about 55k tokens of descriptions). Each gets: its labels, the full JSON of the cases of its family and of the `null`-family cases, the one-line list of every case, `families.md` and `reading-rules.md`. It returns, as JSON: for each label, the cases it illustrates (existing ids, new ids, or none); the new cases; the changes to existing cases (a sharper signature, a check, a neighbour), each with the labels that justify it.
4. **The guard**: a new case needs labels from at least two stations, or a non-label source. A pattern seen at one station only stays without a case and is listed in the report as a suggestion for `stations.md` (maintained by hand, not written by the skill).
5. **Merge and write** (main session): merges new cases proposed by two subagents for the same thing, links neighbours both ways, writes `auto/cases/` and `.read.json`, runs the check (below) until it says 0 errors.
6. **Report**: in the chat, the cases added, those whose text changed (their `review` removed, to validate again in the JSON), those that only gained sources, the cases deleted, the labels left without a case, the suggestions for `stations.md`.
### The search
`scripts/cases.py`: the RAG of the cases, next to `scripts/precedents.py`, the RAG of the labels, which the user kept (each has its own index in `.index/`).
- `python3 scripts/cases.py "<what you see>" [--family F] [--k N]`: the closest cases, each printed in full with its provenance (validated or not, its label sources with their station and dates). No `--exclude`: a case is general, and the analyst is told that a source inside its own range is not an independent confirmation. [builder check; my call]
- `python3 scripts/cases.py --list`: one line per case (`id`, `kind`, `family`, `name`), without Ollama, so an agent sees every candidate and its neighbours.
- `--index`, `--check` as today. The text embedded for a case: `kind`, `family`, `name`, `signature`. The index file keeps the same mechanics (vectors by hash of the text; vanished texts forgotten).
### The check
`python3 scripts/validate.py` also checks `auto/cases/` (dotfiles ignored): `id` equals the file name; `kind` in the three values; `family` a key of `families.md` or `null`; non-empty `name`, `signature`; every neighbour an existing case; every source a label id present in `auto/` or `expert` / `client report`; no station name (the files of `auto/`) in `name`, `signature`, `checks`, `tell_apart`, `client`. "0 errors expected" stays the single verification.
### What changes elsewhere
- `~/aimsight-agents/agents/analyst.md`: the catalogue of phenomena and the precedents give way to the cases (`cases.py --list`, then `cases.py "<what you see>"`); in the analysis outline, "Phenomenon of the catalogue" and "Precedents" become one line, "Case: <id>, how it fits | none". `agents/support.md`: the cases among what it reads.
- `~/aimsight-app/instructions/analyst.md`: the labels are no longer "read through retrieval" but generalized into cases; their descriptions stay detailed.
- `~/aimsight-tools/GUIDE.md`: the false friends now live in the cases.
- `~/aimsight-optimizer/instructions/upgrader-detectors.md` and `validator-detectors.md`: they read `families.md` for its catalogue too; one line points them to `cases.py --list` and `auto/cases/`, as the user wants the cases read by any agent. [builder check; my call]
- This repo: `README.md` (the knowledge table: the cases are `auto/cases/` through `cases.py`; the tools), `CLAUDE.md` (the same, and "Verify"), `families.md` and `reading-rules.md` intros, `labeling-rules.md` (its pointers to the catalogue), `stations.md` (its pointer to `precedents.py`), `.claude/settings.json` (the permission of `precedents.py` becomes that of `cases.py`).
## Left to the builder
- The exact prompts of the subagents and the JSON they return.
- The slugs of the seeded cases.
- How `.read.json` is laid out, as long as it stays in `auto/cases/` and in git.
- The wording of the pointer lines left in the markdown.