synaptiai/agent-capability-standard/detect

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

Inputs not listed here are outside the capability's contract: a workflow step that binds them gets W604 (STANDARD v1.1 §5.5).

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:

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

Field Definitions

Examples

Example 1: Detect SQL Injection Vulnerability

Input:

data: src/api/user_controller.py
pattern: "SQL injection pattern"
threshold: 0.5  # report matches with at least this confidence

Output:

detected: true
target_type: "SQL injection vulnerability"
matches:
  - signal: "String concatenation in SQL query with user input"
    strength: high
    location: "src/api/user_controller.py:47"
  - signal: "Raw SQL execution without parameterization"
    strength: medium
    location: "src/api/user_controller.py:52"
locations:
  - "src/api/user_controller.py:47"
  - "src/api/user_controller.py:52"
false_positive_risk: low
confidence: 0.85
evidence_anchors:
  - "src/api/user_controller.py:47"
  - "src/api/user_controller.py:52"
assumptions:
  - "User input flows from request.params to query variable"
  - "No input sanitization in calling function"
next_actions:
  - "Verify data flow from user input to SQL query"
  - "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:

data: "src/**/*.{jsx,tsx}"
pattern: "componentWillMount|componentWillReceiveProps"

Output:

detected: true
target_type: "deprecated React lifecycle method"
matches:
  - signal: "componentWillMount usage"
    strength: high
    location: "src/components/Dashboard.jsx:23"
locations:
  - "src/components/Dashboard.jsx:23"
false_positive_risk: low
confidence: 0.95
evidence_anchors:
  - "src/components/Dashboard.jsx:23"
assumptions:
  - "Project uses React 16.3+ where these methods are deprecated"
next_actions:
  - "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 matches
• [ ] 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