# 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.