---
name: context-intelligence-tool-design
version: 1.0.0
description: Use when selecting a detection strategy and implementation primitive for a context-intelligence signal. Classifies signals as deterministic, probabilistic, llm-evaluated, or hybrid, and applies the cheapest-sufficient-capability principle.
user-invocable: false
allowed-tools: read_file, glob, grep, delegate, load_skill, todo
model_role: reasoning
license: MIT
---
# 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.