chore: import maquina-comercial-pessoal history via subtree

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

git-subtree-dir: maquina-comercial-pessoal
git-subtree-mainline: f5af038e19
git-subtree-split: a9ef4d776d

maquina-comercial-pessoal/docs/superpowers/specs/2026-07-29-commercial-outreach-pilot-design.md

@@ -0,0 +1,320 @@
+# Commercial Outreach Pilot Design
+
+## Goal
+
+Create a supervised WhatsApp prospecting operation for Gustavo, commercial representative of Grupo GTI, focused on qualified conversations and demonstrations for GTI Vendas and G-Delivery without treating volume as the primary objective.
+
+The pilot must preserve the operator's control, identify replies before any further automation, honor opt-outs, avoid unverified numbers, and produce enough evidence to improve targeting and copy.
+
+## Current Context
+
+- The lead base contains 2,680 companies in Santo Antonio de Jesus, Bahia.
+- The current database groups 2,066 leads under ERP or management interest and 614 under WhatsApp self-service interest.
+- The current automation is disabled.
+- The current generic template, `Meu servico`, does not represent either approved product.
+- The existing `5-12` second interval is not suitable for this pilot and must not be reused.
+- The WhatsApp number is more than two years old, has normal personal-use history, has never been restricted, and will become exclusively commercial.
+- The number will remain on regular WhatsApp during the pilot. A future migration to WhatsApp Business or an official integration remains an operational option.
+- Gustavo is authorized to use his number and prospect for both products.
+- Grupo GTI handles demonstrations, implementation, support, and closing after qualification.
+
+## Commercial Identity
+
+- Sender: `Gustavo - Representante Comercial do Grupo GTI`.
+- Company: `Grupo GTI`.
+- ERP product: `GTI Vendas`.
+- Online-order product: `G-Delivery`.
+- Authorized social proof: Grupo GTI has more than seven years of operation and more than 100 clients in Santo Antonio de Jesus and the surrounding region.
+- Prices, implementation fees, links, and detailed conditions must not appear in the first message.
+- The message must not promise unavailable functionality, unapproved integrations or customizations, technical deadlines, or guaranteed commercial results.
+
+## Product Positioning
+
+### GTI Vendas
+
+GTI Vendas centralizes sales, inventory, invoicing, tabs or orders, finance, and administrative processes. It is sold through a personalized presentation because configuration depends on the client's operation.
+
+Primary segments:
+
+- Restaurants.
+- Markets, grocery stores, and minimarkets.
+- Bakeries and convenience stores.
+- Clothing stores.
+- Building-material stores.
+- Auto-parts stores and mechanical workshops.
+- Other commerce requiring integrated management.
+
+Commercial path:
+
+1. Ask one segment-specific operational question.
+2. Continue by text if the lead replies.
+3. Identify interest without performing a complete technical diagnosis.
+4. Collect participant name, company, preferred day, and preferred time.
+5. Hand the scheduled demonstration to the Grupo GTI team in the office.
+
+### G-Delivery
+
+G-Delivery gives a food business its own order link, with a fixed monthly fee and no fee per order. The client may self-register and test the product for seven days or request a demonstration.
+
+Primary segments:
+
+- Hamburger restaurants.
+- Pizzerias.
+- Acai shops.
+- Meal-prep and lunch-box businesses.
+- Snack bars.
+- Other businesses clearly focused on meal delivery.
+
+Commercial path:
+
+1. Ask whether the business has its own order channel or depends on commission-charging applications.
+2. Continue by text if the lead replies.
+3. Offer either a seven-day self-service test or a demonstration.
+4. For a demonstration, collect participant name, company, preferred day, and preferred time.
+5. Hand the scheduled demonstration to the Grupo GTI team in the office.
+
+## Campaign Priority
+
+Campaigns run sequentially so that early evidence can improve later campaigns:
+
+1. G-Delivery for hamburger restaurants, pizzerias, acai shops, meal-prep businesses, and snack bars.
+2. GTI Vendas for restaurants, markets, grocery stores, minimarkets, bakeries, and convenience stores.
+3. GTI Vendas for clothing, building materials, auto parts, mechanical workshops, and remaining eligible commerce.
+
+Overlapping food businesses receive the first offer selected by this order. A second product is introduced only when the conversation reveals a relevant need; the pilot does not automatically send a second product message.
+
+## Lead Eligibility
+
+A lead may enter a daily queue only when all conditions are true:
+
+- It belongs to the campaign's approved segments.
+- It has never received an initial campaign message for that product.
+- Its latest equivalent-number verification state is `confirmado`.
+- It is not opted out under either Brazilian ninth-digit variant.
+- It has not replied to a previous commercial message.
+- It has no pending, accepted, sent, delivered, read, or unknown campaign send for the same product.
+- It has not been manually removed from the daily preview.
+
+Phone verification is gradual. Per operating day, the system may check at most `ceil(1.5 * the approved daily send limit)` previously unverified numbers. It never scans the entire lead base in one operation. If that cap does not produce enough confirmed numbers, the daily queue remains below its send limit.
+
+No initial customer-exclusion list is required. Existing clients may be contacted, but any reply immediately removes them from automation and allows manual classification.
+
+## Personalization
+
+- Use the trade name only when present and natural.
+- Do not use long legal names, CNPJ values, or business names dominated by numbers.
+- Without a reliable trade name, begin with `Ola, tudo bem?`.
+- Do not claim that the business uses delivery, marketplaces, tabs, invoicing, or any specific process. Ask instead.
+- Do not mention the RFB source or imply prior personal knowledge.
+- Message variants are fixed and auditable. No generative AI writes outbound messages during execution.
+- Rendering may replace the opening greeting with `Ola, pessoal da {nome_fantasia}, tudo bem?` when the trade name passes the natural-name rule. Otherwise it preserves the generic greeting. The rest of the approved variant remains unchanged.
+
+Approved `foco_gestao` mappings:
+
+- Restaurants: `vendas, estoque, comandas e emissao fiscal`.
+- Markets and grocery commerce: `vendas, estoque e emissao fiscal`.
+- Mechanical workshops: `ordens de servico, estoque e financeiro`.
+- Other commerce: `vendas, estoque, financeiro e notas fiscais`.
+
+## Approved Initial Messages
+
+Every message must include the simple refusal sentence. Diacritics may be used in the final UI text; the examples below define meaning and structure.
+
+### GTI Vendas - Variant A
+
+> Ola, tudo bem? Sou Gustavo, representante comercial do Grupo GTI. Hoje voces controlam {foco_gestao} em um unico sistema? Se nao fizer sentido para sua empresa, e so me avisar que nao volto a entrar em contato.
+
+### GTI Vendas - Variant B
+
+> Ola! Aqui e Gustavo, do Grupo GTI. Trabalhamos com gestao para empresas de Santo Antonio de Jesus e regiao. Como voces organizam hoje {foco_gestao}? Se nao fizer sentido para sua empresa, e so me avisar que nao volto a entrar em contato.
+
+### GTI Vendas - Variant C
+
+> Ola, tudo bem? Sou Gustavo, do Grupo GTI. Ha mais de 7 anos atendemos empresas da regiao e ja temos mais de 100 clientes. Voces utilizam algum sistema para {foco_gestao}? Se nao fizer sentido para sua empresa, e so me avisar que nao volto a entrar em contato.
+
+### G-Delivery - Variant A
+
+> Ola, tudo bem? Sou Gustavo, representante comercial do Grupo GTI. Queria entender como voces recebem os pedidos de delivery hoje: possuem um canal proprio ou dependem de aplicativos que cobram comissao? Se nao fizer sentido para sua empresa, e so me avisar que nao volto a entrar em contato.
+
+### G-Delivery - Variant B
+
+> Ola! Aqui e Gustavo, do Grupo GTI. Voces ja possuem um link proprio para receber pedidos, sem pagar comissao por venda a aplicativos? Se nao fizer sentido para sua empresa, e so me avisar que nao volto a entrar em contato.
+
+### G-Delivery - Variant C
+
+> Ola, tudo bem? Sou Gustavo, representante comercial do Grupo GTI. Trabalho com uma solucao de pedidos online por canal proprio e queria primeiro entender como funciona o delivery de voces hoje. Se nao fizer sentido para sua empresa, e so me avisar que nao volto a entrar em contato.
+
+The queue records the exact variant and fully rendered text before approval. Retries never choose a different variant.
+
+## Cadence
+
+The pilot has no follow-up. Each eligible lead receives at most one initial message for the selected product.
+
+Operating windows:
+
+- Monday through Friday, `09:30-11:30` and `14:00-17:00` local time.
+- No weekend sends.
+- Public holidays are handled by the supervisor pausing or not approving that day's queue; automatic holiday-calendar integration is outside the pilot.
+
+Daily progression:
+
+- Week 1: up to 10 messages per operating day.
+- Week 2: up to 12 messages per operating day.
+- Week 3: up to 15 messages per operating day.
+- Week 4: up to 18 messages per operating day.
+
+The supervised campaign quota and the application's manual-send quota are separate. A manual test or individual send does not reduce the automatic campaign balance, and the UI displays both totals independently.
+
+Timing rules:
+
+- Random interval from 12 to 25 minutes between attempts.
+- At most four send attempts in any rolling hour.
+- Sends are distributed across both windows rather than exhausting the quota at the start of the day.
+- A weekly increase is never automatic. Gustavo reviews metrics and explicitly approves the next limit.
+- The number's age, daily volume, and delay do not guarantee protection against restriction.
+
+## Supervised Daily Operation
+
+1. The application selects never-contacted leads from the active campaign.
+2. It gradually verifies unverified phone numbers up to the daily `1.5 * send limit` cap.
+3. It removes unregistered numbers, opt-outs, replied leads, duplicates, and prior sends.
+4. It creates a daily preview containing business display name, phone, segment, product, variant, rendered message, scheduled window, and selection reason.
+5. Gustavo approves the queue, removes individual entries, or pauses the campaign.
+6. Approved entries receive immutable scheduled timestamps distributed under the cadence rules.
+7. The worker reserves each send atomically immediately before provider use.
+8. Replies, opt-outs, connection failures, and uncertain sends take precedence over scheduled work.
+9. The end-of-day summary records outcomes and unresolved items.
+
+Automation starts disabled after every server restart. Starting or resuming a day requires explicit operator action during the pilot.
+
+## Reply Handling
+
+Inbound detection uses a hybrid model:
+
+- Any inbound message immediately pauses that lead and removes scheduled work.
+- The application places the conversation in `Respostas pendentes`.
+- It does not generate or send an automatic commercial reply.
+- Gustavo reads the conversation on the phone and manually classifies it.
+
+Pipeline stages:
+
+- `fila_preparada`
+- `aprovado_para_envio`
+- `enviado`
+- `respondeu`
+- `interessado_gti_vendas`
+- `interessado_g_delivery`
+- `demonstracao_agendada`
+- `teste_g_delivery_iniciado`
+- `sem_interesse`
+- `opt_out`
+- `venda_fechada`
+
+Explicit requests to stop are acknowledged respectfully and added to permanent opt-out. Ambiguous replies only pause the lead for manual review.
+
+## Manual Conversation Guidance
+
+### Positive GTI Vendas Reply
+
+Continue by text, acknowledge the response, ask at most one brief question if necessary, and offer a personalized presentation. Once accepted, collect participant name, company, preferred day, and preferred time.
+
+### Positive G-Delivery Reply
+
+Continue by text, confirm how orders are received, and offer either the seven-day self-registration test or a demonstration. For a demonstration, collect participant name, company, preferred day, and preferred time.
+
+### No Interest
+
+Thank the person, confirm that no further contact will be made, and classify the conversation as `sem_interesse` plus permanent opt-out when the reply requests no more contact.
+
+## Automatic Pauses
+
+Pause the campaign when any condition occurs:
+
+- WhatsApp disconnects, enters an error state, or loses its session.
+- A send has an unknown outcome.
+- Daily provider/send failures exceed 10 percent after at least 10 attempts.
+- Negative or opt-out responses exceed 10 percent after at least 20 contacts.
+- Overall response remains below 5 percent after at least 50 contacts.
+- The operator presses the immediate-pause control.
+
+An automatic pause never resumes itself. Gustavo reviews the reason and explicitly resumes or ends the campaign.
+
+## Metrics
+
+Metrics are segmented by campaign, product, segment, and exact message variant:
+
+- Previewed, approved, removed, and attempted messages.
+- Accepted, server-acknowledged, delivered, read, unknown, and failed sends.
+- Replies and time to first reply.
+- Positive replies.
+- No-interest replies and opt-outs.
+- GTI Vendas demonstrations scheduled.
+- G-Delivery demonstrations and seven-day tests started.
+- Sales closed.
+
+Derived rates:
+
+- Reply rate.
+- Positive-reply rate.
+- Reply-to-demonstration or test conversion.
+- Demonstration/test-to-sale conversion.
+- Opt-out/negative rate.
+- Delivery failure and unknown-outcome rates.
+
+The dashboard may display small samples but must not declare a winning variant until that exact product/segment/variant group has at least 40 sends. The first month is a learning pilot; no artificial sales target is imposed.
+
+## Data Model Boundaries
+
+The implementation should add focused records for:
+
+- Campaign definitions and current approved weekly limit.
+- Fixed campaign message variants.
+- Daily queue items with immutable rendered message and scheduled timestamp.
+- Campaign status and pause reason.
+- Inbound reply detection and first-reply timestamp.
+- Manual pipeline stage and stage-event history.
+- Demonstration/test scheduling notes.
+
+Existing lead source data, WhatsApp verification cache, opt-outs, provider delivery history, and message ACK timestamps remain authoritative in their current tables. The campaign layer references them rather than duplicating their meaning.
+
+## Reliability And Error Handling
+
+- Queue creation and send reservation are transactional.
+- A lead cannot have two active queue entries for the same campaign/product.
+- A scheduled entry rechecks reply, opt-out, verification, connection, daily limit, hourly limit, and campaign status immediately before sending.
+- Unknown delivery remains terminal and is never retried automatically.
+- Server restart recovers in-progress queue items without duplicating sends.
+- An inbound message that races with a scheduled send wins when detected before provider invocation.
+- A connection or database error produces a visible pause reason and operator action, not a silent retry loop.
+- The application stores no generated free-form outbound copy beyond the approved rendered message.
+
+## Compliance And Risk
+
+- Every first message identifies Gustavo and Grupo GTI.
+- Every first message includes a simple refusal mechanism.
+- Equivalent Brazilian phone variants share opt-out identity.
+- Contact history is retained only as needed for deduplication, audit, and commercial metrics.
+- No message includes source-database details or unnecessary personal data.
+- Cold outreach and device-linked automation retain restriction and policy risk. Volume controls reduce operational exposure but cannot eliminate it.
+- A migration to WhatsApp Business or an official messaging integration may be evaluated after pilot evidence.
+
+## Testing And Acceptance
+
+Automated tests must cover:
+
+- Product/segment campaign selection and overlap priority.
+- Natural trade-name fallback and safe message rendering.
+- All six fixed message variants and prohibited-content checks.
+- Gradual verification without full-base scanning.
+- Daily progression, two windows, 12-25 minute delays, and rolling four-per-hour limit.
+- Preview approval, item removal, immutable variants, and explicit weekly increase.
+- Atomic reservation and duplicate prevention.
+- Reply race, immediate lead pause, and pending-response queue.
+- Permanent equivalent-number opt-out.
+- Disconnect, session error, unknown outcome, failure-rate, negative-rate, low-response, and manual pauses.
+- Restart recovery without resend.
+- Pipeline stages, stage history, demonstration/test notes, and metrics.
+- No follow-up generation during the pilot.
+- Browser-level supervised daily flow on desktop and mobile.
+
+No automated or browser test sends a real message unless Gustavo explicitly authorizes that individual recipient and test.