Compaction

Reduces the context snapshot and progress file to a fraction of their original size while preserving the information that matters for issue-craft and pr-context. Inspired by Kimi CLI's open-source compaction system (MoonshotAI/kimi-cli), with head+tail preservation adapted from Kimi Code PR #1313.

When to Trigger

• The progress file (.slim/acf/<slug>.md) exceeds ~2000 tokens (~8000 chars)
• The context snapshot has more than 5 sections with more than 5 bullets each
• The user explicitly asks to compact or compress context
• Before passing context to a model with a small context window
• Between phases when the snapshot has accumulated stack-audit findings

Kimi's Compaction Techniques (adapted for ACF)

ACF borrows five key techniques from Kimi's compaction system:

1. Head+Tail Preservation

Kimi Code's PR #1313 splits the conversation into three regions:

• Head: the oldest messages (the original task statement), kept verbatim
• Tail: the most recent messages, kept verbatim
• Middle: everything else, summarized into a compact block

An elision marker ([... N tokens compacted ...]) is inserted between the head and tail so the agent can see how much was compressed.

ACF adapts this with SDLC-specific bounds:

• Head (max 500 tokens): the original user request — the first message of the session — is preserved verbatim. This ensures the original task statement never vanishes in long sessions.
• Tail (max 1000 tokens): the most recent phase output (e.g., the last stack-audit findings or the current issue draft) is preserved verbatim.
• Middle: everything between head and tail is compacted using the priority-based compression below.
• Elision marker: [... ~N tokens compacted ...] is inserted between the head and tail sections.

If the head or tail exceeds its token budget, it is truncated to the budget with a [... truncated ...] marker. If the entire session fits within head + tail budgets, no compaction is needed.

2. Priority-Based Compression

Kimi's compact.md prompt defines compression priorities in order:

1. Current Task State (what is being worked on RIGHT NOW)
2. Errors and Solutions (all encountered errors and their resolutions)
3. Code Evolution (final working versions only, remove intermediate attempts)
4. System Context (project structure, dependencies, environment setup)
5. Design Decisions (architectural choices and their rationale)
6. TODO Items (unfinished tasks and known issues)

ACF applies the same priorities to the SDLC context:

1. Current issue/PR draft — preserve verbatim
2. Stack-audit findings — preserve orphan PRs, close gaps, escaped issues
3. Test commands and CI checks — preserve exact command strings
4. Architecture facts — compress to one-line summaries
5. Conventions — compress to label names only
6. Completed phases — compress to one-line outcomes

3. XML-Tagged Output Structure

Kimi's compaction output uses XML-like tags for structured retrieval: <current_focus>, <environment>, <completed_tasks>, <active_issues>, <code_state>, <important_context>.

ACF uses the same pattern for the compacted snapshot:

<current_focus>
[The issue or PR currently being crafted — 1-2 lines]
</current_focus>

