---
name: minimal-change-coding-guidelines
description: "Guides an agent to make the smallest change that solves the problem, with no speculative abstractions and no unrelated edits in the diff. Use when an agent or contributor tends to over-engineer, and a bug fix or small feature should land as a minimal, reviewable diff. Do not use for large refactors or deliberate redesigns of a module. Related topics: coding, technical."
---

# Minimal-Change Coding Guidelines

Guides an agent to make the smallest change that solves the problem, with no speculative abstractions and no unrelated edits in the diff.

## When to use

Use this skill when an agent or contributor tends to over-engineer, and a bug fix or small feature should land as a minimal, reviewable diff. Do not use it for large refactors or deliberate redesigns of a module.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. State in one sentence the behaviour that must change and the behaviour that must stay the same.
3. Read the surrounding code and note its conventions, so the edit matches them.
4. Edit at the root cause, adding no new abstractions, options, dependencies or impossible-case handling.
5. Add or adjust a test that fails before and passes after, then run the existing checks and record the result.
6. Summarise the touched files and risks, and list unrelated problems noticed but left unchanged.

## Inputs

- **Task** (longer free text)
- **Relevant files** (longer free text)
- **Existing conventions** (longer free text)
- **Tests available** (choose one: Unit tests exist, Only manual checks, No tests)
- **Change budget** (choose one: A few lines, One function, One file, Several files if needed)

## Output

The code change as a minimal diff, followed by a summary of files touched, the reason for each change, checks run, risks, and a list of noticed-but-untouched issues.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Minimal-Change Coding Guidelines

Make the smallest correct change for this task.

- Task: {{Task}}
- Relevant files: {{Relevant files}}
- Existing conventions: {{Existing conventions}}
- Tests available: {{Tests available}}
- Change budget: {{Change budget}}

Before editing, state in one sentence the behaviour that must change and the behaviour that must not. Read the code around the change and follow its conventions, even where you would write it differently. Make the edit at the place where the cause lives, not where the symptom shows. Do not add abstractions, configuration options, new dependencies or error handling for cases that cannot happen. Do not rename, reformat, reorder or tidy lines unrelated to the task; if you spot a real problem elsewhere, list it afterwards instead of fixing it. Add or adjust a test that fails before the change and passes after, when tests exist. Run the existing checks and report what ran. Finish with a summary: files touched, why each line changed, risks, and anything noticed but left alone.

## Pitfalls

- Reformatting a file while fixing one line, which buries the real change in whitespace noise.
- Adding a helper or option for a future need, which becomes code someone must maintain with no user.
- Fixing where the error appears instead of where it starts, so the same bug returns elsewhere.