# Optimal Session Startup Prompt for Tractatus

**Version**: 2.0 (2025-10-12)
**Updated**: After discovering conversation length >> token count for compacting events

---

## Recommended Session Startup Prompt

```
Continue working on the Tractatus project. Primary task: [ADD SPECIFIC TASK HERE]

This is [NEW SESSION / CONTINUED after X compactions].

Key context from last session:
- [BULLET 1: Most important achievement/state]
- [BULLET 2: Current blocker or next step]
- [BULLET 3: Critical context that would be expensive to lose]

Files actively being worked on:
- [FILE 1]
- [FILE 2]

Session constraints:
- Conversation limit: 40 messages before handoff recommended
- Token budget: 200k
- Compactions so far: [0/1/2/3]
```

---

## Why This Format Works

### 1. **Conversation Limit Front and Center**

**Problem**: Previous sessions focused on token budget (200k) but compacting happens based on **message count**, not just tokens.

**Observation**:
- First compaction: ~60 messages
- Second compaction: ~70+ messages
- Each compaction: 1-3 minutes + critical context loss

**Solution**: Set **40-message limit** as primary constraint.

### 2. **Compaction Tracking**

**Critical**: Number of compactions is the BEST predictor of session degradation.

**Pressure multipliers**:
- 0 compactions: Normal operations
- 1 compaction: 1.5x conversation pressure (ELEVATED)
- 2 compactions: 3.0x conversation pressure (HIGH → CRITICAL)
- 3+ compactions: 5.0x conversation pressure (DANGEROUS)

**Action**: After 2nd compaction, IMMEDIATELY create handoff and start fresh.

### 3. **Minimal but Critical Context**

**Problem**: Long handoffs → more tokens → faster compacting

**Solution**: 3 bullets of ONLY what's expensive to reconstruct:
- Completed work (prevents re-doing)
- Current state (prevents re-investigation)
- Critical decisions (prevents re-debate)

### 4. **Active File List**

**Why**: Claude can quickly re-read files. No need to paste content in prompt.

**Format**: Just list file paths. Use Read tool immediately after startup.

---

## Example: Card Presentation Task

**Good startup**:
```
Continue working on Tractatus. Primary task: Add card presentations (sections) to 35 documents.

This is a NEW SESSION (0 compactions).

Key context:
- Database investigation complete (36 docs total, only 1 has sections)
- Priority 1: 4 Getting Started documents need sections first
- Template: architectural-overview-and-research-status (18 sections)

Files:
- scripts/check-sections.js (audit tool)
- docs/session-handoff-2025-10-12-database-cleanup.md (full context)

Constraints:
- 40-message limit before handoff
- 200k token budget
- 0 compactions so far
```

**Bad startup** (causes rapid compacting):
```
Continue working on Tractatus. Last session we were working on documentation and there were some issues with the database. I think we need to add card presentations to documents. The database had some problems - dev had 60 documents but prod had 32, and there were categories that didn't match, and only one document had sections which was the architectural overview one with 18 sections. We need to add sections to like 35 documents and there's a priority list somewhere. Also we fixed the Introduction document because it had the word "guarantee" in it which violates the rules. The handoff document has all the details. Also the sidebar categories weren't collapsing properly but I think that's fixed now. Let me know if you need more context about what happened.
```

**Why bad?**:
- 140 tokens (7% of budget gone immediately)
- Vague task description
- Verbose background (just point to handoff file)
- No session constraints mentioned
- Will trigger faster compacting

---

## Session Handoff Protocol

### When to Create Handoff

**Immediate handoff if ANY**:
- ✅ 40 messages reached
- ✅ 2+ compactions occurred
- ✅ HIGH pressure or above
- ✅ Complex task remains with 150k+ tokens used

**Advisory handoff**:
- 30 messages + 100k tokens
- ELEVATED pressure + complex task
- Multiple errors clustering

### Handoff Document Structure

