Pipeline Hygiene Audit

skill

Read the pipeline, flag stale/missing-field deals, and report hygiene issues to a file and the team.

Download .md

Pipeline Hygiene Audit

Review the sales pipeline for stale or incomplete deals, then report the issues to a file and to the team.

When to use

  • On a recurring cadence (weekly or biweekly) to keep pipeline data clean.
  • When a sales lead asks for a pipeline health check before a forecast review.
  • When deals seem to be sitting without movement or key fields look empty.

Tools

  • http-get: read deal records and fields from the CRM.
  • shell-execute: process the deal data to detect staleness and missing fields.
  • write-file: save the hygiene report artifact.
  • send-message: notify the team of hygiene issues found.

Playbook

  1. Confirm the audit scope: which pipeline, stage range, and staleness threshold (e.g. no activity in 14+ days).
  2. Call the CRM REST API with http-get (e.g. GET https://api.hubapi.com/crm/v3/objects/deals) to pull all open deals with their stage, last-activity date, owner, amount, and close date. Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials. If the call returns 401/403 or no Integration row exists, stop and message a human via send-message asking them to create the Integration, naming the service and required scopes.
  3. Use shell-execute to run a small script that parses the pulled deal data and flags: deals with no activity past the staleness threshold, deals missing required fields (amount, close date, owner, next step), and deals stuck in the same stage beyond a normal duration.
  4. For deals tied to related records (contacts, companies), call the CRM REST API with http-get again as needed to confirm missing fields aren't just unlinked.
  5. Use shell-execute to compile the flagged deals into a structured summary: counts by issue type, list of affected deal IDs/names, owners, and dollar amounts at risk.
  6. Write the full hygiene report to a file using write-file, including the audit date, scope, and every flagged deal with its specific issue(s).
  7. If any deal record needs a field corrected or a stage updated, do not attempt this yourself — CRM record updates require PATCH/PUT, which is not possible with the declared tools. Instead, list the required changes in the report and hand off to a human via send-message.
  8. Send a summary via send-message to the sales team channel or owner, highlighting the top issues (count of stale deals, count of missing-field deals, total dollar amount at risk) and pointing to the saved report file.
  9. If the CRM API rate-limits the pull, back off and retry, and note the rate limit in memory via the appropriate durable-learning step so future audits pace requests accordingly.

Failure modes

  • 401/403 response from the CRM API -> missing Integration row; stop and escalate via send-message naming the service and required scopes.
  • Empty result set from http-get -> verify the endpoint URL, pipeline ID, and filter parameters before assuming the pipeline is empty.
  • Rate limit hit during pulls -> back off with delays between http-get calls and note the limit for future runs.
  • CRM page layout or field names changed and API calls stop matching expected fields -> fall back to browser-search to confirm current field names before resuming the audit.

Done when

  • A hygiene report file exists (via write-file) listing every stale or missing-field deal with specifics.
  • The team has received a send-message summary pointing to the report.
  • Any needed CRM field corrections are documented as a change list for human handoff, not silently skipped.