Usage boundaries and preparation
This skill can be installed on its own; the necessary methods are all in this file and do not depend on the author's machine or other skills. First read the target project's specifications and confirm the target repository/workspace, version, user outcomes, and allowed changes; reference repositories are read-only. When there are no project rules, read the actual README, scripts, and source code to infer the entry points.
Execute with currently available and authorized tools: if there is no independent agent, you may use a new session/manual review or self-check from multiple perspectives, and note the actual review method; if there is no browser/real API, complete the executable parts and hand off the uncovered acceptance items, and do not pretend that independent review, GUI, or real service passed. The project's original runtime environment is still required; do not bind to a model vendor or specific plugin.
For complex tasks, you may use assets/task-record.md to save necessary facts; for simple tasks, record the results directly and do not mechanically add process.
Do not directly infer a full rewrite from "the architecture looks messy." Use experiments to locate complexity with no benefit while preserving valuable safeguards.
Define the outcomes and baseline that need to be preserved
Clearly write down the original user tasks, behavior/data contracts, and failure protections that must be preserved. Choose the normal paths of representative tasks and the related error, recovery, boundary, or low-frequency scenarios.
Collect baselines related to the current problem: time consumption, model calls/cost, memory, dependencies, maintenance points of duplicate implementations, failures, or false blocks. Lines of code are used to find candidates, not as a quality metric on their own.
Find candidates and run single-variable experiments
Prioritize checking: multiple implementations of the same rule, multiple sources of the same data, expensive review layers, retained old entry points, configurations with no actual consumers, repeatedly transformed data, and dependency relationships that prevent real tests from covering them.
In an isolated working copy or a rollback-capable experiment, remove, bypass, or replace one mechanism at a time, and rerun the same inputs and acceptance. Record what the experiment changed, which outcomes were maintained, which outcomes degraded, and how costs changed. When the task only requires evaluation, the experiment must not become a permanent refactoring of the official source code.
Safety, data integrity, and recovery guardrails must have corresponding failure or attack scenarios. No difference on normal samples is not enough to prove that these guardrails are redundant. Mark candidates whose benefits are hard to observe as pending verification, and do not delete them based on their names.
Make specific trade-offs
| Candidate mechanism | Original responsibility | Experimental change | Behavioral evidence | Cost change | Conclusion |
|---|
The conclusion may be keep, remove, merge, replace, or pending verification. Before merging duplicate implementations, check platform, interface, and behavioral differences; unifying code cannot be achieved by deleting necessary differences.
Choose the smallest combination that can solve the current user problem, and explain the benefits and migration costs. Do not include every existing problem, and do not introduce a new framework that is not needed just to reduce the current number of layers.
Implementation and retirement
When the task has already authorized implementation, continue to complete the specific changes; when only analysis is required, deliver a reviewable plan. When modifications touch official data/migrations or external operations, follow the current authorization and do not infer extra permissions from "refactoring."
After the new path goes live, check old functions, routing/registration, configuration, tests, dependencies, and public documentation. Retire old paths without consumers based on evidence; when a compatibility entry point is temporarily retained, state the responsibility and verifiable retirement conditions to avoid a permanent dual track.
Rerun baseline tasks and related regressions, and measure the actual cost. Necessary invariants are protected by regression tests; do not write tests that only match directory structure, naming, or implementation text.
Delivery
Explain what user outcomes were preserved, what experimental support removed, how the cost changed, and whether the old path was retired. Do not state unmeasured benefits as numbers. One successful task cannot claim that all historical behavior is equivalent; explicitly list uncovered platforms and low-frequency conditions.