From e2c34c711c14bef4e931e42176426bf76b4d8714 Mon Sep 17 00:00:00 2001 From: maxime Date: Tue, 17 Nov 2026 14:23:56 +0100 Subject: [PATCH] CLAUDE.md, README.md: add, change or remove; a tool removed only for a good reason (superseded or wrong) Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 6 +++--- README.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7be660d..b6407e0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -tools: the reading harness of the AIMsight agents (`README.md`), and nothing else. The user guide is `GUIDE.md`; a new tool or a new option goes into it in the same change. `DATA.md` (what the data are) is maintained by hand by the user; `GUIDE.md` is the upgrader's (`agents` repository, run by Optimizer's `optimize` skill). +tools: the reading harness of the AIMsight agents (`README.md`), and nothing else. The user guide is `GUIDE.md`; a new tool or a new option goes into it in the same change, a removed one leaves it in the same change. `DATA.md` (what the data are) is maintained by hand by the user; `GUIDE.md` is the upgrader's (`agents` repository, run by Optimizer's `optimize` skill). - **Checking a change**: rerun the touched tool from a calling repository (aimsight-app: `python3 tools/scripts/.py data/ --start … --end …`), and the commands of the guide that use it; `python3 tools/scripts/quality.py --self-test` (from the calling repository). @@ -10,9 +10,9 @@ Rules: - No import from the detectors (`detectors/`). - Standard library; matplotlib, through the caller's `.venv/bin/python`, for the figures only. - Never a value from `metrics/` that is an identifier (`SIM_CCID`, `ip*`); read-only on `data/`; never read `.env`. -- Break nothing: existing options and outputs stay, the analyses' reports cite commands that must keep working. +- Break nothing by accident: the analyses' reports cite commands, so a change keeps the existing options and outputs working; only a removal (below) may break one, and its report gives the command that replaces it. - A change to improve the tools touches `scripts/` and `GUIDE.md` only; `README.md`, `CLAUDE.md` and `DATA.md` (the user's) are not part of it. -- Remove nothing: no tool, no option, no output, no sentence of the guide; a tool that did not help on one range may help on another, and a single analysis is not enough to clean the list. Optimise or add. +- Add, change or remove. A sentence of the guide is changed or removed freely. A tool (or one of its options or outputs) is removed only for a good reason, said in the change's report: it is superseded (another tool, or an option of one, now shows the same: nothing is lost), or it is wrong (false values, a judgement in its output) and fixing it costs more than it is worth. Not a reason: it did not help on one range; it may help on another, and a single analysis is not enough to clean the list. Never removed by a change to improve the tools, only proposed to the user: `data.py`, `common.py`, a tool named outside this repository (`README.md`, aimsight-app's `instructions/analyst.md`). - The simplest first: a sentence of the guide or a better default; otherwise an option of an existing tool; a new tool as a last resort. A new script has a docstring at the top, like the others, and enters the table of `GUIDE.md` in the same change. - `scripts/data.py` is the one reader of the station data, shared by the app, the tools and the detectors (which import it: benchmark, Optimizer): touch it only to fix a reading error, never remove or rename a public name. A change to it changes the detectors' benchmark: rerun `python3 detectors/bench/regression.py --labels labeling/auto --data data` from aimsight-app, and say the change at the top of the change's report. Standard library only, no import from the other scripts. - `scripts/common.py`: what the tools share beyond reading (columns, steps, noise, sensor list, runs, file names); standard library, no matplotlib (some tools run with `python3`). A tool imports `data` and `common`, never another tool. diff --git a/README.md b/README.md index a989bd3..2e2f85c 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,6 @@ Without `--out`, the figures go to `out/diagnostic/` of the current folder. Stan ## Who changes it -Only the `upgrader` (`agents` repository) writes there, run by Optimizer's `optimize` skill after an analysis: it brings the analyst's useful scripts into the tools, it optimizes or adds, it removes nothing. +Only the `upgrader` (`agents` repository) writes there, run by Optimizer's `optimize` skill after an analysis: it brings the analyst's useful scripts into the tools; it adds, changes or removes (a tool only for a good reason, `CLAUDE.md`). Copied from aimsight-app (`agent-tools/` and the `lire-les-donnees` skill, commit dd6f1bf) on 2026-11-16. The architecture of the repositories: `~/aimsight-app/docs/architecture.drawio`.