yq-simplify-code

Find Code Simplifications

Turn a broad request to simplify a codebase into a small set of well-proven removals, consolidations, or demotions. Follow the code and repository decisions; prefer a few candidates with complete evidence over a long list of plausible guesses. This skill can produce an audit, durable proposals, targeted TODOs, or implementation when the user authorizes changes.

Simplification is reduced owned surface and cognitive load, not fewer lines at any cost. A wrapper that relocates the same complexity, a dependency that adds more glue than it removes, or a deletion that silently drops supported behavior is not a win.

Establish repository context

1. Confirm the requested scope, output, and write authority. A review request reports findings; a fix or implementation request may change code within scope.
2. Read applicable agent instructions, CONTEXT.md, architecture docs, ADRs/RFCs/decision notes, package manifests, public API docs, compatibility policy, and testing guidance.
3. Identify protected seams and product commitments. Treat a recorded decision as rationale to test against current evidence, not eternal truth; treat tests as evidence of expected behavior, not proof that every pinned behavior remains valuable.
4. Inspect the actual checkout, branch/base, dirty state, generated sources, and runtime-loading paths before judging reachability.

Do not import another repository's architectural exceptions. A seam is protected only when this project's code, contract, or current decision evidence protects it.

What makes a strong candidate

A strong candidate removes, folds, narrows, or demotes real surface area and shows that its ongoing cost exceeds its present value. Common forms include:

• a public method, event, config knob, extension hook, registry notification, helper, package, command, or durable field with no production consumer;
• tests or docs as the only consumers of behavior that is not a supported contract;
• two representations mirroring the same fact across state, events, caches, persistence, projections, or UI models;
• an interface method every implementation carries but no caller uses;
• a package or service split that exists only for fixtures, demos, or support code and adds publish, versioning, or dependency overhead;
• speculative generality such as unused multi-tenancy, background orchestration, invalidation, plugin hooks, fallback layers, or compatibility shims with no supported owner;
• defensive copies, validators, rollback paths, or expected-output inventories that protect an impossible or unsupported boundary;
• hand-rolled parsers, framing, retries, globbing, diffing, scheduling, or data structures already covered by a suitable runtime builtin or maintained dependency;
• an added-then-removed feature whose old implementation, tests, docs, migrations, or decisions still remain as sediment.