refactor

Files (5)

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

SKILL.md (first lines)

# Refactoring agent

## When to use

- **Rule of Three**: Third instance triggers extraction. Exception:
  security and validation logic warrants unification at 2+.
- **Adding features**: Restructure to accommodate the change first.
- **Fixing bugs**: Clarify structure to expose the error.
- **Code review**: Improve unfamiliar code incrementally.
- **Smells detected**: See violation catalog in
  `references/refactoring-guide.md`.

## Goal

- Execute disciplined, semantics-preserving transformations to remove
  `DRY`, `SOLID`, and `Structure` violations, improving maintainability
  without altering observable behavior.

## 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**—Precondition guard. Halt immediately on failure.
   - Abort if no scope exists.
   - Read `references/testing-guide.md`.
   - Read `references/shell-command-guide.md`.
   - Read `references/cleanup-guide.md`.
   - Read relevant production code, adjacent tests, and test commands.
   - Confirm automated test suite passes before touching code.
   - Detect `antipatterns` using the violation catalog in
     `references/refactoring-guide.md`.
   - **Short-circuit**: halt and emit `Result: No Changes` if none
     detected: duplicated logic, long methods, large classes,
     `primitive` obsession, `SOLID` violations.
   - When detected smells carry high regression risk resisting safe
     atomic extraction under existing tests: record in `Findings`, omit
     edits, and emit `Result: No Changes`.
2. **ORIENT**—Name the smallest production area worth refactoring and
   what won't change. Capture pre-task baseline snapshot per
   `references/cleanup-guide.md`.
3. **PLAN**—Declare the minimal change and rationale.
   - Target one cohesive responsibility boundary (for example,
     extracting a dedicated collaborator, domain service, or validation
     module) rather than whole-class overhauls or disconnected
     micro-edits.
   - Declare the ordered sequence of transformations needed to decouple
     that responsibility.
   - Analyze package, module, or class boundaries for cyclic imports and
     unresolved downstream consumers.
   - Select the fix from the playbook; resolve compound violations using
     the triage rules in `references/refactoring-guide.md`.
4. **ACT**—Apply one transformation at a time. Execute only what PLAN
   declared.
5. **VERIFY**—Loop over every criterion declared in PLAN:
   - Run the full suite 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 codebase smells as blockers.
6. **REPORT**—Emit the result following the result directives and using
   the result template.

## Directives

- **Cohesive Scope**: Scope each invocation to one distinct
  responsibility boundary; batch related transformations internally
  under sequential test verification rather than micro-slicing single
  methods.
- **Two Hats**: Never add features or new tests while refactoring.
  Extracting internal functions, modules, or cohesive units under
  existing test suites satisfies Two Hats without requiring new test
  files.
- **Violations**: Detect and fix using the violation catalog and fix
  playbook in `references/refactoring-guide.md`.

## Constraints

- **No Confirmation Halts**: Never halt to request user scope
  confirmation or interactive direction; execute the smallest safe
  transformation within detected scope or emit `Result: No Changes`.
- **Zero Behavioral Change**: External function and observable behavior
  must remain identical.
- **Defer if Broken**: Stabilize failing code before refactoring.
- **Inherit Baseline**: Treat the test suite as-found at refactor start
  as the authoritative baseline, regardless of prior tooling in the same
  session.
- **Track Own Edits Only**: Capture each file's content before this
  run's first edit to it. Revert means rewriting captured content back,

From mystilleef/spae-framework, MIT.

More from mystilleef/spae-framework