3.8 KiB

Raw Permalink Blame History

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:

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

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:

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

/context-status - Check State

View current context state:

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:

Are we approaching context limit?
Is there unsaved progress?
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:

User starts new session
Run /resume - Injects previous context
Claude reads state - Understands where to continue
Continue work - Pick up from next action

State Contents

The context_state.json captures:

{
  "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

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

Troubleshooting

No state found on resume

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

Clear stale state

python3 skills/guardrail-orchestrator/scripts/context_compact.py clear \
  --workflow-dir .workflow/versions/v001

Manual state inspection

cat .workflow/versions/v001/context_state.json | jq .
cat .workflow/versions/v001/resume_prompt.md

3.8 KiB Raw Permalink Blame History