From b9712e049fe337d2906331d62bc6bea1a2f1b372 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 9 Aug 2026 23:57:01 +0000 Subject: [PATCH 1/4] Add guidance against flippant appeals to obviousness 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. --- chapters/citations-evidence.qmd | 109 +++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 2 deletions(-) diff --git a/chapters/citations-evidence.qmd b/chapters/citations-evidence.qmd index 83d406e..664d057 100644 --- a/chapters/citations-evidence.qmd +++ b/chapters/citations-evidence.qmd @@ -72,6 +72,110 @@ However, when in doubt, provide a citation—over-citing is preferable to under-citing. +## Do not substitute flippancy for support + +Some phrases assert that a claim needs no support +instead of supplying any: + +- "it is obvious that" +- "clearly, it follows that" +- "it should be familiar to you that" +- "the familiar formula" +- "of course" +- "as everyone knows" + +The problem is the appeal, not the individual words: +"clearly" is fine as an adverb of manner +("the methods section clearly describes the sampling frame"), +and becomes a problem only when it stands in for an argument. + +These phrases do no work for the reader. +A reader who already knows the result gains nothing +from being told that it is familiar, +and a reader who does not +is told that the gap is their own fault, +without being given any way to close it. +The phrasing also conceals a common failure mode: +writers reach for "obviously" most often +at the steps they have checked least carefully. +If you cannot supply a derivation or a citation for a step, +that is a reason to work the step out, +not a reason to call it obvious. + +Replace such phrases with one of the following: + +- **A direct derivation.** + Show the intermediate steps, + or state which identity or algebraic manipulation takes you from one line to the next. +- **A specific citation.** + Name the source that establishes the result, + and give a chapter, section, page, or equation number + whenever the source is long enough + that a bare citation would leave the reader searching. +- **A cross-reference.** + When you established the result earlier in the same document, + point to it by number + (see [Defining terms clearly](defining-terms.qmd) + for the Quarto cross-reference syntax). + +Deleting the phrase and keeping the claim +is also usually an improvement: +"the log-likelihood is a sum of three terms" +asserts exactly as much as +"the log-likelihood is obviously a sum of three terms", +and it invites the reader to check the claim +rather than to defer to it. + +:::{#exm-flippant-derivation} + +## Replacing an appeal to familiarity + +> ❌ Substituting the normal density into the likelihood +> gives the familiar three-term formula. +> +> ✅ For an independent sample $x_1, \ldots, x_n$ +> from a normal distribution with mean $\mu$ and variance $\sigma^2$, +> substituting the normal density into the likelihood +> and taking logarithms gives +> $$ +> \ell(\mu, \sigma^2) = +> -\frac{n}{2}\log(2\pi) +> - \frac{n}{2}\log\left(\sigma^2\right) +> - \frac{1}{2\sigma^2}\sum_{i=1}^{n}\left(x_i - \mu\right)^2. +> $$ +> The three terms are, +> in order: +> a constant that does not involve the parameters, +> a term that depends on $\sigma^2$ but not on $\mu$, +> and the sum of squared deviations of the data from $\mu$, +> divided by $-2\sigma^2$. + +The second version gives the reader the formula and where it came from, +so they can check the algebra themselves. +The first version asks them to take the writer's word for it, +and offers no help to anyone who has not seen the result before. + +::: + +### "Trivial" and "trivially" + +"Trivial" and "trivially" usually work the same way: +they announce that a step is too small to write down, +which relieves the writer of writing it down. +Treat them as a prompt to check the step, +and to write it out if it takes only a line. + +The word has one defensible use, +which is describing how a general expression reduces to a simpler one +in a special case — +for example, +how a weighted average reduces to an ordinary average +when all of the weights are equal. +Even in that use, +"minimal case" or "degenerate case" +names the situation more precisely, +and avoids the dismissive tone that "trivial" carries. + ## What makes a citation relevant A relevant citation is one that actually supports the specific claim you are making. @@ -186,7 +290,8 @@ To effectively support your claims: ## Common citation errors to avoid - **Citation needed**: Making claims without any supporting citation or evidence -- **Vague attribution**: Using phrases like "studies have shown" without citing specific studies +- **Vague attribution**: Using phrases like "studies have shown" without citing specific studies +- **Appeal to obviousness**: Using "obviously", "clearly", or "as is well known" in place of a derivation or a citation - **Circular citation**: Citing a paper that doesn't contain the claimed information but cites another paper that does (cite the original source) - **Citation padding**: Adding citations that don't actually support your claims just to appear well-referenced - **Selective citation**: Only citing work that supports your position while ignoring contradictory evidence @@ -234,5 +339,5 @@ understand the foundation of your arguments, and locate resources for further learning. Always ask yourself: "How does my reader know this is true?" -If the answer isn't obvious from your text, +If your text does not answer that question, add a citation or present direct evidence. From 057e6cbae5d6a10e7641f6a3199f8c409b0c0c89 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 10 Aug 2026 02:23:00 +0000 Subject: [PATCH 2/4] Drop an unsupported claim from the new flippancy section 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. --- chapters/citations-evidence.qmd | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/chapters/citations-evidence.qmd b/chapters/citations-evidence.qmd index 664d057..d837f30 100644 --- a/chapters/citations-evidence.qmd +++ b/chapters/citations-evidence.qmd @@ -95,12 +95,13 @@ from being told that it is familiar, and a reader who does not is told that the gap is their own fault, without being given any way to close it. -The phrasing also conceals a common failure mode: -writers reach for "obviously" most often -at the steps they have checked least carefully. -If you cannot supply a derivation or a citation for a step, -that is a reason to work the step out, -not a reason to call it obvious. +They also cost the writer something. +Working a step out is how you find out whether it holds; +calling it obvious settles the question by assertion, +and leaves any error in the step where it is. +So if you cannot supply a derivation or a citation for a step, +treat that as a reason to work the step out, +not as a reason to call it obvious. Replace such phrases with one of the following: @@ -121,7 +122,7 @@ Replace such phrases with one of the following: Deleting the phrase and keeping the claim is also usually an improvement: "the log-likelihood is a sum of three terms" -asserts exactly as much as +makes the same claim about the log-likelihood as "the log-likelihood is obviously a sum of three terms", and it invites the reader to check the claim rather than to defer to it. From 530e34c3e35acd515f6ecdd68738f95536308f66 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 10 Aug 2026 04:08:32 +0000 Subject: [PATCH 3/4] Address review notes on the flippancy section 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. --- chapters/citations-evidence.qmd | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/chapters/citations-evidence.qmd b/chapters/citations-evidence.qmd index d837f30..321122b 100644 --- a/chapters/citations-evidence.qmd +++ b/chapters/citations-evidence.qmd @@ -84,10 +84,13 @@ instead of supplying any: - "of course" - "as everyone knows" -The problem is the appeal, not the individual words: -"clearly" is fine as an adverb of manner +The problem is the appeal, not the individual words. +"Clearly" is fine as an adverb of manner ("the methods section clearly describes the sampling frame"), -and becomes a problem only when it stands in for an argument. +and "of course" is fine when it flags an assumption +you have already established. +Each becomes a problem only when it stands in +for an argument you have not made. These phrases do no work for the reader. A reader who already knows the result gains nothing @@ -168,9 +171,9 @@ and to write it out if it takes only a line. The word has one defensible use, which is describing how a general expression reduces to a simpler one -in a special case — -for example, -how a weighted average reduces to an ordinary average +in a special case. +For example, +a weighted average reduces to an ordinary average when all of the weights are equal. Even in that use, "minimal case" or "degenerate case" @@ -292,7 +295,7 @@ To effectively support your claims: - **Citation needed**: Making claims without any supporting citation or evidence - **Vague attribution**: Using phrases like "studies have shown" without citing specific studies -- **Appeal to obviousness**: Using "obviously", "clearly", or "as is well known" in place of a derivation or a citation +- **Appeal to obviousness**: Using "obviously", "clearly", or "as everyone knows" in place of a derivation or a citation - **Circular citation**: Citing a paper that doesn't contain the claimed information but cites another paper that does (cite the original source) - **Citation padding**: Adding citations that don't actually support your claims just to appear well-referenced - **Selective citation**: Only citing work that supports your position while ignoring contradictory evidence From 08a5a9f6720652992ce49127eae15af813e274d6 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 10 Aug 2026 04:15:11 +0000 Subject: [PATCH 4/4] Make the three-term enumeration a bullet list 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. --- chapters/citations-evidence.qmd | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/chapters/citations-evidence.qmd b/chapters/citations-evidence.qmd index 321122b..61bd036 100644 --- a/chapters/citations-evidence.qmd +++ b/chapters/citations-evidence.qmd @@ -149,10 +149,11 @@ rather than to defer to it. > $$ > The three terms are, > in order: -> a constant that does not involve the parameters, -> a term that depends on $\sigma^2$ but not on $\mu$, -> and the sum of squared deviations of the data from $\mu$, -> divided by $-2\sigma^2$. +> +> - a constant that does not involve the parameters; +> - a term that depends on $\sigma^2$ but not on $\mu$; +> - the sum of squared deviations of the data from $\mu$, +> divided by $-2\sigma^2$. The second version gives the reader the formula and where it came from, so they can check the algebra themselves.