code-plan-refactor

Generate a safe refactoring plan only; do not apply code changes.

Process

Step 1 - Identify Context

• Inspect changed files with jj diff -s; restrict with jj diff -- path.
• Focus on user-specified files, paths, abstractions, or pain points.
• Clarify the desired outcome and non-goals.

Step 2 - Research and Scout

Apply a scout lens to analyze affected code areas, call sites, tests, abstractions, dependency edges, and local conventions for {task}:

• Map relevant files, conventions, and call paths; cite file paths and line numbers.

• Distinguish confirmed patterns from one-offs; stay read-only and task-relevant.

• For cross-module refactors, apply an architect lens to analyze module boundaries, ownership, dependency direction, and structural invariants for {task}:

  • Map current boundaries, ownership, and dependency direction first.
  • Recommend the smallest architecture that preserves invariants.
  • Avoid speculative generality.

Apply a planner lens to design a minimal behavior-preserving refactoring plan for {task}, including ordering, stop points, alternatives, and tradeoffs:

• Prefer simple, boring solutions; preserve existing project patterns.
• Make tradeoffs and assumptions explicit; scope to the current problem.

Apply a reviewer lens to review the proposed refactor for correctness, behavior preservation, simplicity, and project-convention risks:

• Ground findings in file paths and line numbers; prioritize the requested lens.
• Distinguish confirmed findings from speculative risks; explain why each issue matters.

Step 3 - Adjudicate Decisions

• For high-impact or conflicting design decisions, apply an oracle lens to adjudicate the conflicting refactoring recommendations for {task}:
  • Identify the decision; state assumptions and constraints.
  • Pick the smallest safe path that preserves future options.
  • State an explicit confidence level (high/medium/low) for the adjudication and its key assumptions.
  • Note what evidence would change the recommendation.

Step 4 - Audit

• For production-bound refactors, apply an auditor lens to audit the refactoring plan for {task} for production risks:
  • Data loss, migration hazards, rollback safety, contract compatibility, and correctness/security risk.
  • Flag only material risk; this is a final gate, not iterative style review.

Step 5 - Validate Findings

• Read relevant code yourself and validate findings.

Step 6 - Design Refactor

• Identify safe transformations (extraction, rename, simplification, deletion, inlining, module movement).
• Simplify design: prefer deleting or inlining code over adding new layers; ensure every abstraction earns its complexity.
• When deciding whether to split or combine modules, read the john-ousterhout-software-design reference and apply its "better together OR better apart" and deep-modules / information-hiding principles; do not split into shallow modules or leak information across boundaries.
• When choosing refactorings, read the martin-fowler-code-smells reference and match each smell to its primary fix; treat smells as heuristics, not hard violations, and skip what tooling already enforces.
• Break the work into small, behavior-preserving steps with verification after each.
• Identify where characterization tests are required before refactoring starts.
• Do not apply any code changes.

Step 7 - Report

Provide a structured report with:

1. Context Analysis — relevant code structure, patterns, call sites, dependency edges, behavior-preservation constraints.
2. Risk Analysis — risky transformations and mitigation strategies; tests/checks needed before changes.
3. Simplicity Constraint:
   • Deletion, inlining, or no-code alternatives.
   • Over-engineering risks.
   • Minimal viable scope.
4. Refactoring Plan:
   • Numbered, concrete steps with target files.
   • Verification procedures per step.
   • Rollback or stop points.

Prioritize actionable, specific guidance over abstract advice.