7.4 The "explain then rewrite" pattern

The core idea

When you ask an LLM to change code it doesn’t understand, it will still change it—confidently. “Explain then rewrite” is how you prevent that.

The pattern is:

1. Explain: force the model to describe what the code currently does, in your terms.
2. Validate: you correct misunderstandings and confirm intent.
3. Plan: it proposes a small, reviewable sequence.
4. Rewrite: it outputs diff-only changes step-by-step.

Why explanation first prevents breakage

This pattern prevents three common failure modes:

• Misread intent: the model guesses what code is “for” and changes it incorrectly.
• Hidden contracts: the model breaks behavior that wasn’t mentioned in the prompt.
• Overreach: the model proposes “improvements” outside scope.

When you force an explanation first, you surface contracts and assumptions before they become regressions.

What to paste (and what not to)

For explanation, you usually want a narrow slice:

• the file(s) you plan to change,
• their direct dependencies (imports/types) if needed,
• any failing tests or error output,
• a short file tree for orientation.

Avoid pasting:

• the entire repo (unless necessary),
• generated files or huge vendor bundles,
• secrets or sensitive data.

Explanation checklist (what you want back)

Ask the model to explain using a structured checklist. You want:

• High-level purpose: what the module does in one paragraph.
• Inputs/outputs: function signatures, data flow, return values.
• Side effects: file/network/db writes; global state.
• Error behavior: what exceptions/errors occur and where.
• Invariants: assumptions the code relies on.
• Edge cases: what breaks easily.
• Dependencies: what it calls and what calls it.
• Tests: what currently verifies it (if any).

If the model can’t answer one of these, it should say “unknown” and ask a question. That is a good sign, not a failure.

A safe rewrite flow (explain → plan → diff)

Once you have a correct explanation, your flow should be:

1. Confirm constraints: what files are in scope, what behavior must not change.
2. Ask for a plan: 3–8 steps, each with verification.
3. Implement step-by-step: diff-only, run tests between steps.
4. Stop at ship points: commit when stable.

This avoids the classic “one big rewrite” failure.

Copy-paste prompt sequence

Prompt A: explain only

I want to change this code, but first I need you to explain it.

Task:
Explain what this code does, including data flow, error handling, and assumptions.

Output format:
- 10–20 bullet summary of behavior
- List of inputs/outputs and invariants
- List of risks/edge cases
- List of questions/unknowns (if any)

Important:
- Do NOT propose changes yet
- Do NOT write any code yet

Context:
- File tree: (paste)
- Relevant files: (paste)

Prompt B: plan the change

Now propose a plan to implement this change:
[describe change]

Constraints:
- Only touch these files: [...]
- Preserve existing behavior except for the specified change
- Keep diffs small and reviewable

For each step:
- files touched
- verification (tests/commands)

Stop after the plan.

Prompt C: implement one step

Implement step 1 only.

Constraints:
- Diff-only changes
- Do not change other files
- After the diff, list how to verify

Common pitfalls (and fixes)

Pitfall: confident but wrong explanation

Fix: challenge with evidence: “Show me where in the code that happens.” If it can’t point to it, treat it as uncertain.

Pitfall: it sneaks changes into the “explanation” step

Fix: restate: “Stop. Explanation only. No recommendations or code.” Then rerun.

Pitfall: plan proposes broad refactors

Fix: constrain scope: “Rewrite the plan to deliver value in the smallest diff possible; defer refactors.”

Where to go next

• 7.5 Diff-only changes
• 8. Debugging with AI