From f1b3af5f09eebc7e99c14cdb57f4c672921cca11 Mon Sep 17 00:00:00 2001 From: Brummel Date: Thu, 9 Jul 2026 10:56:40 +0200 Subject: [PATCH] docs(boss,specify): propagate the intent-in-English provenance rule to decision-log writers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- boss/SKILL.md | 17 +++++++++++------ specify/SKILL.md | 12 +++++++----- specify/agents/spec-skeptic.md | 6 ++++-- 3 files changed, 22 insertions(+), 13 deletions(-) diff --git a/boss/SKILL.md b/boss/SKILL.md index beb16c5..fd8a714 100644 --- a/boss/SKILL.md +++ b/boss/SKILL.md @@ -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. diff --git a/specify/SKILL.md b/specify/SKILL.md index 9df73b3..8c5e376 100644 --- a/specify/SKILL.md +++ b/specify/SKILL.md @@ -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: . The fork(s) below are still listed open on this issue; this records their resolution. - **Fork: ** → . - Basis: . + Basis: . ``` `Basis:` carries either provenance (user decision) or rationale (derived @@ -210,7 +212,7 @@ This issue seeds . The design was settled in an in-context discussion with no prior tracker issue; this records it. Load-bearing fork(s) resolved: - **Fork: ** → . - Basis: . + Basis: . ``` The body names the *work*, not the spec file — the spec does not exist diff --git a/specify/agents/spec-skeptic.md b/specify/agents/spec-skeptic.md index 4056655..6ee00b1 100644 --- a/specify/agents/spec-skeptic.md +++ b/specify/agents/spec-skeptic.md @@ -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