/pipeline-sync

name: pipeline-sync
description: "Live view of your Pipedrive pipeline reconciled against your local pipeline tracker; flags drift, maps focus deals, and pushes confirmed updates to the CRM. Use when the user says 'sync my pipeline', 'show me my pipeline', 'reconcile the CRM'. Not for connecting Pipedrive in the first place; use `pipedrive-setup`."
context: conversation

Purpose

Give the user a **live, reconciled view of their pipeline**. Pipedrive owns the canonical deal *numbers*; the local pipeline tracker note (default `04-Projects/Pipeline_Tracker.md`, or the `tracker_path` set in `System/integrations/pipedrive.yaml`) owns the *strategy* and the *focus list*. This skill pulls the live numbers, diffs them against the tracker, shows where they've drifted, and, only when the user confirms, writes changes back to either side.

Requires the Pipedrive integration. If `System/integrations/config.yaml -> pipedrive.enabled` is not `true`, tell the user to run `/pipedrive-setup` first and stop.

Usage

• `/pipeline-sync`: pull live pipeline, reconcile against the tracker, show a drift report
• `/pipeline-sync map`: (re)map focus deals to their Pipedrive records (first-run, or after adding a deal)
• `/pipeline-sync discover`: list open Pipedrive deals **not** in the tracker (find what you're missing)

Method

Gate the run on the companion skill, integration state, configured tracker path, and a complete live read. Build a deal-by-deal ledger containing the tracker and Pipedrive identifiers, values, source update times, retrieval `as-of` time, and read completeness. Reconcile mappings, fields, totals, and untracked deals without changing either system. Present each drift direction as a human choice. For every confirmed mutation, preview the exact payload or file diff, apply only that choice, then read back both affected authorities before moving to the next change. Treat ambiguous network outcomes as unresolved, not retryable failures.

Output contract

Return integration and coverage status, the source ledger, drift rows, unchecked deals, mapping gaps, totals reconciliation, and decisions still required. The final change summary must be derived only from read-back receipts and must name each verified target. Explicitly report zero changes, partial completion, or failure rather than using a fixed success sentence. Include unresolved and unknown items, the denominator behind every total, and any ambiguous write that must be inspected before retry. A tool response alone is never a success receipt.

Operating principles (non-negotiable)

• **Confirm every write.** Never call a Pipedrive write tool (`pipedrive_add_deal_note`, `pipedrive_add_deal_activity`, `pipedrive_update_deal`, `pipedrive_create_deal`, `pipedrive_create_org`) without first showing the exact payload (use `dry_run: true`) and getting the user's explicit yes. CRMs are often shared with colleagues. The tools preview by default and only send on an explicit `dry_run: false`, so that parameter is the record of the user's yes — never pass it to "get past" a preview the user has not actually seen and approved.
• **A partial read is not a clean read.** `pipedrive_get_pipeline_snapshot` and `pipedrive_list_deals` return a `complete` flag and a `warning` when they could not see everything. When `complete` is false, report the named deals as *unchecked*; never fold them into "no drift" or "nothing else in the CRM".
• **Never auto-resolve drift.** For each difference, the user chooses the direction. Default to doing nothing.
• **Tracker totals matter.** If a deal value or probability changes on the tracker side, recompute any gross/weighted totals the tracker maintains and update its `last_updated` field if it has one.
• **Re-read before editing.** Re-read the tracker and any company page immediately before editing it; don't trust session memory of file state.
• **Report, don't editorialise.** Drift is information, not a prompt to pressure the user into action. Show the numbers plainly and let them decide.

---

Evidence, authority, and recovery

Treat catalogue-visible companion skills and Pipedrive prerequisites as gates, not optional context. Before gathering, verify that the catalogue exposes the `pipedrive-setup` companion, that the Pipedrive integration is enabled and connected, and that the configured tracker path is readable. If a required companion or prerequisite is missing, unavailable, or contradictory, name it and stop or degrade to a clearly labelled local-only report; never fake a live CRM view.

• Record provenance for every drift row and total: source path or Pipedrive

record, source date/updated time, and the `as-of` time of the read. Keep tracker and CRM values side by side. If they conflict, show both sources and dates; keep missing data as `Unknown`, never invent absent facts, or silently choose a direction.

• A partial read is an incomplete read. When `complete` is false, a warning is

present, or a companion returns only part of the catalogue, list every unchecked deal and the missing scope, disclose denominator coverage, and do not report "no drift" or write based on the partial result.

• Keep reconciliation read-only until an authorized human decides. A mapping,

recommendation, or drift direction is not a human decision. Before any tracker or Pipedrive change, show an exact write preview: target, exact before/after content or payload, and all derived total changes. Require the authorized human's explicit confirmation; do not rely on implied approval.

• After every confirmed write, read back the changed record and tracker and

reconcile the read-back with the approved preview. Report success only when the values match. If a write fails, times out, or read-back is incomplete or differs, state what may have changed, re-read the authoritative source, and wait for explicit human direction before repairing or retrying.

• Retry idempotency must be proved rather than assu