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
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.
+7 -5
View File
@@ -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
+4 -2
View File
@@ -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