diff --git a/issue/SKILL.md b/issue/SKILL.md index f681ddb..0593597 100644 --- a/issue/SKILL.md +++ b/issue/SKILL.md @@ -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 `, 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