Identify fragile systems
Built to run unattended once a day. It strings together three skills, and
each step's details live in that skill's SKILL.md:
system-history: collecting history and scoring systems;
fragility-common: the findings scripts (duplicate matching, sightings,
and filing in the configured tracker), the run directory, and the plan
format;
refactor-plan: the fragile vs fast-moving judgment, and the plan file.
H=.agents/skills/system-history/scripts
F=.agents/skills/fragility-common/scripts
P=.agents/skills/refactor-plan/scripts
S=.agents/skills/identify-fragile-systems/scripts
RUN=<YYYY-MM-DD> # defaults to today's UTC date
Hard rules
- Planning only. Never change product code, open a PR, or push.
- Never run blob-reading git commands. See
fragility-common.
- Check the tracker for an existing ticket before investigating a system.
- A plan needs a named repeated mechanism, taken from diffs you read. A
high fix count alone is not a finding.
- File only
high or medium confidence plans. A low finding goes in
decisions.json, so a later night can confirm it.
- Stop on any nonzero exit from a preflight and report it. Exit 2 is never a
pass.
Steps
Preflight: $H/doctor.ts and $F/findings-doctor.ts. For a run-link
warning, set FRAGILITY_RUN_URL.
Collect: $H/collect.ts --run $RUN (24 h window, 21-day lookback).
Triage: $H/analyze.ts --run $RUN. It writes analysis.md and
targets.json, with the hot systems, their scores, and triage verdicts.
Dedup early: $F/findings-match.ts --run $RUN. For each hot system
matched to an open or declined ticket, run
$F/findings-upsert.ts --run $RUN --key <KEY> --system <system> --apply
and don't re-plan it. The exceptions:
- The ticket was resolved as fixed. That's a recurrence: plan it and
upsert it, which opens a linked ticket.
- The diffs show a different root problem. Plan it under a new slug, and
name the related ticket.
Investigate the unmatched systems in score order. Focus on
likely-fragile, mixed, and high-scoring settling. Skip coupled
unless the coupling is the defect. Skip likely-fast-moving and
insufficient-signal unless their diffs say otherwise. For each system:
- read 3 to 6 fix PRs with
$H/pr.ts;
- read the current top files;
- decide using
.agents/skills/refactor-plan/references/rubric.md.
Fan out one read-only sub-agent per system when you can. Give it the
system's analysis.md section and the rubric, and ask for the mechanism,
the PR numbers, and a verdict.
Plan: one plan per root problem, which may span several systems.
Scaffold it with $P/new-plan.ts, then fill it in as refactor-plan
describes.
Record decisions: give every hot system you didn't plan or sight a
one-line reason in <dataDir>/$RUN/decisions.json.
File: $F/findings-upsert.ts --plan <file> (a dry run), then add --apply.
If it reports overlapping tickets, read their diffs: pass --key KEY when
the plan is that ticket's problem, or --distinct-from KEY,... when it
isn't.
Summarize: $S/summarize.ts --run $RUN. Exit 1 means some hot system
is still undecided, so go back to step 7.
Final report
Write 3 to 6 lines covering:
- tickets created and sighted, with links;
- plans held back by the cap;
- any check that could not run.
Use 🟢 when nothing is undecided and every applied upsert succeeded.
Use 🟡 when something was held back or a check exited 2, and say what.
1---2name: identify-fragile-systems3description: >-4 Nightly refactor review: find the systems the last day's commits hit5 hardest, use three weeks of history to tell fragile from fast-moving, write6 a plan per systemic fix, and file deduplicated refactor-findings tickets. Use for7 /identify-fragile-systems or the nightly run. For a single bug report, use8 investigate-bug instead.9user-invocable: true10scope: dev11metadata:12 source: https://skillmd.com/skills/builderio/identify-fragile-systems13 internal: true14---1516# Identify fragile systems1718Built to run unattended once a day. It strings together three skills, and19each step's details live in that skill's SKILL.md:2021- `system-history`: collecting history and scoring systems;22- `fragility-common`: the findings scripts (duplicate matching, sightings,23 and filing in the configured tracker), the run directory, and the plan24 format;25- `refactor-plan`: the fragile vs fast-moving judgment, and the plan file.2627```bash28H=.agents/skills/system-history/scripts29F=.agents/skills/fragility-common/scripts30P=.agents/skills/refactor-plan/scripts31S=.agents/skills/identify-fragile-systems/scripts32RUN=<YYYY-MM-DD> # defaults to today's UTC date33```3435## Hard rules3637- Planning only. Never change product code, open a PR, or push.38- Never run blob-reading git commands. See `fragility-common`.39- Check the tracker for an existing ticket before investigating a system.40- A plan needs a named repeated mechanism, taken from diffs you read. A41 high fix count alone is not a finding.42- File only `high` or `medium` confidence plans. A `low` finding goes in43 `decisions.json`, so a later night can confirm it.44- Stop on any nonzero exit from a preflight and report it. Exit 2 is never a45 pass.4647## Steps48491. **Preflight**: `$H/doctor.ts` and `$F/findings-doctor.ts`. For a `run-link`50 warning, set `FRAGILITY_RUN_URL`.512. **Collect**: `$H/collect.ts --run $RUN` (24 h window, 21-day lookback).523. **Triage**: `$H/analyze.ts --run $RUN`. It writes `analysis.md` and53 `targets.json`, with the hot systems, their scores, and triage verdicts.544. **Dedup early**: `$F/findings-match.ts --run $RUN`. For each hot system55 matched to an open or declined ticket, run56 `$F/findings-upsert.ts --run $RUN --key <KEY> --system <system> --apply`57 and don't re-plan it. The exceptions:58 - The ticket was resolved as fixed. That's a recurrence: plan it and59 upsert it, which opens a linked ticket.60 - The diffs show a different root problem. Plan it under a new slug, and61 name the related ticket.625. **Investigate** the unmatched systems in score order. Focus on63 `likely-fragile`, `mixed`, and high-scoring `settling`. Skip `coupled`64 unless the coupling is the defect. Skip `likely-fast-moving` and65 `insufficient-signal` unless their diffs say otherwise. For each system:66 - read 3 to 6 fix PRs with `$H/pr.ts`;67 - read the current top files;68 - decide using `.agents/skills/refactor-plan/references/rubric.md`.6970 Fan out one read-only sub-agent per system when you can. Give it the71 system's `analysis.md` section and the rubric, and ask for the mechanism,72 the PR numbers, and a verdict.736. **Plan**: one plan per root problem, which may span several systems.74 Scaffold it with `$P/new-plan.ts`, then fill it in as `refactor-plan`75 describes.767. **Record decisions**: give every hot system you didn't plan or sight a77 one-line reason in `<dataDir>/$RUN/decisions.json`.788. **File**: `$F/findings-upsert.ts --plan <file>` (a dry run), then add `--apply`.79 If it reports overlapping tickets, read their diffs: pass `--key KEY` when80 the plan is that ticket's problem, or `--distinct-from KEY,...` when it81 isn't.829. **Summarize**: `$S/summarize.ts --run $RUN`. Exit 1 means some hot system83 is still undecided, so go back to step 7.8485## Final report8687Write 3 to 6 lines covering:8889- tickets created and sighted, with links;90- plans held back by the cap;91- any check that could not run.9293Use 🟢 when nothing is undecided and every applied upsert succeeded.94Use 🟡 when something was held back or a check exited 2, and say what.