Bonus 07 of 07
How to read a diff - and why you must before accepting any change
Goal: A diff shows you exactly what Codex changed — line by line. Reading it is the most important habit a non-developer can build. This lesson teaches you what the symbols mean, which areas are scary to change, how to spot unwanted edits, and how to ask Codex for a targeted revert.
What to do
Learn what plus and minus mean in a diff
A diff uses two symbols to show changes. A minus sign (-) at the start of a line means that line was removed. A plus sign (+) at the start of a line means that line was added. Lines with no symbol are unchanged — they are shown for context. When Codex changes a line, you see the old version with a minus and the new version with a plus. Read the worked example below carefully. Every concept in this lesson comes back to these two symbols.
WORKED DIFF EXAMPLE — read this carefully
File changed: components/HeroSection.tsx
@@ -12,7 +12,7 @@
<section className="hero">
- <h1>Welcome to my site</h1>
+ <h1>Build your first app without coding</h1>
<p>Start your free challenge today.</p>
</section>
What this means:
- Line removed: the old heading "Welcome to my site"
+ Line added: the new heading "Build your first app without coding"
Lines with no symbol: unchanged — shown for context only
The @@ numbers tell you which line in the file this section is near.
You do not need to understand the numbers — just read the + and - lines.Check the changed-files list before reading individual diffs
Before you read the diff inside any file, look at the full list of changed files. In GitHub Desktop this is the left panel. The list itself is your first safety check — it tells you how many files changed and which ones. Your approved file list from the session should match this panel exactly. Count the files. Read every name. Do not start reading individual diffs until you have checked the full list against what you approved.
Identify scary areas — files you should never approve quickly
Some areas of a project carry high risk if changed incorrectly. When any of these file paths or names appear in your changed-files list, slow down and read every line of the diff carefully — even if Codex described the change as small.
SCARY AREAS — read these diffs with extra care
Authentication and login
Files with: auth, login, session, middleware, token, jwt, cookie
Payments and billing
Files with: payment, stripe, billing, checkout, subscription, price
Database and data
Files with: migration, schema, sql, supabase, prisma, database, seed
Environment and secrets
Files with: .env, config, secrets, credentials, keys
Security
Files with: rls, policy, cors, permissions, firewall, protect
Build configuration
Files with: next.config, tsconfig, vite.config, webpack, package.json
Rule: if the changed file name contains any of these words or patterns,
do not approve until you have read every plus and minus line in that file's diff.Spot unrelated changes and decide what to do
An unrelated change is a modification to a file or line that has nothing to do with your original request. Codex sometimes "improves" things it noticed while working — adding comments, reformatting lines, fixing unrelated issues. These may or may not be problems, but you did not ask for them, which means you did not evaluate their safety. The rule: any change you did not request must be examined before it is kept.
Ask Codex to explain the full diff in plain English
If a diff contains changes you are not sure about, paste the whole diff into Codex and ask for a plain-English explanation. Use the prompt below. Copy the diff from GitHub Desktop by clicking on the file and selecting the changed content, or use the "Copy diff" option if available.
I am reviewing a diff from a recent Codex session. I need you to explain it in plain English before I decide whether to accept or reject the changes.
Here is the diff:
[PASTE THE FULL DIFF HERE]
Please do the following:
1. Describe in plain English what changed in each file.
2. For each change, tell me whether it matches the task I originally asked for, which was: [DESCRIBE YOUR ORIGINAL REQUEST].
3. Flag any change that looks unrelated to my original request.
4. Flag any change that touches authentication, payments, database, environment files, or security rules.
5. Do not make any further changes. This is a review step only.Ask Codex for a targeted revert if you want to keep some changes but not others
Sometimes a diff has good changes mixed with unwanted ones. You want to keep the wanted change and undo only the unwanted part. Do not discard the whole file — ask Codex for a targeted revert using the prompt below. Always do this in GitHub Desktop with the original file still showing as "changed" (do not commit first).
I reviewed the diff from our last session and I want to keep some changes but revert others.
Changes I want to KEEP:
[DESCRIBE WHAT YOU WANT TO KEEP — e.g., "the updated heading text in HeroSection.tsx"]
Changes I want to REVERT:
[DESCRIBE WHAT YOU WANT UNDONE — e.g., "the reformatting of the paragraph styles in the same file"]
Please do the following:
1. Show me exactly which lines need to be restored to their original state to complete the revert.
2. Make only those specific line changes. Do not touch the lines I listed under "keep."
3. After making the revert, show me the resulting diff so I can confirm it looks correct.
4. Do not change any other file.Expected result
You can read a diff and identify added lines, removed lines, the full changed-files list, scary-area files, and unrelated changes. You used the explain-diff prompt to get a plain-English summary, and you practiced asking for a targeted revert for unwanted changes.
Key takeaway
- Reading the diff is not optional. It is the only way to know what actually changed versus what you asked for. Run it after every session, every time — even when the session felt smooth.