code-hygiene

name

code-hygiene

description

Inspect recently changed or explicitly targeted code for smells, cleanup opportunities, language idioms, simplification, and safe source shrinking while preserving behavior. Use when the user asks to clean up, simplify, shrink, refine, make clearer, polish, reduce complexity, check code smells, or review recent code changes for maintainability. Build a bounded hygiene packet, consult the bundled smell/examples references, delegate to the focused hygiene-worker when available, edit only scoped files, and verify the result.

Code Hygiene

Inspect and refine scoped code for clarity, consistency, idiomatic structure, and maintainability without changing behavior. Prefer a few high-confidence improvements over broad rewrites.

Operating Model

This skill is the orchestrator. It determines scope, gathers just enough context, builds a compact packet, and either delegates to hygiene-worker or executes that worker contract inline when delegation is unavailable.

Use the runtime rule-card index first, then load only the bundled references needed for the matched rule ids, requested language, or selected mode:

• references/code-smells.md: smell catalog, safe moves, and overreach warnings.
• references/minimality-ladder.md: deletion, reuse, stdlib, native, dependency, and minimum-code checks.
• references/simplification-examples.md: before/after examples and bad simplifications.
• references/language-patterns.md: language-specific simplification and verification cues.
• references/review-checklist.md: final acceptance checks.
• references/evaluation-plan.md: how to test this plugin against behavior, safety, and diff size.

Workflow

1. Resolve the target scope.

   • If the user provided file paths, use only those files unless they ask for broader cleanup.
   • Otherwise prefer recent changes from git: staged and unstaged files.
   • If no explicit target or git diff exists, ask for a target before editing.
   • Exclude generated, vendored, lock, minified, snapshot, and build output files unless explicitly requested.

2. Collect context narrowly.

   • Read relevant repo instructions such as AGENTS.md, CLAUDE.md, CONTRIBUTING.md, formatter and linter config, and package/build files.
   • Read nearby code that demonstrates local patterns for the scoped files.
   • Identify nearby tests and likely verification commands.
   • Do not load the whole repo when a local pattern is enough.

3. Load hygiene references on demand.

   • Correlate cached observations to current files before choosing references.
   • Load only rule cards and Markdown references relevant to matched rules or the requested language.
   • Read simplification, minimality, and review guidance only when the requested mode or matched rules require it.
   • Do not preload the whole reference bundle when no current finding or language request needs it.

4. Build a hygiene packet.

   • Keep it compact enough for a focused worker.
   • Include the target files, constraints, relevant guidance, local patterns, observed smells, idiom notes, shrink opportunities, candidate edits, and verification commands.
   • Use this shape:

scope:
  reason: explicit user request | recent git diff | staged changes
  files: []
constraints:
  preserve_behavior: true
  public_api_changes: forbidden unless explicitly requested
  generated_files: skip
  broad_refactors: skip unless explicitly requested
style_context:
  guidance_files: []
  local_patterns: []
signals:
  smells: []
  idioms: []
  minimality:
    delete:
    reuse:
    stdlib:
    native:
    already_installed_dependency:
    minimum_code:
  shrink:
    removable_surface:
    readability_limit:
  non_goals: []
candidate_edits:
  - file:
    intent:
    risk:
verification:
  commands: []

5. Run the focused worker.

   • If a multi-agent primitive is available, delegate to hygiene-worker with only the packet and the relevant file contents.
   • If no worker primitive is available, follow hygiene-worker instructions inline.
   • The worker must not expand scope without returning to the orchestrator.

6. Apply edits conservatively.

   • Preserve observable behavior, public interfaces, error semantics, data formats, and test intent.
   • Prefer deleting or reusing existing code over inventing a helper.
   • Prefer standard-library and native platform features over custom code or new dependencies.
   • Favor clarity over line-count reduction.
   • Treat source shrinking as a mode of cleanup, not a license to minify readable code.
   • Do not rewrite stable code just because it could be different.
   • Do not convert explicit, readable logic into clever expressions.

7. Verify.

   • Run the most focused formatter, typecheck, lint, or test command available for the changed files.
   • If no project command is obvious, run git diff --check and review the diff manually.
   • If verification cannot run, say exactly why.

8. Report.

   • List changed files.
   • Summarize the hygiene categories, not every line.
   • Include verification commands and outcomes.
   • Call out any intentionally skipped smells or follow-up opportunities.

Helper Scripts

Resolve <PLUGIN_ROOT> as the plugin directory containing this skill's skills/ folder. Then:

bash "<PLUGIN_ROOT>/scripts/changed-files.sh"
bash "<PLUGIN_ROOT>/scripts/collect-context.sh" <file>...
bash "<PLUGIN_ROOT>/scripts/candidate-smells.sh" <file>...

These scripts are advisory. Prefer repository-specific tooling when it is more precise.

Hard Limits

• Do not touch unrelated files.
• Do not remove tests because they are noisy.
• Do not change generated artifacts unless they are the explicit target.
• Do not change public APIs, schemas, migrations, or serialized formats unless the user asks.
• Do not use broad formatting over the entire repo unless that is already the established local workflow for the scoped files.
• Do not remove validation, authorization, escaping, bounds checks, accessibility, or data-loss protection to make code shorter.