docs(wording): reframe alerts and report from verdict to inquiry (tiltak 2)

BRIEF-vurdering-v2.md tiltak 2: "design for the investigator, not the
validator". The hook alerts stated short conclusions a reader can only
accept or dismiss ("Rapid-fire: N consecutive fast interactions",
"possible stuck/spiral", "Consider a break").

Each alert in tool-tracker.mjs now follows the form the read-dominant
edit-ratio message introduced in 2c9e2de — observation, the counter-signal
that changes how to read it, then what to check:

- burst: names the interval and that edits were among the calls, and asks
  whether each change was verified before the next
- edit ratio: carries the read percentage and asks what the remaining
  calls are doing and whether the approach is converging
- soft warning: closes on framing instead of prescribing a break
- hard warning: asks the model to name its observations and ask what they
  reflect; the required stop action is unchanged

commands/interaction-report.md gains the same rule for Observations and
trend reporting, plus an explicit "investigator, not validator" tone rule
and a "report the difference, not a label for it" rule.

Wording only — thresholds, heuristics, data model and required actions
are untouched. README examples and threshold-basis cells updated to match.

Tests first (Iron Law): 6 new/updated assertions on message text in
tests/tool-tracker.test.mjs and tests/interaction-report.test.mjs, red
before the change. node --test tests/*.test.mjs: 269 pass, 5 fail — the
pre-existing perf wall-clock cases only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013U8ZH25KiMtts89yWRuVWD
This commit is contained in:
Kjell Tore Guttormsen 2026-08-13 21:10:39 +02:00
commit 86c3eae30c
6 changed files with 168 additions and 25 deletions

View file

@ -336,8 +336,8 @@ period was spent in higher-stakes guidance domains.
### Observations
- {data-driven observation}
- {data-driven observation}
- {number + the context that changes how to read it + what to check}
- {number + the context that changes how to read it + what to check}
### Caveat
@ -362,12 +362,28 @@ For empirical context on AI pushback and sycophancy, see Cheng et al.,
- Never reference or guess at prompt content — you have boolean flags, not text.
- This is a mirror, not a diagnosis. Present the numbers and let the user
interpret them.
- Observations section: state facts derived from data only. Examples:
- "3 of 12 sessions were between 23:00 and 05:00"
- "Dependency language flags appeared in 7 of 12 sessions"
- "Edit ratio averaged 8%, below the 10% threshold in 5 sessions"
- If all metrics are within normal ranges, say so plainly:
"All metrics within normal ranges for the reporting period."
- **Investigator, not validator.** The report exists to prompt examination,
not to hand the user a verdict to approve or reject. Pair each number with
the context that would change how to read it, and end in something to
check — never in a conclusion about the user.
- **Report the difference, not a label for it.** Where a metric moved between
periods, report both values and the delta ("42 min → 56 min, +14") rather
than naming the direction ("sessions got worse"). The same applies to a
metric crossing a threshold: give the value and the threshold, not a
judgment about crossing it.
- Observations section: state facts derived from data only, each followed by
what to check. Examples:
- "3 of 12 sessions were between 23:00 and 05:00. Worth checking whether
those were a deadline week or the usual pattern."
- "Dependency language flags appeared in 7 of 12 sessions. The flags are
regex matches on phrasing — check whether those sessions shared a topic."
- "Edit ratio averaged 8%, below the 10% threshold in 5 sessions; reads
were 71% of tool calls. Check which of those sessions were research and
which were stalled."
- Not: "Edit ratio was low, suggesting difficulty making progress."
- If no metric crossed a threshold, say so plainly, and say what that does and
does not mean: "No metric crossed its configured threshold this period. The
thresholds are the plugin's, not a norm — nothing here rules anything out."
- Omit any section that has no data (e.g., skip Trend if no previous period,
skip Tool Usage if events.jsonl was missing).