Change Cleanup

Purpose

Use this skill to clean up the code introduced or changed by the current branch while keeping scope tight and evidence-based.

The primary goal is to improve the quality of the branch's changes, not to perform opportunistic repo-wide cleanup. Focus first on files added or modified in the branch, then expand only when a small supporting refactor outside the diff is necessary to remove duplication or extract a shared helper.

Scope Rules

1. Ask which mode to use only when the user did not already provide one.

   • If the user already specified self-driving, smart, or assisted, confirm that mode and proceed.
   • If the mode is still unknown, in that first response briefly explain what each mode means.
   • Present the modes as a numbered list in this order so the user can reply with just the number:
     1. self-driving
     2. smart
     3. assisted

2. State the base branch before doing cleanup work.

   • Use the base the user provided, if any.
   • Otherwise, use the base of the branch's open pull request when one exists (gh pr view --json baseRefName --jq .baseRefName).
   • Otherwise, pick the closest candidate among origin/master and any feature integration branches (origin/integ-*): the one whose merge-base with HEAD has the fewest commits between it and HEAD. If the candidates are equally close, ask the user.
   • Make the chosen base explicit so the user can correct it.

3. Use the branch diff against the base branch as the primary cleanup boundary.

4. Within an existing file, only apply cleanup to newly added or modified code units.

   • Do not add docs, specs, or comments to unchanged functions just because the module changed.
   • Do not add @doc to unchanged public functions.
   • Do not add comments to unchanged private helpers.
   • If a changed function needs broader internal reshaping to make the new logic clean, refactor that full function as needed.

5. Allow touching files outside the diff only when that is the smallest sound change needed to:

   • extract a shared helper
   • consolidate duplicated logic
   • move a changed function into a more appropriate module

6. Do not perform speculative cleanup on unrelated untouched code.

   • If something is ugly but outside the changed surface, leave it alone.
   • Exception: if a changed function must be reorganized so the modified behavior remains understandable and maintainable, clean up that function.

Cleanup Targets

Evaluate the changed surface for the following:

1. Helper overgrowth and duplication

   • Detect repeated helper patterns, especially repeated defp helpers across modules.
   • Before creating a new helper, search for an existing one in the same function, same module, and nearby domain modules.
   • If a helper should be shared, prefer extracting or reusing a common implementation instead of copying the same pattern again.

2. Missing or outdated specs

   • Add or update @spec for new or modified functions where the language conventions support it.
   • Prefer @spec for:
     • new or modified public functions
     • callbacks and behaviour implementations
     • shared functions called across modules
     • logic with non-obvious inputs or return shapes
   • Consider @spec for private functions only when the logic is complex enough that the type contract materially improves readability or static analysis.
   • Do not add low-value specs that only restate obvious contracts such as generic map(), list(), or trivial wrappers without improving documentation or Dialyzer coverage.
   • For Phoenix function components, prefer attr declarations as the primary interface contract. Add @spec only when the component has non-trivial options or when surrounding helper functions expose a meaningful contract.
   • Before using Module.t() in a spec, verify that the referenced module actually defines @type t() or @opaque t().
   • If the module does not export t(), use the correct structural type instead, such as %Module{} or another explicit type that the module really exposes.

3. Missing or outdated public function docs

   • Add or update @doc for new or modified public functions.
   • Keep the documentation concise and behavior-focused.

4. Missing or outdated module docs

   • New modules should have at least a minimal @moduledoc.
   • When a function is added or changed in an existing module, review the current @moduledoc.
   • Update it when the changed surface alters the module's responsibility, scope, or public surface.
   • If the changed function no longer matches the module's stated purpose, evaluate moving it to a more appropriate module.

5. Inline explanation for complex logic

   • Add a short inline comment when new or modified logic is hard to understand without business context.
   • Use comments to explain intent, constraints, or domain logic.
   • Do not add comments that restate obvious code.
   • Do not mention ticket IDs, people, chat history, or temporary implementation history.

6. Stale assigns, props, attrs, and other iteration residue

   • Check for unused LiveView assigns, function component attrs, React props, and similar state or interface residue introduced during iteration.
   • Remove them only after confirming they are truly unused.
   • Prefer reusing already-available state rather than introducing overlapping derived state.

7. Overlapping state

   • Detect newly introduced assigns or props that duplicate information already available elsewhere.
   • Prefer computing simple derivations from existing state when that is cheaper and clearer than maintaining parallel state.

8. Duplicate functions or near-duplicate behavior

   • Search beyond the current edit loop when needed.
   • Confirm duplication with codebase facts before proposing consolidation.

9. Stale added files and orphaned entrypoints

   • For every file added by the branch, identify how it is reached from an active root: application code, tests, scripts, workflows, config, docs that are meant to be executed, or a documented convention used by an existing runner.
   • Search by path, basename, exported module/class/function names, and any string-based references the file introduces. This is required for dynamic systems where static imports are not enough, such as YAML scenario hooks, workflow paths, reflection-based module names, route/action names, or generated-file conventions.
   • If an added file is only referenced by another added file, continue tracing that chain until it reaches an active root. If the chain has no active root, classify the files as stale iteration residue.
   • For tests and scenario assets, verify that the relevant runner, spec, workflow, or documented command actually invokes the new file. A scenario fixture, hook, or support module should not remain only because it could be useful later.
   • Prefer proposing deletion when a whole added file belongs to an abandoned setup path and removing it does not affect the active branch behavior. Keep the evidence in the finding.

Workflow

1. Determine the mode before starting the cleanup pass.

   • If the user already provided self-driving, smart, or assisted, confirm that mode and proceed without asking again.
   • Otherwise, in the first reply include:
     • the explicit base branch, detected as described in Scope Rules step 2 unless already provided
     • one short sentence explaining the cleanup frame
     • a numbered list:
       1. self-driving: fully automatic cleanup pass; research, decide, and implement without per-finding approval
       2. smart: inspect first, summarize findings, review them interactively, then wait for approval before editing
       3. assisted: walk rule-by-rule with the user before any edits, then wait for approval before editing
   • If the mode was not already provided, end by asking the user to reply with 1, 2, or 3.

2. Confirm the cleanup frame.

   • State the base branch.
   • State that the cleanup scope starts from the diff against that base.
   • Note that supporting refactors outside the diff may still be considered when needed for reuse or deduplication.

3. Build context from facts.

   • Inspect the diff against the base branch.
   • List added, modified, deleted, and renamed files separately so newly added files can be checked for an active entrypoint instead of only reviewed internally.
   • Read the changed code.
   • Search nearby modules or components when checking for duplication, helper reuse, or better module placement.
   • For added files, trace usage from each file to an active root before deciding that the file belongs in the branch.
   • Do not guess about usage, duplication, or business intent.

4. Classify findings before proposing edits. For each finding, record:

   • the rule it maps to
   • the affected code unit
   • whether it is definitely actionable, needs user input, or should be left alone
   • whether it requires touching a file outside the diff

5. After applying approved cleanup changes, always include a suggested commit message in the final response.

   • Use the format "[TICKET-ID] Commit message".
   • Derive TICKET-ID from the branch name, changed docs, PR/ticket context, or previously established conversation context.
   • If no ticket id can be found, use "[TICKET-ID]" literally and mention that the placeholder should be replaced.
   • Keep the message concise and specific to the cleanup performed.