docs(issue): state that the writing rules bind comments too
The four-rules header read "on create and on edit", naming only the issue-body operations, even though the skill's scope (description, when-to-use table, tea mechanics) covers commenting and rule 4 is written around the comment-anchor reader. Make the binding explicit and carve out rule 3 (a comment has no title).
This commit is contained in:
+6
-2
@@ -43,7 +43,10 @@ reference issue). This skill is the shared convention they lean on.
|
|||||||
|
|
||||||
## The four writing rules
|
## The four writing rules
|
||||||
|
|
||||||
These apply to every issue, on create and on edit.
|
These apply to every issue, on create and on edit — and equally to
|
||||||
|
every comment: a comment is tracker text like any other, and rule 4 in
|
||||||
|
particular is written around a reader who lands on a bare comment anchor.
|
||||||
|
The one carve-out is rule 3 — a comment has no title.
|
||||||
|
|
||||||
1. **Impersonal and tool-neutral.** Declarative voice — no "you", no
|
1. **Impersonal and tool-neutral.** Declarative voice — no "you", no
|
||||||
imperative aimed at the reader, and equally no first-person narration of
|
imperative aimed at the reader, and equally no first-person narration of
|
||||||
@@ -98,7 +101,8 @@ These apply to every issue, on create and on edit.
|
|||||||
3. **Imperative, concise title.** Verb-first, one line, no trailing
|
3. **Imperative, concise title.** Verb-first, one line, no trailing
|
||||||
period — scannable in the list, mirroring commit-message style.
|
period — scannable in the list, mirroring commit-message style.
|
||||||
Checkboxes (`- [ ]`) are allowed in the body for sub-points or a
|
Checkboxes (`- [ ]`) are allowed in the body for sub-points or a
|
||||||
small acceptance checklist.
|
small acceptance checklist. A comment carries no title, so this rule
|
||||||
|
alone has no comment analogue — the other three bind it unchanged.
|
||||||
- Avoid: "parser bug" / "There is a problem with the parser."
|
- Avoid: "parser bug" / "There is a problem with the parser."
|
||||||
- Use: "Preserve backslash escapes in quoted strings"
|
- Use: "Preserve backslash escapes in quoted strings"
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user