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.
This commit is contained in:
2026-07-09 10:56:40 +02:00
parent dacadba07f
commit f1b3af5f09
3 changed files with 22 additions and 13 deletions
+11 -6
View File
@@ -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 chat that produced it, so each must be self-contained, reachable from the
tracker, and free of this loop's own control-flow. tracker, and free of this loop's own control-flow.
- **Quote a user decision's provenance inline** — the words and the date - **State a user decision's provenance inline in English** — the
("`ja, mach B`" — 2026-06-28) — never a pointer at the chat ("settled decision's intent and the date ("chose the mechanism refinement over the
in the discussion", "decided in-context"). The chat is unreachable from rewrite" — 2026-06-28) — never a pointer at the chat ("settled in the
the tracker; a pointer to it strands every later reader. 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 - **Reproduce each fork's options and chosen rationale inline.** A bare
label ("Approach B") indexes a set the reader cannot see — spell the label ("Approach B") indexes a set the reader cannot see — spell the
options out, or name the choice on its own terms. 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.) | | "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. | | "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. | | "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). | | "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. | | "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. | | "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 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 *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 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 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 `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. - 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.
+7 -5
View File
@@ -162,8 +162,10 @@ A comment records one of two distinct things, and the distinction is
load-bearing: load-bearing:
- A **user decision** the conversation settled — minuted with - A **user decision** the conversation settled — minuted with
**provenance** (a verbatim user statement, or explicit attribution + **provenance** (the user's decision intent stated in English + explicit
date). Legitimate: you are recording what the user chose. 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** - A **derived orchestrator decision** — recorded with its **rationale**
(why one option is groundably better). Legitimate under the new stance, (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 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 Spec: <spec-name>. The fork(s) below are still listed open on this
issue; this records their resolution. issue; this records their resolution.
- **Fork: <name>** → <decision>. - **Fork: <name>** → <decision>.
Basis: <verbatim user statement + attribution, OR "derived:" + the Basis: <user decision intent in English + attribution, OR "derived:" +
groundable rationale>. the groundable rationale>.
``` ```
`Basis:` carries either provenance (user decision) or rationale (derived `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. in an in-context discussion with no prior tracker issue; this records it.
Load-bearing fork(s) resolved: Load-bearing fork(s) resolved:
- **Fork: <name>** → <decision>. - **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 The body names the *work*, not the spec file — the spec does not exist
+4 -2
View File
@@ -94,8 +94,10 @@ In addition, every dispatch:
the discussion, or, for a cycle that had *no* seeding issue, the the discussion, or, for a cycle that had *no* seeding issue, the
*body* of the issue `specify` created to record it. Either counts as *body* of the issue `specify` created to record it. Either counts as
the sources resolving the fork **only if it carries provenance** — a the sources resolving the fork **only if it carries provenance** — a
record of the user's decision (a verbatim statement, or explicit record of the user's decision (its intent stated in English + explicit
attribution + date). A bare `decision: X` with no provenance is an 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 orchestrator self-assertion dressed as settled, not a source: it does
**not** resolve the fork, and a load-bearing decision whose only **not** resolve the fork, and a load-bearing decision whose only
support is such a record is a refutation. If the project declares no support is such a record is a refutation. If the project declares no