# Disciplined Code Changes

> Apply engineering guardrails when writing, modifying, or refactoring code — scoped changes, verified assumptions, simplest correct solution, real validation, no premature optimization.

- Skill: `egkz/disciplined-code-changes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add egkz/disciplined-code-changes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/egkz/disciplined-code-changes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: egkz (https://skillmd.com/u/egkz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/egkz/disciplined-code-changes

---


# Disciplined Code Changes

Guardrails against the ways code assistance commonly goes wrong. Apply them while
the work happens, not as a post-hoc review.

## Before you start

- Restate the requested change in one sentence. If your restatement is broader than
  the request, you have already scoped-crept.
- Name the assumptions the implementation depends on — about requirements, APIs,
  existing behavior, architecture. Verify the ones that would change the design.
- If the requirements are ambiguous in a way that changes what you build, ask now.
  One question beats a rewrite.

## The rules

### Prefer small, verifiable changes

Make the smallest change that satisfies the request, in a form where you can
demonstrate it works.

*Violation looks like:* a large diff landing all at once with no intermediate point
where behavior was checked.

### Keep changes scoped to the requested task

No unrelated refactors, cleanup, renames, or stylistic edits. Note them separately
if they matter; do not fold them in.

*Violation looks like:* the diff touches files the request never mentioned, or
reformats lines you only happened to read.

### Validate behavior, not just compilation

Run the relevant tests and checks. A build that succeeds is not evidence that the
requested behavior works.

*Violation looks like:* "this should work now" with no command run and no output
shown.

### Check assumptions

When an assumption materially affects the implementation, verify it against the
code, the docs, or the running system rather than proceeding on confidence.

*Violation looks like:* calling an API with a signature you remember rather than one
you looked up.

### Prefer the simplest correct solution

Reject unnecessary abstractions, layers, interfaces, configuration options, and
dependencies. If a substantially simpler implementation satisfies the requirements,
that is the implementation.

*Violation looks like:* a factory, a strategy interface, or a new config flag
introduced for a single call site with one caller.

### Preserve unrelated code

Do not remove or rewrite comments, error handling, or behavior merely because you
consider them unnecessary or prefer another approach. Existing code usually encodes
a reason you cannot see.

*Violation looks like:* deleting this comment because the code "reads fine":

```kotlin
// Fall back to the default timeout because the configured value can be null for
// newly created environments, and OkHttp requires a positive timeout value.
val timeout = config.requestTimeout ?: DEFAULT_TIMEOUT
```

### Keep the codebase clean

Remove scaffolding, debug output, and scratch files introduced during the work.
Leave behind no dead code, unused abstractions, or unnecessary dependencies.

Never leave comments that narrate the editing session — no "updated to handle the
new case", "removed the old approach", "refactored per request". Comments explain
the code as it stands, to a reader who was not there.

### Surface uncertainty and tradeoffs

When requirements are ambiguous, or when multiple approaches carry meaningful
tradeoffs, say so and either ask or state the tradeoff plainly. Do not pick one
silently and present it as the only option.

*Violation looks like:* choosing between two storage designs without mentioning that
a choice existed.

### Do not optimize prematurely

Get it correct first. Optimize only when there is a demonstrated need or an explicit
performance requirement, and verify the optimization preserves correctness.

*Violation looks like:* caching, batching, or hand-unrolling something nobody has
measured.

### Do not overdo documentation

Generated documentation is cheap to produce and expensive to keep true. Write what
carries real information and will stay accurate. Prefer clear code and precise names
over prose restating them.

*Violation looks like:* a docstring on every trivial getter, or an architecture
document nobody asked for.

## Work from success criteria

Prefer explicit, testable outcomes over step-by-step instructions. When given a
desired outcome, choose how to reach it — while staying inside the project's
existing conventions and constraints. When you are the one specifying work, state
the criteria rather than the steps.

## Before you hand back

1. The relevant tests and checks were actually run, and you can show the output.
2. No temporary code, debug statements, or scratch files remain.
3. Every file in the diff is one the task required touching.
4. No comment refers to the editing process or to prior versions of the code.
5. Any assumption you could not verify, or tradeoff you chose between, is stated
   explicitly in your response.