reasoning-handover-protocol

What this skill does

# 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

---

## Part 1: Directory Structure Specification

### 1.1 Root Directory: `.reasoning/`

The `.reasoning/` directory serves as the persistent workspace for cognitive reasoning sessions. It maintains session state, handover files, and evidence chains across pattern transitions.

```
.reasoning/
├── sessions/
│   └── session-{uuid}/
│       ├── manifest.json              # Session metadata and state
│       ├── pattern-state/             # Per-pattern working state
│       │   ├── tot/
│       │   │   ├── state.json         # ToT-specific state
│       │   │   └── branches/          # Branch exploration data
│       │   ├── bot/
│       │   │   ├── state.json         # BoT-specific state
│       │   │   └── approaches/        # Approach exploration data
│       │   ├── he/
│       │   │   ├── state.json         # HE-specific state
│       │   │   └── hypotheses/        # Hypothesis tracking
│       │   └── {pattern}/             # Other patterns follow same structure
│       ├── handovers/                 # Pattern-to-pattern handover records
│       │   └── {sequence}-{from}-to-{to}.json
│       ├── checkpoints/               # Mid-reasoning save points
│       │   └── checkpoint-{timestamp}.json
│       ├── evidence/                  # Shared evidence repository
│       │   ├── gathered/              # Evidence files
│       │   └── index.json             # Evidence registry
│       └── synthesis/                 # Final outputs
│           └── conclusion-{timestamp}.json
├── templates/                         # Reusable handover templates
│   └── {pattern}-handover-template.json
└── 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.

```json
{
  "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:

```json
{
  "$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:

```json
{
  "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:

```json
{
  "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"
    }
  }