context-intelligence-tool-design

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/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:

## 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.