> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Trigger Execution

> Understanding multiple triggers, event merging, priority queuing, and slash command behavior in Overcut workflows.

Advanced reference for how Overcut manages multiple triggers, prevents conflicts, and handles complex execution scenarios.

<Note>
  For basic trigger setup, see [Triggers](/docs/workflows/triggers) and [Workflow Execution Control](/docs/workflows/workflow-execution-control).
</Note>

***

## Multiple Trigger Behavior

<CardGroup cols={2}>
  <Card title="Mention Triggers" icon="at">
    Any `@overcut` mention triggers ALL workflows with mention trigger type.
  </Card>

  <Card title="Slash Commands" icon="terminal">
    Each slash command triggers only its specific workflow and can terminate active agent steps.
  </Card>

  <Card title="Sequential Execution" icon="list-ol">
    All workflows for the same PR/issue run one at a time, ordered by priority.
  </Card>

  <Card title="Event Merging" icon="compress">
    Multiple triggers of the same queued workflow merge into a single execution.
  </Card>
</CardGroup>

## Key Concepts

### **Trigger Specificity**

* **Mention (`@overcut`)**: Triggers ALL mention workflows regardless of text after mention
* **Slash Command (`/review`)**: Triggers only the specific workflow registered for that command
* **Event Triggers**: Each workflow has one primary trigger type (e.g., `pull_request_opened`)

### **Slash Command Termination**

Slash commands have special power to interrupt active work:

<Steps>
  <Step title="Graceful Termination">
    Active agent steps (both `agent.run` and `agent.session`) receive termination signal
  </Step>

  <Step title="Grace Period">
    Agents get 5 minutes to complete current operation before stopping
  </Step>

  <Step title="Session Cleanup">
    Active sessions are cleared immediately and stop receiving new comments
  </Step>

  <Step title="New Workflow">
    Slash command workflow queues or starts normally
  </Step>
</Steps>

**Example:**

```
User: "@overcut help with this bug"  → Session starts
User: "Can you explain line 45?"     → Routes to session
User: "/review"                      → Terminates session, starts review
```

***

## Parallel Execution & Locking

### **Resource-Based Locking**

Overcut ensures workflows don't conflict by locking execution per resource:

<CardGroup cols={2}>
  <Card title="Sequential per Resource" icon="list-ol">
    Only one workflow runs per issue/PR at a time to prevent conflicts
  </Card>

  <Card title="Parallel Across Resources" icon="arrows-split-up-and-left">
    Different issues/PRs can run workflows simultaneously
  </Card>
</CardGroup>

### **How Locking Works**

**Same Resource = Sequential Execution:**

```yaml theme={"dark"}
# All workflows for PR #123 run one at a time
PR #123 opened     → Starts immediately
Comment on PR #123 → Queued (waits for first to finish)
Label on PR #123   → Queued (waits in line)
Review on PR #123  → Queued (waits in line)
```

**Different Resources = Parallel Execution:**

```yaml theme={"dark"}
# These run simultaneously
PR #123 workflow   ✅ Running
Issue #456 workflow ✅ Running  
PR #789 workflow   ✅ Running
```

***

## Queue Management & Deduplication

### **Intelligent Event Merging**

When the same workflow is triggered multiple times while queued, events automatically merge to prevent redundant executions:

<Steps>
  <Step title="Duplicate Detection">
    System checks if the same workflow is already queued for the same lock key
  </Step>

  <Step title="Event Merging">
    New trigger merges with existing queued workflow instead of creating duplicate
  </Step>
</Steps>

### **Priority-Based Processing**

Queued workflows are processed by priority, then first-in-first-out:

| Priority      | Description        | Processing Order |
| ------------- | ------------------ | ---------------- |
| `1` (High)    | Critical workflows | Processed first  |
| `5` (Default) | Standard workflows | Default priority |
| `10` (Low)    | Background tasks   | Processed last   |

### **Automatic Deduplication**

When the same workflow is triggered multiple times while queued, events automatically merge:

```yaml theme={"dark"}
# Example: Auto-triage workflow with issue_labeled trigger
10:01 - Label "bug" added     → Execution starts (running)
10:02 - Label "critical" added → Queued (first still running)  
10:03 - Label "security" added → Merged with queued execution
10:05 - First completes       → Queued execution runs with all labels
```

***

## Advanced Queue Features

### **Delayed Execution**

Workflows can be configured with delays to batch rapid events:

```yaml theme={"dark"}
name: "Batch Comment Analysis"
trigger:
  type: "issue_commented"
  settings:
    delaySeconds: 30  # Wait 30 seconds before processing

steps:
  - name: "analyze-comments"
    type: "agent"
    instruction: "Analyze recent comment activity"
```

**Benefits:**

* Batches rapid-fire events (multiple comments, labels)
* Reduces redundant executions
* Allows time for related events to merge

