7.5 KiB
name, description
| name | description |
|---|---|
| cases | Builds or refreshes the cases of auto/cases/ (the phenomena, false friends and lessons, one JSON file each) 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 (/cases). |
The cases
A case generalizes labels: the signature of a phenomenon, how to confirm it, how to tell it from its neighbours, what the client is told. The agents read the cases through python3 scripts/cases.py (search, --list); the labels themselves are no longer searched. The design, binding: docs/superpowers/specs/2026-11-18-cases-design.md (sections "A case" and "The skill").
Rules
- Never read nor write
manual/(the user's alone). Touch onlyauto/cases/, and, at the seed, the three markdown sections below; aimsight-app writes inauto/at the same time. - Never write
review, never commit. Removereviewfrom a case only when you change itskind,family,name,signature,checks, atell_apartorclient; adding a source or a neighbour link keeps it. - A case is general: English, words without numeric values, no station or target name in its text (where it was seen is in
sources). A caseidis a short English slug, equal to its file name, and never changes. - Never delete a case that has a non-label source (
user,expert,client report): hand-written knowledge leaves only by the user's hand. - A new case needs labels from at least two stations (the station of a label is its id before the last
-), or a non-label source.
Read first
The design (sections above), families.md and reading-rules.md in full, and python3 scripts/cases.py --list.
Seed: when --list prints no case
- One case per bullet of:
families.md, section "The phenomena":kindphenomenon;familythe key of its###heading,nullunder "Family of the cause";reading-rules.md§6 "False friends":kindfalse friend;familynullunless the bullet is about one family;reading-rules.md§8 "Lessons from cases outside the labels":kindlesson.
- Fields:
sources=userplus its bracketed sources ([NORDEND-169]→NORDEND-169,[expert]→expert,[client report]→client report), dropping a label id thatauto/no longer has;namethe bullet's bold name;signaturethe bullet's text, reworded only to say what is seen (move a station name of the text tosourcesif it is a label, otherwise make it general);neighboursthe entries the bullet says how to tell apart, linked both ways with the sametell_apart;checksonly when the bullet names a tool or a column;clientonly when the bullet says what the client is told and it differs from the family's line; noreview. Write each toauto/cases/<id>.json, indented by two spaces. - Replace the body of each of the three sections (keep its heading) by one paragraph:
- phenomena: "They are the cases:
auto/cases/(kindphenomenon), listed bypython3 scripts/cases.py --list, searched bypython3 scripts/cases.py "<what you see>". A phenomenon not among them is labelled too, without forcing a cause." - false friends: "They are the cases:
auto/cases/(kindfalse friend), listed bypython3 scripts/cases.py --list, searched bypython3 scripts/cases.py "<what you see>"." - lessons: the same with
kindlesson.
- phenomena: "They are the cases:
python3 scripts/validate.pyuntil it says 0 errors for the cases;python3 scripts/cases.py --index.- Report the cases written (
--list) and every bullet that did not become its own case (merged, and into which), then stop: the pass over the labels is the next/cases, once the user has read the seed.
Refresh: when cases exist
-
python3 scripts/cases.py --pending .index/cases-workclears the files of an earlier refresh there, writes one<family>.jsonlper family with labels to read, and prints the counts and the label ids deleted since the last record. -
One subagent per family file, all in one message (Agent tool,
general-purpose), each with this prompt, its<slug>filled in:You attach AIMsight displacement labels to cases. Work in
/home/maxime/aimsight-labeling. Never readmanual/. Read in fullfamilies.mdandreading-rules.md; runpython3 scripts/cases.py --list(every case); read the case filesauto/cases/*.jsonof family<family>and those whosefamilyisnull, and any other case the list makes relevant. Then read every label of.index/cases-work/<slug>.jsonl. For each label, say which cases it illustrates: existing ids, ids of cases you propose, or none. A label may illustrate several cases (rain that also makes the references switch; a false friend it shows). Propose a new case only for a pattern no case covers, general (English, words without numbers, no station or target name), with the labels that show it; give itid(short English slug),kind(phenomenon,false friend,lesson),name,family(a key offamilies.mdor null),signature(what is seen: what moves, what does not),checks(the reading tools or images that confirm it),neighbours(existing or proposed case ids, each withtell_apart), andclientonly if it differs from the family's line. Propose a change to an existing case (a sharper signature, a check, a neighbour, a client line) only with the labels that justify it. A pattern you see at one station only goes tosingle_station, not to a new case. Write only this JSON to.index/cases-work/<slug>.answer.json:{"assignments": {"<label id>": ["<case id>"]}, "new_cases": [{"id": "", "kind": "", "name": "", "family": null, "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>"]}]}Every label of the file appears inassignments. Answer in one line: the number of labels, of new cases, of changes. -
Guard and merge (you, from the answer files of the families
--pendingjust wrote):- drop a new case whose
labelsspan fewer than two stations: remove it from those labels'assignments, and add its pattern to thestations.mdsuggestions; - merge new cases that two subagents proposed for the same thing (one id, the union of their labels; rewrite the assignments to that id);
- write each new case to
auto/cases/<id>.jsonwithsources= its labels, withoutlabelsand withoutreview; - link neighbours both ways (the reverse link reuses the
tell_apart); a neighbour id that does not exist is dropped; - apply
changes(several on the same field: write one text that holds them), removingreviewas the rules say.
- drop a new case whose
-
Record: merge the
assignmentsof those answers into.index/cases-work/assignments.jsonas{"assignments": {...}}, thenpython3 scripts/cases.py --record .index/cases-work/assignments.json. -
Check:
python3 scripts/validate.py casesuntil 0 errors (fix the cases, never the labels);python3 scripts/cases.py --index. -
Report, in the chat: the cases added; the cases whose text changed (their
reviewremoved: to validate again by editing the JSON); the cases that only gained sources; the cases deleted; the labels left without a case (--pendingrun again lists them); thestations.mdsuggestions (the user writesstations.mdby hand); theskippedlabels of the record.