style(no-slop): remove every em-dash + banned words across all modules + capstone
Apply the no-ai-slop standard (now binding in AGENTS.md): the em-dash character is banned outright (restructured, not blind-replaced), plus the banned word/phrase list (delve, leverage, robust, seamless, truly, unlock, etc.). 0 em-dashes remain in modules + capstone; the only "robust" left is the planted M10 ai-change.patch trap. Module H1 titles use a colon separator. All deliberate teaching devices preserved; labs compile/parse (py/sh/yaml/json); no junk. AGENTS.md updated with the hard no-slop rules. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TfzV5QvtPDz8LJS3Pu5VLT
This commit is contained in:
@@ -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 1–2, 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 B–C 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.
|
||||
"""
|
||||
|
||||
|
||||
Reference in New Issue
Block a user