context-intelligence-tool-design

# Context Intelligence Tool Design Phase 2 specialist skill, called by the context-intelligence-tool-designer agent via self-delegation with `context_depth="none"`, scoped to one signal (or one logical batch of related signals) at a time. ## Companion Reference @context-intelligence:context/context-intelligence-primitives-reference.md The companion contains: - Primitive taxonomy - Reduce-AI-dependency decision order - Shared library + thin wrapper pattern - Routing matrix roles Treat as authoritative reference — do not duplicate. ## Wrapper Form, Specialization & Progressive Discovery (R1–R3) Design depth for *how* a chosen primitive is shaped. These are mode-only design guidance; they point to existing homes rather than restating them. ### R1 — Wrapper form by consumer: **module vs CLI** The shared-library → thin-wrapper *pattern itself* already has a home: it is the mode's **Standing Rule 3** (`modes/context-intelligence.md`). **Do not restate that pattern — point to Standing Rule 3.** R1 adds only the new nuance: once you have a shared library, choose its wrapper form **by who consumes it**: - **An agent consumes it** → wrap the shared library as an Amplifier **module** (agent tool). - **A human or script consumes it** → wrap it as a **CLI** (bash subcommand). Same library, wrapper form chosen by consumer — **module vs CLI** is a consumer decision, not a default. ### R2 — Exploit narrow-domain knowledge When the domain is specific enough, build a **specialized** tool that returns exactly what is needed — avoiding discovery round-trips and bloated tool responses. A narrow, purpose-built result beats a general query the caller must post-process. ### R3 — Progressive over upfront Prefer **progressive discovery + pagination/navigation** over big upfront reads. The operational rules for this (probe-first, ≤3-strategy ladder, head-limited extraction, summarize-and-discard, the call budget) live in the authoritative discipline file — open it on demand: `context-intelligence:context/navigation-budget-discipline.md`. **Do not rephrase those rules here.** > **Guard — event semantics:** Do not restate the event-semantics authority principle here. It > is named once in `context-intelligence:context/context-intelligence-strategy.md` — reference > it there. ## Scope ### In Scope - Classify detection strategy for a signal (deterministic / probabilistic / llm-evaluated / hybrid) - Select the correct Amplifier primitive for the signal - Populate the five enrichment fields: `detection_strategy`, `detection_notes`, `ai_dependency`, `reasoning_requirement`, `suggested_primitive` ### Out of Scope - Investigating signals - Refining concept definitions - Designing evaluation scenarios Anything that cannot be classified due to a vague concept → return a structured gap entry, do not investigate. ## Per-Signal Classification Process ### Step 1: Read the Signal Entry Read the signal entry from `domain-signals.md` — read only that entry, not the full file. ### Step 2: Apply Detection Strategy Tier Decision Apply detection strategy tier decision in the following exact order: **Deterministic first** — event structure parsing only: - Event type presence - Field value match - Count threshold - Time window - Sequence **Probabilistic second** — pattern matching + thresholds: - Regex - Ratio - Shape - Size threshold **LLM-evaluated only if neither deterministic nor probabilistic works.** Before committing to pure LLM-evaluated, ask whether deterministic feature extraction can narrow scope. If yes → choose hybrid. ### Step 3: Shared Library + Thin Wrapper (Deterministic / Probabilistic) For deterministic or probabilistic signals, specify three surfaces of the shared library + thin wrapper pattern: 1. **Shared library function**: `context_intelligence/{signal_name}.py` 2. **Thin module wrapper**: `modules/tool-{signal-name}/` 3. **CLI subcommand**: `scripts/context-intelligence.py --{subcommand-name}` ### Step 4: LLM Signal Declaration (LLM-evaluated / Hybrid) For LLM-evaluated or hybrid signals: - Declare `reasoning_requirement` using routing matrix: `fast` / `general` / `reasoning` / `coding` - Specify the corresponding `model_role` in the artifact recommendation - For hybrid signals: deterministic feature extraction lives in the shared library; the classification call is LLM-dependent ### Step 5: Populate `suggested_primitive` Populate `suggested_primitive` with a complete implementation path: - **Code-based signals**: concrete file paths - **LLM-based signals**: artifact shape (skill / agent with `model_role` / recipe step) ## Detection Strategy Decision Table | Strategy | Definition | Code Pattern | |---|---|---| | Deterministic | Event structure parsing only — no ML, no thresholds, no regex | Field access, type check, count compare, time diff, sequence match | | Probabilistic | Pattern matching + configurable thresholds — regex, ratio, shape, size | `re.match`, ratio calc, size compare, configurable threshold | | LLM-evaluated | Requires language understanding, semantic judgment, or rubric evaluation | Skill or agent call with `model_role` declaration | | Hybrid | Deterministic feature extraction narrows scope, then LLM classifies | Shared lib extracts features; LLM call receives structured input | ## Output Format The following fields are ready to write into `domain-signals.md`: - `detection_strategy` — one of: `deterministic` / `probabilistic` / `llm-evaluated` / `hybrid` - `detection_notes` — brief rationale for the chosen strategy - `ai_dependency` — `none` | `low` | `medium` | `high` - `reasoning_requirement` — routing matrix role: `fast` / `general` / `reasoning` / `coding` (omit for deterministic/probabilistic) - `suggested_primitive` — complete implementation path or artifact shape ## Gap Handling If a signal cannot be classified due to ambiguity (missing definition, unspecified boundary, insufficient probe data): **DO NOT investigate or guess.** Return a structured gap entry as a Markdown section in your result: ```markdown ## Gap [N] — [status: open | resolved] Concept: [name] Gap type: missing-signal | ambiguous-definition | insufficient-data Question: [specific question for facilitator] Blocks: [signal name] | additive Resolution: [filled when resolved] ``` The tool-designer appends the gap entry to `signal-gaps.md` and continues with other signals. Gaps never block progress.