# Session Analysis Run — 2026-02-09

## Context

QuickCall ingests AI coding sessions from 4 CLI tools. We have 34 sample Codex CLI sessions from developer Nikhil (Jan 28-31, cold-ranker ML project). Goal: produce a **weekly developer retrospective** that creates an "aha moment" — backed by actual evidence from sessions.

Per mentor feedback: frame as self-improvement, not surveillance. Every insight MUST include the actual quote/excerpt from the session that supports it.

---

## How to Run (2 commands)

```bash
# Terminal 1: Launch 6 Claude Code agents in tmux grid
cd ~/work/all-things-quickcall/trace
bash scripts/analyze/claude-grid.sh --yolo 6

# Terminal 2: Start the fully automated orchestrator
bash scripts/analyze/orchestrate.sh
```

Walk away. The orchestrator handles everything. Come back in ~1-1.5 hours.

---

## Output Location

```
docs/run1-09022026/analysis-outputs/
├── coordination/              # Agent status JSON files (orchestrator reads these)
│   ├── orchestrator.json      # Overall run status
│   ├── parser.json            # Parser agent status
│   ├── analyzer-a.json        # Analyzer batch A status
│   ├── analyzer-b.json        # Analyzer batch B status
│   ├── analyzer-c.json        # Analyzer batch C status
│   ├── synthesizer.json       # Synthesis agent status
│   ├── renderer.json          # Renderer agent status
│   └── verifier.json          # Verification report
├── parsed/                    # Parsed session data (one JSON per session)
├── deep_dive/                 # Rich narrative per session (one .md per session)
├── synthesis.md               # Cross-session patterns with evidence
├── retrospective.md           # Final weekly retrospective (Markdown)
├── dashboard.html             # Interactive HTML dashboard
└── metrics.json               # Aggregated metrics
```

