docs(boss,specify): propagate the intent-in-English provenance rule to decision-log writers

21a745d rewrote issue rule 4's self-containment carve-out: a chat decision's provenance is its intention rendered in English, a verbatim quote only where the exact wording is load-bearing, and then translated. The three sites that instruct writing such provenance still prescribed the old verbatim-quote form: - boss/SKILL.md — the decision-log comment rules, the common-mistakes row, and the red-flags entry now demand the intent statement instead of quoting the user's words. - specify/SKILL.md — the fork-resolution comment templates' Basis lines carry the intent form. - specify/agents/spec-skeptic.md — the grounding lens accepts a provenance record in the intent form, not only a verbatim statement.
2026-07-09 10:56:40 +02:00
parent dacadba07f
commit f1b3af5f09
3 changed files with 22 additions and 13 deletions
@@ -351,10 +351,15 @@ These decision-log comments are issue entries — they obey
 chat that produced it, so each must be self-contained, reachable from the
 tracker, and free of this loop's own control-flow.

- **Quote a user decision's provenance inline** — the words and the date
-  ("`ja, mach B`" — 2026-06-28) — never a pointer at the chat ("settled
-  in the discussion", "decided in-context"). The chat is unreachable from
-  the tracker; a pointer to it strands every later reader.
+- **State a user decision's provenance inline in English** — the
+  decision's intent and the date ("chose the mechanism refinement over the
+  rewrite" — 2026-06-28) — never a pointer at the chat ("settled in the
+  discussion", "decided in-context"). The chat is unreachable from the
+  tracker, and typically not English while the issue is an English
+  artefact — so state the intent, don't paste the chat's words; quote
+  verbatim only where the exact wording is load-bearing, and then
+  translated (`../issue/SKILL.md` rule 4). A pointer to the chat strands
+  every later reader.
 - **Reproduce each fork's options and chosen rationale inline.** A bare
  label ("Approach B") indexes a set the reader cannot see — spell the
  options out, or name the choice on its own terms.
@@ -749,7 +754,7 @@ the user wants it — there is no autonomous filing to govern.
 | "This spec is clearly good — I'll sign it on my judgement" | Your judgement is not the signature; the Step-5 `grounding-check` `PASS` is. Run grounding and sign on the PASS. A no-override grounding `BLOCK` routes to the human — never signed over on confidence. (The old unanimous `spec-skeptic` panel is retired; do not re-introduce it as a gate.) |
 | "There's an open fork — I'll bounce to `brainstorm` to be safe" | If you can *derive* an answer (sources, code, consistency, risk), decide it boldly and record it in the reference issue. Only a *pure-preference* fork bounces. Bouncing a derivable fork is exactly the timidity the bold stance retired; unsure if your leaning is bias, pull one ad-hoc `spec-skeptic` lens, then decide. |
 | "I derived a fork but didn't bother logging it on the issue" | The reference-issue comment is mandatory. It is the user's only window into a call made without them — and, because a rollback hard-drops the commits, the only surviving trace of the attempt. No reference issue, no fork decision: create the seeding issue first. |
-| "The user was in the discussion, so 'as decided in-context / above' is enough on the issue" | The decision log is read later by a run or user who was NOT in that discussion and may land on the comment alone. Quote the user's words + date inline, reproduce the fork's options and rationale, and link any sibling comment by a host-free relative link (`issues/N#issuecomment-M`) — never "above" / "in-context". The chat is not reachable from the tracker (`../issue/SKILL.md` rule 4). |
+| "The user was in the discussion, so 'as decided in-context / above' is enough on the issue" | The decision log is read later by a run or user who was NOT in that discussion and may land on the comment alone. State the user's decision intent in English + date inline, reproduce the fork's options and rationale, and link any sibling comment by a host-free relative link (`issues/N#issuecomment-M`) — never "above" / "in-context". The chat is not reachable from the tracker, and not English while the issue is (`../issue/SKILL.md` rule 4); quote the exact words only where the wording is load-bearing, and then translated. |
 | "I resolved the fork — I'll note that `specify` runs next so the thread is actionable" | The decision log records the decision and a tool-neutral readiness status, never this loop's dispatch. Directing who runs what next is session control-flow whether the skill is named ("dispatch `implement` next") or periphrased ("hand it to the spec writer") — meaningless to a later reader who isn't the loop, and declarative phrasing doesn't save it; "what's next" lives in the issue's open/labelled state (`../issue/SKILL.md` rule 1). |
 | "Auto-sign let me continue, so I don't need to notify — it's just progress" | The auto-sign notify is mandatory and carries a decision (the user's veto over a signature made without them). It is the one sanctioned mid-flow notify precisely because it is not progress — it is the audit trail for a delegated gate. |
 | "I hit a gap in the skill system itself — I should notify the user about it" | No. File it on the plugin's own tracker with an autonomous-provenance body block and continue (§ Skill-system feedback). It needs no mid-run decision, so notifying would be the attention-burning progress ping the notify discipline forbids; the filed issue is the durable record. |
@@ -773,7 +778,7 @@ the user wants it — there is no autonomous filing to govern.
 - About to re-introduce the retired `spec-skeptic` panel as a sign gate (a unanimous five-juror pass as a precondition) — it is now only the optional Step-1.5 bias-breaker; or to run any auto-sign path outside a `/boss` session, or to skip the mandatory auto-sign notify after signing.
 - About to *decide* a fork that hangs on pure user preference (no derivable better) instead of bouncing it — or its inverse, bouncing a *derivable* fork to `brainstorm` out of timidity.
 - About to make a fork decision without recording it on the run's reference issue, or to run autonomously with no reference issue at all.
- About to record a fork decision that points at the chat ("settled in the discussion", "decided in-context") or at an earlier comment by "above" / "logged above" — the decision log is tracker-reachable per `../issue/SKILL.md` rule 4: quote the provenance and reproduce the options inline, and link a sibling comment by a host-free relative link (`issues/N#issuecomment-M`).
+- About to record a fork decision that points at the chat ("settled in the discussion", "decided in-context") or at an earlier comment by "above" / "logged above" — the decision log is tracker-reachable per `../issue/SKILL.md` rule 4: state the provenance intent in English and reproduce the options inline, and link a sibling comment by a host-free relative link (`issues/N#issuecomment-M`).
 - About to write this loop's next dispatch into a decision-log comment — whether a skill is named ("enter `specify` from here", "next: dispatch `implement`") or periphrased ("hand it to the spec writer next") — instead of a tool-neutral readiness status; which actor runs next is this loop's Step 3/4, not an issue fact (`../issue/SKILL.md` rule 1).
 - About to `git reset` below the session anchor, or to `reset` a commit that has been pushed — the rollback sandbox is the orchestrator's *own unpushed* commits above the anchor only; user-ratified and pushed history is forward-only (`git revert`).
 - About to notify the user about a skill-system deficiency instead of filing it on the plugin's own tracker and continuing (§ Skill-system feedback) — it is captured, never a notify event.
@@ -162,8 +162,10 @@ A comment records one of two distinct things, and the distinction is
 load-bearing:

 - A **user decision** the conversation settled — minuted with
-  **provenance** (a verbatim user statement, or explicit attribution +
-  date). Legitimate: you are recording what the user chose.
+  **provenance** (the user's decision intent stated in English + explicit
+  attribution + date; a verbatim quote only where the exact wording is
+  load-bearing, and then translated — `../issue/SKILL.md` rule 4).
+  Legitimate: you are recording what the user chose.
 - A **derived orchestrator decision** — recorded with its **rationale**
  (why one option is groundably better). Legitimate under the new stance,
  but it must be labelled as what it is: a derived call, never disguised
@@ -183,8 +185,8 @@ skill's conventions). One comment, this shape:
 Spec: <spec-name>. The fork(s) below are still listed open on this
 issue; this records their resolution.
 - **Fork: <name>** → <decision>.
-  Basis: <verbatim user statement + attribution, OR "derived:" + the
-  groundable rationale>.
+  Basis: <user decision intent in English + attribution, OR "derived:" +
+  the groundable rationale>.
 ```

 `Basis:` carries either provenance (user decision) or rationale (derived
@@ -210,7 +212,7 @@ This issue seeds <one-line identity of the work>. The design was settled
 in an in-context discussion with no prior tracker issue; this records it.
 Load-bearing fork(s) resolved:
 - **Fork: <name>** → <decision>.
-  Basis: <verbatim user statement + attribution, OR "derived:" + rationale>.
+  Basis: <user decision intent in English + attribution, OR "derived:" + rationale>.
 ```

 The body names the *work*, not the spec file — the spec does not exist
@@ -94,8 +94,10 @@ In addition, every dispatch:
  the discussion, or, for a cycle that had *no* seeding issue, the
  *body* of the issue `specify` created to record it. Either counts as
  the sources resolving the fork **only if it carries provenance** — a
-  record of the user's decision (a verbatim statement, or explicit
-  attribution + date). A bare `decision: X` with no provenance is an
+  record of the user's decision (its intent stated in English + explicit
+  attribution + date; a verbatim quote only where the exact wording is
+  load-bearing, and then translated). A bare `decision: X` with no
+  provenance is an
  orchestrator self-assertion dressed as settled, not a source: it does
  **not** resolve the fork, and a load-bearing decision whose only
  support is such a record is a refutation. If the project declares no