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
|
- **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
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user