agentleFS
dinsteindinstein/agent-hub/.agents/skills/nightly-tidy/SKILL.md

nightly-tidy

Skill3 starsChanged 3 months agoMITView on GitHub

Run AgentHub's recurring simplification pass to reduce accidental complexity, improve code shape, and reconcile documentation with behavior. Use for a nightly tidy or a focused cleanup slice.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Prefer, in order: what changed recently (a simplification is still cheap and the docs are most likely left behind).

    line 45
  2. Very specific:

    Read the slice's docs/subsystems/ file before the code.

    line 58
  3. Distinctive:

    Read for what can be removed or collapsed, not for what could be rewritten to taste.

    line 63
  4. Distinctive:

    Only when Pass A left the slice genuinely hard to change.

    line 88
  5. Distinctive:

    Before moving anything, check it is allowed to move:

    line 91
  6. Very specific:

    If a refactor would be *nicer* but touches any row above, it does not happen here — write it down in the docs/subsystems/ file and leave.

    line 99
  7. Distinctive:

    A sentence that restates the code: Delete it — it carries no reason and is the sentence most likely to be wrong after the next change.

    line 124
  8. Distinctive:

    Follow the new-feature skill steps 4–5, unabbreviated — including the worktree and branch teardown.

    line 129
  9. Distinctive:

    Per slice: stop when a pass produces nothing that clears the bar.

    line 140
  10. Distinctive:

    Not because they are perfect, but because a scheduled pass is the wrong place to decide them:

    line 151

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

Nightly tidy

A recurring pass over one slice of the tree, in three concerns — simplify the logic, refactor the shape, make docs and code agree. It runs against a main nobody is mid-way through and lands by the new-feature skill.

One rule governs the loop: every change must name the failure it prevents or the reader it helps. A diff that cannot answer "who is better off" is churn, and churn is not free — main is linear and several worktrees are usually in flight, so every landed commit is a rebase for everyone else. A quiet night is a correct outcome. Landing nothing is a correct outcome.

It does not hunt for bugs (the security-audit skill does) and it does not change behaviour. A behaviour change discovered here becomes a note in the owning docs/subsystems/ file and then a normal feature branch.


0. Preconditions

git fetch origin
git status --short                      # must print nothing
git log --oneline -1 origin/main        # must equal local main
git worktree list                       # note what is in flight

Skip any package an open worktree is touching. Tidying underneath live work turns one rebase into a conflict, and the branch's author pays for it. If the tree is dirty, stop — a background agent may still be writing.

1. Pick tonight's slice

One package, or one narrow theme across a few. Not the whole tree: a diff nobody can review in one sitting gets landed on trust.

git log --since="2 weeks ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20

Prefer, in order: what changed recently (a simplification is still cheap and the docs are most likely left behind); what carries a recorded gap (grep -rn "Current assembly status" docs/subsystems/ — one heading, spelled the same in every file, so this finds all of them); then what nothing has touched in months — least likely to conflict, also least likely to matter.

git worktree add ../agent-hub-tidy-<slice> -b tidy-<slice> origin/main

The three passes are the subtask list; the draft PR opens on the first commit as usual. Title it tidy-<slice>: <what was collapsed> — "tidy" alone tells a reader nothing about whether it touches theirs.

Read the slice's docs/subsystems/ file before the code. Its invariants are what tells a simplification apart from a regression.

2. Pass A — simplify the logic

Read for what can be removed or collapsed, not for what could be rewritten to taste.

Worth a commitWhy it clears the bar
A branch that cannot be reachedA reader spends time deciding when it fires; the answer is never
A helper with one caller, inlined thereThe indirection cost a lookup and bought nothing
Duplicated logic where one copy has driftedThe drift is the finding; the dedup is the fix
An error wrapped twice, or swallowed and re-derivedThe message a user sees is assembled twice from one fact
A parameter every caller passes the same value forIt reads as a choice that exists, and it does not
Dead exported surface with no caller in or out of the treeConfirm the "out of tree" half before removing

Not worth a commit: renames for taste, reordering that changes no meaning, comment rewording, splitting a long function that reads fine top to bottom, or a standard-library call that is neither shorter nor clearer.

Never simplify away a fail-closed path. A check that looks redundant with the one above it is usually the second of two independent gates; collapsing them turns two failures into one.

make fmt && make ci
git commit                              # one commit per finding, naming what it buys

3. Pass B — refactor the shape

Only when Pass A left the slice genuinely hard to change. The bar is higher: a refactor must remove a constraint that is blocking work, or delete a whole category of mistake.

Before moving anything, check it is allowed to move:

About to moveCheck
A package, command, or identifier namedocs/conventions.md#frozen-identifiers — they do not move on a tidy night
An import across a package boundaryAGENTS.md's four hard constraints
The gate chain, the call path, provenance for an exposed name, or a tool selectorAGENTS.md's easiest things to get wrong — each of those is frozen, and none of them move on a tidy night

If a refactor would be nicer but touches any row above, it does not happen here — write it down in the docs/subsystems/ file and leave. A refactor that does change an invariant or a failure direction updates that file in the same commit: the next reader's only defence against a silently changed invariant is that file.

4. Pass C — docs and code agree again

make ci already fails on the mechanical half — dead backticked paths, comments crediting a deleted test, unresolvable docs/conventions.md citations, prose teaching a retired command, a fuzz target missing from the Makefile or AGENTS.md, an untranslated English doc. Do not repeat the machine.

What a human has to read for:

  • A documented invariant the code has stopped enforcing. The dangerous one, and it does not get fixed by editing the sentence — restore the enforcement, or, if it was deliberately dropped, say so there and record what now holds instead. A rule that quietly became a suggestion reads exactly like a rule.
  • "Capability exists ≠ wired up" gone stale in either direction. A fixed gap that still reads as a gap costs a redundant investigation; an unfixed one that no longer reads as a gap is how "I thought that was in effect" happens.
  • A docs/subsystems/ file describing a shape the package no longer has — types renamed, a responsibility moved, a failure direction inverted.
  • Within-section translation drift. docs/zh-CN/ is checked for its heading skeleton and nothing below it, so a dropped bullet survives. Compare side by side for the sections the slice touched.
  • A sentence that restates the code. Delete it — it carries no reason and is the sentence most likely to be wrong after the next change.

5. Land it

Follow the new-feature skill steps 4–5, unabbreviated — including the worktree and branch teardown. A tidy branch gets no shortcut; it is the branch most likely to have touched something whose test lives somewhere else. If the slice touched a parser reading untrusted input, this is a fuzz night too:

make fuzz FUZZ=<target>                 # make ci runs only the seed corpora

Stop condition

Per slice: stop when a pass produces nothing that clears the bar. Do not lower the bar to fill the night — the bar is the only thing separating this loop from churn.

Per night: one slice, one branch, landed or discarded before you finish. A tidy branch left open overnight conflicts with real work and nobody remembers what it was for.

Across nights: what was found and left alone goes in that package's docs/subsystems/ file; what was fixed is in git log. A separate ledger is the thing that goes stale first.

Never touch on a tidy night

Not because they are perfect, but because a scheduled pass is the wrong place to decide them:

  • The four hard constraints and their proofs in internal/depguardtest
  • The gate chain, its order, and any predicate's failure direction
  • Frozen identifiers (docs/conventions.md#frozen-identifiers)
  • VERSION and .github/workflows/ — those belong to the release skill
  • Any file an open worktree has claimed

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.