Skip to main content
Custom Cache Detection Prompts allow you to completely override the default cache detection logic with your own step-specific validation rules. When set, the system uses only your prompt to determine whether the current screen matches the cached screenshot.
For an introduction to trajectories and how they work, see Trajectories 101. This page focuses specifically on custom cache detection prompts that give you full control over trajectory validation.

​
The Problem

During trajectory replay, the system compares current screen states against cached screenshots to determine if it can safely reuse recorded actions. However, the default cache detection logic might not always know:
  • Which UI elements are critical vs. cosmetic for a specific step
  • What minor differences are acceptable (e.g., timestamps, dynamic content)
  • Special conditions that should invalidate the cache
  • Context about why a particular screen state was captured
Without this context, cache detection may:
  • Reject valid matches due to irrelevant differences (false negatives)
  • Accept invalid matches by missing critical changes (false positives)
  • Require human review to understand failures

​
The Solution

Custom Cache Detection Prompts give you full control over the validation logic. When you set a custom prompt:
  • Full Override: Your prompt completely replaces the default cache detection logic
  • Step-specific: Each trajectory step can have its own custom prompt
  • Human-written: Provide exact validation criteria that automated systems can’t infer
  • Direct Control: You define exactly what constitutes a cache hit vs miss
When a custom prompt is set, it completely replaces the default cache detection logic. The system will only see your prompt along with the two screenshots. You must explicitly define what makes a cache hit vs cache miss.

​
How It Works

​
During Cache Detection

When comparing screen states with a custom prompt:
  1. Capture: System takes a screenshot of the current state (Desktop #2)
  2. Load Cache: Retrieves the cached screenshot from the trajectory (Desktop #1)
  3. Your Prompt: The system receives ONLY your custom prompt (no default logic)
  4. Decision: The system evaluates and returns cache hit or cache miss
The system prompt sent to the cache detection agent is simply: 
Your task is to decide whether desktop #1 is effectively the same as desktop #2, in the context of these instructions:

[Your custom prompt here]
If there are coordinate annotations (red circles on the screenshots), a note is added explaining their purpose.

​
In the Trajectory Editor

You can add or edit custom prompts in the trajectory viewer:
  1. Navigate to a trajectory in the Workflows section
  2. Expand any step to view details
  3. Find the “Custom Cache Detection Prompt (Overrides)” field in the Pre-check Snapshot
  4. Add your prompt with explicit hit/miss criteria
  5. Save changes to update the trajectory

​
Example Use Cases

Since your custom prompt completely overrides the default logic, you must be explicit about what defines a cache hit vs miss.

​
Validating Critical Elements

Cache hit if the "Submit Order" button is visible and enabled.
Cache miss if the button is missing, disabled, or in a different position.
Ignore the order number displayed, as it will differ between runs.

​
Checking Layout Structure

Cache hit if the product list shows exactly 3 items in the same layout.
Cache miss if the item count differs or the layout has changed.
Item names will vary based on parameters - ignore text content, focus on structure.

​
Focus Area Validation

Only validate the left sidebar navigation.
Cache hit if the sidebar shows the same menu items in the same positions.
Cache miss if sidebar items are different or rearranged.
Ignore the main content area entirely - it displays real-time data.

​
Conditional States

Cache hit if EITHER:
- A modal is open showing "Processing..." status, OR
- The modal is closed and a results table is visible

Cache miss if neither condition is met.

​
Form Validation

Cache hit if the form has 4 input fields in vertical layout with labels: Name, Email, Phone, Address.
Cache miss if any field is missing or the layout differs.
Ignore the actual values in the fields - they will differ based on parameters.

​
Best Practices

​
Always Define Both Outcomes

Since you’re overriding all default logic, explicitly state both when it’s a cache hit and when it’s a cache miss. Good: “Cache hit if the dialog is visible. Cache miss if it’s not visible or obscured.” Less Good: “The dialog should be visible”

​
Be Specific About What to Check

Good: “Cache hit if three buttons are arranged horizontally at the bottom of the form.” Less Good: “Check the buttons are correct”

​
Explicitly State What to Ignore

Good: “Ignore timestamps, ‘Last Updated’ labels, and dynamic content. Focus only on the form structure.” Less Good: Assuming the system knows what to ignore

​
Consider Parameter Variations

Good: “The username field will contain different values based on parameters - ignore the actual text, just verify the field exists.” Less Good: “Username should be John”

​
Handle Edge Cases

Good: “Cache hit if either the success modal OR the results table is visible. Cache miss if neither is present.” Less Good: “Something might be wrong”

​
Keep It Clear

Aim for clear, unambiguous criteria. Remember: your prompt is the ONLY guidance the system receives for this step.

​
When to Use Custom Prompts

Consider adding a custom prompt when:
  • A step frequently has false positives or negatives
  • The validation criteria are subtle or nuanced
  • Dynamic content makes default comparison unreliable
  • You’ve observed specific failure patterns
  • The step is critical to workflow success
  • You need precise control over what defines a match
You don’t need custom prompts for every step - only where the default cache detection logic isn’t working well for your use case.

​
Technical Details

​
Data Storage

Custom prompts are stored in the pre_check_snapshot object of each trajectory step: 
{
  "pre_check_snapshot": {
    "screenshot": "...",
    "last_agent_thought": "...",
    "custom_cache_detection_instructions": "Your prompt here",
    "coordinates": [...]
  }
}

​
How Override Works

When a custom prompt is set, the cache detection agent receives: 
Your task is to decide whether desktop #1 is effectively the same as desktop #2, in the context of these instructions:

[Your custom prompt]

Note: Both screenshots have a red circle annotation at the same coordinate to help you identify if the UI has shifted.
The note about red circles is only included if coordinate annotations are present. When no custom prompt is set, the system uses its default cache detection logic which considers UI layout, structure, agent thoughts, and parameterization context.

​
Backward Compatibility

Trajectories without custom prompts continue to work normally using the default cache detection logic. The field is optional and defaults to empty/unset.