purify

Files (6)

• SKILL.md
• cleanup-guide.md · references/
• refactoring-guide.md · references/
• shell-command-guide.md · references/
• test-pruning-guide.md · references/
• testing-guide.md · references/

SKILL.md (first lines)

# 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.
- Keep test suites small and fast: prune redundant tests, speed slow
  ones, preserve protection.

## 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.

When scope includes test files, see `references/test-pruning-guide.md`
for the bloat smell catalog, deletion evidence, and speed fixes.

## 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.
   - When scope includes test files, read
     `references/test-pruning-guide.md` and detect bloat using its smell
     catalog.
   - Exit immediately if the survey finds none of: dead code, redundant
     abstractions, unused helpers, over-engineered constructs,
     non-idiomatic patterns, hygiene debt, or test-suite bloat. Emit
     `Result: No Changes` via the template below and halt.
   - When detected waste carries high regression risk resisting safe
     verification under existing tests: record in `Findings`, omit
     edits, and emit `Result: No Changes`.
2. **ORIENT**—State goal and scope in one sentence. Name what won't
   change: behavior, public interfaces, and feature scope. Capture
   pre-task baseline snapshot per `references/cleanup-guide.md`.
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.
   - Prune test bloat per `references/test-pruning-guide.md`, after
     production edits verify green and a fresh baseline exists.
5. **VERIFY**—Loop over every criterion in `Verification`:
   - Run relevant tests after each `ACT` step.
   - Audit task edits against the pre-task baseline using 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 (failing baseline tests,
     compilation errors, or missing runtime environments); never treat
     complex code cleanups as 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.

## Directives

- Prefer deletion over abstraction.
- Prefer direct, idiomatic language features over custom machinery.
- Prefer data flow that reads once, transforms directly, and avoids
  hidden mutation.
- Replace cleverness with direct code.

From mystilleef/spae-framework, MIT.

More from mystilleef/spae-framework