Turn a broad "find things to simplify" request into evidence-backed Agent Notes that remove or collapse existing surface across code, docs, and skills. It is guidance, not a checklist: follow the code, keep judgment active, and prefer a few well-proven candidates over a pile of thin guesses.

A strong simplification removes, folds, or demotes something real and has clear evidence that the current design costs more than it buys:

Thin candidates are usually not enough for an Agent Note: deleting one typo, running a dead-code tool once, removing an intentionally documented backend or adapter, or flagging "this looks complex" without call-site proof.

Use parallel subagents when the user asks for breadth or many candidates. Give each agent a domain and require evidence, not guesses. Useful domains:

If subagents are unavailable, simulate the same breadth yourself. Do not let the first good candidate stop the survey.

Start with the largest production-code deltas. A broad audit that stops after obvious unused symbols can miss the files where duplicated lifecycle or defensive machinery carries most of the cost.

For every defensive copy, freeze, validator, and callback capture, name where the value came from and who owns it next. Same-process typed service/plugin calls ordinarily borrow readonly values; parsers, config loaders, queues, model/tool JSON, durable files, workers, processes, and wire decoders own or validate their data. Tests built around hostile getters, fake typed objects, callback replacement, or mutation after a same-process handoff are evidence of a potentially speculative contract, not automatic justification for keeping it.

For complex asynchronous code, draw the ownership graph and map each sentinel, readiness promise, cancellation path, disposer, and state flag to a distinct owner or transition. When several mechanisms mirror the same liveness or settlement fact, propose one transaction or lifecycle controller instead. Preserve separate machinery where it protects synchronous publication and rollback, callback containment, first-terminal-outcome arbitration, worker/process ownership, or dispose-to-quiescence.

Introducing a dependency is a valid simplification move, not a policy exception; the repository's dependency policy, when recorded, owns the bar. When surveying, ask of protocol parsers, framers, retry/backoff loops, glob matchers, diff engines, and similar infrastructure: does a well-maintained package or a builtin at the repository's engine floor already do this?

Prove a dependency-swap candidate like any other, plus:

For every symbol or behavior, classify consumers before writing:

Use first. Good searches include the exact symbol, event name, package name, config key, method name with both and , and any wire strings. Then read the call sites. A dead-code tool such as can help, but it is not a substitute for understanding public interfaces, dynamic event names, tests, docs, and loader paths.

Reject or downgrade a candidate when:

When the user asks to reduce or coalesce the note tree, or a simplification makes an owning note obsolete, follow the coalescing workflow: classify each old note fully or partially, consolidate through the note-archiving skill, and repair every inbound link before deleting a superseded triplet.

Create one file per durable proposal under the repository's note tree — typically — following its lifecycle and classification rules. Keep prose paragraphs on one physical line and use relative Markdown links.

Prefer this structure, adjusting when the idea needs it:

Be concrete enough that an implementing PR can follow the trail. Avoid vague "simplify this package" Agent Notes. When a proposal overlaps an existing Agent Note, consolidate the useful details into the existing one rather than creating a duplicate.

Use inline TODO/FIXME/XXX only for small, local cleanups that are clearly useful but not durable design decisions. Keep them short and actionable:

When folding simplification ideas from a sibling PR or branch, follow the folding workflow: diff against the base branch, port only the non-overlapping candidates that meet the bar, and update the PR body.

For docs-only Agent Note work, run at least the repository's documentation gates, lint, and — for example plus in a pnpm repo. For code or skill changes, also run the relevant validator when one exists. Select any other evidence from the outgoing diff; the pre-push hook contributes typecheck only.

When opening or updating a PR, summarize:

For each consolidation group, name the old and current owners, state the evidence for full supersession, and explain why deletion is safe. If an added-then-removed scan finds no qualifying note, report that result and the representative partial cases retained.

Use a draft PR while the survey is still expanding; mark ready only when the candidate set, review responses, and validation are settled.