# Context Compaction Skill

## Purpose
Manages context window by saving state before compaction and resuming after.
Ensures workflow continuity across context compressions.

## Activation Triggers
- Manual: `/compact` command
- Manual: `/save-state` command
- Manual: `/resume` command
- Auto: When context usage exceeds 80%

## Commands

### /compact - Full Compaction Workflow
Saves state and prepares for context compaction:

```bash
# 1. Save current workflow state
python3 skills/guardrail-orchestrator/scripts/context_compact.py save \
  --workflow-dir .workflow/versions/v001 \
  --checkpoint

# 2. Display resume prompt for reference
python3 skills/guardrail-orchestrator/scripts/context_compact.py resume \
  --workflow-dir .workflow/versions/v001
```

### /save-state - Quick State Save
Saves state without compaction:

```bash
python3 skills/guardrail-orchestrator/scripts/context_compact.py save \
  --workflow-dir .workflow/versions/v001
```

### /resume - Resume After Compaction
After context is compacted, inject resume context:

```bash
python3 skills/guardrail-orchestrator/scripts/context_compact.py resume \
  --workflow-dir .workflow/versions/v001
```

### /context-status - Check State
View current context state:

```bash
python3 skills/guardrail-orchestrator/scripts/context_compact.py status \
  --workflow-dir .workflow/versions/v001
```

## Auto-Detection Rules

When context feels heavy (many tool calls, large files read), check:
1. Are we approaching context limit?
2. Is there unsaved progress?
3. Should we recommend compaction?

### Warning Thresholds
- **70%**: Log warning, suggest saving state soon
- **80%**: Auto-save state, continue working
- **90%**: Strongly recommend compaction
- **95%**: Force state save immediately

## State Files Generated

After `/compact` or `/save-state`:

```
.workflow/versions/v001/
├── context_state.json      # Full serialized state
├── resume_prompt.md        # Human-readable resume
└── modified_files.json     # Recent file changes
```

## Resume Workflow

After user runs `/compact` and context is cleared:

1. **User starts new session**
2. **Run `/resume`** - Injects previous context
3. **Claude reads state** - Understands where to continue
4. **Continue work** - Pick up from next action

## State Contents

The context_state.json captures:

```json
{
  "session_id": "compact_20250118_143022",
  "workflow_position": {
    "current_phase": "IMPLEMENTING",
    "active_task_id": "task_create_api_login",
    "layer": 2
  },
  "active_work": {
    "entity_id": "api_auth_login",
    "action": "implementing",
    "file_path": "app/api/auth/login/route.ts",
    "progress_notes": "Created route, need JWT generation"
  },
  "next_actions": [
    {"action": "implement", "target": "JWT token generation", "priority": 1}
  ],
  "modified_files": [...],
  "decisions": [...],
  "blockers": [...]
}
```

## Integration with Workflow

This skill integrates with:
- **workflow_state.yml** - Reads current phase and task status
- **tasks/*.yml** - Identifies pending and in-progress tasks
- **Git** - Tracks modified files, can create checkpoints

## Best Practices

1. **Save frequently** - Run `/save-state` after completing major steps
2. **Before risky operations** - Save state before large refactors
3. **End of session** - Always save state before ending work
4. **After compaction** - Always run `/resume` to restore context

## Troubleshooting

### No state found on resume
```bash
python3 skills/guardrail-orchestrator/scripts/context_compact.py status \
  --workflow-dir .workflow/versions/v001
```

### Clear stale state
```bash
python3 skills/guardrail-orchestrator/scripts/context_compact.py clear \
  --workflow-dir .workflow/versions/v001
```

### Manual state inspection
```bash
cat .workflow/versions/v001/context_state.json | jq .
cat .workflow/versions/v001/resume_prompt.md
```