From 2f049dfe6bf5cf50ebbcf71488cf3f3536dfb186 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Tue, 23 Dec 2025 15:10:25 -0800
Subject: [PATCH] docs: add temporal trap warning to onboard section

Helps agents avoid the common mistake of inverting dependency
direction when using temporal language like 'Phase 1 blocks Phase 2'.
---
 CLAUDE.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 50aa29c6..fbe7caaa 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -740,6 +740,17 @@ bd close bd-42 --reason "Completed" --json
 - `3` - Low (polish, optimization)
 - `4` - Backlog (future ideas)
 
+### Dependencies: Avoid the Temporal Trap
+
+When adding dependencies, think "X **needs** Y" not "X **comes before** Y":
+
+```bash
+# ❌ WRONG: "Phase 1 blocks Phase 2" → bd dep add phase1 phase2
+# ✅ RIGHT: "Phase 2 needs Phase 1" → bd dep add phase2 phase1
+```
+
+Verify with `bd blocked` - tasks should be blocked by prerequisites, not dependents.
+
 ### Workflow for AI Agents
 
 1. **Check your inbox**: `gt mail inbox` (from your cwd, not ~/gt)