Commits and Conflicts

Paul’s Hint of the Week · #1

Scope a Change Before You Prompt

· 3 min read · Free sample

Inspired by Episode 3: Just One Small Change

A five-minute ritual that keeps an AI assistant inside the lines: one goal, a fence, a finish line, a plan, and a diff you can actually review.

The goal

Turn a vague request into a bounded task, so your assistant changes what you asked for and nothing else. In Episode 3, “make the button green” became 14,382 changed files. This hint is how you avoid that.

Before you start

  • A clean working tree: commit or stash first, so everything that follows is the assistant’s change.
  • The files you expect to touch. Open them; skim them.
  • Five minutes. It saves an afternoon.

Step by step

Step 1: Write the goal in one sentence

Describe the outcome, not the implementation: “The Submit button on the signup form is green,” not “update the CSS.” If you need “and,” you have two tasks. Split them.

Step 2: Draw the fence

List the files the assistant may edit, then the things it must not touch. Off-limits areas are usually authentication, dependencies and lockfiles, database migrations, formatting of unrelated code, and public APIs.

Step 3: Define done

Write a check you can run or see: a test command, a page to open, a value to confirm. “Done” that can’t be checked isn’t done.

Step 4: Ask for a plan, not code

Have the assistant list the exact changes it intends to make and wait. Trim anything outside the fence before a single line is written. This is the cheapest moment to say no.

Step 5: Measure the diff

When it’s done, check the size before you read the details. If the diff is bigger than the request, reject it and re-scope; don’t review your way through it.

git diff --stat
git diff --name-only
git restore path/outside/the/fence   # drop anything you didn't ask for

Prompts to steal

Goal: The Submit button on the signup form is green (#16a34a).
You may edit: src/components/SubmitButton.tsx
Do not touch: auth, routing, dependencies, formatting of other files.
Done when: the button is green and `npm test` passes.

First, list the exact changes you plan to make. Wait for my OK before editing.
Before you continue: does any part of your plan touch files or behavior
outside the scope above? If so, list it separately and don't do it.

Checklist

  • The goal fits in one sentence, with no “and”.
  • Allowed files are named.
  • Off-limits areas are named.
  • “Done” is a check you can run.
  • You approved a plan before any code was written.
  • git diff --stat matches the size of the request.

Common mistakes

  • “While you’re in there…” Bundling a second request is how scope creep starts. Make it a second task.
  • Trusting the summary. “I made a few small improvements” is a description; the diff is the record.
  • Skipping the plan because the change is small. Small requests are exactly where surprise refactors hide.