```markdown
# Session Handoff: [Brief Title] ✅/🔄/❌

**Date**: YYYY-MM-DD
**Status**: COMPLETE/IN_PROGRESS/BLOCKED

## Executive Summary (3-5 bullets)
- Achievement 1
- Achievement 2
- Next step

## Completed This Session ✅
- Task 1 (with verification)
- Task 2 (with file paths)

## Next Session Priority
1. Specific task (with acceptance criteria)
2. Files to modify
3. Success metrics

## Context Preservation
**Only include if expensive to reconstruct**:
- Database state (if changed)
- Architecture decisions (if made)
- User preferences discovered (if new)

## Verification Commands
```bash
# Command to verify state
command-here
```

---

## Pressure Monitoring Commands

### Check Current Pressure

```bash
# Without compactions
node scripts/check-session-pressure.js --tokens 50000/200000 --messages 25

# With compactions (CRITICAL)
node scripts/check-session-pressure.js --tokens 50000/200000 --messages 25 --compactions 1
```

### Interpret Results

**Normal** (0-30%):
- Continue working
- No special precautions

**Elevated** (30-50%):
- Increase verification
- Monitor message count
- Plan handoff soon

**High** (50-70%):
- Mandatory verification on all changes
- Prepare handoff document
- Avoid starting new complex tasks

**Critical** (70-85%):
- Create handoff immediately
- Finish current atomic task only
- Do NOT start new work

**Dangerous** (85%+):
- STOP all work
- Create emergency handoff
- Start fresh session

---

## Updated Weights (2025-10-12)

```javascript
TOKEN_USAGE:          0.30  // (was 0.35) Still important
CONVERSATION_LENGTH:  0.40  // (was 0.25) PRIMARY factor ⭐
TASK_COMPLEXITY:      0.15  // (unchanged)
ERROR_FREQUENCY:      0.10  // (was 0.15)
INSTRUCTION_DENSITY:  0.05  // (was 0.10)
```

**Key insight**: Message count drives compacting more than token count.

---

## Common Mistakes to Avoid

### ❌ Ignoring Message Count

**Wrong**: "We're only at 100k tokens (50%), plenty of room"

**Reality**: 60 messages = first compaction, regardless of tokens

**Right**: "We're at 35 messages. Plan handoff at 40 regardless of tokens."

### ❌ Continuing After 2nd Compaction

**Wrong**: "We got compacted twice but still have tokens, let's keep going"

**Reality**: 2nd compaction = 3x pressure multiplier = CRITICAL degradation

**Right**: "2nd compaction detected. Creating handoff immediately."

### ❌ Verbose Startup Prompts

**Wrong**: Paste entire previous session in startup prompt

**Reality**: Uses tokens, triggers faster compacting, slows Claude

**Right**: 3 bullets + pointer to handoff file

### ❌ Not Tracking Compactions

**Wrong**: Lose count of how many times conversation was compacted

**Reality**: Can't accurately assess session health

**Right**: Track compactions in handoff document, pass to pressure monitor

---

## Session Startup Checklist

Fresh session:
- [ ] Run `node scripts/session-init.js`
- [ ] Note: 0 compactions, 0 messages, 40-message target
- [ ] Read handoff document (if continuing work)
- [ ] Verify current state (git status, server status)
- [ ] Start work

After compaction:
- [ ] Increment compaction counter
- [ ] Run pressure check with --compactions parameter
- [ ] If 2+ compactions: IMMEDIATE HANDOFF
- [ ] If 1 compaction: Plan to finish current atomic task only

---

## Emergency Handoff Template

When you hit 2+ compactions or CRITICAL pressure:

```markdown
# EMERGENCY HANDOFF: [Task Name]

**Pressure**: CRITICAL (2+ compactions)
**Tokens**: [X]/200k
**Messages**: [X]

## What Was Being Done
[One sentence]

## Current State
- [ ] Complete / [ ] Partial / [ ] Blocked

## Files Modified (uncommitted)
- file1.js
- file2.html

## Next Action (ONE THING)
[Single specific task to complete]

## Verification
```bash
# Single command to verify state
```

That's it. Keep it SHORT.
```

---

## Conclusion

**Old thinking**: "200k tokens = plenty of room"

**New reality**: "40 messages = get ready to hand off"

**Critical metric**: **Compaction count**, not token count

**Optimal workflow**:
1. Start session with minimal prompt (3 bullets)
2. Track messages, not just tokens
3. At 40 messages OR 1st compaction: plan handoff
4. At 2nd compaction: IMMEDIATE handoff
5. Never go to 3rd compaction

**Result**: Shorter sessions, but FAR more productive per-message.

---

**Last Updated**: 2025-10-12
**Next Review**: After 10 sessions using new protocol
