compaction-handling

Context Compaction Handling

When a planning session is long, Claude Code may compact context. To ensure critical information survives compaction:

Working File Persistence

1. Early persistence: As soon as codebase exploration results are gathered, write key findings to 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.
2. Working file structure: ALL working files MUST include a YAML frontmatter block at the top of the file, before any markdown body content. The mandatory schema:

   ---
   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.
3. Recovery: If you detect that context has been compacted (e.g., you cannot recall earlier phase outputs), read 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.
4. Working file naming: Use 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).
5. Cleanup: After plan acceptance and final file output, keep the working file for reference.