reasoning-handover-protocol

name	reasoning-handover-protocol
description	Protocol for cognitive pattern handovers during complex reasoning sessions. Defines .reasoning/ directory structure, handover schemas, and IR-v2 orchestration integration. Use when reasoning sessions require mid-stream pattern transitions, parallel branch merging, state checkpointing, or multi-pattern orchestration. Essential for complex problems where ToT, BoT, HE, or other patterns must hand off work to each other.
model	inherit
license	MIT
user-invocable	false

Reasoning Handover Protocol

Purpose: Standardized protocol for preserving and transferring cognitive state between reasoning patterns during complex analysis sessions. Enables seamless handovers between ToT, BoT, SRC, HE, AR, DR, AT, RTR, and NDF patterns while maintaining evidence chains, confidence scores, and exploration history.

When to Use This Protocol

Use the Reasoning Handover Protocol when:

• IR-v2 orchestrator transitions between patterns mid-session
• Parallel reasoning branches need to merge results
• Long-running analysis requires checkpointing
• Multiple patterns collaborate on the same problem
• Sessions need to be paused and resumed
• Post-hoc audit of reasoning process is required

Do not use when:

• Single-pattern analysis is sufficient
• Analysis completes within one interaction
• No state preservation needed

Note: Forked skills (context: fork) now handle isolation automatically. When a skill runs with context: fork, it gets its own context without polluting the parent session, reducing the need for manual .reasoning/ directory management in simple handover scenarios.

---

Part 1: Directory Structure Specification

1.1 Root Directory: .reasoning/

The .reasoning/ directory serves as the persistent workspace for cognitive reasoning sessions. In practice, most handovers use the simplified structure below. The full structure is available for complex multi-day sessions.

.reasoning/
├── sessions/
│   └── session-{uuid}/
│       ├── manifest.json              # Session metadata and state
│       ├── pattern-state/             # Per-pattern working state (subdirs per pattern)
│       ├── handovers/                 # Pattern-to-pattern handover records
│       ├── checkpoints/               # Mid-reasoning save points
│       ├── evidence/                  # Shared evidence repository
│       └── synthesis/                 # Final outputs
├── templates/                         # Reusable handover templates
└── config.json                        # Global configuration

1.2 Session Directory: session-{uuid}/

Each reasoning session gets a unique directory identified by UUID.

Session UUID Format: YYYYMMDD-HHMMSS-{random8} Example: 20260118-143052-a7b3c9d2

Directory Lifecycle:

1. Created: When IR-v2 orchestrator initiates multi-pattern analysis
2. Active: During reasoning (state updated continuously)
3. Completed: When synthesis finalized
4. Archived: After 30 days (move to .reasoning/archive/)

1.3 Manifest File: manifest.json

The manifest tracks session-level metadata and current state.

{
  "session_id": "20260118-143052-a7b3c9d2",
  "created_at": "2026-01-18T14:30:52Z",
  "last_updated": "2026-01-18T15:45:23Z",
  "status": "active|completed|paused|failed",

  "problem": {
    "statement": "Design authentication system for multi-tenant SaaS",
    "constraints": ["SOC2 compliance", "< 100ms latency", "10M users"],
    "success_criteria": ["Security validated", "Performance tested", "Cost acceptable"]
  },

  "orchestration": {
    "strategy": "sequential|parallel|nested",
    "planned_patterns": ["BoT", "ToT", "AR"],
    "current_pattern": "ToT",
    "pattern_history": [
      {"pattern": "BoT", "started": "...", "completed": "...", "handover_to": "ToT"}
    ]
  },

  "dimensions": {
    "sequential_dependencies": 2,
    "criteria_clarity": 4,
    "solution_space_known": 3,
    "single_answer_needed": 4,
    "evidence_available": 3,
    "opposing_valid_views": 3,
    "problem_novelty": 3,
    "robustness_required": 5,
    "solution_exists": 2,
    "time_pressure": 2,
    "stakeholder_complexity": 2
  },

  "confidence": {
    "overall": 0.72,
    "by_pattern": {
      "BoT": 0.75,
      "ToT": 0.78
    }
  },

  "checkpoints": ["checkpoint-20260118-150000.json"],
  "active_handover": null
}

---

Part 2: Handover Schema Specification

2.1 Universal Handover Format

All pattern-to-pattern handovers follow this base schema:

{
  "$schema": "reasoning-handover-v1",
  "handover_id": "003-bot-to-tot",
  "timestamp": "2026-01-18T15:00:00Z",

  "source_pattern": {
    "name": "BoT",
    "version": "1.0",
    "session_state_path": "./pattern-state/bot/state.json"
  },

  "target_pattern": {
    "name": "ToT",
    "version": "1.0",
    "recommended_entry_point": "step-3-evaluation"
  },

  "context_transfer": {
    "problem_understanding": "...",
    "constraints_identified": ["..."],
    "assumptions_made": ["..."]
  },

  "deliverables": {
    "type": "approaches|branches|hypotheses|synthesis",
    "items": [],
    "confidence_scores": {}
  },

  "evidence_chain": {
    "sources_used": ["..."],
    "key_findings": ["..."],
    "reference_paths": ["./evidence/gathered/..."]
  },

  "recommendations": {
    "focus_areas": ["..."],
    "avoid_areas": ["..."],
    "open_questions": ["..."]
  },

  "metadata": {
    "duration_minutes": 25,
    "branches_explored": 8,
    "branches_retained": 5,
    "confidence_at_handover": 0.75
  }
}

