7.5 KiB
name, description
| name | description |
|---|---|
| why-here | Review a change before delivery after the work involved an abandoned attempt, corrected misunderstanding, completed transition, or superseded implementation, or when the user asks what no longer belongs in the finished result. Keep current requirements and unproven cases unchanged. Do not use for ordinary prose editing, general refactoring, or a repository-wide simplification review. |
Why Here
Review what is about to be delivered by asking of each questionable part: Why is this here now?
Keep it when the finished result still needs it. Remove it when it exists only because of an abandoned attempt, an earlier misunderstanding, a completed transition, or an old implementation that no current requirement preserves. This is not a general simplification pass and less is not automatically better.
Scope
Start with the current diff, user-named files, and any text or artifact being delivered with this change. Treat the task as review-only unless the user explicitly asks to edit, clean up, remove, or otherwise change the artifact. Loading or naming this skill alone does not grant permission to modify files. Do not turn the review into repository-wide cleanup. Note an adjacent problem only when it would materially affect this delivery.
Preserve unrelated user work. Inspect first; do not assume that an unfamiliar field, branch, comment, test, or document is unnecessary.
Process
1. Establish the finished result
Derive the required behavior, structure, contract, and documentation from the user's request, acceptance criteria, owning documentation, current contracts, and real consumers. Identify any public interface, stored data, external system, or compatibility promise in scope. When the sources are missing or conflict, mark the corresponding target as unproven instead of inferring it from the current implementation. Candidates whose required result is unproven remain Unproven; do not classify them as Keep, Confine, or Remove.
Complete when: the required result and the boundaries that can constrain cleanup are explicit.
2. Find parts whose reason may have expired
Inspect the scoped change for parts that appear to exist only because work took a particular route:
- explanations, denials, or comments that answer an earlier misunderstanding or abandoned implementation rather than a likely question or current constraint raised by the finished result;
- narration of attempts, reversals, or investigation instead of the conclusion and its evidence;
- temporary fields, states, flags, branches, adapters, or documentation left by a completed internal transition;
- tests for behavior that was intentionally removed or whose coverage has been replaced;
- old and new representations both retained after the old one has lost its purpose.
Use the counterfactual only to find candidates: if the work had begun from the finished design, would this part still have been introduced? A “no” is a reason to investigate, not permission to delete.
Complete when: every candidate has a location and a concrete reason it may no longer belong.
3. Prove what still earns a place
For prose and comments, judge from the finished artifact. The reader is the person who will receive, use, or maintain that artifact after this conversation, without access to the conversation. Would removing the candidate create a reasonable misunderstanding or change that reader's current understanding, decision, or action? Check any source or requirement the statement claims to preserve.
For code, interfaces, configuration, tests, and data structures, check current callers, clients, configuration, stored data, documented contracts, and external constraints. History may explain why a candidate appeared, but current evidence decides whether it stays.
Classify the result:
- Keep: current understanding or action, behavior, a real consumer, a contract, stored data, or an external constraint still requires it.
- Confine: a temporary compatibility need remains, but keeping it at the conversion, migration, or version boundary would prevent it from spreading through the maintained model. This classification does not by itself authorize the move.
- Remove prose: removing it changes no intended reader's understanding, decision, or action, and no current requirement calls for it.
- Remove structure: no current behavior or obligation depends on it, and available validation can show that removal is safe.
- Unproven: evidence is insufficient. Keep it unchanged and state what would settle the question.
Do not treat an awkward external requirement as residue merely because a clean redesign would prefer not to have it.
Complete when: no removal rests only on taste, age, or the counterfactual.
4. Clean only within the proven boundary
If the current request authorizes edits, remove prose and comments when their absence changes no current understanding, decision, or action. Otherwise, classify and report them without editing. Keep a reason, constraint, or invalidation condition that a future maintainer needs and cannot recover from the artifact itself. Treat safety, security, privacy, recovery, legal, generated, and tool-read notices as behavior or constraints; remove them only after proving they no longer apply and checking the system or tool that consumes them.
If the current request authorizes edits, remove a test only when its protected behavior was intentionally removed or its purpose is covered elsewhere. Otherwise, classify and report it without editing. Read the assertions and confirm the remaining coverage; absence of a runtime caller is not evidence that a test is obsolete.
If the current request authorizes edits, remove internal code or structure only after consumer and contract checks support it and relevant validation is available. A Confine change may be made under that authorization only when it is internal, preserves supported behavior, and does not affect a public interface, durable data, wire format, migration history, or a still-used compatibility path.
Before changing a public interface, durable data, wire format, migration history, or still-used compatibility path, present the evidence and proposed finished state, then obtain explicit authorization.
Complete when: every authorized edit is supported by the classification above, every review-only candidate remains unchanged, and no unrelated cleanup entered the diff.
5. Validate the result
If edits were made, run the focused checks that can detect a changed behavior, broken consumer, or invalid contract. Repeat relevant searches after removal and inspect the final diff for newly orphaned code, tests, configuration, or documentation. For a review-only run, report the evidence checks performed and which validation would be required before an edit.
Complete when: edited results are supported by concrete checks; review-only findings name the evidence still required; and every unresolved boundary remains unchanged and is reported.
Delivery
Report the finished state, material constraints that remain, checks actually run, and any candidate left unchanged for lack of evidence or authorization. Do not recreate the discarded path as a removal diary unless the user explicitly asks for an audit record.
Finish by accounting for every reviewed candidate: a retained candidate has a current reason to stay; an unproven candidate remains unchanged with the missing evidence or authorization named; and a removed candidate has supporting evidence and validation.