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"` ---