System history
Scripts run from the repo root:
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.
1---2name: system-history3description: >-4 Blobless-safe git and PR history for this repo. Collects first-parent5 commits, scores systems against the repo's own baseline to separate fragile6 from fast-moving, lists recent changes to specific files as regression7 candidates, and reads PR diffs through GitHub. Use when you need to know how8 an area has been changing, what recently touched a file, or what a PR did.9scope: dev10metadata:11 source: https://skillmd.com/skills/builderio/system-history12 internal: true13---1415# System history1617Scripts run from the repo root:1819```bash20H=.agents/skills/system-history/scripts21pnpm exec tsx $H/<script>.ts --run <id> [...]22```2324Every script accepts `--help`. Exit codes: 0 ok, 1 failed, 2 could not run.25Output goes to the run directory described in `fragility-common`.2627## Never read history with blob commands2829This checkout is usually a blobless partial clone. `git show`, `git diff`,30`git log -p`, `--stat`, `--numstat` and `git blame` fetch blobs one at a31time and stall. Use these scripts instead. If one lacks a capability, extend32it.3334## Scripts3536- `doctor.ts`: the base branch is present, and `gh` is authenticated.37- `collect.ts`: writes `commits.json`, with first-parent commits on38 `origin/<baseBranch>` for `--lookback-days`, and the ones inside39 `--window-hours` marked. It uses tree-level data only, and takes seconds.40- `analyze.ts`: writes `analysis.json`, `analysis.md`, and `targets.json`.41 - **Window mode** (the default): picks the systems the review window42 touched most. Each gets a percentile score against every active system,43 plus a triage verdict: `likely-fragile`, `settling`, `mixed`, `coupled`,44 `likely-fast-moving`, or `insufficient-signal`. Verdicts are leads, not45 conclusions.46 - **Focus mode** (`--focus <file,file>`): scores the systems that contain47 the given files, lists every lookback fix to each file, and lists48 **regression candidates**. Those are every commit of any kind that touched49 the files in `--regression-days` (default `regressionDays`). Use50 `--label "<title>" --label-url <url>` to name what the focus is for.51 - `--keywords <word,word>`: lists lookback fixes anywhere whose subject52 matches. Use it to find the same bug class in other systems.53 - It re-classifies commit subjects on every run, so after tuning54 `config.json`, re-run `analyze.ts` without collecting again.55- `pr.ts --pr N [--file <substring>] [--max-lines N] [--no-diff]`: a PR's56 description and diff from GitHub. Output is bounded, and truncation is57 always stated.5859## Reading the scores6061Counts can't tell you why a fix was needed. Before calling a system fragile,62read 3 to 6 of its fix PRs with `pr.ts`. The judgment rubric is in63`.agents/skills/refactor-plan/references/rubric.md`.6465## Tuning6667Thresholds, ignore lists, system depth, and the regression window live in68`config.json`.