---

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│  SEPARATE TERMINAL (not in tmux)                        │
│  orchestrate.sh — supervisor loop every 15s             │
│  Reads coordination/*.json                              │
│  Sends prompts via tmux send-keys when deps are met     │
│  Auto-nudges stuck/failed agents                        │
│  Handles git commit + push between phases               │
└──────────────┬──────────────────────────────────────────┘
               │ tmux send-keys → "Read prompts/X.md and execute"
               ▼
┌─────────────────────────────────────────────────────────┐
│  tmux session (launched by claude-grid.sh --yolo 6)     │
│                                                         │
│  ┌─────────────────────┐  ┌─────────────────────┐      │
│  │ Pane 0: PARSER       │  │ Pane 1: ANALYZER-A  │      │
│  │ Parse 34 JSONL files │  │ Deep-dive 12 files  │      │
│  │ Compute heuristics   │  │ (Jan 28 + Jan 29a)  │      │
│  ├─────────────────────┤  ├─────────────────────┤      │
│  │ Pane 2: ANALYZER-B   │  │ Pane 3: ANALYZER-C  │      │
│  │ Deep-dive 11 files   │  │ Deep-dive 11 files  │      │
│  │ (Jan 29b + Jan 30a)  │  │ (Jan 30b + Jan 31)  │      │
│  ├─────────────────────┤  ├─────────────────────┤      │
│  │ Pane 4: SYNTHESIZER  │  │ Pane 5: RENDERER    │      │
│  │ Cross-session        │  │ Retrospective.md +  │      │
│  │ pattern synthesis    │  │ Dashboard.html +    │      │
│  │                      │  │ Verification        │      │
│  └─────────────────────┘  └─────────────────────┘      │
└─────────────────────────────────────────────────────────┘
```

**Dependency chain:**
```
parser ──┬──→ analyzer-a ──┐
         ├──→ analyzer-b ──┼──→ synthesizer ──→ renderer+verifier
         └──→ analyzer-c ──┘
```

---

## How the Orchestrator Works

### Prompt Delivery
Prompts are stored as files in `scripts/analyze/prompts/`. The orchestrator sends a SHORT command to each tmux pane:
```
"Read the file scripts/analyze/prompts/parser.md and follow every instruction in it exactly. Start immediately."
```
This avoids tmux escaping issues with large text. The Claude agent reads the full prompt file using its Read tool.

### Dependency Management
Each agent writes a JSON status file to `coordination/`. The orchestrator polls every 15s:
- `status: "not_started"` + deps met + pane idle → send prompt
- `status: "in_progress"` → log current task, check for staleness
- `status: "completed"` → check if downstream agents can start
- `status: "failed"` + pane idle → auto-nudge with retry instruction
- No update for 5 minutes while in_progress → nudge "you appear stuck"

### Git Operations
Only the orchestrator does git. Agents do NOT commit. The orchestrator runs `git add + commit + push` every ~2.5 minutes and after each phase completes.

### Auto-Recovery
- Failed agents get re-prompted automatically
- Stuck agents (no status update in 5 min) get nudged
- Each agent's prompt file contains complete context — if a Claude session dies and restarts, the orchestrator re-sends the prompt

---

## Core Metrics (4 Deep, Not Wide)

| Metric | What it answers | How |
|--------|----------------|-----|
| **Session Outcome** | "Did AI actually solve my problem?" | Classify: resolved, abandoned, partial, context-only |
| **Iteration Efficiency** | "Am I getting better at prompting?" | Turns per session, turns-to-resolution |
| **Session Type** | "What am I spending my time on?" | Classify: bug-fix, feature, exploration, setup, refactor |
| **Struggle Detection** | "Where did I waste time?" | Detect: repeated prompts, error loops, pivots, abandonment |

Every metric is backed by QUOTED evidence from the actual session.

---

## Agent Assignment (34 files across 3 analyzers)

| Agent | Sessions | Files |
|-------|----------|-------|
| **analyzer-a** | Jan 28 (all 7) + Jan 29 (first 5) | 12 files |
| **analyzer-b** | Jan 29 (remaining 11) + Jan 30 (first 1) | 11 files (note: Jan 30 first file goes here) |
| **analyzer-c** | Jan 30 (remaining 2) + Jan 31 (all 8) | 11 files (note: 1 Jan 30 file already in analyzer-b) |

Exact filenames are listed in each agent's prompt file.

---

## Execution Timeline

```
t=0s      Orchestrator sends parser prompt → Pane 0
t=~8min   Parser done → Orchestrator sends analyzer-a/b/c prompts → Panes 1,2,3
t=~40min  All analyzers done → Orchestrator sends synthesizer prompt → Pane 4
t=~50min  Synthesizer done → Orchestrator sends renderer prompt → Pane 5
t=~65min  Renderer + verifier done → Orchestrator prints summary, exits
```

Git checkpoints happen every ~2.5 minutes throughout.

---

## Files Created

| File | Purpose |
|------|---------|
| `scripts/analyze/claude-grid.sh` | Launches 6-pane tmux grid with Claude Code |
| `scripts/analyze/orchestrate.sh` | Supervisor: polls status, sends prompts, handles git |
| `scripts/analyze/prompts/parser.md` | Full instructions for parser agent |
| `scripts/analyze/prompts/analyzer-a.md` | Full instructions + exact file list for analyzer A |
| `scripts/analyze/prompts/analyzer-b.md` | Full instructions + exact file list for analyzer B |
| `scripts/analyze/prompts/analyzer-c.md` | Full instructions + exact file list for analyzer C |
| `scripts/analyze/prompts/synthesizer.md` | Full instructions for synthesis agent |
| `scripts/analyze/prompts/renderer.md` | Full instructions for render + verify agent |

---

## Key Design Decisions

1. **Prompts as files, not inline**: Avoids tmux escaping nightmares. Agents read their own instructions.
2. **Orchestrator owns git**: No merge conflicts from parallel agents committing.
3. **Status JSON protocol**: Simple, file-based coordination. No shared memory, no IPC. Survives crashes.
4. **Evidence-first**: Every LLM prompt template requires `QUOTE the specific text`. Verifier cross-checks quotes against source JSONL.
5. **Decomposed LLM work**: Each Claude agent analyzes one session at a time. Never stuffed together. Easy to swap models later.
6. **Heuristics before LLM**: Parser computes rule-based metrics first. Analyzers add narrative depth. Synthesizer finds patterns. Renderer produces deliverables.
7. **VM path fallback**: All prompts include both local (`docs/internal/2026/`) and VM (`/home/sagar/trace/docs/internal/2026/`) paths.

---

## Verification Checklist

After the run completes, check:

1. `coordination/verifier.json` — should show `"status": "passed"`
2. `retrospective.md` — read it as a developer. Does it feel useful or creepy?
3. `dashboard.html` — open in browser. Charts render? Session cards expand?
4. `deep_dive/` — spot-check 3 files. Are quotes real or hallucinated?
5. `metrics.json` — do numbers add up to 34 sessions?

### Known ground truth:
- `rollout-2026-01-28T17-08-14` (9 lines) → should be `context-only`
- `rollout-2026-01-28T15-51-17` (62 lines) → should be `setup`, ~7 turns
- `rollout-2026-01-29T22-48-55` (228 lines) → should be `bug-fix`, ~31 turns
