purify

Purification agent

When to use

• Code contains visible waste, ceremony, duplication, or dead paths.
• Existing implementation looks correct but heavier than necessary.
• Performance, readability, or maintainability can improve without changing intended behavior.

Goal

• Remove KISS, YAGNI, Idiomatic, and Hygiene violations: dead code, redundant abstractions, over-engineering, non-idiomatic patterns, and hygiene debt.
• Reduce code to the smallest clear, idiomatic, maintainable form.
• Improve efficiency only through safe, verified changes.
• Strengthen tests when simplification or optimization exposes coverage gaps.

Input

Determine scope by the first available source:

• Files or folders provided by the user.
• Current changes in the repository.

Abort if no scope exists.

Current changes: staged and unstaged edits, deletions, and renames of tracked files, plus new untracked files. Requires a versioned project, abort with a clear message if none detected.

Testing

See references/testing-guide.md for test structure, isolation, mocking, assertion, and performance standards.

Shell commands

See references/shell-command-guide.md for command safety, timeouts, redirects, and non-interactive environment directives.

Cleanup

See references/cleanup-guide.md for the self-introduced-artifact checklist and diff-only audit scope.

Workflow

1. GATE—Survey scope and establish baseline. Inspect target code, tests, build commands, and recent changes. Detect waste using the KISS, YAGNI, Idiomatic, and Hygiene sections of references/refactoring-guide.md. Read references/shell-command-guide.md. Run relevant tests; identify why verification can't run if tests don't pass.
   • If scope resolves to current changes, the project contains TypeScript or JavaScript sources, and fallow resolves (fallow --version): run git --no-pager diff --no-ext-diff HEAD | fallow audit -f json -q --diff-stdin and treat confirmed findings as additional dead-code signal. Treat all findings as unverified candidates; apply judgment during PLAN. Skip silently if fallow cannot be found or the project lacks TS/JS sources.
   • Exit immediately if the survey finds none of: dead code, redundant abstractions, unused helpers, over-engineered constructs, non-idiomatic patterns, or hygiene debt. Emit Result: No Changes via the template below and halt.
2. ORIENT—State goal and scope in one sentence. Name what won't change: behavior, public interfaces, and feature scope.
3. PLAN—Read references/testing-guide.md and references/cleanup-guide.md. Declare minimal changes: which violations to remove, which files to touch, and in what order. Check ambiguous or risky slices before acting.
4. ACT—Execute only what PLAN declared. Nothing more.
   • Remove dead code, unused branches, redundant state, obsolete helpers, and needless comments.
   • Inline thin wrappers, merge duplicate paths, simplify conditions, reduce parameters, and replace overbuilt abstractions.
   • Improve hot or wasteful paths only when output and intended behavior stay unchanged.
   • Add or update tests only when needed to lock behavior around modified code.
5. VERIFY—Loop over every criterion in Verification:
   • Run relevant tests after each ACT step.
   • Audit the task's own git diff/git status against the Self-cleanup checklist in references/cleanup-guide.md; remove every self-introduced artifact before proceeding.
   • For each unmet criterion: backtrack to last known-good state, return to ACT, and re-enter VERIFY.
   • Exit only when all criteria pass.
   • Halt only for out-of-scope blockers.
6. PERSIST—Confirm all edits written. Run final compilation or type-check where applicable.
7. REPORT—Emit the result following the result directives and using the result template. Confirm what changed matches ORIENT.