From 5aed15bb98c86d39377babbcc334e441c3311197 Mon Sep 17 00:00:00 2001 From: Edwin van den Houdt Date: Fri, 4 Sep 2026 23:44:17 +0200 Subject: [PATCH] docs: record the supervisor-as-second-writer mistake from RD-24 A task notification fires every time an agent stops with no live children, including a pause mid-task. RD-24's agent paused and notified; the supervisor read that as abandonment, took over the tree, ran the gate and edited the ticket Status while the agent was still working. The agent resumed, correctly detected a second writer, and refused to commit. This is the mirror image of the RD-17 race the section above records: there a fresh supervisor met a running agent, here a running agent met its own supervisor. Co-Authored-By: Claude Opus 5 --- docs/project/readable-codebase/README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/project/readable-codebase/README.md b/docs/project/readable-codebase/README.md index ccdc2c5..5de8e1f 100644 --- a/docs/project/readable-codebase/README.md +++ b/docs/project/readable-codebase/README.md @@ -294,3 +294,18 @@ git log --oneline -1 # did an agent already commit the ticket? If the tree is dirty and this session did not dirty it, find the agent before you write a ticket around the evidence it leaves. + +**The mirror-image mistake, made during RD-24: the supervisor became the second writer.** A +task notification fires every time an agent stops with **no live children — including a pause +mid-task**. RD-24's agent paused, said it was waiting on a check, and notified. The supervisor +read that as an abandoned task, took over the working tree, ran the gate and edited the ticket +`Status:` — while the agent was still running. The agent then resumed, correctly detected a +second process writing its tree, and refused to commit. + +Nothing was lost, because the agent stopped instead of committing. Two rules follow: + +- **A notification is not proof the work is finished.** A finished agent hands back a report + with acceptance numbers. "I am waiting for X" is a pause. +- **Before taking over an agent's tree, confirm the agent is gone**: `ps aux | grep "npm run"`, + and check whether its own result has arrived. Taking over is a real option — RD-24 was + finished that way — but it must be a decision, not an assumption.