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/"
```