From a6a521688534e33b7e9e54efd45a4973ad45191b Mon Sep 17 00:00:00 2001 From: LMKaelbot Date: Tue, 24 Feb 2026 21:44:21 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20add=20Pitfalls=20&=20Patterns=20section?= =?UTF-8?q?=20=E2=80=94=20race=20condition=20fix=20for=20sub-agent=20file?= =?UTF-8?q?=20edits?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When main session + sub-agents both edit a shared task file, the edit tool's exact-match requirement causes silent failures. Solution: split into an immutable goals file (main session only) and an append-only task log (sub-agents only append, never edit). Also adds tip to keep AUTONOMOUS.md token-light by archiving completed tasks to a separate file loaded only on-demand. Verified in production over ~1 day of autonomous heartbeat workflows. --- usecases/overnight-mini-app-builder.md | 34 ++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/usecases/overnight-mini-app-builder.md b/usecases/overnight-mini-app-builder.md index b01520b..be0ccf8 100644 --- a/usecases/overnight-mini-app-builder.md +++ b/usecases/overnight-mini-app-builder.md @@ -81,6 +81,40 @@ in real-time as you complete tasks. - For overnight app building specifically: explicitly tell it to build MVPs and not to overcomplicate. You'll wake up every morning with a new surprise. - This compounds over time — the agent learns what kinds of tasks are most helpful and adjusts. +## Pitfalls & Patterns (Learned in Production) + +### ⚠️ Race Condition: Sub-Agents Editing Shared Files + +When you run this workflow with sub-agents, both the main session and spawned sub-agents may try to update the same task file (e.g., your Kanban/AUTONOMOUS.md). This causes silent failures. + +**Why it happens:** OpenClaw's `edit` tool requires an exact `oldText` match. If a sub-agent updates a line between the time your main session reads the file and tries to edit it, the text no longer matches — the edit silently fails. + +**The fix: split your task file into two roles:** + +1. **`AUTONOMOUS.md`** — stays small and clean. Contains only goals + open backlog. Only the main session touches this. Sub-agents never edit it. + +2. **`memory/tasks-log.md`** — append-only log. Sub-agents only ever *add new lines at the bottom*. Never edit existing lines. + +```markdown +# tasks-log.md — Completed Tasks (append-only) +# Sub-agents: always append to the END. Never edit existing lines. + +### 2026-02-24 +- ✅ TASK-001: Research competitors → research/competitors.md +- ✅ TASK-002: Draft blog post → drafts/post-1.md +``` + +This pattern is borrowed from Git's commit log: you never rewrite history, you only add new commits. It eliminates race conditions entirely and has a bonus: `AUTONOMOUS.md` stays small, so it costs fewer tokens every time it's loaded in a heartbeat. + +**Rule to give your agent:** In sub-agent spawn instructions, always include: +> "When done, append a ✅ line to `memory/tasks-log.md`. Never edit `AUTONOMOUS.md` directly." + +### 💡 Keep AUTONOMOUS.md Token-Light + +The task tracking file gets loaded on every heartbeat poll. If it grows unbounded with completed tasks, you'll burn tokens unnecessarily. + +Keep `AUTONOMOUS.md` under ~50 lines: goals (one-liners) + open backlog only. Archive everything completed to a separate file that is only read on-demand. + ## Based On Inspired by [Alex Finn](https://www.youtube.com/watch?v=UTCi_q6iuCM&t=414s) and his [video on life-changing OpenClaw use cases](https://www.youtube.com/watch?v=41_TNGDDnfQ).