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:
2026-07-06 11:56:09 +02:00
parent 42e4bf5286
commit 21a745d090
+24 -6
View File
@@ -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 - **The producing chat by reference, in any phrasing** — "the
in-context discussion", "settled before the run", "the session / in-context discussion", "settled before the run", "the session /
cycle transcript", an in-context juror/panel verdict (`D3`). No cycle transcript", an in-context juror/panel verdict (`D3`). No
anchor can ever reach it; the irrecoverable case. (Quoting the anchor can ever reach it; the irrecoverable case. (State the
decision's words inline is fine — see the carve-out below.) decision's intention inline in English — see the carve-out below.)
- **A weak prose pointer** — "above", "below", "earlier", "the prior - **A weak prose pointer** — "above", "below", "earlier", "the prior
comment", "logged above", "as discussed" — with no resolvable comment", "logged above", "as discussed" — with no resolvable
locator: a relative link to the target comment 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` by being written down, never by being pointed at (the `boss`
reference-issue mechanic, `../boss/SKILL.md` § The reference issue). reference-issue mechanic, `../boss/SKILL.md` § The reference issue).
**These stay self-contained** (don't strip them chasing the rule): an **These stay self-contained** (don't strip them chasing the rule): a
inline dated verbatim quote of a chat decision ("`mach es so!`" — dated inline statement of a chat decision's *intention*, in English
2026-06-29) — the reader sees the exact words, and only a surplus ("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 "settled in-context" sentence *beside* it is the violation; an
enumerated fork `(A)`/`(B)` whose options are restated here; a enumerated fork `(A)`/`(B)` whose options are restated here; a
glossary code glossed inline; a provenance sentence whose fact is also 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 "decided", drop or anchor "logged above"). Flag the *pointer* a
tracker-only reader can't resolve, never the content it reproduces. 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 - Avoid: "Approach B (the mechanism refinement decided + logged
above)." — "logged above" points to a sibling comment with no above)." — "logged above" points to a sibling comment with no
resolvable locator, so a reader who landed on this comment can't reach 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` | | `-d` body with a guessed flag (`--body`) | tea rejects it | `--description`/`-d` |
| Editing without viewing first | Clobbers others' edits | `tea issues <idx>`, then edit | | Editing without viewing first | Clobbers others' edits | `tea issues <idx>`, then edit |
| Reading/echoing tea's config | Token leak | tea is already authenticated | | 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 | | "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 | | 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 | | 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 - A reachable reference the entry's point leans on, its substance not
glossed inline — a linear reader can't grasp the entry without navigating glossed inline — a linear reader can't grasp the entry without navigating
away (the comprehension test, rule 4) 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 `tea issues edit` without having viewed the issue
- About to print or `cat` the tea config - About to print or `cat` the tea config