fix(issue,boss): bar tracker entries from carrying the loop's own dispatch

An issue or decision-log entry must state the situation, not the
orchestration loop's next move. "Next step: enter `specify`" — and its
role-periphrasis "hand it off to the spec writer next", which names no
skill — is Claude-Code session control-flow, meaningless to a tracker
reader who is not the loop. A distinct defect class from rule 4
reachability, and not curable by declarative phrasing: the content is
harness-native.

issue rule 1 retitled "No direct address" -> "Impersonal and
tool-neutral". The discriminator is status vs. dispatch, name-independent
(describes the work's condition -> keep; directs who runs what next ->
cut), and rule 1 now also bars first-person loop narration. boss § The
reference issue gains "Record the decision, not the dispatch". Triple-
encoded in both skills (rule/mechanic + table/rationalisation + red-flag).

Future-only; existing entries are not edited.
This commit is contained in:
2026-06-29 18:00:40 +02:00
parent 82bb8642b2
commit fe0ad9d739
2 changed files with 54 additions and 8 deletions
+17 -3
View File
@@ -294,9 +294,10 @@ things at once:
remains of the dead-ended line. remains of the dead-ended line.
These decision-log comments are issue entries — they obey These decision-log comments are issue entries — they obey
`../issue/SKILL.md` rule 4, the reachability test: a later run or user `../issue/SKILL.md`: rule 1 (impersonal and tool-neutral) and rule 4 (the
lands on the **comment**, not the chat that produced it, so each must be reachability test). A later run or user lands on the **comment**, not the
self-contained and reachable from the tracker. 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 - **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 ("`ja, mach B`" — 2026-06-28) — never a pointer at the chat ("settled
@@ -308,6 +309,17 @@ self-contained and reachable from the tracker.
- **Tie a later comment to an earlier one by that comment's full URL, or - **Tie a later comment to an earlier one by that comment's full URL, or
restate the point** — never "above" / "logged above" / "the prior restate the point** — never "above" / "logged above" / "the prior
comment", which a reader on a direct comment-anchor link cannot resolve. comment", which a reader on a direct comment-anchor link cannot resolve.
- **Record the decision, not the dispatch.** The comment logs what was
decided and why, and may carry a durable, tool-neutral readiness status
("design settled — ready for spec production"). It never writes this
loop's own next move into the issue — neither a named skill ("enter
`specify` from here", "next: dispatch `implement`") nor a role-periphrasis
for the same hand-off ("hand it to the spec writer next"). The test is
dispatch vs. status: directing *who runs what next* is out even when it
names no skill; the work's *condition* (settled, ready, blocked-on) stays.
Which actor runs next is Step 3/4 of *this* loop, meaningless to a later
reader who is not the loop; the issue's open/labelled state carries
"what's next" (`../issue/SKILL.md` rule 1).
The provenance block in § Skill-system feedback shows the form: The provenance block in § Skill-system feedback shows the form:
provenance written into the issue body, never pointed at. provenance written into the issue body, never pointed at.
@@ -662,6 +674,7 @@ the user wants it — there is no autonomous filing to govern.
| "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 its full URL — 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. Quote the user's words + date inline, reproduce the fork's options and rationale, and link any sibling comment by its full URL — never "above" / "in-context". The chat is not reachable from the tracker (`../issue/SKILL.md` rule 4). |
| "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. |
| "Something was awkward this run — file it against the plugin tracker" | Only a *durable plugin* deficiency qualifies: the fault is the plugin's (not the project's) and it would recur on the next run. One-off project friction is not plugin feedback; when unsure whose fault it is, it is the project's. File on the plugin tracker (never the project's), dedupe against its issues first, and mark provenance in the body — never with a new label. | | "Something was awkward this run — file it against the plugin tracker" | Only a *durable plugin* deficiency qualifies: the fault is the plugin's (not the project's) and it would recur on the next run. One-off project friction is not plugin feedback; when unsure whose fault it is, it is the project's. File on the plugin tracker (never the project's), dedupe against its issues first, and mark provenance in the body — never with a new label. |
@@ -684,6 +697,7 @@ the user wants it — there is no autonomous filing to govern.
- 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 its full URL. - 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 its full URL.
- 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.
- About to file plugin feedback for one-off project friction rather than a durable plugin deficiency, against the *project's* tracker instead of the plugin's, without deduping against the plugin's issues, or marked with a new provenance label instead of the body block. - About to file plugin feedback for one-off project friction rather than a durable plugin deficiency, against the *project's* tracker instead of the plugin's, without deduping against the plugin's issues, or marked with a new provenance label instead of the body block.
+37 -5
View File
@@ -39,11 +39,37 @@ convention they lean on.
These apply to every issue, on create and on edit. These apply to every issue, on create and on edit.
1. **No direct address.** Impersonal, declarative voice. No "you", 1. **Impersonal and tool-neutral.** Declarative voice — no "you", no
no imperative aimed at the reader. State the situation, not imperative aimed at the reader, and equally no first-person narration of
instructions to a person. the loop's own acts ("I'll now run audit", "I'll hand this off next"):
- Avoid: "You need to fix the parser because you broke escaping." an issue is nobody's monologue, neither addressed to a reader nor spoken
- Use: "The parser drops backslash escapes in quoted strings." by the loop. State the situation, not what an actor does about it. The
issue is also a durable, tool-agnostic artefact, so it never carries the
orchestration loop's own next move — any direction of *what the loop runs
next*: most blatantly naming a skill or pipeline step ("enter `specify`",
"dispatch `implement`"), but equally a role-periphrasis for the same
hand-off that names nothing ("hand it to the spec writer next", "kick off
the next pipeline stage"). That is session control-flow, meaningless to a
tracker reader — a human months later, a different tool — who is not the
loop; rephrasing it in declarative voice does not save it, because the
*content* is harness-native.
- The discriminator is **status vs. dispatch**, not whether a skill is
named. A sentence stating *what is true of the work* — the next
**work** itself ("next: a breakout-style trend entry") or a durable
readiness **status** ("design settled — ready for spec production";
"implementation done — ready for audit", fine even when the phase-noun
is also a skill name; "blocked on #N") — is legitimate. A sentence
directing *who runs what next* is out **whether or not it names a
skill**. Apply it sentence by sentence: does it describe the work's
condition (keep) or an actor's next move (cut)? "What's next" otherwise
lives in the issue's open/labelled state, not a prose dispatch of the
next skill in the body.
- Avoid: "You need to fix the parser because you broke escaping." /
"Next step: enter `specify` from this comment." / "Ready to hand off to
the spec writer next."
- Use: "The parser drops backslash escapes in quoted strings." / "The
design is settled here — no open load-bearing fork remains; ready for
spec production."
2. **Validated or flagged.** Every factual statement is either 2. **Validated or flagged.** Every factual statement is either
verified — carrying its evidence (command output, log line, verified — carrying its evidence (command output, log line,
@@ -186,6 +212,7 @@ Notes:
| Mistake | Why it's bad | Instead | | Mistake | Why it's bad | Instead |
|---|---|---| |---|---|---|
| "You should…" / reader-directed imperative | Breaks rule 1, ages badly | State the situation declaratively | | "You should…" / reader-directed imperative | Breaks rule 1, ages badly | State the situation declaratively |
| Orchestration next-step in title or body — directing who runs what next, whether a skill is named ("enter `specify`", "dispatch `implement`") or periphrased ("hand it to the spec writer next") | Harness session control-flow, invisible to a tracker reader who isn't the loop; declarative phrasing doesn't save it | Drop it — a tool-neutral readiness status ("ready for spec production"); the issue's open/labelled state carries "what's next" |
| A guess written as fact | Misleads future actors | Flag it: "Claim (unverified): …" | | A guess written as fact | Misleads future actors | Flag it: "Claim (unverified): …" |
| Title as a noun blob ("parser bug") | Not scannable | Imperative verb phrase | | Title as a noun blob ("parser bug") | Not scannable | Imperative verb phrase |
| `-d` body with a guessed flag (`--body`) | tea rejects it | `--description`/`-d` | | `-d` body with a guessed flag (`--body`) | tea rejects it | `--description`/`-d` |
@@ -199,6 +226,11 @@ Notes:
## Red flags — STOP ## Red flags — STOP
- The word "you" anywhere in title or body - The word "you" anywhere in title or body
- An orchestration next-step in title or body — directing who runs what
next, whether a skill is named ("enter `specify`", "dispatch
`implement`") or periphrased ("hand it to the spec writer next") — in
place of a tool-neutral status (a tool-neutral statement of the next
*work*, or a readiness status, is not what this flags)
- A factual statement with neither evidence nor a "claim" flag - A factual statement with neither evidence nor a "claim" flag
- A title that is a noun phrase or ends with a period - A title that is a noun phrase or ends with a period
- A reference with no resolvable locator (`#N`, a commit SHA, a URL, an - A reference with no resolvable locator (`#N`, a commit SHA, a URL, an