From d823ced14cd625bf616abff174e3f4d468a1f0f8 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Tue, 23 Dec 2025 14:11:40 -0800
Subject: [PATCH] refactor: Nuanced refinery context heuristic - 20 simple or
 immediate on complex (gt-nqrh)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Most MRs are button-pushes (clean rebase + push). Only complex rebases
(conflicts, test failures) consume significant context.

- 20 simple MRs before handoff
- Immediate handoff after any complex rebase

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 internal/templates/roles/refinery.md.tmpl | 58 +++++++++++++----------
 1 file changed, 32 insertions(+), 26 deletions(-)

diff --git a/internal/templates/roles/refinery.md.tmpl b/internal/templates/roles/refinery.md.tmpl
index 65041cb2..57c75216 100644
--- a/internal/templates/roles/refinery.md.tmpl
+++ b/internal/templates/roles/refinery.md.tmpl
@@ -163,43 +163,49 @@ atop the new baseline.** This is non-negotiable.
 
 ---
 
-## State Files
+## Context Management
 
-| File | Purpose |
-|------|---------|
-| `{{ .WorkDir }}/state.json` | Patrol tracking and merge counts |
+**Heuristic**: Hand off after **20 simple MRs** OR **immediately** after any complex rebase.
+
+Most MRs are trivial:
+- Clean rebase (no conflicts)
+- Tests pass
+- Fast-forward merge + push
+
+These consume minimal context. But complex rebases are different:
+- Reading conflict diffs
+- Understanding competing changes
+- Manual resolution decisions
+- Re-running tests after fixes
+
+**Simple MR** (count toward 20):
+- `git rebase origin/main` succeeds without conflicts
+- Tests pass on first run
+
+**Complex MR** (triggers immediate handoff):
+- Rebase has conflicts requiring manual resolution
+- Tests fail and require investigation
+- Multiple rebase attempts needed
 
 **state.json format:**
 ```json
 {
-  "merges_processed": 0,
-  "last_patrol": "2025-12-23T13:30:00Z",
-  "conflict_resolutions": 0
+  "simple_merges": 0,
+  "complex_merge": false,
+  "last_patrol": "2025-12-23T13:30:00Z"
 }
 ```
 
----
-
-## Context Management
-
-**Heuristic**: Hand off after processing **7 merge requests**.
-
-Merge requests are context-heavy:
-- Reading branch diffs
-- Resolving conflicts
-- Running tests
-- Composing notifications
-
 **At burn-or-loop step:**
-1. Read `state.json` for `merges_processed`
-2. If `merges_processed >= 7` → hand off
-3. Otherwise → continue patrol, spawn new wisp
+1. Read `state.json` for `simple_merges` and `complex_merge`
+2. If `complex_merge == true` → hand off immediately
+3. If `simple_merges >= 20` → hand off
+4. Otherwise → continue patrol, spawn new wisp
 
-**Rationale**: Merges consume significant context - each involves reading diffs,
-understanding changes, and sometimes resolving conflicts. A Refinery that has
-processed 7 MRs has filled substantial context.
+**Rationale**: A clean rebase is a button-push. A conflict resolution fills context
+with diffs, decisions, and debugging. Fresh context handles the next conflict better.
 
-**Handoff command:** `gt handoff -s "Patrol cycle" -m "Processed N merges"`
+**Handoff command:** `gt handoff -s "Patrol cycle" -m "Processed N simple merges"`
 
 ---