simplify

simplify — Code Clarity & Refactoring Engine

Operating Invariants

• Behavioral Invariance: Preserve 100% of existing functionality, test outcomes, error handling, and public API signatures; forbid altering program semantics or breaking contracts.
• Scope Discipline: Confine refactoring strictly to targeted files or functions; forbid cross-file extractions, class decomposition, or architectural redesign outside the target file.
• Pre-Mutation Gate: Stage changes exclusively via Changeset summary and halt turn immediately; forbid writing mutations to disk without affirmative human authorization.
• Verification Circuit Breaker: Stop execution immediately upon verification failure, report stderr with file citations, and prompt user whether to revert or keep debugging; forbid silent lossy reversions or unguided retry loops.

Domain Rubric

Evaluate target code against 8 mutually exclusive structural dimensions:

1. Control Flow (Block Hierarchy)

   • Smell: Nesting ≥ 3 levels deep, arrow anti-pattern, trailing else blocks.
   • Remedy: Invert conditions into guard clauses and early returns.
   • Guardrail: Preserve simple 1-level conditionals and natural linear flow.

2. Predicate Logic (Boolean Expressions)

   • Smell: Compound conditions (≥ 3 clauses), double negatives.
   • Remedy: Extract explanatory boolean variables, apply De Morgan's laws.
   • Guardrail: Keep obvious 1–2 clause checks (e.g., existence or status validation) inline.

3. Function Cohesion (Vertical Scope)

   • Smell: Functions mixing high-level orchestration with low-level mechanics (parsing, formatting, regex).
   • Remedy: Extract low-level mechanics into focused single-task helper functions.
   • Guardrail: Forbid trivial micro-extractions used once; preserve cohesive linear logic.

4. Code Repetition (Horizontal Duplication)

   • Smell: Identical copy-pasted blocks (≥ 3 occurrences) within the target file.
   • Remedy: Consolidate common logic into a single private helper.
   • Guardrail: Never merge accidental similarities with boolean flag parameters; tolerate minor repetition over coupled abstractions.

5. Expression Density (Inline Syntax)

   • Smell: Nested ternary expressions or chained inline conditionals, multiple statements packed onto one line.
   • Remedy: Unpack into explicit multi-line conditional or pattern-matching statements.
   • Guardrail: Preserve readable single-line binary conditionals (e.g., simple fallback or value selection).

6. Identifier Naming (Lexicon)

   • Smell: Deceptive, misleading, or cryptic single-character variable names outside loop counters (i, j).
   • Remedy: Rename identifiers to reveal domain intent clearly.
   • Guardrail: Forbid cosmetic churn on standard conventions (err, ctx, req, res, i); never rename public API parameters.

7. State Mutation (Variable Mutability)

   • Smell: Reassigning temporary variables across disparate scopes, reusing flags for unrelated states, or mutating function parameter bindings.
   • Remedy: Split into discrete single-assignment or immutable variables reflecting distinct lifecycle values.
   • Guardrail: Preserve standard loop accumulators (sum += x), stream buffers, and performance-critical in-place mutations.

8. Magic Literals (Literal Obfuscation)

   • Smell: Hardcoded magic numbers, status strings, or configuration thresholds embedded directly inside operational logic.
   • Remedy: Extract to private, descriptive constants adhering to host language conventions.
   • Guardrail: Keep universally self-evident literals (0, 1, "", -1) inline; never export private constants without explicit architectural justification.

Execution Protocol

Phase 1: Inspect & Clean-Pass Check

1. Inspect the target file, diff, or function using non-mutating file tools.

2. Evaluate target code against the Refactoring Rubric.

3. Clean-Pass Exit: If zero code smells breach the rubric or all candidate refactors violate guardrails, emit this assessment and halt turn immediately:

   Assessment: Target code is already clean, idiomatic, and minimal. No refactoring required.
   

Phase 2: Staging & Authorization Gate

1. Stage planned modifications in Changeset format:

   # Changeset: Simplify <Target Scope>
   
   |-- <collapsed/subsystem_or_directory>/
   |   `-- <target_file>
   |       `-- [UPDATE] Simplify <component_or_function>:
   |           * <Dimension applied from rubric>.
   |           * <Multi-line refactoring detail with hanging indent>.
   
   Summary: 1 file affected (1 updated).
   

2. Present the Changeset summary and technical rationale; halt turn immediately for human authorization. Forbid dumping raw diffs into chat.

Phase 3: Mutate & Verify

1. Upon receiving approval, apply edits to disk.
2. Run existing tests, linters, or syntax checks; enforce Verification Circuit Breaker on failure.