# How we keep deals moving

The pipeline-hygiene agent we run on Kortix — it scans HubSpot every day for stale deals, missing next steps, deals stalled in a stage, and overdue tasks, nudges the owning rep in Slack, and escalates the worst offenders to their manager.

Canonical page: https://openchatly.com/use-cases/pipeline-hygiene

A pipeline decays quietly. A deal goes a week without a call or an email and
nobody notices. A rep forecasts a close date and never sets one. A deal sits in
"Proposal Sent" for a month past when it should have moved. A follow-up task
comes due and slides by unflagged. None of this shows up in a stage-by-stage
pipeline report — the deal is still "open," still counted, still apparently
fine.

We run a pipeline-hygiene agent on Kortix that reads HubSpot every day and
flags exactly this: deals gone quiet, missing next steps and close dates,
deals stuck in their current stage, and tasks past due. It nudges the owning
rep in Slack and escalates the worst of the day to their manager. It is
read-mostly — it flags and it nudges, and it never touches a deal's stage,
owner, or amount.

- **Team:** Kortix
- **CRM:** HubSpot
- **Runs on:** Daily cron
- **Mode:** Read-mostly · nudge + flag only

## The problem

This is a different problem than dirty CRM data. Duplicate contacts and
missing job titles are a data-quality issue; a deal that hasn't moved in
three weeks is a process issue — the pipeline itself is not doing what it's
supposed to do, which is progress toward a close. A stage-by-stage pipeline
report can't tell the difference between a deal that's actively advancing and
one that's been quietly parked, because both show up the same way: "open,"
sitting in a stage, counting toward the forecast.

The usual fix is the weekly pipeline review, where a manager scrolls every
open deal looking for the ones that have gone stale. By the time that meeting
happens, a deal that went quiet on Monday has already lost a week, and the
review only catches what someone remembers to ask about. Reps are heads-down
selling, not auditing their own deal hygiene, and a next-step field or a close
date left blank rarely gets attention until forecast time, when it's too late
to fix cheaply.

## What we built

A daily cron triggers an agent that spawns a fresh, isolated session with
read-mostly access to HubSpot. It pulls every open deal, checks it against
four hygiene rules — no logged activity in the configured window, a missing
next step or close date, no stage movement past the configured window, and any
overdue task tied to the deal — and flags what it finds. It nudges each
owning rep in Slack with exactly what needs attention on their deals, and
separately escalates the day's worst offenders to the sales manager's channel.
It never changes a deal's stage, reassigns its owner, or edits its amount.

## How it works

### Copy the setup prompt into a new session

Open your Kortix workspace, start a new session, paste this prompt and send it.
The agent writes the agent file, the pipeline-hygiene-rules skill and the daily
trigger, and opens a change request for you to review. Prefer clicks? Choose
**Use this template** instead.

**Setup prompt**

```
Set up a daily pipeline-hygiene agent in this workspace.

1. Create the agent agents/pipeline-hygiene.md. Its job is to find open HubSpot deals that need attention and nudge their owners. It may use the HubSpot and Slack connectors.

2. Create the skill skills/pipeline-hygiene-rules/SKILL.md with these rules:
   - A deal is stale when it has no logged call, email, meeting or note in 7 days.
   - A deal is incomplete when it has no next step or no close date.
   - A deal is stalled when its stage has not changed in 21 days. A deal has an overdue task when an open task is past its due date.
   - The only HubSpot write is an internal hygiene flag that names the rules a deal trips. Never change a deal's stage, owner or amount.
   - Send each owning rep one Slack message that lists their flagged deals and the action each one needs.
   - Post the day's worst deals to #sales-management once per run, ranked by rules tripped, then amount, then days since the last activity.

3. Add a cron trigger daily-pipeline-hygiene-scan to kortix.yaml. It runs the pipeline-hygiene agent every day at 06:00 with the prompt "Load the pipeline-hygiene-rules skill and run one complete pipeline-hygiene scan."

4. Tell me which of these connectors are not connected yet.

5. Open a change request with all of it. Do not merge it.
```

### Connect your tools

Open **Connectors** in your workspace and connect your CRM and Slack. Credentials
are brokered server-side and never enter the agent's machine.

- **HubSpot** (Required):
Reads open deals and tasks, and sets the hygiene flag.
- **Slack** (Required):
Nudges each owning rep and escalates the worst deals.

