What the Rules Engine Does

The rules engine is a filter layer between scoring and the proposal pipeline. After Prospector scores a batch of leads, the rules engine evaluates each one against your custom rules and decides what happens next: pass the lead through, exclude it, flag it for priority review, or auto-submit it to the proposal pipeline.

Rules give you precise control that scoring alone cannot provide. A lead might score well on all signals but still be wrong for you because it requires on-site work, uses a technology you avoid, or comes from a region where payment processing is unreliable. Rules handle these edge cases.

Rule Structure

Each rule has a condition and an action. Conditions are boolean expressions that test lead attributes. Actions determine what happens when the condition matches.

# ~/.ghoststack/prospector.yaml (rules excerpt)
rules:
  - name: 'exclude-low-budget'
    condition:
      field: 'job.budget.amount'
      operator: 'lt'
      value: 500
    action: 'exclude'

  - name: 'priority-repeat-client'
    condition:
      field: 'client.previous_contracts'
      operator: 'gt'
      value: 0
    action: 'priority'

  - name: 'exclude-keyword'
    condition:
      field: 'job.description'
      operator: 'contains'
      value: 'wordpress theme'
    action: 'exclude'

Supported Operators

Conditions support the following operators:

Operator	Description	Applicable Types
eq	Equal to	string, number, boolean
neq	Not equal to	string, number, boolean
gt	Greater than	number
gte	Greater than or equal	number
lt	Less than	number
lte	Less than or equal	number
contains	Substring match (case-insensitive)	string
not_contains	Substring exclusion	string
in	Value in list	string, number
not_in	Value not in list	string, number
matches	Regex pattern	string

Compound Conditions

You can combine multiple conditions using all (logical AND) or any (logical OR):

rules:
  - name: 'high-value-verified-client'
    condition:
      all:
        - field: 'job.budget.amount'
          operator: 'gte'
          value: 2000
        - field: 'client.verified'
          operator: 'eq'
          value: true
    action: 'auto_submit'

Nesting is supported up to three levels deep. If you find yourself needing deeper nesting, consider splitting the logic into multiple rules with a shared tag for organization.

Actions

Four actions are available:

• exclude: removes the lead from results entirely. It will not appear in scans or the dashboard.
• priority: moves the lead to the top of your review queue and optionally triggers a notification.
• auto_submit: sends the lead directly to the proposal pipeline without manual review. Use with caution.
• tag: attaches a label to the lead for filtering in the dashboard. Does not change the lead’s pipeline behavior.

Evaluation Order

Rules are evaluated in the order they appear in your configuration. The first exclude match removes the lead immediately, and no further rules are evaluated for that lead. priority, auto_submit, and tag actions do not short-circuit; all matching rules of these types are applied.

If you have both broad exclusion rules and narrow inclusion rules, put the inclusion rules first. A lead excluded by an earlier rule never reaches a later rule that might have flagged it as a priority.

Testing Rules

Before deploying a new rule, test it against your existing lead history:

# Dry-run a rule against the last 50 leads
ghoststack prospector rules test --rule "exclude-low-budget" --count 50

The test command shows which leads would have been affected and how, without modifying any actual data. This helps you avoid accidentally filtering out good leads with an overly broad rule.