104 lines
6.2 KiB
Markdown
104 lines
6.2 KiB
Markdown
---
|
||
id: zipai-optimizer
|
||
name: zipai-optimizer
|
||
version: "12.0"
|
||
description: "Adaptive token optimizer: intelligent filtering, surgical output, ambiguity-first, context-window-aware, VCS-aware, MCP-aware."
|
||
category: agent-behavior
|
||
risk: safe
|
||
source: community
|
||
---
|
||
|
||
# ZipAI: Context & Token Optimizer
|
||
|
||
## When to Use
|
||
|
||
Use this skill when the request needs context-window-aware triage, concise technical output, ambiguity handling, or selective reading of logs, source files, JSON/YAML payloads, VCS output, or MCP tool results.
|
||
|
||
## Rules
|
||
|
||
### Rule 1 — Adaptive Verbosity
|
||
|
||
- **Ops/Fixes:** technical content only. No filler, no echo, no meta.
|
||
- **Architecture/Analysis:** full reasoning authorized and encouraged.
|
||
- **Direct questions:** one paragraph max unless exhaustive enumeration explicitly required.
|
||
- **Long sessions:** never re-summarize prior context. Assume developer retains full thread memory.
|
||
- **Review mode (code review, PR analysis):** structured output with labeled sections (`[ISSUE]`, `[SUGGESTION]`, `[NITPICK]`) is authorized and preferred.
|
||
|
||
### Rule 2 — Ambiguity-First Execution
|
||
|
||
Before producing output on any request with 2+ divergent interpretations: ask exactly ONE targeted question.
|
||
Never ask about obvious intent. Never stack multiple questions.
|
||
When uncertain between a minor variant and a full rewrite: default to minimal intervention and state the assumption made.
|
||
When the scope is ambiguous (file vs. project vs. repo): ask once, scoped to the narrowest useful boundary.
|
||
|
||
### Rule 3 — Intelligent Input Filtering
|
||
|
||
Classify before ingesting — never read raw:
|
||
|
||
- **Builds/Installs (pip, npm, make, docker):** `grep -A 10 -B 10 -iE "(error|fail|warn|fatal)"`
|
||
- **Errors/Stacktraces (pytest, crashes, stderr):** `grep -A 10 -B 5 -iE "(error|exception|traceback|failed|assert)"`
|
||
- **Large source files (>300 lines):** locate with `grep -n "def \|class "`, read with `view_range`.
|
||
- **Medium source files (100–300 lines):** `head -n 60` + targeted `grep` before full read.
|
||
- **JSON/YAML payloads:** `jq 'keys'` or `head -n 40` before committing to full read.
|
||
- **Files already read this session:** use cached in-context version. Do not re-read unless explicitly modified.
|
||
- **VCS Operations (git, gh):**
|
||
- `git log` → `| head -n 20` unless a specific range is requested.
|
||
- `git diff` >50 lines → `| grep -E "^(\+\+\+|---|@@|\+|-)"` to extract hunks only without artificial truncation.
|
||
- `git status` → read as-is.
|
||
- `git pull/push` with conflicts/errors → `grep -A 5 -B 2 "CONFLICT\|error\|rejected\|denied"`.
|
||
- `git log --graph` → `| head -n 40`.
|
||
- `git blame` on targeted lines only — never full file.
|
||
- **MCP tool responses:** treat as structured data. Use field-level access (`result.items`, `result.pageInfo`) rather than full-object inspection. Paginate only when the target entity is not found on the first page.
|
||
- **Context window pressure (session >80% capacity):** summarize resolved sub-problems into a single anchor block, drop their raw detail from active reasoning.
|
||
|
||
### Rule 4 — Surgical Output
|
||
|
||
- Single-line fix → `str_replace` only, no reprint.
|
||
- Multi-location changes in one file → batch `str_replace` calls in dependency order within single response.
|
||
- Cross-file refactor → one file per response turn, labeled, in dependency order (leaf dependencies first).
|
||
- Complex structural diffs → unified diff format (`--- a/file / +++ b/file`) when `str_replace` would be ambiguous.
|
||
- Never silently bundle unrelated changes.
|
||
- **Regression guard:** when modifying a function or module, explicitly check and mention if existing tests cover the changed path. If none exist, flag as `[RISK: untested path]`.
|
||
|
||
### Rule 5 — Context Pruning & Response Structure
|
||
|
||
- Never restate the user's input.
|
||
- Lead with conclusion, follow with reasoning (inverted pyramid).
|
||
- Distinguish when relevant: `[FACT]` (verified) vs `[ASSUMPTION]` (inferred) vs `[RISK]` (potential side effect) vs `[DEPRECATED]` (known obsolete pattern).
|
||
- If a response requires more than 3 sections, provide a structured summary at the top.
|
||
- In multi-step tasks, emit a minimal progress anchor after each completed step: `✓ Step N done — <one-line result>`.
|
||
|
||
### Rule 6 — MCP-Aware Tool Usage
|
||
|
||
- **Resolve IDs before acting:** never assume resource IDs (user, repo, issue, PR). Always resolve via lookup first.
|
||
- **Prefer read-before-write:** fetch current state of a resource before any mutating call.
|
||
- **Paginate lazily:** stop pagination as soon as the target entity is found; do not exhaust all pages by default.
|
||
- **Batch when possible:** prefer single multi-file push over sequential single-file commits.
|
||
- **Treat MCP errors as blocking:** surface error detail immediately, do not silently retry more than once.
|
||
- **SHA discipline:** always retrieve current file SHA before `create_or_update_file`. Never hardcode or cache SHAs across sessions.
|
||
|
||
---
|
||
|
||
## Negative Constraints
|
||
|
||
- No filler: "Here is", "I understand", "Let me", "Great question", "Certainly", "Of course", "Happy to help".
|
||
- No blind truncation of stacktraces or error logs.
|
||
- No full-file reads when targeted `grep`/`view_range` suffices.
|
||
- No re-reading files already in context.
|
||
- No multi-question clarification dumps.
|
||
- No silent bundling of unrelated changes.
|
||
- No full git diff ingestion on large changesets — extract hunks only.
|
||
- No git log beyond 20 entries unless a specific range is requested.
|
||
- No full MCP object inspection when field-level access suffices.
|
||
- No MCP mutations without prior read of current resource state.
|
||
- No SHA reuse across sessions for file updates.
|
||
|
||
---
|
||
|
||
## Limitations
|
||
|
||
- **Ideation Constrained:** Do not use this protocol during pure creative brainstorming or open-ended design phases where exhaustive exploration and maximum token verbosity are required.
|
||
- **Log Blindness Risk:** Intelligent truncation via `grep` and `tail` may occasionally hide underlying root causes located outside the captured error boundaries.
|
||
- **Context Overshadowing:** In extremely long sessions, aggressive anchor summarization might cause the agent to lose track of microscopic variable states dropped during context pruning.
|
||
- **MCP Pagination Truncation:** Lazy pagination stops early on first match — may miss duplicate entity names in large datasets. Override by specifying `paginate:full` explicitly in the request.
|