| name | zob-context-discovery |
| description | Use when running, documenting, or reviewing adaptive active search backend context discovery, including zob_context_search, optional ColGREP setup, and grep/find/read fallback behavior. |
ZOB Context Discovery Skill
When to use
Use this skill for:
zob_context_search and zob_context_* discovery workflows.- Active search backend guidance in prompts, docs, or registry entries.
- Optional ColGREP setup/doctor/query UX.
- Reviews of context discovery safety, bounded search output, and exact evidence refs.
Active backend rules
- Prefer
zob_context_search for repo-local discovery when the runtime tool is available.
- When ColGREP is installed and ready, exploratory or natural-language repo discovery MUST start with
zob_context_search/ColGREP before broad grep/find. This includes prompts like “explore this repo”, “where is this mechanism?”, or “find the design/flow”.
- If
zob_context_search is not exposed in the current session/toolset but bash is available, use the compact local wrapper before broad grep: npm run --silent zob:context:query -- --query "<natural language query>" --max-results 6 --max-context-lines 1.
- Do not treat missing native-tool exposure as permission to immediately use broad
rg/grep; the wrapper is the ColGREP path for those sessions.
- Reuse
zob_context_search/ColGREP at context pivot points, not only once at startup: new subsystem/domain, ambiguous or broad file area, fallback_status suggesting narrower paths, repeated low-signal grep/find, unfamiliar code before edits, or unknown validation/test failure.
- Use grep/find/read after semantic discovery for exact proof, known identifiers/strings, final citations, and line refs. If the exact identifier/path/string is already known, grep/read may be used directly.
- When ColGREP is missing, unavailable, or not indexed, fall back to grep/find/read. Missing ColGREP is not a blocker for normal ZOB work.
- Do not auto-install ColGREP, run network/package-manager installer commands, or mutate user tooling without explicit owner approval.
- Keep search bounded to repo-local allowed paths and task-relevant globs.
- Never run broad grep/find over
.pi unless .pi/sessions and .pi/agent-sessions are explicitly excluded/pruned.
- Never read forbidden paths or secret-like files, including
.env, **/.env, **/*secret*, **/*key*, private keys, .pi/sessions, .pi/agent-sessions, node_modules, dist, or build.
- Persist only safe metadata/artifact refs for context packs. Do not persist raw secret/session bodies.
User setup and scripts
npm run zob:context:doctor checks the active backend, reports config/status, and prints install/setup guidance without installing anything.npm run zob:context:init may initialize safe ColGREP settings/indexing only when ColGREP is already installed and the owner runs it deliberately.npm run zob:context:query -- <query> runs a one-shot context query, preferring ColGREP when ready and using grep fallback otherwise.npm run smoke:context-discovery validates deterministic fallback behavior and should pass even when ColGREP is absent.
Prompt injection posture
- Active-backend prompt injection is controlled by
.pi/context-discovery.json under promptInjection.enabled.
- The injected block must stay concise, current-repo scoped, and bounded by the configured include/exclude roots; it is a discovery hint, not a context pack or evidence source.
- Do not inject stale/global context or raw search results into the prompt. Use
zob_context_search or the compact npm run --silent zob:context:query wrapper, then read exact files when details are needed.
UX / performance posture
- Native
zob_context_search execution must remain async/non-blocking from the Pi extension perspective; avoid synchronous long-running ColGREP calls in tool handlers.
- Default discovery output should be compact: a small set of refs/previews, then read exact files. Do not dump raw ColGREP JSON or code bodies into the chat by default.
Evidence expectations
- Cite repo-relative paths and line refs when available.
- Treat semantic/broad search hits as leads until exact grep/read verification confirms the behavior.
- Include provider/fallback metadata in readiness claims when relevant.
- If context discovery cannot search a required path because of scope or forbidden-path policy, report a blocker instead of broadening silently.
Oracle / no-ship criteria
No-ship for context discovery if any of these remain true:
- forbidden sources or secret/session/vendor/build paths are read, indexed intentionally, or returned as results;
- ColGREP setup requires unapproved network/package-manager/installer commands;
- missing ColGREP blocks normal ZOB operation instead of using fallback;
- dynamic prompt injection includes stale/global context, raw search bodies, or unbounded output;
- implementation claims rely on semantic hits without exact grep/read/file-ref verification;
- context freshness or citation coverage cannot be shown for files used as evidence.
