From 04c345b212d9b6481756531866d24fdf287ff047 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Wed, 17 Dec 2025 13:54:01 -0800
Subject: [PATCH] feat: add merge queue implementation plan to beads
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Created detailed implementation beads from docs/merge-queue-design.md:

Foundation (P0, ready):
- gt-h5n.1: MR field parsing
- gt-h5n.2: MR ID generation
- gt-h5n.3: MR state transitions

CLI Commands (P0, under gt-svi):
- gt-svi.1: gt mq submit
- gt-svi.2: gt mq list
- gt-svi.3: gt mq status
- gt-svi.4: gt mq retry
- gt-svi.5: gt mq reject

Engineer Processing (P1, under gt-3x1):
- gt-3x1.1: Main loop
- gt-3x1.2: Fetch and conflict check
- gt-3x1.3: Merge execution
- gt-3x1.4: Failure handling
- gt-3x1.5: Success handling

Integration Branches (P1):
- gt-h5n.4-7: create, land, status, auto-target

Configuration & Advanced (P1-P3):
- gt-h5n.8-15: config, metrics, dashboard, rollback

Also added dependency planning guidance to CLAUDE.md to prevent
inverted dependency mistakes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index ff99f1ec..af5107c6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,3 +28,50 @@ go test ./...
 
 - `gt-u1j`: Port Gas Town to Go (main tracking epic)
 - `gt-f9x`: Town & Rig Management (install, doctor, federation)
+
+### Planning Work with Dependencies
+
+When breaking down large features into tasks, use **beads dependencies** to sequence work - NOT phases or numbered steps.
+
+**Cognitive Trap: Temporal Language Inverts Dependencies**
+
+Words like "Phase 1", "Step 1", "first", "before" trigger temporal reasoning that **flips dependency direction**. Your brain thinks:
+- "Phase 1 comes before Phase 2" → "Phase 1 blocks Phase 2" → `bd dep add phase1 phase2`
+
+But that's **backwards**! The correct mental model:
+- "Phase 2 **depends on** Phase 1" → `bd dep add phase2 phase1`
+
+**Solution: Use requirement language, not temporal language**
+
+Instead of phases, name tasks by what they ARE, and think about what they NEED:
+
+```bash
+# WRONG - temporal thinking leads to inverted deps
+bd create "Phase 1: Create buffer layout" ...
+bd create "Phase 2: Add message rendering" ...
+bd dep add phase1 phase2  # WRONG! Says phase1 depends on phase2
+
+# RIGHT - requirement thinking
+bd create "Create buffer layout" ...
+bd create "Add message rendering" ...
+bd dep add msg-rendering buffer-layout  # msg-rendering NEEDS buffer-layout
+```
+
+**Verification**: After adding deps, run `bd blocked` - tasks should be blocked by their prerequisites, not their dependents.
+
+**Example breakdown** (for a multi-part feature):
+```bash
+# Create tasks named by what they do, not what order they're in
+bd create "Implement conversation region" -t task -p 1
+bd create "Add header-line status display" -t task -p 1
+bd create "Render tool calls inline" -t task -p 2
+bd create "Add streaming content support" -t task -p 2
+
+# Set up dependencies: X depends on Y means "X needs Y first"
+bd dep add header-line conversation-region    # header needs region
+bd dep add tool-calls conversation-region     # tools need region
+bd dep add streaming tool-calls               # streaming needs tools
+
+# Verify with bd blocked - should show sensible blocking
+bd blocked
+```