From 19db0a933af0235348507ddacec85a2b899c7b42 Mon Sep 17 00:00:00 2001 From: Brummel Date: Mon, 29 Jun 2026 10:53:04 +0200 Subject: [PATCH] fix(issue): sharpen rule 4 into a tracker-reachability test Rule 4 ("Self-contained") forbade dangling pointers by example only, so a reference reachable only through the producing chat slipped past it -- e.g. a shipped comment "Approach B (the mechanism refinement decided + logged above)", whose "logged above" names no resolvable entry and whose "Approach B" indexes an A/B fork the entry never reproduces. Reframe rule 4 around one test: a reference is valid iff a reader who lands on the entry alone (e.g. via a direct comment-anchor link) can follow it to its target. A survey of the live tracker (63 issues / 96 comments) found 56 violations in six classes, now each named as an unreachable form: chat references, weak intra-thread pointers ("above" / "logged above"), artifacts named by role, out-of-repo paths, bare un-glossed codes, and locator-shaped tokens that resolve to nothing. Carve-outs keep inline quotations, #N / SHA / URL / repo-path locators, glossed codes, and restated forks legitimate. The constructive escape hatch (log a chat decision to the tracker first, then cite that comment) cross-references boss "The reference issue". Align the Common-mistakes table, the Red-flags STOP gate, and the boss cross-reference. Prescribe a comment's full URL rather than a bare #issuecomment-NNNN fragment, which is not auto-linked on Gitea and so does not itself satisfy the test. Existing tracker entries are left unedited; the rule governs future writing only. --- issue/SKILL.md | 108 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 91 insertions(+), 17 deletions(-) diff --git a/issue/SKILL.md b/issue/SKILL.md index e52137f..9761119 100644 --- a/issue/SKILL.md +++ b/issue/SKILL.md @@ -70,16 +70,76 @@ These apply to every issue, on create and on edit. - Avoid: "parser bug" / "There is a problem with the parser." - Use: "Preserve backslash escapes in quoted strings" -4. **Self-contained.** The issue is understandable on its own, - without the originating conversation. Every reference resolves - directly for any reader — an issue/PR number (`#42`), a commit - SHA, a full URL, or a path that exists in the repo. No dangling - pointers ("as discussed", "see the spec") and no tags, codes, or - acronyms that need outside knowledge to resolve; spell them out or - link them. - - Avoid: "Fixes the regression from the ledger refactor; see the - spec." - - Use: "Fixes the regression behind `#38`, introduced in `a1b2c3d`." +4. **Self-contained — the reachability test.** The issue stands on its + own, without the conversation that produced it. Apply one test to + every reference: *starting from this entry alone — a reader may have + arrived by a direct comment-anchor link, no chat and no sibling + comments loaded — can they follow it to its target?* If not, it is a + dangling pointer: reproduce the content inline, or swap in a + resolvable locator. + + **Reachable — use these:** content stated or quoted inline; an + issue/PR number (`#42`, or cross-repo `Skills #11`); a commit SHA + (`a1b2c3d`, resolves on push); a full URL; a repo-relative path, + optionally with a line range (`parser.rs:84-90`); another comment by + its full URL (the link ending `#issuecomment-NNNN` — the bare fragment + only resolves in-page on that comment's own issue); a same-entry + section marker (`§5`); a convention-resolvable in-repo slug (a + `docs/specs/` slug, a cycle number). + + **Unreachable — rewrite or inline; these never resolve from the + tracker:** + - **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.) + - **A weak prose pointer** — "above", "below", "earlier", "the prior + comment", "logged above", "as discussed" — with no resolvable + locator: the target comment's full URL, a `#N`, or a *same-entry* + `§` marker. A `§` pointing into another comment or file is itself + unreachable — link that comment's URL. + - **An artifact named by role, not locator** — "the OOS harness + issue", "see the ledger", a `Depends on` target — carrying no `#N` / + SHA / URL / repo path. + - **A path outside this repo** — `/mnt/...`, `~/.claude/...`, a Claude + auto-memory slug, another project's `BLOCKED.md`. Only a path in + *this* repo is reachable. + - **A bare code or ordinal whose defining set the entry does not + reproduce** — a plan-item / ledger / lens code (`I7`, `C16`), an + index ("decision #5"). Gloss it in place, or restate the set. + - **A locator-shaped token that resolves to nothing** — a template + placeholder (`#(A)`), or a `#`-number in the wrong format (`#0071` — + issue refs are unpadded integers like `#71`; a leading zero matches + nothing). + + A chat decision becomes referenceable only by being **written to the + tracker first** — log it, then cite that comment; a chat is reachable + 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 + "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 + stated inline, so long as it embeds no unresolvable pointer (keep + "decided", drop or anchor "logged above"). Flag the *pointer* a + tracker-only reader can't resolve, never the content it reproduces. + + - Avoid: "Approach B (the mechanism refinement decided + logged + above)." — "logged above" points to a sibling comment with no + resolvable URL, so a reader who landed on this comment can't reach + the refinement; the violation is the unresolvable pointer, and it + stands even when the mechanism is restated inline. The bare label + "Approach B" compounds it — it indexes an A/B fork this entry never + reproduces, so the letter means nothing to a reader who didn't see + the fork laid out. + - Use — drop the chat-native label, name the option on its own terms, + then inline or link the refinement: "The honest per-held-cycle bleed + (accrue each held cycle, dump at close) — refined in + `http://…/issues/148#issuecomment-2142`." **Language:** title and body are English — an issue is a repo artefact mirrored to Gitea ("would it be committed → English", per @@ -131,16 +191,28 @@ 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 | -| Dangling reference ("see the spec", an internal code) | Reader can't resolve it | Link it: `#N`, SHA, URL, or repo path | +| 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's full URL | +| "above" / "below" / "the prior comment" with no anchor | A reader on a direct comment link can't tell which entry | Add the comment's full URL, 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, URL, or in-repo path — 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 | ## Red flags — STOP - The word "you" anywhere in title or body - A factual statement with neither evidence nor a "claim" flag - A title that is a noun phrase or ends with a period -- A reference with no resolvable locator (`#N`, a commit SHA, a URL, - or an existing repo path), or an acronym/code needing outside - knowledge +- A reference with no resolvable locator (`#N`, a commit SHA, a URL, an + existing repo path, a `docs/specs/` slug or cycle number, a same-entry + `§`, or the fact reproduced inline), or a bare never-glossed code whose + defining set isn't in the entry — in particular: + - a pointer to the chat that produced the entry ("in-context", "the + cycle transcript", a juror code); the chat is never tracker-reachable + - "above" / "below" / "the prior comment" / "as discussed" with no + resolvable locator — the comment's full URL, a `#N`, or a same-entry `§` + - an out-of-repo path (`/mnt`, `~/.claude`, a `memory `, + another project's `.md`) cited as the basis + - a `#`-token that resolves to nothing — a `#(A)` placeholder or a + wrong-format `#0071` - About to `tea issues edit` without having viewed the issue - About to print or `cat` the tea config @@ -149,6 +221,8 @@ Notes: - `~/dev/CLAUDE.md` — repo-English rule, label vocabulary, the `closes #N` commit convention (the tracker is the forward-queue). - `../brainstorm/SKILL.md`, `../audit/SKILL.md`, `../boss/SKILL.md` — - callers that file issues through these conventions (`boss` files - skill-system feedback on the plugin's own tracker with an - autonomous-provenance body block, § Skill-system feedback). + callers that file issues through these conventions. `boss` files + skill-system feedback with an autonomous-provenance body block + (§ Skill-system feedback), and its § The reference issue is the + constructive escape hatch for rule 4: log a chat decision to the + tracker first, then cite that comment instead of pointing at the chat.