<stack>
- Open PRs: [count] | Orphan: [count] | Stale issues: [count]
- Close gaps: [list PR#→Issue# or "none"]
- Escaped issues: [list or "none"]
- Library opportunities: [list or "none"]
</stack>

<tests>
- [exact test command 1] ([N] tests)
- [exact test command 2] ([N] tests)
- Coverage: [command or "none"]
</tests>

<ci>
- [check name 1] (from [workflow file])
- [check name 2] (from [workflow file])
</ci>

<architecture>
- Stack: [one line]
- Key dirs: [paths only]
- Architecture doc: [path or "none"]
</architecture>

<conventions>
- Labels: [type + priority + area required]
- Commit: [conventional commits]
- Branch: [prefix rules]
</conventions>

<completed_phases>
- context-load: [done — snapshot built]
- stack-audit: [done — N findings]
- issue-craft: [in progress — draft at /tmp/issue-body.md]
</completed_phases>

4. First-Person Handoff

Kimi-Code's compaction rework writes the summary as the agent's own continuing notes (first-person), not a third-party report. The summary:

• Preserves exact commands, paths, and outcomes
• States the precise next action
• Flags claimed-but-unverified work rather than trusting it

ACF applies this to the progress file. After compaction, the progress file reads as the agent's own working notes, structured as head + elision + tail + compacted summary:

## Compacted Handoff

### Original Request (preserved)
[user's original request, verbatim — max 500 tokens]

[... ~N tokens compacted ...]

### Current State (preserved)
[most recent phase output, verbatim — max 1000 tokens]

### Compacted Summary
I was working on [issue/PR title]. The context snapshot is compacted.

What I know:
- Stack has [N] orphan PRs, [M] stale issues
- Test command: [exact command] — [N] tests pass
- CI check: [check name] must pass

What I need to do next:
- [precise next action, e.g., "run gh issue create with the draft at /tmp/issue-body.md"]

What I have NOT verified yet:
- [anything claimed but not confirmed, e.g., "CI check names are guessed — verify against .github/workflows/"]

Compaction Rules

1. MUST KEEP: exact test commands, CI check names, issue/PR numbers, label names, orphan PR numbers, close-gap pairs
2. MERGE: similar findings into single lines (e.g., "3 stale issues" not listing all three)
3. REMOVE: full file contents (replace with paths), verbose architecture descriptions (replace with one-line summaries), intermediate drafts
4. CONDENSE: long command lists into counts + the most critical command
5. PRESERVE HEAD: the original user request (first message) is preserved verbatim, up to 500 tokens
6. PRESERVE TAIL: the current phase's output is preserved verbatim, up to 1000 tokens — never compacted
7. ELIDE MIDDLE: insert [... ~N tokens compacted ...] between head and tail to mark compacted content
8. FIRST-PERSON: the handoff note is written as the agent's own notes

Auto-Trigger Threshold

Following Kimi's should_auto_compact logic:

trigger_compaction = (
    token_count >= max_context_size * trigger_ratio  # default 0.85
    or token_count + reserved_context_size >= max_context_size
)

For ACF, the defaults are:

• max_context_size: 8000 tokens (configurable per project)
• trigger_ratio: 0.75 (compact earlier than Kimi's 0.85, since ACF context is already compressed)
• reserved_context_size: 2000 tokens (space for the next phase's output)

Manual Trigger

The user can trigger compaction at any time with a custom instruction:

"compact context — keep the stack-audit findings"
"compress the snapshot — prioritize test commands"

The custom instruction is appended to the compaction prompt, telling the model what to prioritize (same as Kimi's /compact keep db discussions).

Token Estimation

Following Kimi's heuristic: tokens ≈ chars // 4 (approx. 4 chars per token for English). For Spanish content, use chars // 3.5 (Spanish has more characters per token due to accents and longer words).

Output

The compacted snapshot replaces the full snapshot in the progress file. The original full snapshot is NOT kept — compaction is lossy by design. If the full snapshot is needed, re-run context-load.

Relationship to Caveman Mode

Compaction is the standard compression mode. Caveman (phase 8) is the extreme compression mode for when even the compacted snapshot is too large. See skills/08-caveman/SKILL.md.

Sources

• MoonshotAI/kimi-cli — compaction.py
• MoonshotAI/kimi-cli — compact.md prompt
• MoonshotAI/kimi-code — first-person handoff rework (PR #1214)
• MoonshotAI/kimi-code — head+tail preservation (PR #1313)
• Kimi Code CLI Docs — Context compression

Error Handling

• gh CLI not installed: compaction operates on the progress file, not GitHub. It does not require gh. Proceed normally.
• gh not authenticated: not applicable to compaction. Proceed normally.
• GitHub API rate limits: not applicable to compaction. Proceed normally.
• Progress file doesn't exist: if .slim/acf/<slug>.md is missing, report "Progress file not found — nothing to compact. Run context-load first." Do not create an empty compacted file.
• Commands fail: if the progress file cannot be read (permissions, encoding), report the error and skip compaction. Do not destroy the original file. If compaction produces invalid output, restore from the pre-compaction state (the agent should keep a copy before overwriting).

Example

Before (full snapshot, ~2000 tokens)

## Context Snapshot

### Architecture
- Stack: Luau, Knit, Lune build tool
- Key dirs: src/server/, src/client/, src/shared/, scripts/, docs/
- Architecture doc: docs/ARCHITECTURE.md

### Challenge
- Current branch: fix/flashlight-fireserver
- Open issues: 7 (from stack-audit)
- Open PRs: 2 (from stack-audit)

### Templates
- Issue templates: bug-report.yml (auto-labels: bug, area:backend), feature-request.yml
- PR template: .github/PULL_REQUEST_TEMPLATE.md (required: Summary, Closes, AC)

### Tests
- Test commands: lune run scripts/test_core.luau
- Test count: 26 tests across 3 suites
- Coverage tool: none

### CI Checks
- Check names: test (lune), lint (selene), type-check (luau-analyze)
- Required checks: test (lune), type-check (luau-analyze)

### Conventions
- API: OnClientEvent/OnServerEvent for RemoteEvents (NOT .Event)
- Lifecycle: all :Connect() stored + disconnected in KnitDestroy
- Constants: no magic numbers — all in Constants.luau as UPPER_SNAKE_CASE
- Testing: mock Players:GetPlayerByUserId → nil for no-op replication
- Rollout: 3-stage (Hidden → Integrated → Cleanup) for new features
- Commit format: conventional commits
- Branch naming: fix/, feature/, docs/

## Stack-Audit Findings
- Orphan PRs: PR #42 "feat: add leaderboard UI"
- Stale Issues: Issue #17 "fix: flashlight :Fire()"
- Close Gaps: PR #38 merged but issue #29 still open
- Escaped Issues: Issue #51 closed, no merged PR
- Library Opportunities: Roact could simplify issue #17

After (compacted, ~800 tokens)

## Compacted Handoff

### Original Request (preserved)
Fix the flashlight tool to use :FireServer() instead of :Fire().

[... ~1200 tokens compacted ...]

### Current State (preserved)
Issue #17 draft at /tmp/issue-body.md — ready to create.

### Compacted Summary
I was working on fix: flashlight uses :FireServer() instead of :Fire().

What I know:
- Stack has 1 orphan PR (#42), 1 stale issue (#17), 1 close gap (PR#38→Issue#29)
- Test command: lune run scripts/test_core.luau — 26 tests pass
- CI checks: test (lune), type-check (luau-analyze) must pass
- Conventions: OnServerEvent for RemoteEvents, --!strict, conventional commits

What I need to do next:
- Run gh issue create with the draft at /tmp/issue-body.md

What I have NOT verified yet:
- CI check names are from context-load — verify against .github/workflows/