De-slop: remove every em-dash + banned words across all modules + capstone (#94)
Sync course wiki / sync-wiki (push) Successful in 4s

Co-authored-by: claude <claude@jpaul.io>
Co-committed-by: claude <claude@jpaul.io>
This commit was merged in pull request #94.
This commit is contained in:
2026-06-22 23:21:22 -04:00
committed by Claude (agent)
parent 513d7e7ac8
commit c098933f25
99 changed files with 1324 additions and 1315 deletions
@@ -1,4 +1,4 @@
# Module 10 Reviewing Code You Didn't Write
# Module 10: Reviewing Code You Didn't Write
> **The AI wrote a diff that reads beautifully and is wrong in one line you'll skim right past.**
> Reviewing for *plausibility traps*, not just bugs, is a skill almost nobody teaches. This module
@@ -8,12 +8,12 @@
## Prerequisites
- **Module 2 Version Control as a Safety Net.** You read changes with `git diff`. This module
- **Module 2: Version Control as a Safety Net.** You read changes with `git diff`. This module
turns that one-off habit into a disciplined review pass over a whole change.
- **Module 8 Remotes and Hosting.** Your repo lives on a host now, and a change arrives as a
- **Module 8: Remotes and Hosting.** Your repo lives on a host now, and a change arrives as a
*pull request* (GitHub/Gitea/Forgejo) or *merge request* (GitLab): same thing, different name.
We'll write "PR" throughout; it's the unit of review.
- **Module 9 Issues and the Task Layer** (helpful, not required). A PR usually answers an issue;
- **Module 9: Issues and the Task Layer** (helpful, not required). A PR usually answers an issue;
the issue is the "what I asked for" you review the diff against.
If you only have Modules 12, you can still do the core skill of this module locally (reviewing a
@@ -205,7 +205,7 @@ real change, then review a diff the "AI" produced and catch the trap planted in
- **Optional (Part A as a real PR):** the repo you pushed to a host in Module 8. If you don't have
one, do Part A locally as a branch; the review skill in Parts BC is identical either way.
### Part A Open a PR as a gate
### Part A: Open a PR as a gate
1. Have your agent set up the base app as a throwaway `review-lab` repo, then confirm the baseline
behavior yourself. This `review-lab` is *separate* from the `tasks-app` you've built up across
@@ -251,7 +251,7 @@ real change, then review a diff the "AI" produced and catch the trap planted in
automatic on a dangerous one. Once you've read it and it's exactly what you asked for, tell the
agent to merge it into `main`.
### Part B Review the AI's diff (the real exercise)
### Part B: Review the AI's diff (the real exercise)
3. Now a teammate-who-is-an-AI has opened a PR. The prompt it was given was exactly:
**"Add a `delete <index>` command to the tasks app."** The change is captured as a patch in the
@@ -279,7 +279,7 @@ real change, then review a diff the "AI" produced and catch the trap planted in
that changes behavior you tested in Part A. Write down what you think the trap is *before*
step 5.
### Part C Confirm the trap by running the failure case
### Part C: Confirm the trap by running the failure case
5. Now verify your read by running the *failure* path, not the happy one:
@@ -1,4 +1,4 @@
# Reviewing an AI-generated diff working checklist
# Reviewing an AI-generated diff: working checklist
Keep this open while you read a diff the AI produced. The point is not to re-read the whole
file; it's to interrogate **the change** against the prompt you gave. Work top to bottom.
@@ -10,24 +10,24 @@ file; it's to interrogate **the change** against the prompt you gave. Work top t
- [ ] **Read the diff, not the summary.** Ignore the AI's account of what it did; the diff is the
only ground truth. (`git diff main..<branch>`)
## 1. Scope did it change only what was asked?
## 1. Scope: did it change only what was asked?
- [ ] Every hunk maps to the request. Anything outside it is **scope creep** until proven
otherwise.
- [ ] No unrelated files touched (formatting churn, import reshuffles, version bumps).
- [ ] No "while I was here" refactors of code the request never mentioned.
## 2. Deletions what did it take away?
## 2. Deletions: what did it take away?
- [ ] Read every `-` line. Deletions are higher-risk than additions and skim right past you.
- [ ] **Edge-case handling still there?** Bounds checks, `None`/empty guards, `try/except`,
validation, error returns confirm none were dropped or weakened.
validation, error returns; confirm none were dropped or weakened.
- [ ] An error that used to be raised/logged isn't now silently swallowed (`except: pass`).
## 3. Plausibility does it only *look* right?
## 3. Plausibility: does it only *look* right?
- [ ] **Invented APIs.** Every function, method, kwarg, attribute, import, env var, CLI flag,
config key, and endpoint actually exists. Confidence is not evidence verify the
config key, and endpoint actually exists. Confidence is not evidence; verify the
unfamiliar ones against real docs/source.
- [ ] **Invented behavior.** It isn't relying on a flag/option that doesn't do what the name
suggests (e.g. assuming `list.pop` takes a default like `dict.pop`).
@@ -35,7 +35,7 @@ file; it's to interrogate **the change** against the prompt you gave. Work top t
- [ ] **Inverted or weakened conditions.** `if not x` vs `if x`, `<` vs `<=`, `and` vs `or`,
a filter quietly dropped from a comprehension.
## 4. Behavior change would the happy path hide it?
## 4. Behavior change: would the happy path hide it?
- [ ] Does any existing command/function behave differently now? Trace one real call through.
- [ ] **Run the failure case, not the success case.** The trap usually survives the happy
@@ -45,7 +45,7 @@ file; it's to interrogate **the change** against the prompt you gave. Work top t
## 5. Decide
- [ ] I can explain, in my own words, what every hunk does and why it's correct.
- [ ] If I can't, I **request changes** the burden of proof is on the diff, not on me.
- [ ] If I can't, I **request changes**; the burden of proof is on the diff, not on me.
> Rule of thumb: a diff is guilty until proven correct. "It runs" is the weakest possible
> evidence; "I read every `-` line and ran the failure case" is the bar.
@@ -6,7 +6,7 @@ Run it:
python cli.py done 0
State is kept in tasks.json next to this file. The `done` command turns a bad index into a
clean error message and a non-zero exit code note that behavior before you review the AI
clean error message and a non-zero exit code; note that behavior before you review the AI
change, so you can tell if the change quietly alters it.
"""
@@ -2,7 +2,7 @@
Same running example as Modules 1 and 2, with one addition: `complete` now validates the
index and raises a clear error for a bad one. That explicit edge-case handling is here on
purpose it's the kind of thing an AI "refactor" likes to quietly remove. This is the
purpose; it's the kind of thing an AI "refactor" likes to quietly remove. This is the
known-good base you'll review an AI change against in Module 10.
"""