Refactor Plan

General Rules

• Keep behavior-preserving work clearly separate from intentional semantic redesign.
• If behavioral parity is requested, treat parity as a proof task, not an assumption.
• For exploratory planning without merge judgment, keep parity status provisional by default.
• Preserve interface, schema, config, and generated-artifact coupling awareness when types, packages, or module boundaries move.
• Include wiring or registration checks when moving framework configuration, plugins, containers, consumers, handlers, or adapters.
• Prefer targeted parity tests plus build, startup, and runtime smoke gates for touched paths rather than vague "test everything" plans.
• Call out any expected deltas in null handling, exceptions, logging, retry behavior, side effects, concurrency, or transaction shape.
• Do not mix unrelated modernization, formatting, naming churn, and semantic redesign into the same step unless the plan explicitly says that is the goal.
• Prefer evidence-first planning: if invariants, contracts, or affected paths are unclear, investigate before defining the step boundary.
• Preserve plan continuity: when a track hands work to a later track, leave a handoff snapshot instead of silently rewriting history.

Planning Guardrails

• Do not present speculative architecture as if it were already approved.
• Do not label a step "behavior-preserving" if contracts, persistence semantics, or side effects are intentionally changing.
• Do not claim "parity preserved", "no drift", or "safe to merge" before strict comparison evidence is recorded.
• Do not hide risky deltas inside broad step names like "cleanup", "modernization", or "polish".
• Do not use phases as a vague backlog dump; each phase needs a purpose, scope boundary, and exit gate.
• Do not assume a repository needs numbered plans if it already has a better local convention.
• Do not delete prior rationale from existing plan files unless the repository explicitly treats them as disposable working notes.
• Do not create a second refactor-planning folder when the project already has one established.

Bundled References

• Use the reusable checklist in references/checklist.md.
• Use the plan template in templates/plan.md.
• Use the log template in templates/log.md.
• Use the merge-check template in templates/merge-check.md.

If the project already has a numbered scheme such as REFACTOR-0001, reuse that style. If not, adapt the same structure to the local naming convention.

Canonical Output Format

Unless the repository already has a stronger mandatory format, generate plans in this exact section order:

1. Purpose
2. Refactor Type
3. Scope
4. Non-Goals
5. Invariants
6. Planned Work
7. Validation Gates
8. Intentional Deltas
9. Risks / Open Questions
10. Exit Goal

For every step inside Planned Work, include these exact fields:

• Goal
• Why this grouping
• Guardrails
• Targets
• Validation
• Exit gate

When work moves to a later track, add a final handoff section:

• Handoff to Next Track

Use this stricter structure by default. Do not omit sections just because the answers are incomplete; mark them as provisional if needed.

Log Guidance

Write refactor logs as durable execution records, not casual notes.

• Use logs to capture:
  • step completion
  • blocker discovery
  • runtime smoke results
  • merge or parity checks
  • wrap-up and handoff outcomes
• Prefer one log per meaningful event or batch.
• Keep logs factual and scoped:
  • what was attempted
  • what changed
  • what was validated
  • what remains risky
  • what comes next
• Do not mix multiple unrelated events into one log just because they happened on the same day.
• When a log is tied to a plan track, link the active tracking file near the top.
• Prefer ./docs/plans/refactoring/logs/ as the default log folder unless the project already uses a different established location.

Unless the project already has a stronger mandatory format, generate logs in one of these canonical shapes:

• Step log
• Blocker log
• Runtime smoke log
• Wrap-up or handoff log
• Merge check log

Use the shared template and adapt the optional sections to the log type instead of inventing a new structure each time. For merge or parity judgment logs, prefer the dedicated merge-check template instead of the general log form. When baseline or parity expectations are not obvious from the project context, ask for the missing comparison target if needed; otherwise proceed with an explicit provisional assumption and record it in the merge check.

Output Standard

Every refactor plan should make these items explicit:

• compare target or baseline
• invariants to preserve
• scope and non-goals
• step/phase boundaries
• validation gates
• intentional deltas
• residual risks or open questions

If any of those are unknown, mark them as provisional instead of pretending they are settled.

Parity-Strict Mode

When the user prioritizes behavioral parity, this mode is mandatory.

Activation boundary:

• Use this mode when parity, no-drift, or safe-to-merge claims are explicitly requested or clearly implied.
• If the user is only exploring plan options without merge judgment, keep parity provisional and do not force strict conclusions.

Required behavior:

• Pin an explicit compare baseline (branch/commit/release target) and record an immutable reference (resolved commit SHA) when available.
• Build a source mapping of affected old-path to new-path for the full execution flow.
• Perform file-by-file and logic-unit comparison before parity conclusions (branches, predicates, mappings, and side-effect paths).
• Compare query semantics explicitly:
  • selected tables
  • join type and predicates
  • where predicates
  • group/order/limit behavior
  • null/default/fallback behavior
  • status/filter conditions
• Compare write-path semantics explicitly:
  • write targets and predicates
  • upsert/update/insert behavior
  • timestamps, actor/source, and idempotency-relevant fields
• Compare mapping/output construction explicitly:
  • field-by-field payload population
  • defaults, fallbacks, and exception behavior
  • ordering and dedupe semantics
• Compare side-effect semantics explicitly:
  • events/messages emitted
  • audit/history writes
  • cache invalidation
  • notifications
  • security/authorization outcomes
• Compare failure-mode semantics explicitly:
  • exception propagation/translation
  • retry/rollback/compensation behavior
  • transaction boundary and partial-failure behavior

Claim rules:

• If any relevant path is not audited, parity status must be Unknown/Provisional.
• Do not use confidence language to mask missing audit coverage.
• Behavioral parity = Preserved is valid only when strict audit coverage is complete, including side-effect and failure-mode coverage.
• If drift is found mid-audit, report it immediately and revise prior parity claims.
• If a previous parity-safe statement is later contradicted by audit evidence, explicitly retract and correct that statement.