Skill · context · compaction
Compact observations
Compact tool results and errors into the smallest string that still enables the next correct action (12-factor #9). Use when tool results are huge, CI logs dump into context, stack traces eat the window, or the goal is being silently truncated.
GET /api/canon/skills/compaction?format=md
The observation is the prompt for the next call. A 40k-token HTML dump is how the goal dies. Errors should say what to try.
When
Every tool return. Compaction is not a later optimization.
Do
- 01
Success is short
ok, path, hash, hunk count. Not the file contents.
- 02
Errors are hints
ERROR code: what failed, what to try next. Not a stack trace.
- 03
Bulk is a pointer
wrote path (N bytes). grep if needed. Cap result size in the tool schema.
Don't
- Return raw HTTP envelopes or Playwright traces.
- Drop the goal to keep the latest tool dump.
- Retry the same failing call without compacting the error.
Hard rules
- Never drop the goal first.
- Tool schemas cap result size; the executor enforces.
- A truncation notice is part of the observation when you must cut.
compact()
python
def compact(observation) -> str:
if observation.kind == "file":
return f"wrote {observation.path} ({observation.bytes} bytes). grep if needed."
if observation.kind == "error":
return f"ERROR {observation.code}: {observation.hint}"
return observation.short
Refuse
- Context hoarding — Raw HTML, full CI logs, six PDFs, entire JSON envelopes stuffed 'just in case'. The goal is the first thing forgotten.
- Silent truncation — The goal is dropped to keep junk observations. The model continues confidently.
- Mega-tool — One function whose argument is a JSON blob of 'whatever'. An untyped shell with extra steps.
Load with this
Load next
Trigger tests
Should fire
- “Tool results are blowing the context”
- “Compact these errors”
- “The CI log is 200k tokens”
Should not
- “Gzip the HTTP responses”
- “Minify the JavaScript bundle”