Intent

Scan data sources to determine whether a specified pattern, entity, or condition is present. Detection is binary (present/absent) with associated signal strength.

Success criteria:

• Clear boolean determination of presence/absence
• At least one evidence anchor for positive detections
• False positive risk assessment provided
• Confidence score justified by evidence quality

Compatible schemas:

• schemas/output_schema.yaml

Inputs

Procedure

1. Define detection criteria: Clarify exactly what constitutes a positive detection

   • Convert vague patterns to concrete search terms or regex
   • Establish minimum evidence threshold for positive detection

2. Scan target systematically: Search the target data for matching signals

   • Use Grep for text patterns with appropriate flags (-i for case-insensitive, etc.)
   • Use Read for structural inspection when pattern requires context
   • Record location (file:line) for each potential match

3. Evaluate signal strength: For each match, assess how strongly it indicates true presence

   • Strong: exact match with clear context
   • Medium: partial match or ambiguous context
   • Weak: possible match requiring human verification

4. Assess false positive risk: Determine likelihood that detections are spurious

   • High risk: generic patterns, noisy data, few matches
   • Low risk: specific patterns, clean data, multiple corroborating signals

5. Ground claims: Attach evidence anchors to all detection signals

   • Format: file:line for file-based targets
   • Include snippet of matched content for verification

6. Format output: Structure results according to the output contract below

Output Contract

Return a structured object:

yaml
1detected: boolean  # True if pattern/entity was found
2target_type: string  # What was being detected (e.g., "security vulnerability", "deprecated API")
3signals:
4  - signal: string  # Description of what was found
5    strength: low | medium | high  # Signal strength
6    location: string  # file:line or path where found
7false_positive_risk: low | medium | high  # Likelihood of spurious detection
8confidence: number  # 0.0-1.0 based on evidence quality
9evidence_anchors: array[string]  # File:line references
10assumptions: array[string]  # Explicit assumptions made
11next_actions: array[string]  # 0-3 suggested follow-ups if uncertain

Field Definitions

Examples

Example 1: Detect SQL Injection Vulnerability

Input:

yaml
1target: src/api/user_controller.py
2pattern: "SQL injection pattern"
3threshold:
4  min_matches: 1

Output:

yaml
1detected: true
2target_type: "SQL injection vulnerability"
3signals:
4  - signal: "String concatenation in SQL query with user input"
5    strength: high
6    location: "src/api/user_controller.py:47"
7  - signal: "Raw SQL execution without parameterization"
8    strength: medium
9    location: "src/api/user_controller.py:52"
10false_positive_risk: low
11confidence: 0.85
12evidence_anchors:
13  - "src/api/user_controller.py:47"
14  - "src/api/user_controller.py:52"
15assumptions:
16  - "User input flows from request.params to query variable"
17  - "No input sanitization in calling function"
18next_actions:
19  - "Verify data flow from user input to SQL query"
20  - "Check for parameterized query alternatives in codebase"

Evidence pattern: Grep for SQL keywords combined with string formatting patterns, then Read to verify context.

Example 2: Detect Deprecated API Usage

Input:

yaml
1target: src/
2pattern: "componentWillMount|componentWillReceiveProps"
3scope: "*.jsx,*.tsx"

Output:

yaml
1detected: true
2target_type: "deprecated React lifecycle method"
3signals:
4  - signal: "componentWillMount usage"
5    strength: high
6    location: "src/components/Dashboard.jsx:23"
7false_positive_risk: low
8confidence: 0.95
9evidence_anchors:
10  - "src/components/Dashboard.jsx:23"
11assumptions:
12  - "Project uses React 16.3+ where these methods are deprecated"
13next_actions:
14  - "Migrate to componentDidMount or useEffect hook"

Verification

• Output contains detected boolean matching signal presence
• At least one evidence anchor exists for positive detections
• Confidence score correlates with number and strength of signals
• All referenced file:line locations are valid and accessible
• False positive risk assessment is justified

Verification tools: Read (to verify file:line references exist)

Safety Constraints

• mutation: false
• requires_checkpoint: false
• requires_approval: false
• risk: low

Capability-specific rules:

• Do not access paths outside the specified target scope
• Do not modify any files during detection
• Stop and request clarification if detection criteria are ambiguous
• Report uncertainty rather than guessing when signals are weak

Composition Patterns

Commonly follows:

• inspect - Detection often follows initial observation of a system
• search - Detection may refine broad search results

Commonly precedes:

• identify - Positive detection often leads to classification of what was found
• estimate-risk - Detection of anomalies feeds into risk assessment
• plan - Detected issues may trigger remediation planning

Anti-patterns:

• Never use detect for complex entity classification (use identify instead)
• Avoid detect for quantitative assessment (use estimate instead)

Workflow references:

• See reference/composition_patterns.md#risk-assessment for detection in risk workflows
• See reference/composition_patterns.md#observe-model-act for detection in agentic loops