### Priority Configuration

Control execution order with priority settings (1-100 scale):

| Priority  | Use Case           | Example                           |
| --------- | ------------------ | --------------------------------- |
| **1-3**   | Critical workflows | Security scans, incident response |
| **4-6**   | Normal workflows   | Code reviews, standard automation |
| **7-100** | Background tasks   | Documentation, metrics collection |

```yaml theme={"dark"}
name: "Security Scan"
priority: 1  # Runs first
trigger:
  type: "pull_request_opened"
```

### Multiple Mention Workflows

If you have multiple workflows with `mention` trigger, **all** will be triggered by any `@overcut` mention:

```yaml theme={"dark"}
# Both triggered by "@overcut help me"
- name: "Quick Help" (priority: 5)
- name: "Full Analysis" (priority: 8)
```

**Solution**: Use slash commands for specificity:

* `/help` → triggers only Quick Help
* `/analyze` → triggers only Full Analysis

### Event Sequence Example

```
10:01 - PR opened           → "Initial Review" starts (priority: 5)
10:02 - Label "security"    → "Security Scan" queued (priority: 1)  
10:03 - Comment "@overcut"  → "Help" queued (priority: 5)
10:05 - Initial Review done → Security Scan starts (highest priority)
10:07 - Security Scan done  → Help starts
```

***

## Custom Event Lock Keys

[Custom Events](/docs/integrations/custom-events) share the same dispatcher queue and merging behavior as built-in triggers, but the caller controls the lock scope via the optional `?lockKey=` query parameter.

| Caller URL                    | Lock key the dispatcher uses                                   |
| ----------------------------- | -------------------------------------------------------------- |
| No `lockKey`                  | `custom:<eventId>:<requestId>` (unique per call, never merges) |
| `?lockKey=X`                  | `custom:<eventId>:X`                                           |
| `?projectId=P&lockKey=X`      | `custom:<eventId>:P:X`                                         |
| `?projectId=P` (no `lockKey`) | `custom:<eventId>:P:<requestId>`                               |

Two implications:

* Two calls to **different** projects with the same `lockKey` run in parallel: the project ID is folded into the key.
* When `projectId` is omitted (workspace-wide fan-out from a single inbound call), the matched workflows across all allowed projects serialize together under the shared scope, because they represent a single real-world occurrence.

`lockKey` must match `^[A-Za-z0-9_.\-:]{1,128}$`. Invalid values return `400 lockkey_invalid` from the dispatcher.

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Priorities Wisely" icon="sort">
    Reserve 1-3 for critical workflows, use default (5) for most cases.
  </Card>

  <Card title="Design for Interruption" icon="hand">
    Expect users to use slash commands to change direction mid-workflow.
  </Card>

  <Card title="Leverage Merging" icon="merge">
    Trust automatic event merging to reduce redundant executions.
  </Card>

  <Card title="Choose Right Triggers" icon="target">
    Use slash commands for specific actions, mentions for general help.
  </Card>
</CardGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="Can workflows run in parallel on different PRs?">
    Yes! Sequential execution only applies to the same PR or issue. Different resources can have workflows running simultaneously.
  </Accordion>

  <Accordion title="When does event merging happen?">
    Only when a workflow is **queued** (waiting to run), not while it's **running**. If workflow A is running and triggered twice more, the second trigger queues and the third merges with it.
  </Accordion>

  <Accordion title="How do I stop an agent step early?">
    You can terminate agent steps using either comments or UI controls:

    **Via Comments:**

    * **`/done`**: Completes the current agent session step and continues to the next workflow step
    * **`/quit`**: Terminates the entire workflow immediately

    **Via UI (Execution Logs):**

    * **Complete Step** button: Requests the agent to complete and return results ASAP
    * **Quit Workflow** button: Terminates all running steps and marks the workflow as canceled

    Comment commands are processed immediately before the agent receives them, while UI buttons send termination requests to the running agent.
  </Accordion>

  <Accordion title="What's the difference between mentions and slash commands?">
    * **Mentions (`@overcut`)**: Trigger all mention workflows, route to active sessions
    * **Slash commands (`/review`)**: Trigger specific workflow, terminate active agent steps
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Interactive Sessions" icon="comments" href="/docs/reference/interactive-sessions">
    Session behavior and comment routing mechanics
  </Card>

  <Card title="Slash Commands" icon="terminal" href="/docs/workflows/trigger-with-slash-command">
    Setting up and using slash command triggers
  </Card>

  <Card title="Basic Triggers" icon="bolt" href="/docs/workflows/triggers">
    Trigger types and basic configuration
  </Card>

  <Card title="Execution Control" icon="gears" href="/docs/workflows/workflow-execution-control">
    Resource locking and queue management
  </Card>
</CardGroup>