You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit fea48b2
Browse filesBrowse the repository at this point in the historyBrowse files
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.
Copy file name to clipboardExpand all lines: .claude/skills/doc-check/SKILL.md
+7-8Lines changed: 7 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -112,14 +112,13 @@ Missing either one is a defect:
112
112
113
113
### Evidence versus claim
114
114
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.
Copy file name to clipboardExpand all lines: .claude/skills/write-docs/SKILL.md
+15-19Lines changed: 15 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -113,22 +113,18 @@ style.
113
113
114
114
## Evidence versus claim
115
115
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.
132
128
133
129
## What not to write
134
130
@@ -174,9 +170,9 @@ the whole series as a single review.
174
170
- Telling the reader their tool is wrong when it merely needs configuration.
175
171
- Brittle references that rot: hard-coded line numbers, or a screenshot
176
172
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)).
180
176
- Duplicating large content silently instead of flagging the maintenance
181
177
cost to the reviewer.
182
178
- Treating the style guide as optional recall instead of a checklist you open
0 commit comments