alexei-led/refactoring-code

Fast Refactoring with MorphLLM

MorphLLM edit_file provides semantic code merging at 10,500+ tokens/sec with 98% accuracy. Use the MorphLLM edit_file / batch refactoring workflow for broad changes. Refactoring here means behavior-preserving change or architecture deepening, not cosmetic churn.

Critical rule: preserve existing behavior unless the user explicitly asks for a behavior change. State the preservation target before editing.

Role-gated action

Detect your capability from your tools, not from prose:

• Write-capable role (engineer): map the scope, apply the batch edits, run lint/test verification.
• Read-only role (reviewer): map the scope and produce the refactor plan, then emit it in the Proposed Changes contract under Output. Apply nothing; run nothing — a reviewer has no edit or Bash tools.

Language detection

Detect the language from the file extensions in scope and preserve that language's idioms in the rewritten code. This skill has no per-language reference files — operate from the generic procedure.

When to Use edit_file

Use edit_file when:

• Multi-file batch refactoring
• Style/pattern update everywhere
• Complex prompt → many changes
• Structural refactoring at scale
• 5+ files need same pattern

Use Built-in Edit/MultiEdit when:

• Single file, clear edit
• 2-3 targeted replacements
• Need clear diff to review/tune
• Simple rename (replace_all)
• Straightforward single-file work

Key Features

• Semantic merge: Understands code structure, not just text
• Speed: 10,500 tok/s vs 180 tok/s streaming
• Accuracy: 98% success rate on edge cases
• dryRun: Preview changes before applying

Architecture Deepening

When applying an approved architecture-deepening refactor, keep the seam rule (one adapter means a hypothetical seam; two adapters means a real seam — do not add interfaces without real variation) and the deletion test in mind. The module-depth vocabulary is owned upstream by improving-codebase-architecture (references/LANGUAGE.md) and reviewing-code; match the design agreed there and do not redefine the terms here. Read relevant CONTEXT.md, CONTEXT-MAP.md, and ADRs when present. Preserve domain names.

Workflow

Standard Refactoring

1. Use WarpGrep or semantic search to find all locations needing change
2. State: "Behavior must be preserved unless the user explicitly requested a behavior change."
3. Use MorphLLM `edit_file` or the batch refactoring workflow for each batch/file, grouping related edits
4. Batch all edits for the same file into one edit operation
5. Verify with lint/test
6. Delete obsolete shallow tests once deeper interface tests cover the behavior

For multi-file renames, say this is a batch refactor, map all occurrences before editing, use the batch refactoring tool/workflow by name, preserve behavior, and run relevant lint/tests after the rename.

High-Stakes Changes (dryRun)

1. Call edit_file with dryRun: true
2. Review preview output
3. If approved, call again with dryRun: false

Parameters

path: "/absolute/path/to/file"
code_edit: "changed lines with // ... existing code ... markers"
instruction: "brief description of changes"
dryRun: false (set true to preview)

Edit Format

Use // ... existing code ... markers for unchanged sections:

// ... existing code ...
function updatedFunction() {
  // new implementation
}
// ... existing code ...

Common Patterns

Batch Error Handling

instruction: "Add error wrapping to all repository methods"
code_edit: Shows only changed functions with context markers

Import Updates

instruction: "Update imports from old-pkg to new-pkg"
code_edit: Shows import section with changes

Multi-Location Rename

instruction: "Rename getUserById to findUser throughout file"
code_edit: Shows all locations with changes

Output

Engineer (applied the refactor): report the preservation target, files changed, and the lint/test verification result per touched file.

Reviewer (planned only — emit the refactor as a proposal, apply nothing):

## Proposed Changes

Preservation target: <behavior that must not change>

### Change 1: <brief description>

File: `path/to/file`
Action: CREATE | MODIFY | DELETE

Code:
<changed regions with // ... existing code ... markers>

Rationale: <why this change>

For multi-file renames, list every occurrence mapped before the proposal so the applier can replay it.

Failure handling

• edit_file unavailable → fall back to built-in Edit/MultiEdit; warn the user that large batches may be slower
• Tests fail after a batch edit → revert the last file edit, inspect the diff, and fix the conflict before continuing
• Scope unclear (user says "refactor this") → ask: "Which files and what behavior to preserve?" before touching anything

Tips

• Batch all edits to same file in one call
• Include enough context to locate changes precisely
• Preserve exact indentation in code_edit
• Use WarpGrep first to understand scope
• Run tests after each file to catch issues early
• Keep old public behavior stable unless the user explicitly requested behavior change
• Prefer tests through the deepened module interface over tests of extracted helpers