agentleFS
acupof-aiacupof-ai/arle/.claude/skills/find-simplifications/SKILL.md

find-simplifications

Skill19 starsChanged 54 days agoMITView on GitHub

Use when asked to find dead code, unused flags, speculative generality, or simplification candidates in ARLE — "what can we delete", "simplification sweep", "flag deletion wave", or auditing a surface for over-built machinery. Turns a broad "find things to simplify" request into evidence-backed deletions or recorded rejections. Prefer a few well-proven candidates over a pile of thin guesses.

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

2 rules. 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Start with the largest production-code deltas.

    line 38
  2. Very specific:

    Use rg first: exact symbol, both .name( and name(, config key, wire string.

    line 46

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

find-simplifications

Evidence-backed simplification sweeps for ARLE. The project deletes in waves (flag deletion waves 1–3, the 2026-05-18 pivot that removed 167k LOC) — this skill is the method those waves applied, written down.

What counts as a strong candidate

A strong candidate removes, folds, or demotes something real, with evidence that the current design costs more than it buys:

  • A flag, config knob, public method, trait method, registry row, or module has no production consumer — crates/*/src, src/, serve paths, and loader/config paths are the production corpus.
  • Tests, benches, and docs are the only consumers, and the behavior they pin is not load-bearing.
  • Two mechanisms mirror the same fact (two knobs for one axis, two code paths for one shape).
  • A feature implements speculative generality with no product owner: multi-session, background rosters, mid-turn steering, "for later" seams.
  • Hand-rolled code reimplements what a dependency or stdlib already provides, and the swap deletes the implementation plus its tests.
  • An invariant, rollback path, or special case exists only to protect an unused API.

Thin candidates: one dead symbol, a typo, "this looks complex" without call-site proof. cargo machete (nightly) finds unused dependencies; it is not a substitute for reading call sites.

Survey

  • Start with the largest production-code deltas. Obvious unused symbols are the floor, not the sweep — duplicated lifecycle and defensive machinery carry the real cost.
  • For flags: crates/cli/src/args.rs is the registry; trace each flag to its serve mapping and its consumption site. A flag whose consumption is a doc comment or a test is dead.
  • For trait/impl surface: every method every implementation must support but no caller uses is a candidate, not just every unused method.
  • Use rg first: exact symbol, both .name( and name(, config key, wire string. Then read the call sites.

Prove or reject each candidate

Classify consumers before writing anything:

  • Production — crates/*/src, src/, serve/loader/config paths.
  • Non-production — tests, benches, docs, comments.
  • Ambiguous — examples and scripts that may be product smoke paths.

Reject or downgrade when:

  • A production caller exists — the removal is a feature decision, not a cleanup, and needs its own proposal.
  • The behavior is justified by a measured result or a hard-won defensive pattern, and the new evidence does not beat that reason.
  • The removal forces unrelated churn without reducing public surface.
  • The idea is correct but tiny — add a targeted TODO(name): instead.

Record the outcome

  • Deletions land as a commit with the full chain removed (flag → mapping → doc → test), per the no-half-states rule.
  • A rejected simplification that was tempting enough to recur gets a one-line code comment at the site recording why it loses, so it is not re-litigated.
  • Inline TODO(name): / FIXME(name): only for small, local cleanups with an actionable next step. No speculative TODOs.

Validation

  • cargo check on the lanes the diff touches (cuda,no-cuda typecheck is Mac-runnable; metal lane on Apple Silicon).
  • Correctness gates when the deletion touches inference behavior: scripts/lever_gate.sh, not just compile-green.
  • Report: candidates deleted, candidates rejected with reason, what was intentionally excluded.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.