Files
aimsight-labeling/.claude/skills/cases/SKILL.md
T
2026-11-18 10:51:31 +01:00

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 only auto/cases/, and, at the seed, the three markdown sections below; aimsight-app writes in auto/ at the same time.
  • Never write review, never commit. Remove review from a case only when you change its kind, family, name, signature, checks, a tell_apart or client; 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 case id is 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

  1. One case per bullet of:
    • families.md, section "The phenomena": kind phenomenon; family the key of its ### heading, null under "Family of the cause";
    • reading-rules.md §6 "False friends": kind false friend; family null unless the bullet is about one family;
    • reading-rules.md §8 "Lessons from cases outside the labels": kind lesson.
  2. Fields: sources = user plus its bracketed sources ([NORDEND-169] → NORDEND-169, [expert] → expert, [client report] → client report), dropping a label id that auto/ no longer has; name the bullet's bold name; signature the bullet's text, reworded only to say what is seen (move a station name of the text to sources if it is a label, otherwise make it general); neighbours the entries the bullet says how to tell apart, linked both ways with the same tell_apart; checks only when the bullet names a tool or a column; client only when the bullet says what the client is told and it differs from the family's line; no review. Write each to auto/cases/<id>.json, indented by two spaces.
  3. Replace the body of each of the three sections (keep its heading) by one paragraph:
    • phenomena: "They are the cases: auto/cases/ (kind phenomenon), listed by python3 scripts/cases.py --list, searched by python3 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/ (kind false friend), listed by python3 scripts/cases.py --list, searched by python3 scripts/cases.py "<what you see>"."
    • lessons: the same with kind lesson.
  4. python3 scripts/validate.py until it says 0 errors for the cases; python3 scripts/cases.py --index.
  5. 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

  1. python3 scripts/cases.py --pending .index/cases-work clears the files of an earlier refresh there, writes one <family>.jsonl per family with labels to read, and prints the counts and the label ids deleted since the last record.

  2. 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 read manual/. Read in full families.md and reading-rules.md; run python3 scripts/cases.py --list (every case); read the case files auto/cases/*.json of family <family> and those whose family is null, 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 it id (short English slug), kind (phenomenon, false friend, lesson), name, family (a key of families.md or 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 with tell_apart), and client only 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 to single_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 in assignments. Answer in one line: the number of labels, of new cases, of changes.

  3. Guard and merge (you, from the answer files of the families --pending just wrote):

    • drop a new case whose labels span fewer than two stations: remove it from those labels' assignments, and add its pattern to the stations.md suggestions;
    • 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>.json with sources = its labels, without labels and without review;
    • 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), removing review as the rules say.
  4. Record: merge the assignments of those answers into .index/cases-work/assignments.json as {"assignments": {...}}, then python3 scripts/cases.py --record .index/cases-work/assignments.json.

  5. Check: python3 scripts/validate.py cases until 0 errors (fix the cases, never the labels); python3 scripts/cases.py --index.

  6. Report, in the chat: the cases added; the cases whose text changed (their review removed: to validate again by editing the JSON); the cases that only gained sources; the cases deleted; the labels left without a case (--pending run again lists them); the stations.md suggestions (the user writes stations.md by hand); the skipped labels of the record.