Edge Case Protocols — Gamepad-First Design
Status: Draft v1.0 Agent: sandshrew (via opencode) Timestamp: 2026-05-11 Platform: Anbernic RG40XXV — 640×480, D-pad + A/B/X/Y Game: Turn-based strategy, 36-hex grid, LangGraph-driven AI agent units
1. NODE PRODUCED INCOMPLETE OUTPUT
Trigger
Unit began work at a hex node but the LangGraph execution terminated before completion: timeout, LLM error, process interruption, or partial output with missing required sections.
What the Player Sees
┌──────────────────────────────────────────────────────────────┐
│ ⚠ INCOMPLETE OUTPUT Unit: HERON [3/4] │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Node: Hex 14 "Market Analysis" │ │
│ │ │ │
│ │ ✓ SUMMARY ...................................... │ │
│ │ ✓ FINDINGS ...................................... │ │
│ │ ✗ METHODOLOGY [─── MISSING ───] │ │
│ │ ✗ DATA TABLE [─── MISSING ───] │ │
│ │ ✓ CITATIONS ...................................... │ │
│ │ │ │
│ │ Error: timeout after 30s — LLM connection lost │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ▶ Retry (cost: 1⚡) │
│ Salvage partial output │
│ Skip node │
│ Mark as blocked │
│ │
│ [A:Select] [B:Preview] [X:ErrorLog] [Y:QuickRetry] │
└──────────────────────────────────────────────────────────────┘
Button Mapping
| Button | Action |
|---|---|
| D-pad ▲/▼ | Navigate decision options |
| A | Confirm selected option |
| B | Toggle between summary view and full partial output |
| X | Open error log / traceback (scrollable with D-pad, B to close) |
| Y | Quick Retry — skips menu, immediately retries (shortcut) |
State Changes
game_state.interrupts[].resolved = true
game_state.interrupt_type = null
IF retry:
unit_state[unit_id].energy -= 1
node_outputs[hex_id].status = "executing"
node_outputs[hex_id].attempt_count += 1
└─ triggers LangGraph re-execution
IF salvage:
node_outputs[hex_id].status = "salvaged"
node_outputs[hex_id].missing_sections = ["methodology", "data_table"]
game_state.backlog.append({hex_id, missing_sections, unit_id})
unit_state[unit_id].status = "moving"
IF skip:
node_outputs[hex_id].status = "skipped"
unit_state[unit_id].status = "moving"
unit_state[unit_id].path.pop(0) # remove this node from path
IF blocked:
node_outputs[hex_id].status = "blocked"
unit_state[unit_id].status = "idle"
game_state.blocked_nodes.append(hex_id)
Decision Tree
INCOMPLETE OUTPUT
│
├─ RETRY ─────────────────────────────────────────────────────
│ │ cost: 1⚡
│ │
│ ├─ SUCCESS → normal output review flow
│ │
│ └─ FAILURE AGAIN → escalate to "CRITICAL FAILURE"
│ │ node_outputs[hex_id].status = "critical_failure"
│ │
│ ├─ Force Retry (cost: 2⚡, higher timeout)
│ ├─ Salvage (as above)
│ ├─ Abandon (unit recalled, hex marked unreachable)
│ └─ Delegate (flag for another unit type to attempt)
│
├─ SALVAGE ───────────────────────────────────────────────────
│ Partial output accepted. Missing sections added to backlog.
│ Backlog visible from pause menu or end-of-turn summary.
│ Another unit can later fill missing sections via revisit (Case 5).
│
├─ SKIP ──────────────────────────────────────────────────────
│ Node marked skipped. Zero output stored.
│ Unit advances to next hex in path.
│ Skipped nodes can be revisited later.
│
└─ BLOCK ─────────────────────────────────────────────────────
Node marked blocked. Unit stays on hex.
Player must resolve from elsewhere (external resource,
another unit's context, or manual override).
Blocked nodes visible as red outline on main map.
2. NODE PRODUCED OUTPUT BUT UNIT IS STUCK
Trigger
Unit completed work at current hex but cannot path to its next destination. Causes: edge blocked by obstacle, prerequisite hex not yet completed by another unit, unit type incompatible with next node type, path cost exceeds remaining energy.
What the Player Sees
┌──────────────────────────────────────────────────────────────┐
│ ⛔ UNIT STUCK Unit: ACE [7/8] │
│ │
│ Current: Hex 21 ✓ Target: Hex 27 │
│ │
│ ┌─ Grid Preview (minimap) ──────────────────────────────┐ │
│ │ 21──22──23──24 │ │
│ │ ╲ ╱ ╲ ╱ ╲ │ │
│ │ 25──26══27 ◄══ BLOCKED EDGE │ │
│ │ ╱ ╲ ╱ ╲ ╱ Reason: Hex 26 not completed │ │
│ │ 28──29──30 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ Reason: Path blocked — Hex 26 must be completed first │
│ Alt path via 25→28→... cost: 4⚡ (unit has 3⚡) │
│ │
│ ▶ Reroute manually │
│ Auto-find alternate path (cost: 1⚡) │
│ Wait here (check next turn) │
│ Force through (cost: 2⚡, -1 integrity) │
│ Recall unit to base │
│ │
│ [A:Select] [B:Map] [X:Config] [Y:AutoPath] │
└──────────────────────────────────────────────────────────────┘
Button Mapping
| Button | Action |
|---|---|
| D-pad ▲/▼ | Navigate decision options |
| D-pad ◄/► | When "Reroute manually" selected: cycle through alternate hex targets |
| A | Confirm selected option |
| B | Full grid map mode — player uses D-pad to explore grid freely, A selects destination |
| X | View unit config: type, energy, special abilities, prerequisites needed |
| Y | Quick Auto-Find — immediately runs pathfinding (shortcut) |
State Changes
IF reroute:
game_state.mode = "path_select"
└─ player selects target hex on grid
└─ on confirm: unit_state[unit_id].path[] = new_path
└─ unit_state[unit_id].status = "moving"
IF auto_find:
unit_state[unit_id].energy -= 1
└─ A* search with unit constraints
└─ SUCCESS: unit_state[unit_id].path[] = found_path
└─ FAILURE: offer manual reroute or wait
└─ unit_state[unit_id].status = "moving" or "waiting"
IF wait:
unit_state[unit_id].status = "waiting"
unit_state[unit_id].wait_reason = "path_blocked"
game_state.waiting_units.append(unit_id)
└─ end-of-turn: check each waiting unit
└─ if blocker resolved: auto-proceed
└─ if still blocked: increment wait_count
IF force:
unit_state[unit_id].energy -= 2
unit_state[unit_id].integrity -= 1
hex_edges[blocked_edge].status = "bypassed"
unit_state[unit_id].path[] = direct_to_target
unit_state[unit_id].status = "moving"
IF recall:
unit_state[unit_id].position = null
unit_state[unit_id].status = "recalled"
game_state.available_units.append(unit_id)
game_state.units_on_grid.remove(unit_id)
Decision Tree
UNIT STUCK
│
├─ REROUTE MANUALLY ─────────────────────────────────────────
│ Player enters grid map mode:
│ 1. D-pad to navigate hex grid
│ 2. Valid targets pulse green; invalid targets gray
│ 3. Path cost shown on hover: "Via 25→28→... (3⚡)"
│ 4. A to confirm destination
│ 5. If path valid → new path set. If invalid → error beep.
│
├─ AUTO-FIND ────────────────────────────────────────────────
│ │ cost: 1⚡
│ │
│ ├─ PATH FOUND → displayed as dotted line on grid, cost shown
│ │ Player confirms (A) or rejects (B) and retries manually
│ │
│ └─ NO PATH FOUND → message "No valid path exists"
│ ├─ Wait (blockers may resolve)
│ ├─ Force (pay premium)
│ └─ Recall
│
├─ WAIT ─────────────────────────────────────────────────────
│ Unit stays on current hex. Status: "waiting (path_blocked)".
│ Each turn end: recheck edge conditions.
│ Max wait: 3 turns. After 3 turns of no resolution →
│ auto-escalate to force/recall prompt.
│
├─ FORCE THROUGH ────────────────────────────────────────────
│ │ cost: 2⚡ + -1 integrity
│ │ Bypassed edge marked with yellow outline on grid
│ │ If integrity drops to 0 → unit breaks, must be repaired at base
│ │
│ └─ Use sparingly. Forced edges can cause negative events.
│
└─ RECALL ────────────────────────────────────────────────────
Unit removed from grid entirely. Returns to base.
Can be redeployed next turn.
No penalty beyond lost turn.
3. PLAYER DISAGREES WITH OVERALL DIRECTION (RESTRUCTURE)
Trigger
Player reviews unit output and determines the entire approach is wrong — not fixable with line-item corrections. Unit needs a new directive to take a fundamentally different approach.
What the Player Sees
┌──────────────────────────────────────────────────────────────┐
│ 🔄 RESTRUCTURE Unit: HERON [3/4] │
│ │
│ Current output summary: │
│ "AI alignment risks analyzed through regulatory lens..." │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Choose new approach: │ │
│ │ │ │
│ │ ▶ [ANALYTICAL] Systematic breakdown, correctness │ │
│ │ [CREATIVE] Unconventional, novel angles │ │
│ │ [CONCISE] Shortest useful output │ │
│ │ [THOROUGH] Exhaustive, all edge cases │ │
│ │ [SKEPTICAL] Challenge assumptions, find gaps │ │
│ │ [SYNTHETIC] Cross-reference other nodes │ │
│ │ │ │
│ │ [X: Modifiers] [B: Keep current] │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ Restructure history: 2 previous attempts for this node │
│ │
│ [A:Select] [B:Cancel] [X:Modifiers] [Y:PrevAttempts] │
└──────────────────────────────────────────────────────────────┘
Modifier Sub-Screen (X button)
┌──────────────────────────────────────────────────────────────┐
│ + MODIFIERS Unit: HERON [3/4] │
│ │
│ ▶ Focus on: [security] [ethics] [long-term] [none] │
│ Constrain: [budget < $10M] [time < 6mo] [none] │
│ Ignore: [regulations] [competitors] [none] │
│ │
│ Focus keywords change based on neighboring nodes' topics │
│ │
│ [A:Toggle] [◄►:Cycle] [B:Done] │
└──────────────────────────────────────────────────────────────┘
Button Mapping
| Button | Action |
|---|---|
| D-pad ▲/▼ | Navigate approach archetypes |
| A | Select highlighted approach |
| B | Cancel — keep current output, dismiss |
| X | Open modifier sub-screen |
| Y | Cycle through previous restructure attempts for this node |
Modifier sub-screen: | Button | Action | |--------|--------| | D-pad ▲/▼ | Navigate modifier categories | | D-pad ◄/► | Cycle through options within category | | A | Toggle modifier on/off | | B | Confirm modifiers and return to approach selection |
State Changes
node_outputs[hex_id].restructure_count += 1
node_outputs[hex_id].approach_directive = {
archetype: "analytical" | "creative" | "concise" | "thorough" | "skeptical" | "synthetic",
modifiers: {
focus_on: ["security"],
constrain: ["budget < 10M"],
ignore: ["regulations"]
}
}
node_outputs[hex_id].status = "restructuring"
node_outputs[hex_id].previous_attempts[] = {
output: <prior_output>,
directive: <prior_directive>,
result: "rejected_by_player"
}
unit_state[unit_id].status = "rethinking"
IF energy spent on restructure:
unit_state[unit_id].energy -= 1
Decision Tree
RESTRUCTURE
│
├─ SELECT ARCHETYPE (no modifiers) ──────────────────────────
│ Directive written to node state.
│ Unit re-executes node with archetype as system prompt prefix.
│ Example prompt injection:
│ "APPROACH: ANALYTICAL. Break down systematically.
│ Prioritize rigor and correctness. Original task: ..."
│ Output replaces (or appends, player choice) previous output.
│
├─ SELECT ARCHETYPE + MODIFIERS ──────────────────────────────
│ Both folded into directive.
│ Example:
│ "APPROACH: SKEPTICAL. Challenge every assumption.
│ FOCUS ON: security. IGNORE: regulations.
│ Original task: ..."
│
├─ CANCEL ────────────────────────────────────────────────────
│ Unit keeps current output. Proceeds normally.
│ No state changes except interrupt resolved.
│
├─ AFTER RESTRUCTURE EXECUTION ───────────────────────────────
│ │
│ ├─ PLAYER ACCEPTS → normal flow, node completed
│ │
│ ├─ PLAYER STILL DISAGREES → increment restructure_count
│ │ │
│ │ ├─ restructure_count < 3 → offer restructure again
│ │ │
│ │ └─ restructure_count >= 3 → offer escalation:
│ │ ├─ Mark for human review (external, off-grid)
│ │ ├─ Delegate to different unit type
│ │ ├─ Accept best attempt and move on
│ │ └─ Skip node entirely
│ │
│ └─ PLAYER WANTS HYBRID → combine best parts of multiple attempts
│ (triggers a merge UI, D-pad to select sections from each attempt)
Archetype Definitions (injected into LangGraph prompt)
| Archetype | System Prompt Prefix |
|---|---|
| ANALYTICAL | "Take a systematic, step-by-step approach. Break the problem into components. Prioritize correctness and logical rigor. Number your steps." |
| CREATIVE | "Explore unconventional angles and novel connections. Prioritize originality and unexpected insights. Do not follow standard templates." |
| CONCISE | "Produce the shortest useful output. One paragraph summary, max 5 bullet points. Eliminate all redundancy." |
| THOROUGH | "Be exhaustive. Cover every edge case, every sub-topic, every implication. Prefer completeness over brevity." |
| SKEPTICAL | "Challenge every assumption in the given context. Identify weaknesses, gaps, and failure modes. Play devil's advocate." |
| SYNTHETIC | "Look for connections to other nodes' outputs. Combine and reconcile ideas from different sources. Seek unifying themes." |
4. TWO UNITS COLLIDE ON SAME HEX
Trigger
Two units attempt to enter the same hex coordinate in the same turn. Detected during movement phase resolution.
What the Player Sees
┌──────────────────────────────────────────────────────────────┐
│ ⚡ COLLISION — Hex 18 Turn 12 │
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ RANGER [Unit A] │ │ TRIDENT [Unit B] │ │
│ │ ⚡⚡⚡⚡⚡ 5/7 │ │ ⚡⚡⚡ 3/6 │ │
│ │ Priority: HIGH │ │ Priority: MEDIUM │ │
│ │ Arrived: 1st │ │ Arrived: 2nd │ │
│ │ Mission: Scout │ │ Mission: Survey │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
│ ╲ ╱ │
│ ╲ ⚡ ╱ ◄── Both targeting Hex 18 │
│ ╲ ╱ │
│ HEX 18 │
│ │
│ ▶ Ranger enters — Trident redirected │
│ Trident enters — Ranger redirected │
│ Coexist (both enter — compatible unit types) │
│ Ranger delays 1 turn │
│ Trident delays 1 turn │
│ │
│ [A:Confirm] [B:Auto] [X:Stats] [Y:SwapSelection] │
└──────────────────────────────────────────────────────────────┘
Button Mapping
| Button | Action |
|---|---|
| D-pad ▲/▼ | Navigate resolution options |
| D-pad ◄/► | Toggle preview: shows hex grid with proposed resolution outcome animated |
| A | Confirm selected resolution |
| B | Auto-resolve using priority rules |
| X | Toggle detailed stat view for selected unit |
| Y | Swap which unit is displayed as primary/secondary |
State Changes
game_state.collisions.append({
hex_id: 18,
turn: 12,
units: [unit_a_id, unit_b_id],
resolution: <chosen_option>,
timestamp: <game_clock>
})
IF unit A enters:
hexes[18].occupant = unit_a_id
unit_state[unit_a_id].position = 18
unit_state[unit_a_id].status = "working"
// Redirect Unit B
nearest_free = find_nearest_adjacent_hex(18)
unit_state[unit_b_id].position = nearest_free
unit_state[unit_b_id].energy -= 1 # redirect cost
unit_state[unit_b_id].status = "moving"
unit_state[unit_b_id].redirected = true
unit_state[unit_b_id].redirect_source = "collision_hex18"
IF coexist:
hexes[18].occupants = [unit_a_id, unit_b_id]
hexes[18].is_shared = true
unit_state[unit_a_id].position = 18
unit_state[unit_b_id].position = 18
// Both units work on same node — outputs may interact
node_outputs[18].collaborators = [unit_a_id, unit_b_id]
IF delay (e.g., Ranger delays):
unit_state[unit_a_id].status = "waiting"
unit_state[unit_a_id].wait_reason = "collision_delay"
unit_state[unit_a_id].resume_position = 18
unit_state[unit_b_id].position = 18
unit_state[unit_b_id].status = "working"
Auto-Resolve Priority Rules
1. Player-directed unit > AI-autonomous unit
2. Higher mission priority > lower
3. Higher remaining energy > lower
4. Earlier arrival in turn order > later
5. Higher unit level > lower
6. Random coin flip (if all equal)
Decision Tree
COLLISION DETECTED
│
├─ PRIORITY: UNIT A ENTERS ──────────────────────────────────
│ Unit B redirected to nearest adjacent unoccupied hex.
│ If no adjacent hex free: search radius 2 hexes.
│ If still no free hex (grid congested):
│ └─ Unit B forced to wait in place (no movement this turn)
│ status = "waiting_collision_overflow"
│ Auto-resolves next turn when grid opens
│
├─ COEXIST ───────────────────────────────────────────────────
│ │ Only available if: both units share a compatible type pair
│ │ Compatible pairs defined in unit_type_compatibility table:
│ │ SCOUT + SURVEY = compatible (survey needs scout data)
│ │ SUPPORT + any = compatible (support unit augments)
│ │ CARRIER + LIGHT = compatible (carrier transports light)
│ │ Same triad (LAND/SEA/AIR) = generally compatible
│ │
│ ├─ Compatible → both enter, shared hex
│ │ Output: if both produce output, they are merged
│ │ or stacked with labels [Unit A] [Unit B]
│ │
│ └─ Not compatible → option grayed out, tooltip shows why
│
├─ DELAY ─────────────────────────────────────────────────────
│ Selected unit stays at current position for 1 turn.
│ Status: "waiting (collision)".
│ On next turn: automatically attempts hex entry again.
│ If collision persists next turn (another unit beats it):
│ └─ Escalate to priority resolution with penalty:
│ delayed unit gets +1 priority boost per turn delayed
│
└─ AUTO-RESOLVE (B button) ─────────────────────────────────
System applies priority rules and selects resolution.
Result displayed for 2 seconds with "Auto: Ranger enters" message.
Player can override with B again within 2 seconds.
Redirect Logic Pseudocode
function resolve_collision(winner, loser, hex_id):
adjacent = get_ring(hex_id, radius=1) - occupied_hexes
if adjacent.not_empty:
loser.position = nearest(adjacent, loser.current)
loser.energy -= 1
else:
extended = get_ring(hex_id, radius=2) - occupied_hexes
if extended.not_empty:
loser.position = nearest(extended, loser.current)
loser.energy -= 2
else:
loser.status = "waiting_collision_overflow"
loser.stored_target = hex_id
5. UNIT NEEDS TO REVISIT A COMPLETED NODE
Trigger
Player discovers that a previously completed node should be re-examined. New context (another unit's output, a player insight, a game event) makes the original output incomplete, outdated, or contradictory.
What the Player Sees
Trigger From Context Review Screen
┌──────────────────────────────────────────────────────────────┐
│ 📋 UNIT OUTPUT — HEX 22 Unit: HERON [3/4] │
│ │
│ "Market segmentation shows 3 tiers... │
│ However, this contradicts Hex 14's finding that..." │
│ │
│ ┌─ Cross-Reference Alert ────────────────────────────────┐ │
│ │ ⚠ Hex 14 output conflicts with this finding. │ │
│ │ Hex 14 completed Turn 7 by ACE. │ │
│ │ │ │
│ │ [Y: Flag for Revisit] [◄►: See Hex 14 output] │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ [A:Accept] [B:Back] [X:Correct] [Y:FlagRevisit] │
└──────────────────────────────────────────────────────────────┘
Revisit Confirmation Modal
┌──────────────────────────────────────────────────────────────┐
│ 🔁 REVISIT HEX 14? Unit: RANGER [2/4] │
│ │
│ Original output (Turn 7, ACE): │
│ "Market is bifurcated into premium and budget tiers..." │
│ │
│ New context (Turn 12, HERON Hex 22): │
│ "Three distinct tiers identified: premium, mid, budget..." │
│ │
│ ┌─ Revisit Mode ─────────────────────────────────────────┐ │
│ │ │ │
│ │ ▶ APPEND — Add new output, keep original │ │
│ │ OVERWRITE — Replace entire output (old archived) │ │
│ │ │ │
│ │ Cost: 1⚡ | Distance from unit: 3 hexes │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ [A:Confirm] [B:Cancel] [X:FullOriginal] [Y:FullContext] │
└──────────────────────────────────────────────────────────────┘
Button Mapping (Review Screen)
| Button | Action |
|---|---|
| D-pad | Scroll output text |
| A | Accept output and proceed |
| B | Back to grid |
| X | Enter correction mode (for line-item corrections — not this case) |
| Y | Flag current cross-reference for revisit |
Button Mapping (Revisit Modal)
| Button | Action |
|---|---|
| D-pad ▲/▼ | Select mode: Append vs Overwrite |
| A | Confirm revisit with selected mode |
| B | Cancel revisit |
| X | View full original output (scrollable, B to close) |
| Y | View full new context that triggered the revisit |
State Changes
// Revisit queued
game_state.revisit_queue.append({
hex_id: 14,
reason: "conflict_with_hex_22",
source_unit: "HERON",
source_hex: 22,
turn_triggered: 12,
mode: "append" | "overwrite"
})
// Unit dispatched for revisit
unit_state[revisit_unit_id].status = "revisiting"
unit_state[revisit_unit_id].path[] = calculate_path(current, hex_id=14)
// After revisit execution
node_outputs[14].revision_count += 1
node_outputs[14].status = "revisited"
IF append:
node_outputs[14].appended_sections.append({
turn: 12,
source_unit: "RANGER",
trigger_context: "Hex 22 conflict",
content: <new_output>,
original_preserved: true
})
IF overwrite:
node_history[14].append({
turn: 7,
author: "ACE",
content: <old_output>,
overwritten_by: "RANGER",
overwrite_turn: 12
})
node_outputs[14].output = <new_output>
node_outputs[14].status = "completed_revised"
Decision Tree
REVISIT TRIGGERED
│
├─ APPEND MODE ──────────────────────────────────────────────
│ │
│ ├─ Unit routes to hex, executes with context injection:
│ │ "Previous finding: [old output]. New context: [new info].
│ │ Reconcile or extend. Do NOT repeat what was already found."
│ │
│ ├─ Output appended with header:
│ │ "═══ REVISITED: Turn 12 ═══
│ │ Source: Hex 22 (HERON)
│ │ Reason: Contradiction in market tier count
│ │ ═══════════════════════════"
│ │
│ └─ Node stays marked "completed" with revision badge
│ Display: Hex 14 [✓²] — checkmark with superscript revision count
│
├─ OVERWRITE MODE ───────────────────────────────────────────
│ │
│ ├─ Old output archived to node_history.
│ │
│ ├─ Unit executes fresh, with full new context.
│ │ System prompt: "This node was previously completed
│ │ but is being revised. New directive: [new context].
│ │ Produce a complete replacement output."
│ │
│ └─ Node status → "completed_revised"
│ Display: Hex 14 [↻] — circular arrow icon
│
├─ CANCEL ───────────────────────────────────────────────────
│ Revisit flag removed from queue.
│ No state changes. Player can revisit later manually.
│
└─ UNIT CAN'T PATH TO HEX ───────────────────────────────────
Triggers Edge Case 2 (stuck protocol).
Player can assign a different unit that's closer.
Revisit Queue UI (Pause Menu > Revisit Queue)
┌──────────────────────────────────────────────────────────────┐
│ 🔁 REVISIT QUEUE 1 pending │
│ │
│ ▶ Hex 14 "Market Analysis" │
│ Conflict with Hex 22. Triggered Turn 12. │
│ Assign unit: [RANGER] [HERON] [any available] │
│ │
│ [A:Assign] [B:Back] [X:Remove] [Y:ViewContext] │
└──────────────────────────────────────────────────────────────┘
6. CONTEXT ROUTING FAILS
Trigger
The curation agent (which routes relevant context from one unit's output to another unit's node) produces nothing useful. Either: no relevant context found, context is too vague, pointer destination is invalid, or context is empty after filtering.
What the Player Sees
┌──────────────────────────────────────────────────────────────┐
│ 📡 ROUTING FAILURE Unit: TRIDENT [5/6] │
│ │
│ Source: Hex 14 (HERON) ──✕── ? │
│ │
│ ┌─ Failure Details ──────────────────────────────────────┐ │
│ │ │ │
│ │ Agent: CURATOR v2.1 │ │
│ │ Error: No relevant context found │ │
│ │ │ │
│ │ Raw output: "The market analysis from Hex 14 does not │ │
│ │ contain information relevant to the technical │ │
│ │ architecture task at Hex 22." │ │
│ │ │ │
│ │ Filter threshold: 0.6 | Results returned: 0 │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ▶ Route manually (pick destination) │
│ Broaden search (cost: 1⚡) │
│ Store as orphan context │
│ Discard — proceed without routing │
│ Apply to self (TRIDENT gains insight) │
│ │
│ [A:Select] [B:Dismiss] [X:RawOutput] [Y:ManualRoute] │
└──────────────────────────────────────────────────────────────┘
Button Mapping
| Button | Action |
|---|---|
| D-pad ▲/▼ | Navigate options |
| A | Confirm selected option |
| B | Dismiss — leave unit idle, routing unresolved (can revisit) |
| X | View full raw curation agent output (scrollable, B to close) |
| Y | Quick manual route — immediately enter grid selection mode |
State Changes
curation_state[unit_id].status = "failed"
curation_state[unit_id].failure_count += 1
curation_state[unit_id].last_failure = {
turn: <current>,
source_hex: 14,
reason: "no_relevant_context",
raw_output: <curator_response>,
threshold: 0.6,
results_count: 0
}
IF manual_route:
game_state.mode = "manual_routing"
└─ player selects hex on grid
└─ context_routes.append({from: 14, to: <selected>, context: <payload>})
IF broaden_search:
unit_state[unit_id].energy -= 1
curation_state[unit_id].search_params.threshold -= 0.2
curation_state[unit_id].search_params.k += 3
└─ re-run curation with relaxed params
└─ if still fails → escalate
IF store_orphan:
game_state.orphan_contexts.append({
source_hex: 14,
source_unit: "HERON",
context_payload: <output_summary>,
created_turn: <current>,
tags: ["market", "analysis"],
status: "unrouted"
})
IF discard:
curation_state[unit_id].status = "skipped"
unit_state[unit_id].status = "working" # proceeds without routing
IF self_apply:
unit_state[unit_id].insight_tokens += 1
unit_state[unit_id].status = "integrating"
curation_state[unit_id].status = "self_applied"
Decision Tree
ROUTING FAILURE
│
├─ ROUTE MANUALLY ──────────────────────────────────────────
│ │
│ ├─ Grid map mode: valid hexes pulse blue, invalid gray
│ │ Tooltip on hover: "Hex 18: Technical Design (ACE)"
│ │
│ ├─ Player selects destination hex
│ │ │
│ │ ├─ HEX EXISTS AND IS VALID → context routed.
│ │ │ Unit proceeds. Route logged.
│ │ │
│ │ └─ HEX IS INVALID (unreachable, wrong type) →
│ │ error beep + brief reason. Retry selection.
│ │
│ └─ Player presses B → back to options
│
├─ BROADEN SEARCH ──────────────────────────────────────────
│ │ cost: 1⚡
│ │ Curation agent re-runs with:
│ │ threshold -= 0.2 (more permissive)
│ │ k += 3 (more results)
│ │
│ ├─ RESULTS FOUND → display top 3 destinations
│ │ Player picks one (D-pad + A) or selects "none of these"
│ │
│ └─ STILL NO RESULTS → escalate:
│ curation_state[unit_id].status = "degraded"
│ │
│ ├─ Force route (player picks any hex, context routed
│ │ even if irrelevant — flagged "low_confidence")
│ │
│ ├─ Store as orphan (see below)
│ │
│ └─ Discard (see below)
│
├─ STORE AS ORPHAN ─────────────────────────────────────────
│ Context saved with metadata.
│ Viewable from: Pause Menu > Dangling Contexts
│ Orphan contexts list:
│ ┌─────────────────────────────────────────────────────┐
│ │ 🧩 DANGLING CONTEXTS 2 total │
│ │ │
│ │ ▶ Hex 14→? "Market tiers" Turn 12 [Route] │
│ │ Hex 8→? "SWOT analysis" Turn 9 [Route] │
│ │ │
│ │ [A:Route] [X:View] [Y:Discard] [B:Back] │
│ └─────────────────────────────────────────────────────┘
│ Player can route orphan contexts at any time.
│ Max orphans: 10. Exceeding → oldest auto-discarded.
│
├─ DISCARD ─────────────────────────────────────────────────
│ Context discarded. Unit proceeds as if no routing needed.
│ curation_state[unit_id].status = "skipped"
│ No penalty. But lost opportunity for cross-pollination.
│
└─ APPLY TO SELF ──────────────────────────────────────────
Context absorbed by current unit instead of routed.
Unit gains +1 insight_token (temporary stat boost).
Effect: next output gets quality bonus.
Useful when no destination makes sense but context is valuable.
7. SAVE/LOAD WITH ACTIVE INTERRUPTS
Trigger
Player saves the game while one or more interrupts are active (units paused, waiting for player decisions from Cases 1-6). On reload, the game must resume exactly at the interrupt point with full context.
What the Player Sees
Save Screen (with active interrupts)
┌──────────────────────────────────────────────────────────────┐
│ 💾 SAVE GAME Turn 14 │
│ │
│ ⚠ 2 ACTIVE INTERRUPTS — will be saved with game state │
│ │
│ ┌─ Interrupt Queue ──────────────────────────────────────┐ │
│ │ 1. HERON - Incomplete Output (Hex 8) [awaiting] │ │
│ │ 2. ACE - Collision Resolution (Hex 18) [awaiting] │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ▶ Slot 1: Turn 14 — Hex 8/36 — 3 units active [!2] │
│ Slot 2: Turn 12 — Hex 6/36 — 2 units active │
│ Slot 3: Turn 8 — Hex 4/36 — 2 units active │
│ Slot 4: EMPTY │
│ │
│ [A:Save] [B:Back] [X:Details] │
└──────────────────────────────────────────────────────────────┘
Load Screen
┌──────────────────────────────────────────────────────────────┐
│ 📂 LOAD GAME │
│ │
│ ▶ Slot 1: Turn 14 — 3 units — [!] 2 interrupts │
│ Slot 2: Turn 12 — 2 units │
│ Slot 3: Turn 8 — 2 units │
│ Slot 4: EMPTY │
│ │
│ [A:Load] [B:Back] [X:SlotDetails] [Y:Delete] │
└──────────────────────────────────────────────────────────────┘
Load Splash / Resume
┌──────────────────────────────────────────────────────────────┐
│ │
│ │
│ ═══════════════════════════ │
│ TURN 14 — RESUMING │
│ ═══════════════════════════ │
│ │
│ ░░░░ Loading grid... ░░░░ │
│ ░░░░ Restoring units... ░░░░ │
│ ░░░░ Resolving interrupt queue... ░░░░ │
│ │
│ [!] 2 pending decisions │
│ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Camera pans to: HERON @ Hex 8 │ │
│ │ Interrupt: INCOMPLETE OUTPUT │ │
│ │ (Press A to begin / B to overview map) │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
Resuming the Interrupt (identical to original interrupt UI)
┌──────────────────────────────────────────────────────────────┐
│ ⚠ INCOMPLETE OUTPUT Interrupt 1/2 Unit: HERON │
│ │
│ [Same UI as Case 1 — fully restored state] │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Node: Hex 8 "Competitor Analysis" │ │
│ │ │ │
│ │ ✓ EXECUTIVE SUMMARY .................................. │ │
│ │ ✗ COMPETITOR MATRIX [─── MISSING ───] │ │
│ │ ✗ THREAT ASSESSMENT [─── MISSING ───] │ │
│ │ │ │
│ │ Error: LLM timeout after 30s │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ [A:Select] [B:Preview] [X:ErrorLog] [Y:Context] │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ [!] 1 more interrupt after this one │
│ (B for map overview / skip to next) │
└──────────────────────────────────────────────────────────────┘
HUD Elements During Interrupt Resolution
┌──────────────────────────────────────────────────────────────┐
│ Turn 14 [!2] ⚡12/18 🏴3 units │
│ │
│ [Main game area / interrupt modal] │
│ │
└──────────────────────────────────────────────────────────────┘
The [!2] badge in the HUD shows remaining unresolved interrupts. Pulses gently when all interrupts resolved to signal "ready to advance turn."
Button Mapping (Save Screen)
| Button | Action |
|---|---|
| D-pad ▲/▼ | Select save slot |
| A | Save to selected slot |
| B | Back to game |
| X | View slot details: turn, hex progress, unit count |
Button Mapping (Load Screen)
| Button | Action |
|---|---|
| D-pad ▲/▼ | Select save slot |
| A | Load selected slot |
| B | Back to title |
| X | View slot details |
| Y | Delete selected slot (with confirmation prompt) |
Button Mapping (Resume Interrupt — same as original + one addition)
Same as the original edge case's button mapping, plus:
| Button | Action |
|---|---|
| Y | Toggle context recap — shows "What happened before this interrupt" summary for memory refresh |
Context Recap Screen (Y during interrupt resume)
┌──────────────────────────────────────────────────────────────┐
│ 📋 SESSION RECAP Turn 14, Hex 8 │
│ │
│ ┌─ What happened this turn ──────────────────────────────┐ │
│ │ │ │
│ │ • HERON moved Hex 5→Hex 8, began "Competitor Analysis" │ │
│ │ • ACE completed Hex 12, output routed to RANGER │ │
│ │ • RANGER moved Hex 10→Hex 14 │ │
│ │ • CURATOR attempted routing Hex 14→Hex 22 (failed) │ │
│ │ │ │
│ │ ═══════════════════════════════════════════════════════ │ │
│ │ │ │
│ │ • Hex 8: HERON started Competitor Analysis │ │
│ │ └─ TIMEOUT after 30s. Now awaiting your decision. │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ [B:Close] [D-pad:Scroll] │
└──────────────────────────────────────────────────────────────┘
State Changes (Save)
save_data = {
version: "1.0",
turn: 14,
timestamp: <iso8601>,
// Full game state snapshot
game_state: { ...entire_game_state },
unit_states: { ...all_unit_states },
node_outputs: { ...all_node_outputs },
hexes: { ...all_hex_states },
curation_state: { ...all_curation_states },
// INTERRUPT STACK — critical for resume
interrupt_stack: [
{
interrupt_id: "int_001",
interrupt_type: "incomplete_output", // matches Case 1-6
unit_id: "HERON",
hex_id: 8,
turn_triggered: 14,
// Full UI state restoration
ui_state: {
modal_type: "incomplete_output",
selected_option_index: 0, // which option was highlighted
scroll_position: 0, // if output was scrolled
subview: null, // if modifier screen / detail view was open
preview_open: false // B-toggled preview state
},
// Case-specific payload
payload: {
completed_sections: ["executive_summary"],
missing_sections: ["competitor_matrix", "threat_assessment"],
error_type: "timeout",
error_detail: "LLM connection lost after 30s",
attempt_count: 1,
output_so_far: <partial_output_text>
}
},
{
interrupt_id: "int_002",
interrupt_type: "collision",
unit_id: "ACE",
hex_id: 18,
turn_triggered: 14,
ui_state: { ... },
payload: {
colliding_units: ["ACE", "TRIDENT"],
unit_a_stats: { ... },
unit_b_stats: { ... }
}
}
],
// For save slot display
interrupt_count: 2,
units_active: 3,
hexes_completed: 8,
total_hexes: 36
}
State Changes (Load)
// 1. Restore game state
game_state ← save_data.game_state
unit_states ← save_data.unit_states
node_outputs ← save_data.node_outputs
hexes ← save_data.hexes
curation_state ← save_data.curation_state
// 2. Restore interrupt stack
interrupt_stack ← save_data.interrupt_stack
// 3. If interrupt stack is non-empty:
game_state.mode = "interrupt_resolution"
current_interrupt ← interrupt_stack[0]
// 4. Restore UI to exact saved state
ui.modal_type = current_interrupt.ui_state.modal_type
ui.selected_option_index = current_interrupt.ui_state.selected_option_index
ui.scroll_position = current_interrupt.ui_state.scroll_position
ui.subview = current_interrupt.ui_state.subview
// 5. Camera pan to interrupt unit's hex
camera.target = hexes[current_interrupt.hex_id].position
camera.animate(1.5s)
// 6. Display interrupt resolution UI
Decision Tree
SAVE WITH ACTIVE INTERRUPTS
│
├─ Interrupts serialized in interrupt_stack exactly as-is
│ Save file tagged with interrupt_count
│ Save slot shows [!N] badge
│
└─ No special handling needed — interrupts are just state
LOAD WITH ACTIVE INTERRUPTS
│
├─ NO INTERRUPTS → normal load, game resumes in default state
│
├─ INTERRUPTS PRESENT → enter "interrupt resolution mode"
│ │
│ ├─ CAMERA PANS to first interrupted unit
│ ├─ INTERRUPT MODAL appears exactly as saved
│ ├─ PLAYER RESOLVES first interrupt
│ │ │
│ │ ├─ Resolution may spawn NEW interrupts → added to end of stack
│ │ └─ interrupt_stack.shift() — remove resolved interrupt
│ │
│ ├─ IF MORE INTERRUPTS → camera pans to next
│ │ "Interrupt 2/2" indicator updates
│ │
│ └─ STACK EMPTY → game_state.mode = "normal"
│ "Ready to advance" message + turn advance button enabled
│
├─ PLAYER WANTS MAP OVERVIEW (B during interrupt) ───────────
│ Interrupt stays queued. Player can:
│ • Browse full grid, read other nodes' outputs
│ • Check unit states, energy, paths
│ • Cannot advance turn until interrupts resolved
│ • "Resolve Interrupts" prompt remains in HUD
│ • Press Y to jump back to current interrupt
│
└─ CRASH DURING INTERRUPT ───────────────────────────────────
Auto-save triggered on every interrupt spawn.
On next load: last autosave with interrupt stack intact.
Autosave file: separate slot, marked "[AUTO] Turn 14 — [!2]"
Max 3 autosave slots, rotating.
CROSS-CUTTING CONCERNS
Interrupt Priority Order
When multiple interrupts are queued, they resolve in this order:
- Collisions (Case 4) — resolve first, they affect unit positions
- Stuck Units (Case 2) — resolve before units can move
- Incomplete Output (Case 1) — resolve before output can be used
- Routing Failures (Case 6) — resolve before context can flow
- Restructure (Case 3) — unit can't proceed until approach settled
- Revisit Queue (Case 5) — lowest priority, can be deferred
This order ensures dependencies are resolved: positions → movement → output → routing → quality.
Energy Economy
| Action | Energy Cost |
|---|---|
| Retry (Case 1) | 1⚡ |
| Auto-find path (Case 2) | 1⚡ |
| Force through (Case 2) | 2⚡ + -1 integrity |
| Restructure (Case 3) | 1⚡ |
| Redirect from collision (Case 4) | 1-2⚡ (based on distance) |
| Revisit node (Case 5) | 1⚡ + travel |
| Broaden search (Case 6) | 1⚡ |
| Recall unit (Case 2) | 0⚡ (lost turn only) |
| Self-apply context (Case 6) | 0⚡ (gain instead) |
| Skip node (Case 1) | 0⚡ |
Visual Language Conventions
| Symbol | Meaning |
|---|---|
| ⚠ | Incomplete/warning |
| ⛔ | Blocked/stuck |
| 🔄 | Restructure |
| ⚡ | Collision / Energy |
| 🔁 | Revisit |
| 📡 | Routing |
| 💾 | Save |
| [!N] | N pending interrupts |
| [✓] | Completed node |
| [✓²] | Completed node with revisions |
| [↻] | Revised (overwritten) node |
| [✗] | Skipped node |
| [🚫] | Blocked node |
LangGraph State Key Reference
game_state
├── mode: "normal" | "interrupt_resolution" | "path_select" | "manual_routing"
├── turn: int
├── interrupts[]: list of pending interrupt references
├── interrupt_stack[]: serialized interrupt states (for save/load)
├── collisions[]: collision event log
├── routing_failures[]: routing failure log
├── blocked_nodes[]: hex ids of blocked nodes
├── blocked_edges[]: edge ids of blocked edges
├── waiting_units[]: unit ids waiting on conditions
├── revisit_queue[]: pending revisit tasks
├── orphan_contexts[]: unrouted context payloads
├── available_units[]: recalled idle units
└── backlog[]: incomplete sections needing attention
unit_state[unit_id]
├── position: hex_id | null
├── status: "idle" | "moving" | "working" | "waiting" | "rethinking"
│ | "revisiting" | "recalled" | "integrating"
├── energy: int
├── integrity: int
├── insight_tokens: int
├── path[]: hex_id sequence
├── redirected: bool
├── redirect_source: string
├── wait_reason: string
└── resume_position: hex_id
node_outputs[hex_id]
├── status: "empty" | "executing" | "completed" | "salvaged" | "skipped"
│ | "blocked" | "restructuring" | "revisiting" | "completed_revised"
│ | "critical_failure"
├── output: string
├── missing_sections: string[]
├── attempt_count: int
├── restructure_count: int
├── revision_count: int
├── approach_directive: {archetype, modifiers}
├── previous_attempts[]: {output, directive, result}
├── appended_sections[]: {turn, source_unit, content}
├── collaborators: unit_id[]
└── status (legacy, use top-level status)
node_history[hex_id][]
├── turn: int
├── author: unit_id
├── content: string
├── overwritten_by: unit_id
└── overwrite_turn: int
curation_state[unit_id]
├── status: "idle" | "running" | "completed" | "failed" | "degraded"
│ | "skipped" | "self_applied"
├── failure_count: int
├── search_params: {threshold, k}
└── last_failure: {turn, source_hex, reason, raw_output}
save_data
├── version: string
├── turn: int
├── timestamp: iso8601
├── game_state: {...}
├── unit_states: {...}
├── node_outputs: {...}
├── hexes: {...}
├── curation_state: {...}
├── interrupt_stack: [{interrupt_id, type, unit_id, hex_id, ui_state, payload}]
└── interrupt_count: int
IMPLEMENTATION NOTES
Interrupt Dispatch Pattern
When any edge case trigger fires:
function trigger_interrupt(type, unit_id, hex_id, payload):
interrupt = {
interrupt_id: generate_id(),
interrupt_type: type,
unit_id: unit_id,
hex_id: hex_id,
turn_triggered: game_state.turn,
ui_state: capture_ui_state(),
payload: payload
}
game_state.interrupt_stack.push(interrupt)
game_state.mode = "interrupt_resolution"
// Autosave on interrupt trigger
autosave()
// Camera pan to affected hex
camera.pan_to(hexes[hex_id].position)
// Render appropriate modal based on interrupt_type
render_interrupt_modal(interrupt)
Controller Input Buffer
During interrupt resolution, all non-interrupt inputs are buffered: - Turn advance button (Start) is disabled - Unit selection is disabled (except for map overview mode) - Only interrupt modal inputs + map overview (B) are processed
Accessibility
- Hold B for 1 second on any interrupt modal → reads option text aloud (if audio system available)
- Color-coded modal borders: Red=blocking, Yellow=warning, Blue=info
- Option highlighted with both color shift AND left-margin arrow indicator (▶)
- Pulse animation on the selected option (1Hz) for visibility
Document version 1.0. Sandshrew via opencode. Last updated: 2026-05-11. Target container: d3-tui-pi-teams-proto @ /workcell/llm-wiki/wiki/research/edge-case-protocols.md