Strategy — Minimal Diff Edits

When to use

• The user asks to fix a single bug or make a small change and does not want the surrounding file or module rewritten.
• The user wants only the requested change and no drive-by cleanups, reformatting, or unrelated refactors mixed into the same edit.
• The change can be expressed as a targeted, scoped edit to a few lines rather than a rewrite of the whole file or class.

When NOT to use

• Do not enforce minimal diffs when the user has explicitly asked for a full rewrite, a redesign, or a large-scale rework of the file or module.
• Do not apply this strategy when the user explicitly asks to create a new file or scaffold a greenfield module — there is no existing code to keep the diff small against.

Core guidance

• Defer unrelated cleanups to a separate change — When you notice unrelated improvements while making the change, note them for a follow-up instead of folding them into the current edit.
• Edit in place rather than rewriting the file — Prefer an in-place edit of the specific lines over rewriting or regenerating the whole file. Only rewrite a file when the change genuinely touches most of it.
• Match the surrounding style, do not reformat — Match the existing indentation, quote style, and naming of the surrounding code. Do not reformat, re-order imports, or re-wrap lines you are not otherwise editing.
• Read the diff and drop incidental changes — Before finishing, read the diff and remove any change that is not required by the request — stray blank lines, reordered members, or reformatted blocks.
• Scope the edit strictly to the request — Change only the lines needed to satisfy the request. If a line does not contribute to the fix or feature, leave it exactly as it is.

Never

• Never rewrite or regenerate an entire file when a targeted edit to a few lines would satisfy the request.

Prefer

• Prefer the smallest correct edit that satisfies the request, and match the surrounding code's style so the diff shows only the intended change.

Avoid

• Avoid drive-by refactors, import re-ordering, and reformatting of lines you are not otherwise changing; keep unrelated cleanups out of the diff.

Escalate to user when

• Escalate to the user when a correct fix appears to require a large rewrite or broad structural change, and confirm the wider scope before making it.

Quick recipe

1. Read the relevant code and identify the smallest span of lines that must change to satisfy the request. (verify: The identified span is limited to what the request needs, with no adjacent code included.)
2. Edit only those lines in place, matching the surrounding style, then read the resulting diff and remove any incidental change. (verify: The diff contains only the lines required by the request and no reformatting or unrelated edits.)

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Editor auto-formats the whole file — A format-on-save or auto-formatter rewrites the whole file, turning a one-line fix into a hundred-line diff. Fix: Disable format-on-save for the change, or reformat only the lines you edited, so the diff reflects only the intended fix.
2. Regenerating a file silently drops detail — Rewriting a file from memory instead of editing it drops comments, edge-case handling, and formatting that were not part of the request. Fix: Edit the existing content in place; never regenerate a file you could have patched.
3. Fixing nearby code you were not asked to touch — While making the requested change you "improve" adjacent code that was working fine, widening the diff and the blast radius. Fix: Change only what the request needs; record adjacent improvements as a separate follow-up.

Version notes

• Minimal-diff discipline is version-agnostic (PHP >=7.4) — This editing strategy applies to any PHP version; it constrains how the agent edits, not which language features it uses, so it holds from PHP 7.4 upward.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/ai-rules/strategy-minimal-diff.yaml.

Additional resources

• references/anti-patterns.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: ai-rules/strategy-bitrix-d7-incremental, ai-rules/strategy-explicit-over-magic, ai-rules/strategy-framework-conventions, ai-rules/strategy-legacy-safe-edits, ai-rules/strategy-no-untested-refactor, ai-rules/strategy-preserve-public-api, ai-rules/strategy-readonly-immutability, ai-rules/strategy-security-first, ai-rules/strategy-test-driven