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:
+37
-5
@@ -39,11 +39,37 @@ convention they lean on.
|
||||
|
||||
These apply to every issue, on create and on edit.
|
||||
|
||||
1. **No direct address.** Impersonal, declarative voice. No "you",
|
||||
no imperative aimed at the reader. State the situation, not
|
||||
instructions to a person.
|
||||
- Avoid: "You need to fix the parser because you broke escaping."
|
||||
- Use: "The parser drops backslash escapes in quoted strings."
|
||||
1. **Impersonal and tool-neutral.** Declarative voice — no "you", no
|
||||
imperative aimed at the reader, and equally no first-person narration of
|
||||
the loop's own acts ("I'll now run audit", "I'll hand this off next"):
|
||||
an issue is nobody's monologue, neither addressed to a reader nor spoken
|
||||
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
|
||||
verified — carrying its evidence (command output, log line,
|
||||
@@ -186,6 +212,7 @@ Notes:
|
||||
| Mistake | Why it's bad | Instead |
|
||||
|---|---|---|
|
||||
| "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): …" |
|
||||
| Title as a noun blob ("parser bug") | Not scannable | Imperative verb phrase |
|
||||
| `-d` body with a guessed flag (`--body`) | tea rejects it | `--description`/`-d` |
|
||||
@@ -199,6 +226,11 @@ Notes:
|
||||
## Red flags — STOP
|
||||
|
||||
- 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 title that is a noun phrase or ends with a period
|
||||
- A reference with no resolvable locator (`#N`, a commit SHA, a URL, an
|
||||
|
||||
Reference in New Issue
Block a user