FrancoStino/zipai-optimizer

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.