146 lines
3.8 KiB
Markdown
146 lines
3.8 KiB
Markdown
# 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
|
|
```
|