Context Compaction
Relevant source files
The following files were used as context for generating this wiki page:
Context compaction is a critical state-management mechanism within the Roughly pipeline architecture. Its primary purpose is to prevent LLM context overflow—the most frequent failure mode in long AI development sessions—by strategically summarizing and pruning historical session data before high-token-intensity stages.
By compacting context at specific transition points, Roughly ensures that subagents receive the minimum necessary information required for their specific task, preserving "headroom" for complex operations such as code investigation, implementation, and multi-agent review.
Sources: README.md:143-145, README.md:213-214
Compaction Architecture
Roughly pipelines are designed to be "subagent-per-task," meaning each task gets a fresh agent with clean context. The orchestrator (the build or fix skill) coordinates these transitions and manages the shared context state. Context compaction acts as the bridge between these transitions.
Pipeline Placement
Compaction events are strategically placed before specific stages in the implementation and auditing workflows:
| Pipeline | Placement Points | Preserved Data Elements |
|---|---|---|
| Fix Pipeline | Before Stage 2 (Investigate) | Issue description |
| Fix/Build Pipeline | Before Stage 5 (Implement) | Issue/Feature summary, root cause, plan path, PASS verdict |
| Fix/Build Pipeline | Before Stage 6 (Review) | Issue/Feature summary, task ID list, changed files list, verification warnings |
| Fix/Build Pipeline | Before Stage 7 (Verify) | Issue/Feature summary, files changed, review verdict, deferred warnings |
| Fix/Build Pipeline | Before Stage 8 (Wrap-up) | Issue/Feature summary, root cause, files changed, task count, verification verdict |
| Audit Epic | After Batch Per-Story Reviews | Epic title, story ID list, AC status table (verdicts only), quality flags |
Sources: skills/fix/SKILL.md:46-47, skills/fix/SKILL.md:104-106, skills/fix/SKILL.md:173-174, skills/fix/SKILL.md:188-189, skills/audit-epic/SKILL.md:68-71, README.md:213-218
Logic Flow of a Compaction Event
When the orchestrator reaches a compaction point, it identifies essential state variables and discard temporary reasoning, investigation logs, and subagent conversational history.
The diagram shows the decision logic used by orchestrator skills to manage context before initializing new subagents.
Sources: README.md:143-152, skills/fix/SKILL.md:104-106
Process Detail: Fix and Build Pipelines
The Fix and Build pipelines are the primary consumers of context compaction. Because these pipelines can involve up to 8 gated stages and multiple subagent dispatches, they are susceptible to context bloat.
Pre-Implementation Compaction
Before Stage 5 (Implementation), the context is significantly reduced. The subagent does not need the full history of how the plan was drafted or the details of the review-plan iteration loop. Instead, it relies on the plan file stored on disk.
- Logic: Re-read the verified plan file from
.roughly/plans/. - Preservation: Issue summary, root cause (for fix), plan file path, and the mandatory
PASSverdict fromreview-plan.
Sources: skills/fix/SKILL.md:104-106, skills/fix/SKILL.md:113-115
Implementation Feedback Loop
During implementation, Roughly performs a "two-stage review" after each task. If a subagent returns questions or fails spec compliance, it may be re-dispatched. Context compaction ensures that these iterative loops do not consume the available token window for subsequent tasks.
This sequence illustrates how the orchestrator manages information between task implementation iterations.
Sources: skills/fix/SKILL.md:143-149, CONTRIBUTING.md:131-133
Process Detail: Epic Auditing
The audit-epic skill uses a batch-processing approach to manage context when dealing with large numbers of stories (10 or more).
Batch Compaction
For epics with 10+ stories, the audit process is partitioned into batches of 5 stories. After each batch:
- Summarization: Batch findings are summarized into key themes, critical issues, and coverage gaps.
- State Preservation: The orchestrator keeps the story ID list and the specific
MET/PARTIALLY MET/NOT METverdicts for each Acceptance Criterion (AC). - Pruning: Detailed evidence citations and line-specific references from the per-story subagents are discarded to save tokens.
Sources: skills/audit-epic/SKILL.md:61-71, skills/audit-epic/SKILL.md:94-98
Operational Guards
Context compaction is enforced and supported by several structural invariants within the project:
Word and Line Limits
To keep the base context lean, Roughly enforces strict limits on the size of skill and agent definitions:
- Skill Body Cap: 300 lines (e.g.,
skills/*/SKILL.md). - Agent Prompt Cap: 650 words.
- Verification: These limits are enforced by the
verify-allStop hook (.claude/hooks/verify-all.sh).
Sources: CONTRIBUTING.md:144-146, CLAUDE.md:43-46, README.md:162-164
Shared Context Files
Instead of including project-wide rules in every subagent prompt, Roughly uses shared context files (CLAUDE.md and .roughly/known-pitfalls.md) that are read at runtime. This "just-in-time" loading prevents context bloating.
Sources: README.md:155-159, agents/agent-preamble.md:15-18
Conclusion
Context compaction is the operational realization of the "Loud" and "Gated" Roughly philosophy. By forcing the orchestrator to summarize state and prune history at every transition, the system maintains high technical accuracy and prevents the degradation of agent performance that typically occurs as conversational history grows. This architecture allows Roughly to handle complex, multi-task features that would otherwise exceed the reliable context limits of the underlying LLM models.