Pipeline hygiene

Pipeline hygiene

Finds the deals whose CRM data cannot be trusted yet and tells each rep exactly what to fix. Run it the day before a forecast call so the forecast is built on clean data.

When to use

• Weekly, before forecast or deal reviews.
• After a reorg or territory change, to catch ownerless deals.
• Not for judging deal quality (use deal-review-prep for MEDDICC), and not for editing the CRM.

Inputs

1. Open opportunities export at data/opportunities.csv. Closed stages are skipped automatically. Columns are matched by common names:

   • Needed: ID and stage.
   • Used when present: name, owner, amount, close date, next step, stage entered date (or days in stage), last activity date, plus any column named in your required fields.
   • Salesforce: an Opportunities report with Stage Duration and Last Activity. HubSpot: a deals view export with "Date entered current stage" and "Last activity date".
   • Other names: --map field=Column Name (fields: id, name, owner, amount, close_date, stage, next_step, stage_entered, stage_days, last_activity).
2. Rules (optional) at data/hygiene.json, see the kit's examples/hygiene.json: stale_days (30), activity_days (14), far_future_days (365), required fields, required_by_stage (stage name to extra fields, using column names as they appear in the export), and closed_stages.

Ask the user what "stale" means for their sales cycle the first time. A 30 day default is wrong for a 9 month enterprise cycle.

Steps

1. Confirm the export and the rules. If there is no rules file, run with defaults and say which ones.

2. Run:

   node scripts/hygiene.mjs data/opportunities.csv --config data/hygiene.json --out out --name hygiene

3. Read out/hygiene.json. Mention checks_skipped (missing columns) so the user knows what was not checked.
4. Report the score, the top issue types, and the reps with the most deals to fix.
5. Offer per-rep messages: one short note per rep listing their deals and what to update, drafted from out/hygiene-fix-list.csv. Draft only; the user sends them.

Output to the user

**Pipeline hygiene 2026-11-04: 20% clean** (1 of 5 open deals).

| Issue | Deals |
| --- | ---: |
| Stuck in stage over 30 days | 2 |
| Missing required fields | 2 |
| Close date in the past | 1 |

Biggest fix: Contoso Robotics ($120,000, Rep B): close date passed 4 days ago, 81 days in Proposal, no activity in 23 days, no next step.
1 deal has no owner (Adventure Works, $30,000).
Fix list: out/hygiene-fix-list.csv

Guardrails

• Read-only. Never update the CRM, even if a fix is obvious. List it as a suggested edit.
• Do not guess a close date or amount for a deal. The rep owns those.
• Keep messages to reps factual and short. No public shaming lists unless the user asks for a team view.

Pipeline hygiene

Checks every open deal in your CRM export for the problems that wreck a forecast: past close dates, deals stuck in a stage, no recent activity, missing fields, zero amounts, and close dates years away. You get a hygiene score and a fix list per rep.

Who it is for

RevOps and sales managers on HubSpot, Salesforce, or any CRM that exports CSV, who want clean data before the weekly forecast call.

Example

Input: examples/opportunities.csv (six deals) and examples/hygiene.json (Decision Maker required from Proposal on).

Output (out/hygiene.md):

Hygiene score 20%: 1 of 5 open deals are clean.
Rep B: Contoso Robotics: new logo (Proposal, $120,000): close date 2026-10-31 is 4 days ago;
  81 days in Proposal; last activity 23 days ago; missing next_step, Decision Maker
(no owner): Adventure Works: upsell: missing close_date, owner, Decision Maker

Plus out/hygiene-fix-list.csv, one row per deal to fix.

What it can access

• Runs node scripts/hygiene.mjs (Node built-ins only, no network).
• Reads data/ (plus the kit's own examples/), writes data/ and out/.

Setup

None. Export open opportunities to data/opportunities.csv. Optionally copy examples/hygiene.json to data/ and set your own thresholds.