Context Buffer

Core Principles

• Never stream large raw outputs directly into the conversation when not strictly necessary.
• Batch first: prefer grouping related operations into one batch and summarizing, instead of many small calls.
• Index for retrieval: for big texts/logs/docs, create a local index and query it, instead of re-reading the whole file.
• Return summaries + handles: surface a short summary and a stable reference (path/id) so future queries can target only what they need.

This skill describes behavioral patterns for the agent and conventions for future scripts/assets. It does not require any specific runtime.

Behavioral Patterns for the Agent

Use these patterns whenever you:

• read large files/logs (thousands of lines),
• inspect big diffs or repo history,
• would otherwise paste a lot of text back to the user.

1. Summarize Instead of Dumping

When you read a large file/log:

1. Skim/parse it internally.
2. Respond with:
   • a concise bullet summary of key findings,
   • optional small targeted snippets (a few lines each) showing the most relevant parts.
3. Offer to drill down into specific sections on demand, instead of preemptively dumping everything.

Example response pattern:

• "Нашёл 3 ключевые ошибки в логе, кратко:"
• Затем 3–5 буллетов + по 3–7 строк вокруг самой важной ошибки.

2. Batch Related Operations

When multiple related commands or fetches are needed (e.g., several web_search / web_fetch / file reads):

• Group them conceptually into one "batch step".
• Perform all underlying reads/fetches.
• Return один сводный ответ с:
  • общей картиной,
  • списком источников/файлов, которые смотрели,
  • кратким сравнением/диффом.

Avoid a chain of near-identical responses that each restate context.

3. Think in Terms of Handles

Even без отдельного runtime применяй ментальную модель "handle":

• когда опираешься на большой файл/лог, явно называй его:
  • handle: logs/nginx-2026-03-04.log,
  • или handle: git-diff HEAD~10..HEAD.
• в дальнейших ответах ссылайся на этот handle вместо пересказа всего содержимого.

Формат ссылки в ответе:

(анализирую: handle: path/to/file — детали не повторяю, только ключевые фрагменты)

4. Targeted Snippets via Search-Style Thinking

Когда пользователю нужны детали:

• вместо "вот весь файл",
• находи нужные участки по ключевым словам/паттернам,
• возвращай только небольшие окна вокруг совпадений.

Практический алгоритм:

1. Определи поисковый запрос (ошибка, функция, ID).
2. Внутренне найди вхождения.
3. Для каждого вхождения верни 3–7 строк контекста вокруг.
4. Если вхождений много — ограничься 3–5 самыми репрезентативными и скажи об этом.

5. Progressive Disclosure

Если пользователь не просил подробно:

• давай компактный summary,
• явно указывай, что детали можно запросить ("могу показать конкретные фрагменты по X/Y/Z").

Если пользователь просит глубину по конкретным точкам — тогда раскрывай соответствующие окна.

Conventions for Future Automation

Если позже в этом репо появятся скрипты/skills, реализующие реальный буфер:

• Использовать директорию ./.cache/context-buffer/ для хранения сырых больших вывода.
• Хранить метаданные об этих файлах (handle → путь, тип, размер, теги) в простом JSON (например, ./.cache/context-buffer/index.json).
• Возвращать из таких скриптов компактный объект вида:

{
  "handle": "cb-20260304-001",
  "summary": "3 критические ошибки в nginx логе, 2 предупреждения по upstream timeout",
  "path": ".cache/context-buffer/nginx-2026-03-04.log",
  "meta": { "kind": "log", "source": "nginx", "lines": 12500 }
}

Эти соглашения помогут мне и другим агентам работать с тяжёлыми данными без заливания сырья в контекст.

When to Use This Skill (Triggers)

Используй эти паттерны, когда:

• работаешь с большими логами, репортами, CSV, диффами;
• нужно сделать обзор/исследование репозитория или документации;
• нужно прогнать серию однотипных команд/запросов и собрать общую картинку;
• ответ может легко разрастись до сотен строк.

В нормальных малых кейсах (короткий код, маленький файл) — можно отвечать напрямую без дополнительных слоёв.