tractatus/OPTIMAL_SESSION_STARTUP.md

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

# 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

# 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)

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:

# 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