Stage Audit

skill

Check deals against stage-entry criteria and compile a list of misstaged opportunities for review.

Download .md

Stage Audit

Review open deals against each pipeline stage's entry criteria and compile a list of misstaged opportunities for a human to correct.

When to use

  • On a recurring cadence (weekly or before a pipeline review meeting) to catch deals sitting in the wrong stage.
  • When a sales lead asks for a pipeline hygiene check before a forecast call.
  • After a batch of deals has moved stages and you need to confirm the moves were valid.

Tools

  • http-get: read deal records and stage-entry-criteria fields from the CRM.
  • write-file: compile the list of misstaged opportunities into a review artifact.
  • send-message: notify a human that the audit is done and flag deals needing manual stage correction.

Playbook

  1. Confirm the stage-entry-criteria definitions you will check against (e.g. "Proposal" requires a scoped budget field and a champion contact; "Negotiation" requires a proposal-sent date).
  2. Call the CRM REST API with http-get / http-post (e.g. GET https://api.hubapi.com/crm/v3/objects/deals) to pull all open deals with their current stage and relevant fields. 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. For each deal, check whether the required fields and conditions for its current stage are actually populated and satisfied.
  4. Flag any deal missing a required field, missing an activity (e.g. no proposal-sent date despite being in "Negotiation"), or otherwise not meeting entry criteria.
  5. For each flagged deal, note the deal name, owner, current stage, and the specific criterion it fails.
  6. Because updating a deal's stage requires PATCH, which is not possible with the declared tools, do not attempt to move any deal — compile the full list of misstaged opportunities instead.
  7. Write the compiled list to a file with write-file, organized by deal owner so each rep can act on their own items.
  8. Notify the sales lead and the affected deal owners via send-message, summarizing the count of misstaged deals and pointing to the file for corrections.
  9. Complete the task with a structured result summarizing total deals reviewed and total flagged.

Failure modes

  • 401/403 response -> no Integration row for the CRM host; stop and escalate via send-message naming the service and required scopes.
  • Empty result set -> verify the endpoint URL, deal-stage filter, and pagination parameters before concluding there are no open deals.
  • Rate limit hit -> back off and retry with delay; note the rate limit in memory so future audits pace requests.
  • CRM stage-field schema changed or fields are missing -> fall back to browser-search to confirm the current field names before re-running the pull.

Done when

  • A compiled list of misstaged deals, each with owner, stage, and failed criterion, has been written via write-file.
  • The sales lead and relevant deal owners have been notified via send-message with a summary and pointer to the artifact.
  • No stage changes were attempted directly; all corrections are left as a clear human handoff.