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

+372
View File
@@ -0,0 +1,372 @@
# Cases Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Turn the phenomena, false friends and lessons of the knowledge files into JSON cases in `auto/cases/`, kept up to date from the labels by a `/cases` skill, and give the agents a case search in place of the label search.
**Architecture:** Two standard-library scripts: `scripts/validate.py` gains the format check of a case; `scripts/precedents.py` becomes `scripts/cases.py`, the RAG of the cases (search, list) plus the build bookkeeping (which labels to read, recording which case each label went to). The skill `.claude/skills/cases/SKILL.md` drives the LLM part: seeding from the markdown, one subagent per family, merging, then the scripts. The agents' instruction files in the other repos point to `cases.py`.
**Tech Stack:** Python 3 standard library; Ollama `ollama-bge-m3` (bge-m3:567m) for the embeddings, as today; a Claude Code project skill.
**Spec:** `docs/superpowers/specs/2026-11-18-cases-design.md`
## Global Constraints
- Standard library only in `scripts/`.
- English; every time in UTC; case text in words, without numeric values; no station name in a case's text (where it was seen is in its `sources`).
- `manual/` is never read or written.
- aimsight-app writes in `auto/` at the same time: the build touches only `auto/cases/`; commit by path, never `git add -A`.
- A case `id` equals its file name and never changes.
- The skill never writes `review` and never commits; it removes `review` only when it changes `kind`, `family`, `name`, `signature`, `checks`, a `tell_apart` or `client`.
- A case with a non-label source (`user`, `expert`, `client report`) is never deleted by the skill.
- A new case needs labels from at least two stations, or a non-label source.
- Commits in the other repos (`~/aimsight-agents`, `~/aimsight-app`, `~/aimsight-tools`, `~/aimsight-optimizer`): by path, on their current branch, only once the user has said to commit (aimsight-app is on `feat/weather-meteoswiss`: ask before committing there).
## Review Focus
- A label deleted by aimsight-app between `--pending` and `--record`: its assignment is skipped and reported, not an error (test in Task 3).
- A case file the user broke while editing `review` by hand: every command names the file instead of a traceback (test in Task 2; `validate.py` reports `<file> unreadable JSON`, Task 1 step 3).
- Ollama stopped: `cases.py --list` and `--check` still work (test in Task 2).
- Families with a space (`No data`, `Thermal displacement`): the pending files get slug names (test in Task 3).
- A case the user deleted by hand while labels still point to it in `.read.json`: those labels are read again, nothing crashes (test in Task 3).
---
### Task 1: The format check of a case
**Files:**
- Modify: `scripts/validate.py` (docstring, new constants, `check_case`, `main`, new `self_check`)
**Interfaces:**
- Produces: `CASES = os.path.join(AUTO, "cases")`; `KINDS = {"phenomenon", "false friend", "lesson"}`; `NON_LABEL = {"user", "expert", "client report"}`; `check_case(c: dict, name: str, case_ids: set[str], label_ids: set[str], stations: set[str]) -> list[str]` (the errors of one case; `name` is the file stem). `python3 scripts/validate.py` checks the labels and every `auto/cases/*.json` (dotfiles ignored); `python3 scripts/validate.py cases` checks only the cases; `python3 scripts/validate.py --check` runs the self-test and prints `ok`.
- [ ] **Step 1: Write the failing self-test `self_check()` in `scripts/validate.py`, run by `--check`**
```python
def self_check():
ok = {"id": "a", "kind": "phenomenon", "name": "Targets jump together", "family": None,
"signature": "All the targets jump at one measurement.", "checks": ["overview.py --rigid"],
"neighbours": [{"case": "b", "tell_apart": "b lasts for hours"}], "sources": ["NORDEND-1", "user"]}
args = ({"a", "b"}, {"NORDEND-1"}, {"NORDEND"})
assert check_case(ok, "a", *args) == []
assert check_case({**ok, "review": "2026-11-20", "client": "Nothing to do."}, "a", *args) == []
def bad(change, name="a"):
return check_case({**ok, **change}, name, *args)
assert bad({}, name="x") # id differs from the file name
assert bad({"kind": "rule"}) and bad({"family": "Rain"})
assert bad({"signature": ""}) and bad({"name": ""})
assert bad({"neighbours": [{"case": "zzz", "tell_apart": "x"}]}) # unknown neighbour
assert bad({"neighbours": [{"case": "a", "tell_apart": "x"}]}) # itself
assert bad({"neighbours": [{"case": "b", "tell_apart": ""}]})
assert bad({"sources": []}) and bad({"sources": ["NORDEND-9"]}) # empty, unknown label
assert bad({"signature": "At NORDEND the targets jump."}) # station name
assert bad({"signature": "A jump of 3 mm."}) # numeric value
assert bad({"stations": ["NORDEND"]}) # unknown field
assert bad({"review": "yesterday"})
print("ok")
```
- [ ] **Step 2: Run it to see it fail**
Run: `python3 scripts/validate.py --check`
Expected: FAIL (`NameError: check_case`, or `--check` read as a station)
- [ ] **Step 3: Implement `check_case` and the `main` changes**
Fields allowed: `id`, `kind`, `name`, `family`, `signature`, `checks`, `neighbours`, `client`, `sources`, `review`; required: all but `client`, `review` (`checks` may be an empty list). `family` in `FAMILIES` or `None`. `review` matches `^\d{4}-\d\d-\d\d$`. Text fields searched for a station name (whole word, case-sensitive) and for `NUMBER`: `name`, `signature`, each of `checks`, each `tell_apart`, `client`. In `main`: `--check` → `self_check()`; no argument → labels then cases; `cases` → cases only. Stations are the stems of `auto/*.jsonl`; label ids are every `id` of those files; a case file that is not valid JSON is reported as `<file> unreadable JSON` and the others still checked. Print `N cases: E errors` after the labels' line; exit 1 if any error.
- [ ] **Step 4: Run the self-test and the full check**
Run: `python3 scripts/validate.py --check && python3 scripts/validate.py`
Expected: `ok`, then the labels' line with `0 errors` and `0 cases: 0 errors` (no `auto/cases/` yet: treated as empty).
- [ ] **Step 5: Commit**
```bash
git add scripts/validate.py
git commit -m "validate: the format check of a case (auto/cases/*.json)"
```
### Task 2: The case search, `scripts/cases.py`
**Files:**
- Rename: `scripts/precedents.py` → `scripts/cases.py` (`git mv`), then rewrite its corpus
- Modify: `.claude/settings.json` (the allow rule of `precedents.py` becomes `Bash(python3 scripts/cases.py:*)`)
**Interfaces:**
- Consumes: `validate.CASES` (Task 1).
- Produces, in `scripts/cases.py`: `HERE` (the labeling root); `cases(root=HERE) -> list[dict]` (every `auto/cases/*.json` but dotfiles, sorted by id; a file that is not valid JSON → `sys.exit("<path>: unreadable JSON")`); `labels(root=HERE) -> dict[str, dict]` (every label of `auto/*.jsonl` by id, each with `station` added; never `manual/`); `text(c) -> str` = `f"{c['kind']}. {c.get('family') or ''}. {c['name']}. {c['signature']}"`; `provenance(c) -> str` = `"validated by the user on <review>"` or `"not validated"`; `listing(cs) -> list[str]`, one line per case `"<id> | <kind> | <family or -> | <name>"`; `search(q_vector, cs, vectors, k=8, family=None) -> list[tuple[float, dict]]`; `embed`, `start_ollama`, `updated_index` kept (on `text(c)`); `INDEX = HERE / ".index" / "cases_bge-m3_567m.json"`.
- CLI: `cases.py "<what you see>" [--family F] [--k N]`, `--list`, `--index`, `--check`. The label mode and `--exclude` are gone.
- [ ] **Step 1: Rewrite `check()` in `scripts/cases.py` as the failing test**
Keep the existing Ollama-retry test of `embed`; replace the label tests with:
```python
import tempfile
with tempfile.TemporaryDirectory() as d:
root = Path(d)
(root / "auto" / "cases").mkdir(parents=True)
(root / "manual").mkdir()
a = {"id": "a", "kind": "phenomenon", "name": "A", "family": "Visibility", "signature": "a", "sources": ["S-1"]}
b = {"id": "b", "kind": "false friend", "name": "B", "family": None, "signature": "b", "sources": ["user"], "review": "2026-11-20"}
for c in (b, a):
(root / "auto" / "cases" / f"{c['id']}.json").write_text(json.dumps(c))
(root / "auto" / "cases" / ".read.json").write_text("{}")
(root / "manual" / "S.jsonl").write_text(json.dumps({"id": "S-1", "description": "the user's"}) + "\n")
(root / "auto" / "S.jsonl").write_text(json.dumps({"id": "S-1", "start": "2026-11-04T00:00Z", "end": "2026-11-04T01:00Z", "family": "Visibility", "description": "an agent's"}) + "\n")
assert [c["id"] for c in cases(root)] == ["a", "b"] # sorted, dotfile ignored
assert labels(root)["S-1"]["description"] == "an agent's" and labels(root)["S-1"]["station"] == "S"
assert listing(cases(root)) == ["a | phenomenon | Visibility | A", "b | false friend | - | B"]
assert provenance(b) == "validated by the user on 2026-11-20" and provenance(a) == "not validated"
vec = {key(text(a)): [1.0, 0.0], key(text(b)): [0.6, 0.8]}
assert [c["id"] for _, c in search([0.0, 1.0], [a, b], vec)] == ["b", "a"]
assert [c["id"] for _, c in search([0.0, 1.0], [a, b], vec, family="Visibility")] == ["a"]
before = globals()["embed"] # --list without Ollama
globals()["embed"] = lambda *x: (_ for _ in ()).throw(AssertionError("--list called Ollama"))
try:
main_list(root)
finally:
globals()["embed"] = before
(root / "auto" / "cases" / "c.json").write_text("{broken")
try:
cases(root); raise AssertionError("a broken case must stop with its path")
except SystemExit as e:
assert "c.json" in str(e)
```
- [ ] **Step 2: Run it to see it fail**
Run: `python3 scripts/cases.py --check`
Expected: FAIL (`NameError: cases` / `listing`)
- [ ] **Step 3: Implement the functions and the CLI**
`main_list(root=HERE) -> None` prints `listing(cases(root))`, one line each; the CLI's `--list` calls it. Search output, per case: `## <id> — <kind> — <family or "no family"> — similarity <0.00>; <provenance>`, then `signature`, `checks` (one per line), `neighbours` (`<case>: <tell_apart>`), `client` if any, and `sources`, each label id followed by `(<station> <start> → <end>)` from `labels()`, or `(not in auto/)` when absent; non-label sources printed as they are. `--list` and `--check` never call `embed`. Module docstring: what the cases are, the four commands, the index, the container; `labels()` is there for printing sources and for Task 3, and still never reads `manual/`.
- [ ] **Step 4: Run the self-test and the list**
Run: `python3 scripts/cases.py --check && python3 scripts/cases.py --list`
Expected: `ok`, then nothing (no case yet) and exit 0.
- [ ] **Step 5: Commit**
```bash
git add scripts/cases.py scripts/precedents.py .claude/settings.json
git commit -m "cases.py: the RAG of the cases replaces the label search (precedents.py)"
```
### Task 3: The build bookkeeping, `--pending` and `--record`
**Files:**
- Modify: `scripts/cases.py`
**Interfaces:**
- Consumes: `cases`, `labels`, `key`, `HERE` (Task 2).
- Produces: `READ = "auto/cases/.read.json"` relative to the root, `{label_id: {"hash": str, "cases": [case ids]}}`; `label_hash(label) -> str` = `key(f"{start} {end} {family}. {description}")`; `pending(root=HERE) -> tuple[dict[str, list[dict]], list[str]]` (labels to read by family, ids deleted since the last record); `record(assignments: dict[str, list[str]], root=HERE) -> dict` with keys `added` (`{case: [label ids]}`), `removed` (`{case: [label ids]}`), `deleted_cases` (`[ids]`), `skipped` (`[label ids no longer in auto/]`).
- CLI: `cases.py --pending DIR` writes `DIR/<slug>.jsonl` per family (`no-data.jsonl`, `thermal-displacement.jsonl`…; lowercase, spaces to `-`), one label per line with its `station`, and prints the count per family and the deleted ids; `cases.py --record FILE` reads `{"assignments": {...}}` from FILE, applies `record`, prints its report as JSON.
- [ ] **Step 1: Add the failing bookkeeping test to `check()`**
```python
with tempfile.TemporaryDirectory() as d:
root = Path(d); cdir = root / "auto" / "cases"; cdir.mkdir(parents=True)
def put_labels(*ls):
(root / "auto" / "S.jsonl").write_text("".join(json.dumps(l) + "\n" for l in ls))
def case(i, sources, **kw):
(cdir / f"{i}.json").write_text(json.dumps({"id": i, "kind": "phenomenon", "name": i, "family": None, "signature": i, "sources": sources, **kw}))
def get(i):
return json.loads((cdir / f"{i}.json").read_text())
lab = {"id": "S-1", "start": "2026-11-04T00:00Z", "end": "2026-11-04T01:00Z", "family": "No data", "description": "gap"}
(root / "auto" / "T.jsonl").write_text(json.dumps({**lab, "id": "T-5", "family": "Visibility", "description": "fog"}) + "\n")
put_labels(lab); case("c1", ["user"], review="2026-11-20"); case("c2", ["T-5"])
todo, deleted = pending(root)
assert sorted(l["id"] for ls in todo.values() for l in ls) == ["S-1", "T-5"] and deleted == []
r = record({"S-1": ["c1"], "T-5": ["c2"]}, root)
assert r["added"] == {"c1": ["S-1"]} and get("c1")["sources"] == ["user", "S-1"] # c2 had T-5 already
assert get("c1")["review"] == "2026-11-20" # a new source keeps the validation
assert pending(root) == ({}, [])
put_labels({**lab, "description": "longer gap"}) # same id, text changed: read again
assert [l["id"] for l in pending(root)[0]["No data"]] == ["S-1"]
record({"S-1": ["c2"]}, root)
assert get("c1")["sources"] == ["user"] and "S-1" in get("c2")["sources"]
record({"S-1": []}, root) # no case: stays to read
assert "S-1" in [l["id"] for l in pending(root)[0]["No data"]]
try:
record({"S-1": ["nope"]}, root); raise AssertionError("unknown case must refuse")
except SystemExit:
pass
record({"S-1": ["c2"]}, root)
(cdir / "c2.json").unlink() # deleted by hand by the user
assert "S-1" in [l["id"] for l in pending(root)[0]["No data"]]
case("c3", ["S-1", "T-5"]); record({"S-1": ["c3"]}, root)
put_labels() # S-1 deleted by aimsight-app
assert pending(root)[1] == ["S-1"]
r = record({"S-1": ["c3"]}, root) # assigned after its deletion
assert r["skipped"] == ["S-1"] and get("c3")["sources"] == ["T-5"]
case("c4", ["S-2"]); r = record({}, root) # a seeded source never recorded, gone from auto/
assert r["deleted_cases"] == ["c4"] and not (cdir / "c4.json").exists()
assert (cdir / "c1.json").exists() and get("c3")["sources"] == ["T-5"] # non-label source: never deleted
pending_dir = root / "work"; write_pending({"No data": [lab]}, pending_dir)
assert (pending_dir / "no-data.jsonl").exists()
```
(`write_pending(todo: dict[str, list[dict]], out: Path) -> None` is the function behind `--pending`.)
- [ ] **Step 2: Run it to see it fail**
Run: `python3 scripts/cases.py --check`
Expected: FAIL (`NameError: pending`)
- [ ] **Step 3: Implement `label_hash`, `pending`, `write_pending`, `record`**
`pending`: to read = labels whose id is not in `.read.json`, or whose hash differs, or whose recorded cases list is empty or names a case file that no longer exists; deleted = ids in `.read.json` absent from `labels()`. `record`: first check every case id of `assignments` exists (else `sys.exit` naming it, nothing written); labels in `assignments` but absent from `labels()` go to `skipped`; every source that is neither in `NON_LABEL` nor a label id present in `labels()` is removed from every case (this covers the deleted labels and those a seeded case cited without `.read.json` knowing them), and absent ids leave `.read.json`; for each assigned label, remove it from the `sources` of cases outside its new list, append it to those in it (no duplicate), store its hash and list in `.read.json`; a case file that no longer exists is skipped; then delete the case files whose `sources` became empty. `NON_LABEL` is imported from `validate.py`. Write a file only when it changed, as `json.dumps(obj, indent=2, ensure_ascii=False) + "\n"`, through a `.tmp` and `os.replace`. Never touch `review`.
- [ ] **Step 4: Run the self-test**
Run: `python3 scripts/cases.py --check`
Expected: `ok`
- [ ] **Step 5: Commit**
```bash
git add scripts/cases.py
git commit -m "cases.py: --pending and --record, the bookkeeping of a refresh (auto/cases/.read.json)"
```
### Task 4: The skill `/cases`
**Files:**
- Create: `.claude/skills/cases/SKILL.md`
**Interfaces:**
- Consumes: `cases.py --list`, `--pending DIR`, `--record FILE`, `--index`; `validate.py cases` (Tasks 1–3).
- Produces: the procedure the user runs with `/cases` in a session in `~/aimsight-labeling`.
- [ ] **Step 1: Write the frontmatter**
`name: cases`; `description`: builds or refreshes the cases of `auto/cases/` from the labels of `auto/` and, on the first run, from the phenomena, false friends and lessons of `families.md` and `reading-rules.md`; use when the user asks to build, refresh or update the cases.
- [ ] **Step 2: Write the procedure, with these decisions**
1. **Read first**: the design (`docs/superpowers/specs/2026-11-18-cases-design.md`, sections "A case" and "The skill"), `families.md`, `reading-rules.md`, `cases.py --list`.
2. **Seed, when `auto/cases/` holds no case**: one case per bullet of `families.md` "The phenomena" (`kind` phenomenon; `family` from its `###` heading, `null` under "Family of the cause"), of `reading-rules.md` §6 (`false friend`, `family` null unless the bullet is about one family) and §8 (`lesson`). `sources`: `user` plus the bracketed sources (`[X-12]` → `X-12`, `[expert]` → `expert`, `[client report]` → `client report`). `signature` from the bullet, reworded only to say what is seen; `neighbours` from the entries it says how to tell apart (both ways); `checks` only when the bullet names a tool or a column. No `review`. Then replace the three sections by the pointer below, run `python3 scripts/validate.py` until 0 errors, `python3 scripts/cases.py --index`, report the cases written and **stop**: the label pass is the next `/cases`, after the user has read the seed. Pointer, under the kept heading: "They are the cases: `auto/cases/` (`kind` <phenomenon | false friend | lesson>), listed by `python3 scripts/cases.py --list`, searched by `python3 scripts/cases.py "<what you see>"`." (for the phenomena, add: "A phenomenon not among them is labelled too, without forcing a cause.")
3. **Pending**: `python3 scripts/cases.py --pending .index/cases-work`.
4. **One subagent per family file** (Agent tool, general-purpose, all in one message). Prompt: the family file path; the JSON of the cases of that family and of the `family: null` cases (paths in `auto/cases/`); the output of `cases.py --list`; read `families.md` and `reading-rules.md` in full; never `manual/`; for each label, which cases it illustrates (a label may illustrate several, or none); a new case only for a pattern no case covers, general, without a station or target name, with the labels that show it; a change to a case only with the labels that justify it. Return only this JSON:
```json
{"assignments": {"<label id>": ["<case id>", "..."]},
"new_cases": [{"id": "...", "kind": "...", "name": "...", "family": "...", "signature": "...", "checks": [], "neighbours": [{"case": "...", "tell_apart": "..."}], "client": "...", "labels": ["<label id>", "..."]}],
"changes": [{"case": "<case id>", "field": "signature | checks | neighbours | client | name", "value": "...", "labels": ["<label id>"]}],
"single_station": [{"pattern": "...", "labels": ["<label id>"]}]}
```
5. **Guard and merge** (main session): drop a new case whose `labels` span fewer than two stations (the station is the label id before its last `-`): its labels lose that case in `assignments`, its pattern goes to the report's `stations.md` suggestions; merge new cases two subagents proposed for the same thing (one id, union of labels); write each new case with `sources` = its labels and no `review`; link neighbours both ways (the reverse link reuses the `tell_apart`); apply `changes`, removing `review` from a case whose `kind`, `family`, `name`, `signature`, `checks`, a `tell_apart` or `client` changed.
6. **Record and check**: write the merged `{"assignments": ...}` to `.index/cases-work/assignments.json`; `python3 scripts/cases.py --record .index/cases-work/assignments.json`; `python3 scripts/validate.py cases` until 0 errors; `python3 scripts/cases.py --index`.
7. **Report** in the chat: cases added; cases whose text changed (their `review` removed, to validate again in the JSON); cases that only gained sources; cases deleted; labels left without a case; the `stations.md` suggestions; `skipped` labels. Never commit; never write `review`.
- [ ] **Step 3: Check the skill loads and the pending step runs**
Run: `python3 scripts/cases.py --pending .index/cases-work && ls .index/cases-work`
Expected: one `<slug>.jsonl` per family, counts printed (every label is pending: no `.read.json` yet).
- [ ] **Step 4: Commit**
```bash
git add .claude/skills/cases/SKILL.md
git commit -m "skill cases: build and refresh auto/cases/ from the labels"
```
### Task 5: The seed, and this repo's docs
**Files:**
- Create: `auto/cases/*.json` (by the skill)
- Modify: `families.md` ("The phenomena" replaced by the pointer; line 41 gone with it), `reading-rules.md` (§6, §8 replaced by the pointer; intro line 5: drop "`precedents.py` finds others"), `labeling-rules.md` (line 3: "the catalogue of phenomena are in `families.md`" → the families and boundaries in `families.md`, the phenomena in the cases), `stations.md` (line 3: `precedents.py` → the cases, `scripts/cases.py`), `README.md` (knowledge table: "The cases | `auto/cases/`, built by the `cases` skill, through `cases.py`"; phenomena row and false friends wording; the `precedents.py` bullet becomes `cases.py` with `--list`, `--pending`, `--record`; `review` of a case: written by the user in the JSON), `CLAUDE.md` (knowledge line, tools line, rules line 12 "precedents" → "cases", Verify: `python3 scripts/validate.py`, `python3 scripts/validate.py --check`, `python3 scripts/cases.py --check`)
- [ ] **Step 1: Run `/cases`** (seed branch: `auto/cases/` is empty)
Expected: about 58 cases written (39 phenomena + 12 false friends + 6 lessons, give or take merged entries), the three sections replaced, the skill stops after the seed.
- [ ] **Step 2: Check nothing of the markdown was lost**
Run: `git diff --stat families.md reading-rules.md && python3 scripts/cases.py --list | wc -l`
Expected: the removed bullets ≈ the listed cases; read the diff against `--list`: every removed bullet has its case.
- [ ] **Step 3: Update the docs listed above**, then verify
Run: `python3 scripts/validate.py && python3 scripts/validate.py --check && python3 scripts/cases.py --check && python3 scripts/cases.py "all the targets jump together when a reference is dropped" --k 3`
Expected: `0 errors` for labels and cases, `ok`, `ok`, three cases printed, the first about a dropped reference.
- [ ] **Step 4: Show the user the seed**, ask them to read it before the label pass.
- [ ] **Step 5: Commit** (once the user agrees)
```bash
git add auto/cases families.md reading-rules.md labeling-rules.md stations.md README.md CLAUDE.md
git commit -m "Cases: the phenomena, false friends and lessons moved into auto/cases/ (seed)"
```
### Task 6: The agents read the cases
**Files:**
- Modify: `~/aimsight-agents/agents/analyst.md` (line 11; line 28 drop "the catalogue of phenomena,"; line 30 drop "the false friends, the lessons of cases"; line 33 the precedents bullet → the cases bullet; step 2 at line 45; outline lines 71–72; section 3 at line 82)
- Modify: `~/aimsight-agents/agents/support.md:37` (the cases among the knowledge)
- Modify: `~/aimsight-app/instructions/analyst.md:28`
- Modify: `~/aimsight-tools/GUIDE.md:10`
- Modify: `~/aimsight-optimizer/instructions/upgrader-detectors.md:13`, `~/aimsight-optimizer/instructions/validator-detectors.md:13`
**Interfaces:**
- Consumes: `python3 labeling/scripts/cases.py --list` and `python3 labeling/scripts/cases.py "<what you see>" [--family F] [--k N]` (Task 2), from the callers' roots where `labeling/` is a link.
- [ ] **Step 1: Edit `analyst.md`** with these texts:
- line 11: "The phenomena, false friends and lessons learnt so far are the cases (`labeling/auto/cases/`), drawn from the labels." in place of the catalogue and precedents sentence;
- line 33: "- the **cases**: `python3 labeling/scripts/cases.py --list` (every case, one line each), then `python3 labeling/scripts/cases.py "<what you see>"` (`--family`, `--k` as needed): each with its signature, its checks, its neighbours and how to tell them apart, its sources, and whether the user validated it; a label source inside your own range is not an independent confirmation;"
- step 2: the catalogue becomes the cases (`--list` to see every candidate, the search for what you see); the precedents sentences go; "A phenomenon no case knows is labelled too, without forcing a cause." The rest of step 2 (whole range, `--rigid`) stays;
- outline: "- **Case**: <id>, how it fits and what differs | none" replaces the two lines;
- line 82: "and the precedents" → "and the cases".
- [ ] **Step 2: Check the analyst loads with it**
Run: `cd ~/aimsight-app && claude -p "In one line: which command lists the cases, and which searches them?" --plugin-dir ~/aimsight-agents --agent agents:analyst --model haiku`
Expected: names `labeling/scripts/cases.py --list` and `labeling/scripts/cases.py "<what you see>"`; no mention of `precedents.py`.
- [ ] **Step 3: Edit the four other files**:
- `support.md:37`: after `labeling-rules.md`, add "; the cases, `auto/cases/`, through `scripts/cases.py`";
- `aimsight-app/instructions/analyst.md:28`: "- **The labels** are generalized into cases by the `cases` skill (`labeling/auto/cases/`): their descriptions are detailed, as `labeling/labeling-rules.md` asks.";
- `GUIDE.md:10`: "(the measurement chain, gaps, reading rules); the false friends and the phenomena: the cases (`labeling/scripts/cases.py --list`)";
- Optimizer, upgrader line 13: append "; the mechanisms (phenomena, false friends) are the cases: `python3 labeling/scripts/cases.py --list`, their files in `labeling/auto/cases/`"; validator line 13: "- The families document, and the cases (`python3 labeling/scripts/cases.py --list`)."
- [ ] **Step 4: Verify no reader of `precedents.py` is left**
Run: `grep -rn "precedents" ~/aimsight-agents/agents ~/aimsight-app/instructions ~/aimsight-tools/GUIDE.md ~/aimsight-optimizer/instructions ~/aimsight-labeling/*.md ~/aimsight-labeling/.claude`
Expected: no output.
- [ ] **Step 5: Commit each repo by path** (once the user agrees; aimsight-app's branch confirmed with the user)
```bash
git -C ~/aimsight-agents add agents/analyst.md agents/support.md && git -C ~/aimsight-agents commit -m "analyst, support: the cases replace the catalogue and the precedents"
git -C ~/aimsight-app add instructions/analyst.md && git -C ~/aimsight-app commit -m "analyst instructions: the labels feed the cases"
git -C ~/aimsight-tools add GUIDE.md && git -C ~/aimsight-tools commit -m "GUIDE: the false friends are in the cases"
git -C ~/aimsight-optimizer add instructions/upgrader-detectors.md instructions/validator-detectors.md && git -C ~/aimsight-optimizer commit -m "upgrader, validator: point to the cases"
```
### Task 7: The first label pass
**Files:**
- Modify: `auto/cases/*.json`, create `auto/cases/.read.json` (by the skill)
- [ ] **Step 1: Run `/cases` again** (label branch; six subagents, about 160k tokens of labels in all)
Expected: the report of step 7 of the skill; every label of `auto/` in `.read.json`.
- [ ] **Step 2: Verify**
Run: `python3 scripts/validate.py && python3 scripts/cases.py --pending .index/cases-work`
Expected: `0 errors`; pending lists only the labels left without a case.
- [ ] **Step 3: Spot-check three new or changed cases** against their label sources (`cases.py "<their signature>" --k 1`, then the labels named): general wording, no station name, sources from at least two stations or a non-label source.
- [ ] **Step 4: Commit** (once the user agrees)
```bash
git add auto/cases
git commit -m "Cases: first pass over the labels of auto/"
```
@@ -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.