gh-alekspetrov-navigator/skills/nav-compact/SKILL.md

---
name: nav-compact
description: Clear conversation context while preserving knowledge via context marker. Use when user says "clear context", "start fresh", "done with this task", or when approaching token limits.
allowed-tools: Read, Write, Bash
version: 1.0.0
---

# Navigator Compact Skill

Clear your conversation context while preserving all knowledge in a context marker. Like git commit before switching branches - save your state, then start fresh.

## When to Invoke

Invoke this skill when the user:
- Says "clear context", "start fresh", "reset conversation"
- Says "I'm done with this task", "moving to next feature"
- Mentions "approaching token limit", "context getting full"
- Says "compact", "clean up context"
- After completing isolated sub-task

**DO NOT invoke** if:
- User is in middle of implementation
- Context is needed for next immediate step
- Less than 20 messages in conversation (not much to gain)

## Execution Steps

### Step 1: Check If Worth Compacting

Estimate conversation size:
- If < 20 messages: Suggest waiting
- If 20-50 messages: Safe to compact
- If > 50 messages: Highly recommended

Show message:
```
📊 Current session: ~[N] messages

Compacting will:
- Create marker with current state
- Clear conversation history
- Free up ~[X]k tokens for new work

Continue? [Y/n]:
```

### Step 2: Create Automatic Marker

Invoke `nav-marker` skill (or create marker directly) with auto-generated name:

```
Marker name: before-compact-{YYYY-MM-DD}-{HHmm}
Note: "Auto-created before compact"
```

This marker should capture:
- Last 10-15 messages summary
- Files modified
- Technical decisions
- Current progress
- Next steps

### Step 3: Set Active Marker

Write the marker filename to `.active` file:

```bash
echo "{marker-filename}.md" > .agent/.context-markers/.active
```

This tells `nav-start` to offer restoration on next session.

### Step 4: Display Compact Instructions

Show user how to compact:

```
╔══════════════════════════════════════════════════════╗
║                                                      ║
║  🗜️  Navigator Compact                                ║
║                                                      ║
╚══════════════════════════════════════════════════════╝

✅ Context marker created:
   .agent/.context-markers/{marker-filename}.md

📋 Marker contains:
   - Conversation summary (last 15 messages)
   - Files you modified
   - Technical decisions made
   - Current progress & next steps

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔹 TO COMPACT:

Claude Code doesn't allow me to clear the conversation
programmatically. You need to do it manually:

**Method 1: New conversation**
1. Start a new conversation
2. Say "load my context" or "start my session"
3. I'll detect the active marker and restore your state

**Method 2: /clear command** (if available)
1. Type /clear
2. Say "load my context"
3. Active marker will be restored

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 Your progress is saved. You won't lose any context.

Next session:
1. Say "start my session" or run /nav:start
2. I'll detect the marker: "{marker-filename}"
3. Confirm to restore, and you'll be back where you left off

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Step 5: Confirm Marker Location

Verify marker was created:

```bash
ls -lh .agent/.context-markers/{marker-filename}.md
```

Show file size and confirm success:
```
✅ Marker saved successfully
   File: {marker-filename}.md
   Size: {X} KB (~{Y} tokens)

Your context is preserved!
```

## Important Notes

**Why manual compact?**

Claude Code conversations cannot be programmatically cleared from within a conversation. The user must:
- Start a new conversation, OR
- Use `/clear` command (if available)

This skill creates the marker and sets up auto-restoration, but the actual clearing must be done by the user.

**Auto-restoration workflow:**

```
Session 1:
  User: "Clear context"
  → nav-compact creates marker
  → Sets .active file
  → Instructs user how to clear

Session 2 (new conversation):
  User: "Start my session"
  → nav-start detects .active file
  → Offers to restore marker
  → User confirms
  → Context restored!
```

## Common Use Cases

### After Completing Feature
```
User: "Feature complete, clear context for next task"
→ Creates marker: "before-compact-2025-10-16-1430"
→ Captures: Feature implementation details
→ User starts new conversation
→ Restores marker, begins next feature
```

### Approaching Token Limit
```
User: "Context getting full, let's compact"
→ Creates marker: "before-compact-2025-10-16-1500"
→ Preserves: All current work
→ User clears conversation
→ Continues with fresh context
```

### Switching Between Tasks
```
User: "Done with auth, moving to payments"
→ Creates marker: "auth-feature-complete"
→ Clear context
→ New session: Fresh start for payments
→ Can restore auth marker later if needed
```

## Error Handling

**Marker creation fails**:
```
❌ Failed to create marker

Cannot compact without preserving context.
Fix marker creation first.
```

**Not enough context to preserve**:
```
⚠️  Very little context (< 10 messages)

Compacting now won't save much. Consider:
- Continue working
- Compact after more progress

Continue anyway? [y/N]:
```

**Active marker already exists**:
```
⚠️  Active marker already exists:
   .agent/.context-markers/.active

This means you have an unrestored marker from previous compact.

Options:
1. Load that marker first (recommended)
2. Overwrite with new marker
3. Cancel compact

Your choice [1-3]:
```

## Success Criteria

Compact is successful when:
- [ ] Context marker created successfully
- [ ] Marker contains comprehensive summary
- [ ] `.active` file created (for auto-restoration)
- [ ] User knows how to clear conversation
- [ ] User knows marker will auto-restore on next session

## Scripts

**compact.py**: Automated compact workflow
- Create marker
- Set active file
- Generate restore instructions

## Best Practices

**When to compact:**
- ✅ After completing isolated feature/sub-task
- ✅ After major documentation update
- ✅ Before switching to unrelated work
- ✅ When approaching 70%+ token usage
- ❌ In middle of implementation
- ❌ When context needed for next step
- ❌ After every few messages (wasteful)

**Compact frequency:**
- Small task (30 min): No compact needed
- Medium task (2-3 hours): Compact after completion
- Large task (full day): Compact at logical breakpoints
- Multi-day task: Compact at end of each session

## Notes

This skill automates the preparation for compacting but cannot clear the conversation itself (Claude Code limitation).

The value is in:
1. Automatic marker creation
2. Setting up auto-restoration
3. Guiding user through process
4. Preserving context seamlessly

This provides same functionality as `/nav:compact` command but with natural language invocation.