choruz-find-simplifications
Skill1.1k starsChanged 19 days agoApache-2.0View on GitHub
Use when working in this repository to find non-obvious simplification candidates, remove redundant comments or implementation-heavy documentation, write proposed Agent Notes or inline TODO/FIXME/XXX notes, audit or coalesce superseded Agent Notes, or fold worthwhile simplification ideas from another branch; especially for dead, duplicated, speculative, over-built, added-then-removed, or hand-rolled-where-a-crate-exists surfaces.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/notes/implemented/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- choruz-archive-agent-notesSkill
- choruz-ci-test-reliabilitySkill
- choruz-code-reviewSkill
- choruz-docSkill
- choruz-merging-stacked-prsSkill
- choruz-pre-push-checksSkill
- choruz-pre-simplify-auditSkill
- choruz-prose-standardSkill
- choruz-prSkill
- choruz-record-demoSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
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
- Distinctive: line 12
Read AGENTS.md, especially the pre-release stance: no compatibility shims, delete the old path.
- Distinctive: line 14
Use the Agent Note tree to learn intentional architecture.
- Distinctive: line 15
Treat the multiple terminal drivers (Claude Code, Codex, Gemini) and the connector, bridge and remote-control transports as intentional by …
- Distinctive: line 43
Use git grep first: the exact symbol, the route, the event name, the table or column, the config key, the env var.
- Very specific: line 68
Use FIXME (blocks a release), TODO (soon) and XXX (someday) only for small, local cleanups that are clearly useful but not durable design …
≈ “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.
Files
Finding Choruz simplifications
Turn a broad "find things to simplify" request into evidence-backed Agent Notes that remove or collapse existing surface area. This is guidance, not a checklist: follow the code, keep judgement active, and prefer a few well-proven candidates over a pile of thin guesses.
Start with repository context
- Read AGENTS.md, especially the pre-release stance: no compatibility shims, delete the old path.
- Skim docs/architecture.md before judging anything under
crates/,services/orservices/choruz-pipeline; a simplification that fights the stage model (router, executor, writer, fanout) or the sync feed needs extra evidence. - Use the Agent Note tree to learn intentional architecture. A recorded decision is not a veto, but a candidate that collapses one must beat its recorded rationale, not just cite this skill.
- Treat the multiple terminal drivers (Claude Code, Codex, Gemini) and the connector, bridge and remote-control transports as intentional by default; removing an unused method inside one of them can still be valid.
What counts as a strong candidate
- A handler, endpoint, event, config knob, helper, crate, table column or test fixture has no production consumer.
- Tests or docs are the only consumers, and the behaviour they pin is not load-bearing.
- Two representations mirror the same fact (a cached count and its source rows, a client-side copy of server state that the sync feed already carries).
- A shared crate exposes methods every service must support but no service calls.
- A feature implements speculative product generality with no owner.
- A hand-rolled parser, retry loop, path matcher or serializer duplicates a maintained crate or npm package the workspace already depends on, and the swap would delete the implementation plus its dedicated tests.
- Dead paths left by a retired surface (the desktop app, the maildir protocol's predecessors, renamed features) that still compile because nothing removed them.
Thin candidates are not enough for a note: one typo, one unused import, or "this looks complex" without call-site proof. Fix those directly or leave a TODO.
Survey broadly
Use parallel subagents when the user asks for breadth, one domain each, evidence required. Useful domains: the message path (gateway handlers, outbox, sync feed, fanout); the pipeline (router, executor, writer, cron, watcher); the web client (hooks under apps/web/lib, components, the docs pages); runtime and host (choruz-supervisor, supervisor, connector, bridge); scripts, infra and CI. Start with the largest production files (git ls-files | xargs wc -l | sort -rn); the biggest deltas hide the duplicated lifecycle machinery.
Prove or reject each candidate
For duplicate-owner audits, apply architecture boundaries: run its gate, then trace semantic ownership and authoritative state in the requested scope. Report mechanically scanned paths separately from consumer-reviewed paths. Keep distinct provider protocols, transports, leases and independent library storage contracts when their consumers justify the difference. When fixing a confirmed recurrence, add a precise guard or strengthen the shared behavioral contract instead of creating a second implementation-specific suite.
Classify consumers before writing:
- Production corpus:
crates/*/src,services/*/src,apps/*/src,apps/web/{app,components,lib,hooks},infra/,migrations/. - Non-production corpus: tests,
docs/, notes, fixtures, snapshots, comments. - Ambiguous corpus:
scripts/and the e2e harness, which may be product smoke paths.
Use git grep first: the exact symbol, the route, the event name, the table or column, the config key, the env var. Then read the call sites, the trait impls, dynamic dispatch (driver type strings, event type strings), and the SQL.
Reject or downgrade when a production caller exists and the change would be a feature decision; when an implemented note justifies the API and the new evidence does not beat it; when the removal forces unrelated churn without reducing the surface; or when the idea is correct but tiny (use a TODO with the urgency tags below).
Simplify prose with the code
Comments and documentation are maintained surface area. Delete comments that restate code or explain behaviour owned elsewhere; keep required local contracts. Apply choruz-prose-standard.
Coalesce superseded Agent Notes
When a simplification makes an owning note obsolete, follow choruz-archive-agent-notes for retention judgement and mechanics. Preserve every unique rationale, alternative, consequence and reintroduction condition in the current owner; repair inbound links; delete or archive per the README's consolidation rule. Do not expand every code survey into a repository-wide note audit.
Write the Agent Note
One file per durable proposal at .agents/notes/proposed/<class>/yyyy-mm-dd-topic.md (class simplification for a removal):
# Agent Note: <action-oriented title>/Status: proposed## Problem: name the current surface, cite the files, state the consumer evidence, separating production callers from tests and docs.## Proposal: exactly what to remove, fold, or rehome, including tests, docs, migrations and selector rules.## Alternatives considered: the strongest case for keeping it, made legible.## Acceptance criteria: the observable end state and the gates that prove it.## Risks: behaviour changes, future product wants, and why the trade-off is still reasonable.
Inline TODO notes
Use FIXME (blocks a release), TODO (soon) and XXX (someday) only for small, local cleanups that are clearly useful but not durable design decisions. Name the smell with a stable tag, say why it is safe to revisit, and what action would simplify it.
Validation and PR hygiene
For note-only work run python3 scripts/verify_agent_notes.py and git diff --check. For a removal, run what choruz-pre-push-checks selects for the touched crates and specs, and git grep the removed symbols afterwards. In the PR, summarise the areas surveyed, what was intentionally excluded, the candidates added or consolidated, and the checks that passed. Use a draft PR while the survey is still expanding.
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
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.

