Add guidance against flippant appeals to obviousness - #42
Conversation
Phrases like "it is obvious that", "clearly, it follows that", and "the familiar formula" assert that a claim needs no support instead of supplying any. They leave a reader who does not already know the result with no way to close the gap, and they cluster around the steps a writer has checked least carefully. Add a section to the citations-and-evidence chapter that names the pattern, gives the three ways to fix it (derive it, cite a specific chapter/section/page/equation, or cross-reference an earlier result), and works a normal log-likelihood example through the rewrite. Cover "trivial"/"trivially" separately, since its one defensible use -- describing how a general expression reduces in a special case -- is usually served better by "minimal case" or "degenerate case". Also add the pattern to the chapter's list of common citation errors, and reword the conclusion so it does not lean on "obvious" itself.
|
CI status on Two red marks remain, neither caused by this diff, so I have not touched either:
Generated by Claude Code |
|
@claude review |
|
👀 Picked up by workflow run #31346875231. Setup runs first; Claude itself responds after that. |
The section argued that writers reach for "obviously" most often at the steps they have checked least carefully. That is an empirical claim about writer behavior, stated without a citation, inside a chapter about not making unsupported claims -- exactly the failure the section warns against. I have no source for it, so it goes. Replace it with the part of the point the argument actually needs, which is a claim about what the phrasing does rather than how often writers use it: working a step out is how you learn whether it holds, and calling it obvious settles the question by assertion instead. Also soften "asserts exactly as much as" to "makes the same claim about the log-likelihood as", since "obviously" does add a (weak) claim about how hard the step is.
|
Heads up: the review you asked for never ran. The Since I am the session that wrote this branch, here is my own read of the diff rather than an independent review — worth weighting accordingly. One real problem, now fixed in
That is an empirical claim about writer behavior with no citation, in a chapter about not making unsupported claims, inside a section arguing you should derive or cite instead. I have no source for it, so I removed it rather than dressing it up. The replacement keeps only the part the argument needs — a claim about what the phrasing does, not how often writers use it:
Same commit softens "asserts exactly as much as" to "makes the same claim about the log-likelihood as", since "obviously" does add a weak claim about difficulty. Checked and believed correct:
Open question for you: the section lands in Citations and evidence because the remedy you specified is prove-or-cite. It would also sit defensibly in Word choice, next to "Avoid vague and metaphorical language". Happy to move it if you would rather keep word-level tone advice together. Generated by Claude Code |
|
👀 Picked up by workflow run #31349655766. Setup runs first; Claude itself responds after that. |
|
This is a Checking for any additional
No additional — posted by @claude post-step from workflow run |
|
@claude review |
|
👀 Picked up by workflow run #31353997858. Setup runs first; Claude itself responds after that. |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
Three points from the code review, all in the new section:
- Replace the spaced em-dash before the "weighted average" example with
a sentence break. The avoid-ai-tells chapter names the em-dash as a
default connector as a formatting tell, and a section arguing for
rhetorical rigor should not model the habit.
- Give "of course" the same carve-out "clearly" already had. Unlike the
other entries, it has an honest use -- flagging an assumption you have
already established -- so the caveat now covers both words, and the
test for both is whether the phrase stands in for an argument you have
not made.
- Make the phrase in the "Common citation errors" bullet ("as is well
known") match the one catalogued in the section list ("as everyone
knows"), so the two lists point at the same target.
|
All three review notes are addressed in Em-dash as connector. Fixed. The spaced em-dash before the weighted-average example is now a sentence break:
You were right that one instance is not a cluster, but a section arguing for rhetorical rigor should not model a habit the guide names elsewhere. "as is well known" vs "as everyone knows". Fixed — the errors bullet now uses "as everyone knows", matching the section list. "of course". I gave it the same carve-out "clearly" already had rather than dropping it, since your reasoning applies to both words equally:
That keeps the entry — "of course" is a real offender in the appeal sense — while making the test explicit for both. Re-rendered to HTML and re-ran the non-standard-character check after the edits; both clean. One note on the Generated by Claude Code |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
CLAUDE.md asks for bullet lists rather than comma-separated prose for lists of three or more items. The worked example enumerated the three terms of the log-likelihood in a single sentence, which is exactly the shape that rule covers, and the reader does scan it: each item pairs with one term of the displayed equation. The example is meant to model good practice, so it should follow the project's own convention. Semicolons separate the items because the last one contains a comma.
|
Took the optional note too, in
I went the other way from the review's own leaning, for two reasons. The reader does scan this one — each item pairs with one term of the displayed equation, which is different from the "chapter, section, page, or equation number" case at line 116, where the items are interchangeable alternatives inside a clause. And the block is a worked example of good practice, so it is the last place that should quietly opt out of the project's own convention. Semicolons separate the items because the last one contains a comma. Re-rendered and confirmed the list renders correctly inside the blockquote, with the display math above it intact; the non-standard-character check passes. Generated by Claude Code |
|
Claude finished review — View run I have everything needed to finalize this confirming review. Review: PR #42 — Add guidance against flippant appeals to obviousnessWhat changed since the last review round: The most recent review (2026-08-10T04:14:21Z, verdict Ready for merge) left one optional, non-blocking observation: the three-term enumeration inside the ✅ worked example ( Commit Verified:
No new issues introduced by this commit. No CLAUDE.md violations, no math errors, no broken cross-references, no fabricated citations or paths. VerdictReady for merge — this confirms and extends the prior verdict at #42 (comment); the only outstanding optional note from that round has now been addressed and verified, and no new findings surfaced. |
|
3 participants
Why
Phrases like "it is obvious that", "clearly, it follows that", and "the familiar formula" assert that a claim needs no support instead of supplying any. A reader who already knows the result gains nothing from being told it is familiar; a reader who does not is told the gap is their own fault and given no way to close it.
The guide had no section on this, and its "common citation errors" list covered vague attribution ("studies have shown") but not the appeal-to-obviousness version of the same dodge.
What changed
All changes are in
chapters/citations-evidence.qmd, which is the natural home since the remedy is to prove the result or cite a specific source.Commits
b9712e0— adds the section, the subsection, the error-list bullet, and the conclusion reword.057e6cb— removes a claim from the first commit which asserted that writers reach for "obviously" most often at the steps they have checked least carefully. That is an empirical claim about writer behavior with no citation, in a chapter about not making unsupported claims. Replaced with the part the argument needs: working a step out is how you learn whether it holds, and calling it obvious settles the question by assertion instead.9dcdcf5— merge ofmain(not mine), bringing in theclaude-code-reviewworkflow fix from Fix claude-code-review.yml startup_failure: grant actions: read, pin @v2 #44.530e34c— review round 1: drops a spaced em-dash used as a connector, extends the "clearly" carve-out to cover "of course", and aligns the phrase in the errors bullet with the one in the section list.08a5a9f— review round 2: converts the three-term enumeration in the worked example into a bullet list, per CLAUDE.md's rule for lists of three or more items.Verification
quarto render chapters/citations-evidence.qmdto HTML and RevealJS: both succeed, the example callout and the display math render, the bullet list nests correctly inside the blockquote, and no cross-references are unresolved..github/scripts/check-non-standard-chars.py: passes.Open question
The section sits in Citations and evidence because the remedy is prove-or-cite. It would also fit in Word choice, beside "Avoid vague and metaphorical language", if you would rather keep word-level tone advice together.