Category: Engineering Domain: Debugging & Maintenance

• The user asks to "fix a bug with minimal changes", "do a focused bugfix", or "scope a minimal repair"
• A bug report needs triage to identify the smallest set of files to touch
• A PR is at risk of scope creep (unrelated refactors, style changes, "nearby" fixes)
• A hotfix or release-blocker needs a low-risk, reviewable change set
• The user asks "what is the minimal change to fix X?" or "which files do I need to touch for this bug?"

• Files most likely related to the bug (keyword matching, import tracing)
• Estimated change scope (number of files, lines)
• Risk assessment for the change
• Recommended fix approach (minimal vs. structural)

1. Write a clear bug description — reproduction steps, expected vs actual behavior
   • Validate: the description names the observable failure, not a guess at the cause
2. Run

   change_scope_analyzer.py

   to identify scope
   • Validate: analyzer output lists concrete files and an estimated line count
3. Review the recommended files and approach
   • Validate: recommended approach is "minimal" — if it says "structural", stop and scope a refactor PR separately
4. Make ONLY the changes needed to fix the bug
   • Validate:

     git diff --stat

     matches (or is smaller than) the analyzer's recommendation
5. Verify no unrelated changes leaked in
   • Validate:

     git diff

     shows no formatting-only changes, no unrelated imports, no "while I'm here" edits
6. Submit PR with focused change set
   • Validate: commit message states the exact bug fixed, and a regression test is included

1. After making changes, re-run analyzer
2. Compare actual changes against recommended scope
3. Flag any out-of-scope modifications for separate PRs
   • Validate: any file touched that was not in the analyzer recommendation has a one-line justification or is reverted

• Focused Fix Methodology - Principles, anti-patterns, and decision framework

• Fix the exact bug reported
• Add a regression test for the fix
• Document why the fix works in the commit message
• Keep the diff as small as possible

• Refactor surrounding code during a bugfix
• Fix "nearby" issues in the same PR
• Change formatting or style in touched files
• Add features disguised as bugfixes