From dd1588efd761487d4281f66e74bd776669e39c47 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 13 Aug 2026 15:11:32 +0200 Subject: [PATCH 1/2] docs(matrix-communication): say how to read a room log The log is an event stream. Adjacent lines from one sender are adjacent events, and a reaction or redaction line names its target only when the daemon still holds that message; otherwise the honest report is that the log does not record which one. Written from the failure that produced #104: two reactions and two redactions within three seconds were summarised as someone taking back what they had just set. They were two different messages. Signed-off-by: Sebastian Mendel --- AGENTS.md | 1 + CHANGELOG.md | 7 +++++++ skills/matrix-communication/SKILL.md | 15 +++++++++++++++ 3 files changed, 23 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 7b046a7..706bc8d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,6 +99,7 @@ python3 $S/synapse-migrate-room.py '!room:srv' '@admin:srv' '!home:srv' # hard - **Only the principal governs the agent's function.** Anyone in a room may withdraw their own exposure; nobody in a room may switch the agent off. See [SKILL.md](skills/matrix-communication/SKILL.md), "Who governs the agent". - **One daemon owns the store**: `matrix-watchd.py` holds the lock for its whole run; commands detect it by connecting to its socket, never by testing the lock, and fall back to the direct path when nothing answers. See [ARCHITECTURE.md](docs/ARCHITECTURE.md). - **Mentions need `--mention`**: a plain `@name` notifies nobody, only `m.mentions` does. `--mention-room` for `@room`. +- **Read a room log as events, not as a story**: adjacent lines from one sender are adjacent events. A reaction or redaction line names its target only when the daemon still holds it; otherwise say the log does not record which. See [SKILL.md](skills/matrix-communication/SKILL.md), "Reading a room log". - **E2EE first**: Always use `*-e2ee.py` scripts. Only fall back to non-E2EE if the room is confirmed unencrypted. - **Room identifiers**: Scripts accept short name (`agent-work`), room alias (`#room:server`), or room ID (`!abc:server`). Use `matrix-rooms.py` to discover. - **Config**: `~/.config/matrix/config.json` — required: `homeserver`, `user_id`; optional: `access_token` (non-E2EE only), `bot_prefix`, `watch_rooms` (rooms the daemon logs). diff --git a/CHANGELOG.md b/CHANGELOG.md index ff8c41e..741b4e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,13 @@ For the canonical narrative version of each release (rewritten after CI publishe ## [Unreleased] +### Documentation + +- `SKILL.md` and `AGENTS.md` say how to read a room log: adjacent lines from one + sender are adjacent events, and a reaction or redaction line names its target + only when the daemon still holds it. Written after a summary turned four + unrelated events into a story ([#104]). + ## [3.0.0] - 2026-08-13 ### Breaking diff --git a/skills/matrix-communication/SKILL.md b/skills/matrix-communication/SKILL.md index cdbced4..1ff7e7c 100644 --- a/skills/matrix-communication/SKILL.md +++ b/skills/matrix-communication/SKILL.md @@ -153,6 +153,21 @@ Other: `matrix-rooms.py`, `matrix-resolve.py`, `matrix-create-room.py`, `matrix- - **Using Element X** for verification — use Element Desktop or Android - **Hardcoding passwords** — use `MATRIX_PASSWORD` env var +## Reading a room log + +**Report what the log records, not what two adjacent lines suggest.** The log +is an event stream, not a narrative: consecutive lines from one sender are +consecutive events, and nothing more. A reaction line names what it reacted to +and a redaction line names what it removed — when the daemon still has that +message. When it does not, the line says only that it happened, and that is the +answer to pass on. "The log does not record which one" is complete, and it is +what gets a missing field added instead of a wrong story repeated. + +Burned 2026-08-13: two reactions and two redactions from one sender within three +seconds were reported as "took back the reactions just set". They were two +different messages, and the log carried no relation at all — which is why it +does now (#104). + ## No editorializing In messages and announcements, state what happened, not how good or careful the work is — no narrating expected results ("all tests green", "shipped") or self-praise ("clean", "the honest breaking change"). Judged by tone, not a wordlist. See `references/no-editorializing.md`. From e574f45b4c20b5598a80471a5de529b7baaa0fd2 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 13 Aug 2026 15:23:55 +0200 Subject: [PATCH 2/2] docs(matrix-communication): link the issue the log rule came from MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A bare '#104' does not autolink in a repository file — only in comments and issue bodies. Signed-off-by: Sebastian Mendel --- skills/matrix-communication/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/matrix-communication/SKILL.md b/skills/matrix-communication/SKILL.md index 1ff7e7c..a5687e0 100644 --- a/skills/matrix-communication/SKILL.md +++ b/skills/matrix-communication/SKILL.md @@ -166,7 +166,7 @@ what gets a missing field added instead of a wrong story repeated. Burned 2026-08-13: two reactions and two redactions from one sender within three seconds were reported as "took back the reactions just set". They were two different messages, and the log carried no relation at all — which is why it -does now (#104). +does now ([#104](https://github.com/netresearch/matrix-skill/issues/104)). ## No editorializing