---
name: lead-status
description: Use when handling tenant-bound synthetic lead intake, Google Sheets status/quality observations, and uncertain write reconciliation.
---

# Preserve the lead identity and the meaning of its outcome

## Version and authority boundary

Read the selected profile and the exact contract from the package root. Unconverted V1 uses `contracts/pipeline.contract.json`, mode `simulation`, demo IDs, supplied synthetic records, geometric placeholders and the existing offline validator only. V1 restrictions remain intact. For V2 explicitly select `contracts/pipeline.v2.contract.json`; reject unconverted V1 with an explanation. Conversion creates a separate simulation artifact, preserves its source, enriches missing fields, rebuilds all digests, and never promotes `approve_demo` to human authorization. Neither mode names nor schema validation enable a connector. This build uses no network, accounts, secrets, installs or customer records; integration-test and customer-pilot are separate future gates, not claims of readiness.

Use approved API/MCP/connectors first when integration is separately enabled; browser fallback is only for a capability unavailable in the authorized programmatic path, at the same authority boundary. Never launch external scripts, installers, model CLIs or services from this Skill. Source rule IDs below resolve to `docs/knowledge-register-v1.md` (checked 2026-10-24). Untested real behavior remains **unverified**.

Before requesting new OAuth or a project, inspect the client's existing authorized CRM/Sheets connector and verify access to the exact destination and read/write operations. For supervised MVP, hand off a bounded lead/write plan with tenant, route, stable source ID and write ID to that connector, observe its actual response, read back the row and journal the outcome. A prepared plan or recommendation is not delivery. Connector-mediated testing does not prove webhook ingestion or operation after chat closes; use an existing client-owned integration for continuous receipt where suitable, or describe the precise missing setup and seek approval.

Client connection decision: (1) If the existing agent connector can perform the requested supervised action, use it and report the receipt/readback. (2) For continuous receipt outside chat, prefer a suitable native form-to-CRM integration the client already operates. (3) Offer client-owned n8n only when routing, field mapping, multiple destinations, retry or status feedback needs a custom workflow. Explain the proposed source trigger and authentication, exact field/tenant mapping, stable lead key and replay behavior, target write plus readback, uncertain-write reconciliation, bounded retry and error alert, and how a CRM status change returns to the report. Identify the owner, minimum permissions, data retention and approvals before setup. An agent supplies judgment and supervised actions; a configured workflow engine handles ongoing events. Neither a recommendation nor an n8n diagram proves a deployed connection.

For native Meta leads, distinguish app capability, token scope, Page Leads Access and form ownership. During client onboarding, verify the eligible app and credential type plus exact Page/form access. Select only permissions needed for the chosen route, including `leads_retrieval` for native retrieval. Read back granted scopes and assets, then verify a synthetic test-lead fetch under an approved boundary. A scope checkbox alone never grants Page or Leads Access. Website-only campaign creation does not universally need `leads_retrieval`. Do not issue or replace a token from this instruction.

## Tenant and destination [A2, S1, N2]

Read explicit profile, source/owner mappings, pipeline and intake authorization before accepting an event. Check tenant/account/page/form/destination on events and source reads; unknown or mismatched identity is refused with no default. Unique lead identity is `(tenant_id, source_lead_id)`; same ID in different tenants is distinct. Identical replay is idempotent; changed replay is conflict, never overwrite or status reset. Destination is first Google Sheets, separate/private/synthetic only in pilot; no agency Airtable requirement, Monday records or provider expansion. No real names/phones/emails or public sheet sharing in this build.

Allowlist spreadsheetId AND sheetId and reviewed schema. Row number is never identity: re-resolve stable external key and source/write IDs before a write. Block moved/deleted/duplicate keys or schema changes for reconciliation. Write untrusted values as RAW. Executor owns source/intake/write_id columns; status, qualified, reason, notes and owner belong to the human and are read-only in normal processing. Only approved initialization on a new row and separately authorized synthetic status test are exceptions; replay never reinitializes human fields. Controlled structure and pause-before-maintenance are required; local checks are not atomic against concurrent row movement or a sheet owner bypass.

## Writes and recovery [S1, H1]

Persist authenticated intake before ack; worker/queue/outbox are explicit services, not this skill. Save write_id and prepared / in-flight / confirmed / failed-safe / uncertain / confirmed_then_missing. Preserve entity IDs after partial completion. Timeout, elapsed time, local fencing or two empty searches cannot prove a remote append was canceled. No blind retry or new source ID. Resolve uncertain only with sufficient target evidence or bounded documented human disposition; deletion after confirmation is reported and never auto-recreated. Single writer/durable journal reduces races but does not promise exactly-once. Respect bounded scan windows/quota; Sheets offers no assumed conditional upsert or change feed. Report queued as queued, not delivered; prove independent process operation separately.

## Quality and measurement [N2, R1, M1]

Keep handling status separate from qualified yes/no/not-reviewed, customer-defined criterion/version, reason, reviewer and assessment time. Missing review is unknown, never no. A recorded successful-sales label is not independently verified sale or revenue; require separate business evidence. Missing ad ID stays null/unknown. Preserve source creation time, observed time and is_test for cohorting. Refresh source snapshots in the authorized window; exclude test records from business reports. Report only last observed Sheets state, not a full edit history or a verified human identity inferred from a cell. Trace intake gap and status to source snapshots. Remote delivery, security, background service, sale and revenue remain unverified until separately tested.