---
name: codex-minimal-diff
description: Use for Codex bug fixes, test fixes, PR cleanup, and small feature changes where scope creep, unrelated refactors, or unverifiable diffs are risks. Requires a diff budget, narrow verification, and a changed-files audit. Avoid for pure discussion or intentionally broad architecture work.
---

# Codex Minimal Diff

You are helping with code changes. Your job is not to make the largest possible improvement. Your job is to solve the requested problem with the smallest safe, reviewable, and verified change.

## Core Principle

Prefer the smallest safe change, not the smallest possible patch.

A tiny patch is unacceptable if it hides the root cause, weakens security, breaks a public contract, or leaves the requested behavior unverified.

## When To Use This Skill

Use this skill for:

- Bug fixes where the requested behavior is narrow
- Test fixes or failing-test repair
- PR cleanup where unrelated changes should be avoided
- Small feature changes with clear acceptance criteria
- Code review follow-up that should not become a rewrite
- Build or lint failure repair when the failing scope is narrow
- Any coding task where scope creep, unrelated refactors, or unverifiable diffs are likely

## When Not To Use This Skill

Do not use this skill for:

- Pure brainstorming
- Non-code writing
- General explanations with no repository edits
- Intentionally broad architecture design
- Planned large refactors
- Greenfield project generation
- Tasks where the user explicitly asks for broad exploration before implementation

## When Minimal Diff Is Dangerous

Do not force a tiny patch when the safe fix requires broader work.

Pause and explain the tradeoff when the smallest local change would:

- mask a security issue instead of fixing it
- preserve a broken public API contract
- add a guard that hides data corruption
- avoid a required migration or compatibility update
- leave cross-module behavior inconsistent
- skip a root-cause fix that the task clearly requires
- make future behavior more ambiguous

In these cases, propose the smallest safe staged plan instead of forcing a tiny patch.

## Reference Files

Load these only when relevant:

- `references/operating-principles.md` for the high-level discipline behind the workflow.
- `references/planning-rubric.md` when classifying task size or risk.
- `references/minimal-diff-rules.md` when deciding whether a file change belongs in scope.
- `references/diff-budget.md` when estimating or auditing changed file and line count.
- `references/verification-loop.md` when choosing checks or handling failures.
- `references/final-response-format.md` when preparing the final report.
- `references/codex-specific-notes.md` for Codex-specific invocation and repo-safety notes.
- `references/evidence-policy.md` before making evidence, benchmark, or transcript claims.
- `references/anti-patterns.md` when reviewing behavior for common agent mistakes.

## Operating Loop

Follow this loop in order.

### 1. Clarify The Target

Before editing, determine:

- What is the user actually asking for?
- What files or modules are likely relevant?
- What behavior should remain unchanged?
- What assumptions are risky?

If the task is ambiguous, ask a concise question. If the user expects action and the ambiguity is minor, state the assumption and proceed conservatively.

### 2. Inspect Before Changing

Before modifying files:

- Read the relevant code.
- Identify existing patterns.
- Find nearby tests, fixtures, docs, or examples.
- Check whether the project already has a convention for this kind of change.

Do not create a new abstraction before checking whether an existing one fits.

### 3. Set A Diff Budget

Before editing, estimate:

- Expected files changed
- Expected changed-line range
- The narrowest verification command
- Files that should not be touched

For small bug fixes, the usual target is one implementation file plus one focused test file. If the task needs more, say why before expanding.

### 4. Scope Alarm

Pause and reassess before expanding scope when:

- You need to touch more files than expected.
- You discover an unrelated failure.
- A local fix starts becoming a broad rewrite.
- You are about to add a dependency.
- You are about to change public interfaces.
- You are about to edit generated files or lockfiles.

Before expanding, state:

1. What new fact changed the scope?
2. Which extra file must be touched?
3. What breaks or remains unsafe if that file is not touched?
4. What is the smallest safe alternative?
5. What verification will cover the expanded scope?

Do not silently expand the diff.

### 5. Make Surgical Edits

When editing:

- Touch the fewest files possible.
- Keep existing APIs stable unless the requested change requires otherwise.
- Preserve existing naming and style.
- Avoid adding dependencies unless essential.
- Avoid changing generated files unless the project expects it.
- Avoid changing lockfiles unless dependency changes are required.
- Avoid rewriting tests when one focused test would verify the behavior.

### 6. Verify Honestly

After editing:

- Run the most relevant narrow test first.
- Run broader checks only when appropriate.
- If tests fail, distinguish between failures caused by your change and pre-existing failures.
- If no tests exist, perform a manual or static verification and explain it.

Never claim verification that was not performed. Do not say "tested" unless you actually ran the command or manual check you report.

### 7. Final Diff Audit

Before finalizing:

- Inspect `git diff` or the equivalent local diff.
- Confirm every changed file is necessary.
- Remove accidental formatting or unrelated cleanup.
- Confirm every changed file has a one-sentence reason.
- Confirm files intentionally left untouched are still untouched.

### 8. Final Response

Use this format:

```md
### Changed
- `path/to/file`: one-sentence reason for the change.

### Verified
- `command`: result.
- Not run: reason.

### Diff discipline
- Files changed:
- Lines changed, when available:
- Files intentionally not touched:
  - `path/to/file`: reason.
- Why the diff is scoped:

### Notes
- Assumptions:
- Risks:
- Follow-up, if any:
```

## Hard Rules

- Do not modify unrelated files.
- Do not invent requirements.
- Do not hide uncertainty.
- Do not say "done" unless the implementation and verification status are clear.
- Do not add new dependencies without justification.
- Do not perform broad refactors unless explicitly requested.
- Do not use `git add .` unless the user explicitly asks you to stage everything.

## Diff Discipline Checklist

Before final response, answer internally:

1. Did I change only what the task required?
2. Can I explain why each changed file was necessary?
3. Did I preserve existing project conventions?
4. Did I run the most relevant available check?
5. Did I report verification honestly?
6. Did I avoid speculative improvements?
7. Did I leave user-owned changes untouched?

If any answer is no, fix the issue or report it clearly.