Skip to content

Commit fea48b2

Browse files
committed
chore: make content-guidelines the canonical home for evidence-versus-claim
Round 1 review: the rule belongs in docs/.style per the skills' own precedence and feedback-loop rules. One canonical statement in content-guidelines.md; both skills now cite it, and the reader test (does the reader type or receive the identifier) is the rule, with page categories demoted to examples.
1 parent e035627 commit fea48b2

3 files changed

Lines changed: 44 additions & 27 deletions

File tree

‎.claude/skills/doc-check/SKILL.md‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -112,14 +112,13 @@ Missing either one is a defect:
112112

113113
### Evidence versus claim
114114

115-
Code evidence justifies a claim; it does not belong in the claim. Flag
116-
user-facing pages that expose enum values, database column or field names,
117-
function or struct names, or internal subsystem names the reader never types
118-
or receives. The page should state the behavior in the target persona's
119-
terms; the exact identifiers belong in the PR description's evidence section.
120-
The exception is reference, API, CLI, and configuration docs, where
121-
identifiers are the interface the reader types or receives, and exact values
122-
are required.
115+
This is the canonical rule
116+
[Evidence justifies a claim; it does not belong in the claim](../../../docs/.style/content-guidelines.md#evidence-justifies-a-claim-it-does-not-belong-in-the-claim)
117+
in the content guidelines; the content guidelines govern. Flag a page that
118+
exposes an identifier (enum value, column or field name, function or struct
119+
name, internal subsystem name) the reader never types or receives; the page
120+
should state the behavior in the target persona's terms. Where the reader
121+
does type or receive the identifier, exact values are required instead.
123122

124123
### No emdash, endash, or ` -- ` as punctuation
125124

‎.claude/skills/write-docs/SKILL.md‎

Lines changed: 15 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -113,22 +113,18 @@ style.
113113

114114
## Evidence versus claim
115115

116-
Code evidence justifies a claim; it does not belong in the claim. Reading the
117-
source is how you verify behavior (workflow step 1), not what you publish.
118-
Translate what the code proves into the target persona's terms:
119-
120-
- Enum values, database column and field names, function and struct names,
121-
and internal subsystem names stay in the PR description's evidence section,
122-
where the reviewer can check them.
123-
- The page states the behavior in the reader's vocabulary. An admin-facing
124-
page says "chats with ongoing work are never selected", not "chats with
125-
status `running`, `interrupting`, or `requires_action` are excluded".
126-
- The exception is pages where identifiers are the interface. Reference, API,
127-
CLI, and configuration docs document exact flag names, endpoint paths,
128-
response fields, and accepted values, per
129-
[Verify against the code; document exact values](../../../docs/.style/content-guidelines.md#verify-against-the-code-document-exact-values).
130-
The test: does the reader type or receive the identifier? If they never see
131-
it, it is evidence, not content.
116+
The canonical rule is
117+
[Evidence justifies a claim; it does not belong in the claim](../../../docs/.style/content-guidelines.md#evidence-justifies-a-claim-it-does-not-belong-in-the-claim)
118+
in the content guidelines; they govern. The test is whether the reader types
119+
or receives the identifier. Application notes:
120+
121+
- Reading the source is how you verify behavior (workflow step 1), not what
122+
you publish. When the reader test says "no", the identifiers you copied in
123+
step 1 go in the PR description's evidence section, and the page states the
124+
behavior in the persona's terms.
125+
- Reference, API, CLI, and configuration docs usually pass the test, as does
126+
any step where the reader reads a field from a response, so exact values
127+
are required there. The test decides, not the page category.
132128

133129
## What not to write
134130

@@ -174,9 +170,9 @@ the whole series as a single review.
174170
- Telling the reader their tool is wrong when it merely needs configuration.
175171
- Brittle references that rot: hard-coded line numbers, or a screenshot
176172
standing in for text the reader could copy.
177-
- Publishing verification evidence as content: enum values, internal
178-
identifiers, or subsystem names on a page whose reader never types or
179-
receives them.
173+
- Publishing verification evidence as content: identifiers on a page whose
174+
reader never types or receives them (see
175+
[Evidence versus claim](#evidence-versus-claim)).
180176
- Duplicating large content silently instead of flagging the maintenance
181177
cost to the reviewer.
182178
- Treating the style guide as optional recall instead of a checklist you open

‎docs/.style/content-guidelines.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,28 @@ approximations:
9494
*Why:* Precise values are what make accuracy checkable; "roughly 5
9595
minutes" can't drift-fail, but `300s default` can.
9696

97+
### Evidence justifies a claim; it does not belong in the claim
98+
99+
Verifying a behavior against the code does not mean publishing the code's
100+
vocabulary. The test for whether an identifier belongs on a page: **does the
101+
reader type or receive it?**
102+
103+
- If yes, document the exact value, per
104+
[Verify against the code; document exact values](#verify-against-the-code-document-exact-values).
105+
This is the normal case for reference, API, CLI, and configuration content,
106+
and for any step where the reader reads a field out of a response or types
107+
a flag.
108+
- If no, state the behavior in the target persona's terms and keep the
109+
identifier in the PR description's evidence, where the reviewer can check
110+
it. Enum values, database column and field names, function and struct
111+
names, and internal subsystem names on a page whose reader never sees them
112+
are unverifiable by that reader and rot unnoticed. Example: an admin page
113+
says "chats with ongoing work are never selected", not "chats with status
114+
`running`, `interrupting`, or `requires_action` are excluded".
115+
116+
*Why:* Identifiers the reader never receives can't be confirmed or corrected
117+
by the reader, and they silently drift when the implementation changes.
118+
97119
### Documentation lands with the change
98120

99121
A PR that introduces or changes a user-facing feature should include the

0 commit comments

Comments
 (0)