Prompt Compression Guide

# Compressing prose into an SWE/SDE-proof prompt

The goal isn't just "shorter" — a shorter prompt that's now ambiguous costs the user more tokens overall, because the coding agent will burn a turn asking a clarifying question, or worse, silently guess wrong and burn many turns fixing it. Compression should remove words, never remove information the agent needs to act correctly on the first pass.

## Cut freely

These add tokens without adding information an autonomous agent needs:

- **Hedging and filler**: "I was thinking maybe it would be good if...", "just wondering if you could possibly...", "not sure if this makes sense but..." → state the requirement directly.
- **Pleasantries and meta-commentary**: "thanks so much", "let me know what you think", "I really appreciate it" → drop entirely from the agent-facing prompt.
- **Restated context**: if the same constraint or fact is mentioned three times in three different paragraphs (common when someone writes a prompt stream-of-consciousness), state it once, in the place it's most load-bearing.
- **Narrated reasoning that doesn't change the ask**: "I've been going back and forth on whether to use X or Y, and I think I've landed on X because..." → just say "Use X." (the reasoning trail is for the human's own thinking, not something the agent needs to execute the task).
- **Passive/roundabout phrasing**: "It would be great if the function could be made to handle..." → "Handle..." Imperative voice is both shorter and more directly actionable for an agent.

## Never cut

These are exactly the details that separate a prompt an agent can execute unsupervised from one that generates a plausible-looking wrong answer:

- **Exact identifiers**: file paths, function/class/variable names, table/column names, env var names, branch names, package versions. An agent guessing at these produces code that doesn't compile, doesn't match the codebase, or silently does the wrong thing.
- **Constraints and boundaries**: anything phrased as "must not", "don't touch", "keep backwards compatible", "no new dependencies", performance/security requirements. These are cheap to state and expensive to violate.
- **Acceptance/done criteria**: what test to run, what output to check, what "finished" looks like. Without this an agent (and the human reviewing its work) can't tell success from failure.
- **Order-dependent steps**: if step 3 depends on step 2's output, keep them as separate ordered steps rather than merging into one compressed instruction that loses the dependency.
- **Edge cases the user explicitly called out**: if they mentioned a specific failure mode, empty-input behavior, or gotcha, that's usually there because they hit it before or know the codebase has a sharp edge there — don't fold it into a generic instruction.

## If something looks ambiguous, don't resolve it silently

If, while compressing, you notice the original prompt is genuinely unclear about something material — e.g. it never says which of two similarly-named files to edit, or leaves the expected output format unstated — that's not something to "helpfully" infer during compression. Flag it back to the user as a specific open question alongside the compressed prompt, rather than picking an interpretation and burying it. A compressed prompt that silently resolved an ambiguity looks *more* confident and complete than the original, which is worse than the original being visibly vague.

## Before/after pattern

**Before** (typical heavy prompt):
> So I've been working on this API and I think there might be an issue with how we're handling pagination, like sometimes when you request page 2 it seems to return some of the same results from page 1? I'm not 100% sure if that's actually happening or if I'm misreading the response, but if you could take a look at the pagination logic, probably in the controller or maybe the service layer, and see if there's an off-by-one error or something like that, and fix it if you find something, that would be really helpful. Also while you're in there it would be great if you could add some basic tests for the pagination if there aren't any already, just to make sure this doesn't happen again in the future. Thanks!

**After**:
> Bug: paginated API results overlap between page 1 and page 2 (suspected off-by-one). Investigate `controller` and `service` layers for the pagination logic. Fix the root cause if found. Add tests covering page-boundary correctness if none exist. Done when: page N and page N+1 return disjoint result sets, verified by a passing test.

Note what survived: the specific symptom (overlap between page 1/2), the suspected cause (off-by-one), where to look (controller/service), and explicit done-criteria (disjoint results, test passing). What got cut: the hedging ("I'm not 100% sure"), the narrated uncertainty, and the pleasantries — none of which changes what the agent should do.