HanZephyr Find Simplifications
Look for changes that reduce the maintenance burden while preserving the required behavior. A survey or analysis reports candidates in the conversation by default. Create proposal files, inline notes, or implementation changes only when the task or existing authorization includes them. Do not turn a code survey into a decision-record cleanup.
Choose the scope
Infer the scope from the request and available project context. Read relevant architecture decisions and conventions before challenging an intentional design. For a broad audit, inspect distinct areas of meaningful complexity; for a local request, stay with that behavior and its dependencies. Prefer a few supported candidates to a quota of suggestions.
Useful candidates include duplicated representations of one fact, unused internal operations, layers that add no independent contract, repeated lifecycle bookkeeping, and custom infrastructure already covered by a suitable builtin or dependency. Fewer lines are not sufficient evidence: a change that hides complexity, weakens checks, or shifts work to callers may be worse.
Establish consumers and obligations
For each candidate, search names, configuration keys, serialized values, registration points, and dynamic loading paths, then inspect their uses. Separate runtime consumers from tests and documentation, and examine examples or scripts before classifying them. Search results and dead-code tools are leads, not proof of absence.
Check public interfaces, downstream integrations, reflection, generated code, persisted data, migrations, and supported compatibility paths when relevant. If consumers outside the inspected code cannot be established, qualify the conclusion rather than declaring the interface unused. A test-only consumer may protect a public obligation or a rare failure path.
Describe the exact operation or state to remove or combine, its current purpose, and what becomes unnecessary as a result. Explain any behavior change explicitly; calling it a simplification does not authorize a product or compatibility change. Revisit an existing design decision only with evidence that addresses its rationale.
Inspect ownership and lifecycle
For copies, freezes, validation, and retained callbacks, identify the data's origin, mutation rights, trust level, and next owner. Same-process calls are not automatically safe, and static types do not establish runtime trust. Remove defensive behavior only when the supported callers and contracts make it redundant.
For asynchronous code, map readiness flags, cancellation, terminal outcomes, resource ownership, and disposal to the transitions they protect. Multiple flags may duplicate one fact, or may represent distinct states such as published-but-not-ready and cancelled-but-still-running. Preserve mechanisms that handle partial initialization, reentrancy, first-terminal-outcome arbitration, callback failures, or cleanup completion unless the replacement covers them.
Evaluate replacement costs
A builtin or dependency can reduce custom code when it covers the actual semantics at the project's supported runtime versions. Compare remaining glue, error behavior, performance, licensing, maintenance, and transitive dependencies. Verify current dependency facts when they affect the recommendation. Follow the project's dependency policy; do not assume introducing a package is either always preferable or forbidden.
Count what is removed across implementation, tests, and documentation against what callers and maintainers must now understand. Preserve focused tests that still protect required behavior after the change.
Present or implement the result
For each worthwhile candidate, report the evidence and locations, proposed change, expected benefit, behavior or compatibility cost, uncertainty, and the smallest useful verification. Distinguish safe local cleanup from work requiring a design decision. Reject weak candidates instead of creating TODOs to retain them.
When implementation is authorized, make the complete scoped change, update affected consumers and documentation, and verify the remaining contract. If a durable proposal is requested or required by project conventions for that implementation, use the existing format and location; do not introduce an ADR system merely to record the survey.
If the change overlaps an existing decision record, identify what remains current before editing it. A removed implementation may still have persistent-data obligations or useful rejection rationale. Report obsolete records discovered outside the authorized scope rather than moving or deleting them automatically.