nav-compact

What this skill does

# 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 0: Detect PreCompact Hook (Fast Path) [v6.10.0+]

**Before doing anything else**, check whether the project has the PreCompact hook installed.

```bash
HAS_HOOK=$(grep -l "nav_pre_compact" .claude/settings.json .claude/settings.local.json 2>/dev/null | head -1)
```

**If the hook is present**:

→ **Fast path activated**. The `PreCompact` hook will write the marker automatically when the user runs `/compact` (or when Claude Code auto-compacts). Skip Steps 2–5 (marker creation + `.active` writing) — the hook owns those. Just print:

```
╔══════════════════════════════════════════════════════╗
║  🗜️  Navigator Compact (hook-managed)                 ║
╚══════════════════════════════════════════════════════╝

✅ PreCompact hook is installed — Navigator will write the
   marker automatically when you run /compact.

Auto-compact is also covered: when Claude Code compacts
silently near the context limit, the hook still fires and
writes a marker tagged with `-auto-` in the filename.

Just run:    /compact

The PostCompact hook will append Claude Code's official
summary to the marker once compact finishes. On your next
session, "Start my Navigator session" picks up the marker
via .active and offers restore.
```

That's it. Don't create a duplicate marker — the hook handles it deterministically.

**If the hook is absent** (legacy project, manually disabled, or pre-v6.10 install):

→ **Legacy path**. Execute Steps 1–5 below as documented. Manual marker creation, then user runs `/compact`.

---

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