2.2 Pattern-Specific Handover Extensions

BoT (Breadth of Thought) Handover

When BoT hands off to another pattern:

{
  "bot_specific": {
    "exploration_summary": {
      "level_0_approaches": 8,
      "level_1_subapproaches": 32,
      "total_explored": 40,
      "retained_above_40pct": 18
    },

    "approach_registry": [
      {
        "id": "approach-1",
        "name": "Write-through caching",
        "level": 0,
        "confidence": 0.72,
        "status": "retained",
        "strengths": ["..."],
        "weaknesses": ["..."],
        "best_for": "Strong consistency requirements",
        "subapproaches": ["1.1", "1.2", "1.3"]
      }
    ],

    "pruned_approaches": [
      {
        "id": "approach-6",
        "name": "Blockchain-based cache",
        "pruned_reason": "Complexity exceeds benefit, confidence 28%",
        "pruned_at": "level-0"
      }
    ],

    "top_5_viable": ["approach-2", "approach-1", "approach-4", "approach-3", "approach-7"],

    "handover_recommendation": {
      "to_tot": "Evaluate top 3 approaches against defined criteria",
      "to_he": "If problem is diagnosis, use approaches as hypothesis set",
      "to_ar": "Validate top approach before implementation"
    }
  }
}

ToT (Tree of Thoughts) Handover

When ToT hands off to another pattern:

{
  "tot_specific": {
    "tree_structure": {
      "total_levels": 4,
      "branches_per_level": [5, 5, 5, 5],
      "winning_path": ["branch-2", "branch-2.3", "branch-2.3.4", "branch-2.3.4.2"]
    },

    "branch_scores": {
      "branch-2": {
        "novelty": 18,
        "feasibility": 19,
        "completeness": 17,
        "confidence": 18,
        "alignment": 19,
        "total": 91
      }
    },

    "winning_solution": {
      "path": "L0:Eventual-consistency > L1:CRDTs > L2:OR-Set > L3:Tombstone-compaction",
      "final_score": 91,
      "confidence": 0.88,
      "key_insight": "CRDTs provide eventual consistency without coordination overhead"
    },

    "alternatives_considered": [
      {
        "path": "L0:Write-through > L1:Redis-cluster",
        "final_score": 78,
        "why_not_selected": "Latency requirements not met under load"
      }
    ],

    "handover_recommendation": {
      "to_ar": "Validate CRDT approach against adversarial scenarios",
      "to_src": "Trace implementation steps for CRDT integration",
      "to_he": "If issues arise, use pruned branches as hypothesis set"
    }
  }
}

HE (Hypothesis-Elimination) Handover

When HE hands off to another pattern:

{
  "he_specific": {
    "hypothesis_registry": [
      {
        "id": "H1",
        "name": "Memory leak in connection pool",
        "initial_probability": 0.3,
        "current_probability": 0.05,
        "status": "eliminated",
        "eliminated_by": "evidence-003",
        "elimination_reason": "Memory stable at 2GB, no growth over 4 hours"
      },
      {
        "id": "H3",
        "name": "Slow external API response",
        "initial_probability": 0.2,
        "current_probability": 0.85,
        "status": "confirmed",
        "confirmed_by": ["evidence-005", "evidence-007"],
        "mechanism": "Payment gateway P99 latency increased from 50ms to 800ms"
      }
    ],

    "evidence_chain": [
      {
        "id": "evidence-001",
        "type": "log_analysis",
        "source": "application-logs",
        "finding": "No OOM errors in last 24h",
        "hypotheses_affected": {
          "H1": "eliminated",
          "H2": "unchanged"
        }
      }
    ],

    "elimination_path": {
      "started_with": 12,
      "remaining": 1,
      "elimination_sequence": ["H1", "H5", "H2", "H8", "H4", "H6", "H7", "H9", "H10", "H11", "H12"]
    },

    "root_cause": {
      "hypothesis": "H3",
      "confidence": 0.85,
      "mechanism": "External payment API degradation causing request queuing",
      "confirmation_test": "Timeout reduction test showed immediate improvement"
    },

    "handover_recommendation": {
      "to_tot": "Evaluate mitigation options for external API dependency",
      "to_ar": "Stress-test proposed timeout configuration",
      "to_src": "Trace exact failure path through code"
    }
  }
}

SRC (Self-Reflecting Chain) Handover

When SRC hands off to another pattern:

{
  "src_specific": {
    "chain_trace": [
      {
        "step": 1,
        "action": "Trace user click to event handler",
        "result": "Event handler found in UserSubmit.tsx:45",
        "confidence": 0.92,
        "dependencies": [],
        "backtracked": false
      },
      {
        "step": 2,
        "action": "Analyze event handler logic",
        "result": "Handler calls validateForm() then submitToAPI()",
        "confidence": 0.88,
        "dependencies": ["step-1"],
        "backtracked": false
      },
      {
        "step": 3,
        "action": "Check validateForm() return value",
        "result": "Validation passes, returns true",
        "confidence": 0.45,
        "dependencies": ["step-2"],
        "backtracked": true,
        "backtrack_reason": "Assumption about validation logic was wrong"
      },
      {