Files

3.1 KiB

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, 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/<tool>.py data/<STATION> --start … --end …), and the commands of the guide that use it; python3 tools/scripts/quality.py --self-test (from the calling repository).

Rules:

  • A tool returns values: no threshold, no category, no "anomaly", no "normal"; the analyst judges.
  • Nothing specific to a station, a sensor or a date.
  • 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 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.
  • 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.
  • Every time is in UTC. Commits by path, never git add -A. Language: English.