From finesse
Context compaction handling for Finesse planning sessions — working file schema, recovery rules, and phase codes
How this skill is triggered — by the user, by Claude, or both
Slash command
/finesse:compaction-handlingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
When a planning session is long, Claude Code may compact context. To ensure critical information survives compaction:
When a planning session is long, Claude Code may compact context. To ensure critical information survives compaction:
finesse-plans/<name>-working.md. Update this file at each major phase boundary. The YAML frontmatter (see item 2) must be included from the first write and updated at each phase boundary.---
mode: planning-only # CRITICAL: Never edit source code. Never implement.
allowed_agents: [code-explorer, code-architect, task-decomposer, clarity-checker, completion-validator, scope-safety-reviewer, phase-structure-analyzer, failure-mode-auditor, goal-achievement-auditor, exploration-orchestrator, scope-analyzer, architecture-designer, plan-constructor, plan-validator]
task_type: <feature|bugfix|refactor|testing|performance|research>
workflow: <feature-development|bug-fix|refactor-chore|testing|performance-optimization|research>
current_phase: <phase code, e.g., F5, B3, RE4>
completed_phases: [<list of completed phase codes, e.g., F1, F2, F3, F4>]
uat_fast_forward: <true|false>
session_name: <kebab-case session descriptor>
decomposed: <true|false>
refinement_budget: <number> # --max-refinements value, populated during Validation
refinement_cycles_used: <number> # cycles consumed so far, updated during Validation
context_pressure: <low|moderate|high|critical> # populated during Plan Construction
context_budget: # populated during Plan Construction
peak_iteration_tokens: <number>
context_window: <number>
pressure_pct: <number>
estimated_cost_range: <string>
file_count: <number>
file_categories:
small: <number>
medium: <number>
large: <number>
sub_workflows: # only present if decomposed: true
- name: <sub-workflow kebab-case name>
type: <task type>
wave: <wave number>
current_phase: <phase code>
completed_phases: [<completed phase codes>]
context_pressure: <low|moderate|high|critical> # per-sub-workflow, populated during Plan Construction
context_budget: # per-sub-workflow, populated during Plan Construction
peak_iteration_tokens: <number>
pressure_pct: <number>
estimated_cost_range: <string>
---
Below the YAML frontmatter, the working file body MUST start with a Session Constraints block, followed by free-form markdown:
## Session Constraints (DO NOT DELETE)
- PLANNING-ONLY session. Output is a ralph-loop command. NEVER edit source code.
- Task agents ONLY for: code-explorer, code-architect, task-decomposer, 6 validation agents, and 5 orchestrator agents (exploration-orchestrator, scope-analyzer, architecture-designer, plan-constructor, plan-validator)
- Write ONLY to finesse-plans/ and .finesse/
- NEXT ACTION: [describe the current/next phase step]
- DO NOT: edit source files, launch general-purpose agents, implement the plan
After the Session Constraints block, include: codebase findings, UAT checkpoint decisions and their outcomes, prompt draft (if one exists), promise draft (if one exists), open questions or blockers.finesse-plans/<name>-working.md to recover state. The YAML frontmatter is parsed first to determine the exact resume point, followed by reading the markdown body for phase-specific content.finesse-plans/<name>-working.md where <name> matches the eventual plan name. If the plan name is not yet determined, derive a session descriptor from the first 3-4 words of the task description in kebab-case (e.g., finesse-plans/_working-fix-token-refresh.md).Identity-level post-compaction rules (planning-only, no code changes, no implementation agents, present-don't-implement) are in the planner-identity skill's Post-Compaction Identity Recovery section. Those apply automatically.
The following procedural rules are specific to recovery in the full /finesse workflow:
finesse-plans/<name>-working.md in full. This is your single source of truth.mode field in YAML frontmatter. If it says planning-only, you are in a Finesse session. If you are not in plan mode, call EnterPlanMode before doing anything else.npx claudepluginhub jonathanung/finesse --plugin finesseSaves critical files, task progress, and working state before context compaction, then restores them after. Use before /compact or when auto-compact triggers.
Manages long-session context to prevent drift and degradation via proactive summarization, branch isolation, and compaction strategies. Invoke when context feels heavy, accuracy slips, or after a major phase boundary.
Suggests context compaction at logical breakpoints like phase transitions, milestones, or after 40 tool calls to avoid official auto-compact bugs. Activates via hooks in long dev sessions.