From c43ebc5b7e9afb49c32e7d5aa8fa32eae2bdcd54 Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Mon, 23 Feb 2026 22:23:18 +0100 Subject: [PATCH] Add 'Leaving Context for Future Agents' section to beads SKILL.md Prompts agents to comment on beads with decisions, dead ends, and discoveries during execution, and to search past beads before starting non-trivial work. Covers human-authored comments as equally authoritative context. Implements bd-3r1. Co-Authored-By: Claude Sonnet 4.6 --- skills/beads/SKILL.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/skills/beads/SKILL.md b/skills/beads/SKILL.md index f285d60..01de809 100644 --- a/skills/beads/SKILL.md +++ b/skills/beads/SKILL.md @@ -124,6 +124,48 @@ To determine if a parent bead has incomplete child tasks, query the children end 4. Complete it: `echo "complete bd-xyz" | 9p write agent/beads/ctl` 5. Completing a bead unblocks its dependents +## Leaving Context for Future Agents + +Beads serve as dynamic/temporal memory for agent execution. Beyond status tracking, they capture decisions, dead ends, discoveries, and rationale — context that helps future agents working on related tasks avoid repeated mistakes and build on prior work. + +This is distinct from `agent-kb` (stable, reusable architectural knowledge). Beads hold *execution-time context*: what was tried, what failed, what was discovered, and why a particular approach was chosen. + +### When to Comment + +Comment on your bead as you work — not just at completion. Record: +- **Decisions**: "Chose approach Z because X failed due to Y." +- **Dead ends**: "Tried X, failed because Y. Avoided." +- **Discoveries**: "Found that endpoint /foo also rotates the refresh token." +- **Constraints**: "Avoided approach A because of constraint B (see bd-xyz)." + +Comments may come from agents or humans (e.g., a human reviewing work, recording a constraint, or explaining a decision). Treat both equally as authoritative context. + +```bash +echo "comment bd-abc \"Tried X first but hit rate limits. Switched to Y which batches requests.\"" | 9p write agent/beads/ctl +``` + +### When to Search Past Beads + +Before starting any non-trivial task, search completed beads for related terms to surface prior decisions and gotchas: + +```bash +9p read agent/beads/search/authentication | jq '.[].title' +9p read agent/beads/search/refresh-token | jq '.[].description' +``` + +When a bead looks relevant, read its full event history to see comments — this is where the most valuable context lives, including human-authored notes: + +```bash +9p read agent/beads/bd-abc/events | jq '.[] | select(.type == "comment") | .body' +``` + +### What NOT to Do + +- ❌ **NEVER create "knowledge beads"** solely to record information — this pollutes the task system with non-task entries +- ❌ Don't leave your bead with only status updates — rationale and discoveries are more valuable to future agents than "completed X" + +Context belongs *in your task bead*, recorded as comments during execution. + ## JSON Output for Programmatic Use All read endpoints return JSON for easy parsing.