docs(issue): prescribe stating chat-decision intent in English over verbatim quotes
Rule 4's self-containment carve-out endorsed pasting a dated verbatim chat quote inline. In practice the chat is not English (chat language per settings) while an issue is an English repo artefact, so the quote imported a foreign language and the chat register into the artefact — and usually only restated an intent already stated in English beside it. The prescribed self-containment vehicle is now the decision's intention rendered in English. A verbatim quote survives only where the exact wording is itself load-bearing, and then translated — never a non-English quote imported verbatim. Applied to the carve-out, its upstream pointer, the common-mistakes table (new row), and the red-flags checklist.
This commit is contained in:
+24
-6
@@ -162,8 +162,8 @@ The one carve-out is rule 3 — a comment has no title.
|
||||
- **The producing chat by reference, in any phrasing** — "the
|
||||
in-context discussion", "settled before the run", "the session /
|
||||
cycle transcript", an in-context juror/panel verdict (`D3`). No
|
||||
anchor can ever reach it; the irrecoverable case. (Quoting the
|
||||
decision's words inline is fine — see the carve-out below.)
|
||||
anchor can ever reach it; the irrecoverable case. (State the
|
||||
decision's intention inline in English — see the carve-out below.)
|
||||
- **A weak prose pointer** — "above", "below", "earlier", "the prior
|
||||
comment", "logged above", "as discussed" — with no resolvable
|
||||
locator: a relative link to the target comment
|
||||
@@ -189,9 +189,10 @@ The one carve-out is rule 3 — a comment has no title.
|
||||
by being written down, never by being pointed at (the `boss`
|
||||
reference-issue mechanic, `../boss/SKILL.md` § The reference issue).
|
||||
|
||||
**These stay self-contained** (don't strip them chasing the rule): an
|
||||
inline dated verbatim quote of a chat decision ("`mach es so!`" —
|
||||
2026-06-29) — the reader sees the exact words, and only a surplus
|
||||
**These stay self-contained** (don't strip them chasing the rule): a
|
||||
dated inline statement of a chat decision's *intention*, in English
|
||||
("dissolve the old into the new, but only once the new carries" —
|
||||
2026-07-03) — the reader gets the substance, and only a surplus
|
||||
"settled in-context" sentence *beside* it is the violation; an
|
||||
enumerated fork `(A)`/`(B)` whose options are restated here; a
|
||||
glossary code glossed inline; a provenance sentence whose fact is also
|
||||
@@ -199,6 +200,17 @@ The one carve-out is rule 3 — a comment has no title.
|
||||
"decided", drop or anchor "logged above"). Flag the *pointer* a
|
||||
tracker-only reader can't resolve, never the content it reproduces.
|
||||
|
||||
**State the intent, don't paste the chat.** The self-containment
|
||||
vehicle is the decision's intention rendered in English, not the chat's
|
||||
verbatim words. The chat is typically not English (chat language per
|
||||
settings) while an issue is an English repo artefact ("would it be
|
||||
committed → English"), so a pasted quote imports a foreign language and
|
||||
the chat's register into the artefact — and it usually adds nothing the
|
||||
intent statement doesn't already carry. Quote the exact words only
|
||||
where the precise wording is itself load-bearing, and even then render
|
||||
them in English (translate the original); never import a non-English
|
||||
chat quote verbatim.
|
||||
|
||||
- Avoid: "Approach B (the mechanism refinement decided + logged
|
||||
above)." — "logged above" points to a sibling comment with no
|
||||
resolvable locator, so a reader who landed on this comment can't reach
|
||||
@@ -278,7 +290,8 @@ Notes:
|
||||
| `-d` body with a guessed flag (`--body`) | tea rejects it | `--description`/`-d` |
|
||||
| Editing without viewing first | Clobbers others' edits | `tea issues <idx>`, then edit |
|
||||
| Reading/echoing tea's config | Token leak | tea is already authenticated |
|
||||
| Pointer to the chat that produced the entry ("in-context", "the cycle transcript", a juror code) | The chat is invisible to a tracker reader — never reachable | Quote the words inline, or log the decision to the tracker and cite that comment with a relative link (`issues/N#issuecomment-M`) |
|
||||
| Pointer to the chat that produced the entry ("in-context", "the cycle transcript", a juror code) | The chat is invisible to a tracker reader — never reachable | State the decision's intent inline in English, or log the decision to the tracker and cite that comment with a relative link (`issues/N#issuecomment-M`) |
|
||||
| A verbatim chat quote pasted inline, especially not in English | Imports a foreign language and the chat register into an English artefact; usually just restates the intent | State the decision's intent in English; quote verbatim only where the exact wording is load-bearing, and then translated |
|
||||
| "above" / "below" / "the prior comment" with no anchor | A reader on a direct comment link can't tell which entry | Add a relative link to the comment (`issues/N#issuecomment-M`), a `#N`, or a *same-entry* `§` marker |
|
||||
| Artifact or path named without a locator — "the harness issue", "see the ledger", `/mnt/...`, `~/.claude/...` | Nothing to navigate to from the tracker | Supply a `#N`, SHA, in-repo path, or relative link — or reproduce the fact inline |
|
||||
| Bare un-glossed code or ordinal (`I7`, `C16`, "decision #5") | Its defining set isn't in the entry | Gloss it inline, or restate the set |
|
||||
@@ -315,6 +328,11 @@ Notes:
|
||||
- A reachable reference the entry's point leans on, its substance not
|
||||
glossed inline — a linear reader can't grasp the entry without navigating
|
||||
away (the comprehension test, rule 4)
|
||||
- A verbatim chat quote pasted inline, especially one not in English —
|
||||
the chat is typically non-English and the issue is an English artefact,
|
||||
and the quote usually only restates the intent; state the decision's
|
||||
intent in English (quote the exact words only where the wording itself
|
||||
is load-bearing, and then translated)
|
||||
- About to `tea issues edit` without having viewed the issue
|
||||
- About to print or `cat` the tea config
|
||||
|
||||
|
||||
Reference in New Issue
Block a user