### Run it once with this prompt

Merge the change request, then start a session with the **pipeline-hygiene**
agent and send this prompt. Check the flags and the nudges before you let the
schedule take over.

**Prompt**

```
Run one pipeline-hygiene scan on HubSpot.

1. Read every open deal with its stage, amount, close date, next step, time in stage, activities and open tasks.
2. Flag each deal with no activity in 7 days, no next step or close date, no stage change in 21 days, or an overdue task.
3. Write only the hygiene flag on each flagged deal. Do not change any stage, owner or amount.
4. Send each owning rep one Slack message with their flagged deals and what to do about each one.
5. Post the worst offenders to #sales-management: deal, owner, amount, rules tripped and days since the last activity.
```

### Let the daily schedule take over

The change request added this trigger to `kortix.yaml`. From now on the agent
runs every day at 06:00, each run in a new session on its own cloud computer.
To change the time, edit the cron line, or open **Triggers** in the workspace.

**kortix.yaml**

```yaml
triggers:
  - slug: daily-pipeline-hygiene-scan
    name: Daily pipeline-hygiene scan
    on:
      cron: "0 0 6 * * *"
    run:
      agent: pipeline-hygiene
      prompt: Load the pipeline-hygiene-rules skill and run one complete pipeline-hygiene scan.
```

### Write only the hygiene flag

The agent reads deals, activities and tasks. The only field it writes is the
hygiene flag. It never moves a stage, reassigns an owner, edits an amount, logs
an activity or closes a task. The rep and the sales manager decide what happens
to each deal.

### Read the nudges and the escalation

Each run ends with one nudge per rep and one escalation in the managers'
channel. This is what a run looks like in the session:

> **Daily pipeline-hygiene scan · 06:00**
>
> Prompt: Load the pipeline-hygiene-rules skill and run one complete pipeline-hygiene scan.
>
> Scanned **184** open deals and flagged **23**. **11** are stale, **7** have
> no next step or close date, **4** are stalled and **5** have overdue tasks.
> Sent nudges to **9** reps and escalated the top **5** deals to
> #sales-management.

> **The pattern**
> A daily **cron** spawns a session with read-mostly **connector** access to
> HubSpot. The hygiene rules live as a **skill**. The agent flags stale,
> incomplete, stalled, and overdue deals, nudges the rep, escalates the worst
> to the manager, and never changes a deal's stage, owner, or amount.

## Make it do more

Once it works, paste any of these into the same session.

**Weekly hygiene trend**

```
Every Monday, post to #sales-management how many deals tripped each rule in each of the last 4 weeks.
```

**Check before the forecast call**

```
The day before each forecast call, list every deal in the Commit forecast category that has a hygiene flag, and send the list to each owner.
```

**Cover reps who are away**

```
Keep a list in memory of reps who are out of office, and send their nudges to their manager until they are back.
```

## Guardrails

Reading and flagging every open deal every day is a trust question, so the
agent's access is narrow and one-directional in the ways that matter:

- **Isolation.** Every run happens in its own isolated sandbox. Only the
  hygiene flag write and the Slack messages are written back out.
- **Scoped secrets.** The HubSpot credential is encrypted in the secrets
  manager and injected into the sandbox at runtime, scoped to the agents you grant them to
  or the logs.
- **Read-mostly.** The agent's only write to HubSpot is an internal hygiene
  flag on the deal. It never changes a deal's stage, reassigns its owner, or
  edits its amount — those decisions stay with the rep and the manager.
- **Nudge and flag only.** The agent's output is a Slack message or a flag; it
  never takes an action on a rep's behalf.
- **Everything is code.** The staleness window, the stage-stall window, and
  the escalation criteria are files in the repo, versioned and changed through
  a reviewed **change request** rather than a dashboard setting.

## The outcome

- **Every day:** Open pipeline re-checked against the current HubSpot state
- **4 rules:** Stale, missing fields, stalled stage, and overdue tasks in one pass
- **Read-mostly:** Stage, owner, and amount are never touched by the agent

The deals that used to sit quietly until the next pipeline review now surface
the same day they go stale, with a nudge to the rep who owns them and an
escalation for the ones a manager should already be watching. The agent only
flags and nudges; the rep and the manager still decide what moves.
