# 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 ` 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 ` 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(": 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 "` or `"not validated"`; `listing(cs) -> list[str]`, one line per case `" | | | "`; `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 "" [--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: `## — — — similarity <0.00>; `, then `signature`, `checks` (one per line), `neighbours` (`: `), `client` if any, and `sources`, each label id followed by `( → )` 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/.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` ), listed by `python3 scripts/cases.py --list`, searched by `python3 scripts/cases.py ""`." (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": {"