system-history

# System history Scripts run from the repo root: ```bash H=.agents/skills/system-history/scripts pnpm exec tsx $H/<script>.ts --run <id> [...] ``` Every script accepts `--help`. Exit codes: 0 ok, 1 failed, 2 could not run. Output goes to the run directory described in `fragility-common`. ## Never read history with blob commands This checkout is usually a blobless partial clone. `git show`, `git diff`, `git log -p`, `--stat`, `--numstat` and `git blame` fetch blobs one at a time and stall. Use these scripts instead. If one lacks a capability, extend it. ## Scripts - `doctor.ts`: the base branch is present, and `gh` is authenticated. - `collect.ts`: writes `commits.json`, with first-parent commits on `origin/<baseBranch>` for `--lookback-days`, and the ones inside `--window-hours` marked. It uses tree-level data only, and takes seconds. - `analyze.ts`: writes `analysis.json`, `analysis.md`, and `targets.json`. - **Window mode** (the default): picks the systems the review window touched most. Each gets a percentile score against every active system, plus a triage verdict: `likely-fragile`, `settling`, `mixed`, `coupled`, `likely-fast-moving`, or `insufficient-signal`. Verdicts are leads, not conclusions. - **Focus mode** (`--focus <file,file>`): scores the systems that contain the given files, lists every lookback fix to each file, and lists **regression candidates**. Those are every commit of any kind that touched the files in `--regression-days` (default `regressionDays`). Use `--label "<title>" --label-url <url>` to name what the focus is for. - `--keywords <word,word>`: lists lookback fixes anywhere whose subject matches. Use it to find the same bug class in other systems. - It re-classifies commit subjects on every run, so after tuning `config.json`, re-run `analyze.ts` without collecting again. - `pr.ts --pr N [--file <substring>] [--max-lines N] [--no-diff]`: a PR's description and diff from GitHub. Output is bounded, and truncation is always stated. ## Reading the scores Counts can't tell you why a fix was needed. Before calling a system fragile, read 3 to 6 of its fix PRs with `pr.ts`. The judgment rubric is in `.agents/skills/refactor-plan/references/rubric.md`. ## Tuning Thresholds, ignore lists, system depth, and the regression window live in `config.json`.