Files
2026-11-18 10:51:31 +01:00

373 lines
29 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/"
```