Minimal File Changes

Goal

Deliver the requested outcome with the smallest reasonable set of changes:

• Minimise file churn
• Avoid new abstractions unless they are clearly necessary
• Preserve existing project structure and conventions

Default Behaviour

• Prefer editing existing files over creating new ones.
• Prefer local refactors (within the touched file) over introducing new layers (services, helpers, traits, DTOs).
• Do not create new base directories or reorganise folder structure without explicit user approval.

When to Create New Files

Only create new files when one of the following is true:

1. Laravel conventions require it

   • e.g. migrations, tests, policies, form requests, jobs, events/listeners, new models/components explicitly requested

2. The user explicitly asked

   • e.g. “create a new class”, “extract to a service”, “make a new component”

3. A change would be unsafe or unmaintainable without separation

   • If you believe separation is required, explain why in 1-2 sentences and ask for approval before creating the new file.

One File at a Time Rule

If a new file is required:

• Create only one new file per iteration
• Then stop and ask if the user wants to proceed with the next file/change

What NOT to Do

• Do not introduce new architectural patterns (Repository, Service layer, DTOs) by default.
• Do not create Helpers/, Services/, Support/, DTO/, or similar folders without explicit approval.
• Do not split code across multiple files “for cleanliness” unless asked.
• Do not do broad renames, mass formatting, or reorganisations unrelated to the request.

How to Handle Tension Between “Best Practice” and “Minimal Change”

If the best-practice approach conflicts with minimal change:

• Provide the minimal-change solution first
• Optionally propose a follow-up improvement as a separate step
• Do not implement the broader refactor unless the user approves

Anti-patterns

• “I extracted this into 5 new classes to improve readability” (without being asked)
• “I reorganised these folders to follow a cleaner architecture”
• “I created a base abstraction for future use”