From b998fe9df44298d86780d13fcc65aff5b0b6325f Mon Sep 17 00:00:00 2001 From: Francisco Solla Date: Mon, 14 Sep 2026 02:32:41 -0300 Subject: [PATCH] =?UTF-8?q?docs(plan):=20C158=20+=20C159=20=E2=80=94=20Sol?= =?UTF-8?q?linha=20no=20acervo=20de=20falas=20e=20na=20comunica=C3=A7?= =?UTF-8?q?=C3=A3o?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Registra os planos aprovados no gate de 2026-09-14: tool do Sollinha para sugerir trechos do acervo de falas (C158) e chat escopado ao acervo para a assessoria de comunicação (C159, depende de C158). Related #982 Related #983 --- docs/plans/sollinha-acervo-falas-trechos.md | 78 ++++++++++++++++++++ docs/plans/sollinha-para-comunicacao.md | 79 +++++++++++++++++++++ 2 files changed, 157 insertions(+) create mode 100644 docs/plans/sollinha-acervo-falas-trechos.md create mode 100644 docs/plans/sollinha-para-comunicacao.md diff --git a/docs/plans/sollinha-acervo-falas-trechos.md b/docs/plans/sollinha-acervo-falas-trechos.md new file mode 100644 index 00000000..5a3a7dbe --- /dev/null +++ b/docs/plans/sollinha-acervo-falas-trechos.md @@ -0,0 +1,78 @@ +# Sollinha: sugerir trechos de falas do acervo para vídeos + +Status: plano — registrado (blocked até plano em main) +Atualizado em: 2026-09-14 +Issue: #982 +Priority: P1 +Impeccable: A — N/A (resposta em texto/markdown no chat existente; sem superfície nova) +Rascunho UI: N/A — sem UI +Appetite: ~1 dia eng; uma tool read-only nova + orientação no prompt + testes; sem migration/collection/Consent +Responsável: — + +## Intenção + +O acervo de falas do deputado já está em produção (C153/C154/C155), mas achar o trecho certo para uma peça continua sendo garimpo manual: buscar, abrir o vídeo e caçar a minutagem. Quem produz conteúdo já conversa com o Sollinha para outras tarefas — e agora quer perguntar em linguagem natural ("qual uma boa fala para um reels sobre o hospital do subúrbio?") e receber trechos candidatos prontos para levar à edição. Falta a ponte entre a pergunta e o acervo. + +## Persona e fluxo + +- **Persona / contexto:** quem produz conteúdo da campanha (coordenação/candidatura hoje; assessoria de comunicação via C159, item irmão), sob prazo curto de peça, com o chat do Sollinha aberto no sheet/drawer. +- **Job principal:** converter um tema em 1–3 trechos de fala do deputado, com citação aproximada e minutagem, para montar o vídeo sem garimpar o acervo na mão. +- **Fluxo desejado:** pergunta o tema ("hospital do subúrbio") → o Sollinha busca no acervo → devolve as sugestões com trecho citado e minutagem de começo/fim → o usuário abre o acervo no ponto do trecho, assiste e baixa. +- **Anti-goals de produto:** não é editor de vídeo nem entrega arquivo; não lê a fala inteira no chat; não inventa fala nem minutagem; não vira busca semântica; não expõe o acervo fora de `/campanha`. + +## Objetivo e aceite + +- A pergunta de exemplo ("Qual seria uma boa fala do deputado para criarmos um reels sobre o hospital do subúrbio?") devolve 1–3 sugestões, cada uma com citação aproximada do trecho e minutagem de começo e fim. +- Cada sugestão leva ao acervo no ponto do trecho (onde já há assistir/baixar/abrir a fonte); o chat não entrega arquivo nem edita. +- **Guardrails:** sem trecho encontrado, o Sollinha diz que não achou — nunca inventa fala ou minutagem; cada sugestão é um trecho contínuo, curto o bastante para virar peça; quem não lê o acervo recebe negativa clara (fail-closed), nunca dado parcial nem erro técnico; a citação vem do ASR e pode ter ruído — vale como localizador, a referência é o vídeo; sem migration/collection/Consent. + +## Dados (intenção) + +- **Vou apresentar dados?** Sim, superfície neste item — o consumidor é o usuário no chat; a resposta é a superfície. +- **Decisões desbloqueadas:** quem edita escolhe qual fala vira peça e já sabe o ponto de corte, em vez de procurar o trecho no acervo. +- **Forma:** _adiada ao plano de implementação_ — restrições de produto: trecho contínuo com começo e fim; citação aproximada + minutagem; poucas sugestões por resposta; nada de transcrição inteira nem métrica de acervo. + +## Dados da decisão (literais) + +- N/A — nenhum valor fixo de dados a preservar: a faixa de sugestões e o formato do link são comportamento de resposta, detalhados no plano de implementação (sem tabela, ID, env ou string exata de produto). + +## Direção no codebase (hipótese) + +- **Áreas prováveis:** `src/utilities/ai/tools/` (tool nova + registro em `index.ts`) e `src/utilities/ai/systemPrompt.ts`; reuso da busca existente do acervo em `src/utilities/speech/` (`speechListFilters.ts`, `speechViewModels.ts`, `speechPageData.ts`) e do normalizador `src/lib/speechSearch.ts`. +- **Precedente a olhar:** tools de leitura atuais (factory por contexto que consulta com o usuário da sessão); gate de negação por papel de B180; retorno com critério/escopoRestrito/truncado de B185; links do chat de B162/B187/B188/B198; testes de lockdown por tool e int do acervo (`tests/unit/electionToolsLockdown.unit.spec.ts`, `tests/int/speechAcervo.int.spec.ts`). +- **Risco de acoplamento:** leader lockdown intocado e advisor segue negado no acervo; o gate da tool deve espelhar quem tem leitura do acervo (o communicator incluído) — o gate de staff não cobre esse recorte. Os segmentos ASR são frasais e o acervo hoje destaca UM segmento; juntar trechos contíguos com começo/fim é justamente o trabalho novo deste item. + +## Dependências + +- Entregues (duras, satisfeitas): C153 (catálogo `speech`/`speechSegment`), C154 (vertical Comunicação + busca no acervo), C155 (backfill; 997 discursos em produção). +- C159 (chat para a assessoria de comunicação — #983) depende deste item, não o contrário: a tool nasce com o gate do acervo para que C159 a herde. +- Nenhuma dependência dura bloqueante. + +## Fora de escopo + +- Ler a fala inteira / transcrição completa no chat — a íntegra fica no detalhe do acervo. +- Cortar, editar ou gerar vídeo, e baixar arquivo pelo chat — o acervo já oferece assistir/baixar/abrir a fonte. +- Busca semântica/embeddings — a busca textual do acervo é a base (item futuro se houver demanda). +- TTS, narração, legendas e curadoria de trechos/favoritos/listas editoriais. +- Exposição pública do acervo e mudanças de UI no acervo (C154) além do reuso. + +## Rabbit holes de produto + +- **Busca semântica/embeddings.** Se alguém "só completar": índice vetorial, sinônimos, reranking, infra nova. **Corte neste item:** busca textual existente; sem resultado, o Sollinha diz que não achou. +- **Ler a fala inteira no chat.** Se alguém "só completar": transcrição longa na resposta, contexto estourado, citação sem foco. **Corte neste item:** só trechos contínuos curtos com começo/fim; a íntegra fica no acervo. +- **Cortar/editar/gerar vídeo.** Se alguém "só completar": editor, fila de render, storage. **Corte neste item:** o chat sugere e aponta; edição é ferramenta externa. +- **Publicar o acervo fora de `/campanha`.** Se alguém "só completar": página pública, compartilhamento externo, direitos. **Corte neste item:** acervo segue interno. + +## Questões em aberto (produto) + +- **Quem usa nesta entrega?** **Opções:** A) só quem já tem o chat (coordenação/candidatura) | B) a assessoria de comunicação também, via C159. **Decisão do gate (2026-09-14): B** — a assessoria de comunicação também usa, via C159 (item irmão, dependente desta tool), sem bloquear esta entrega. +- **O link na resposta aponta para onde?** **Opções:** A) acervo interno no trecho (`?t=`), que já dá assistir/baixar | B) também URL direta do VOD/YouTube. **Decisão do gate (2026-09-14): A** — o trecho sugerido aponta para o acervo interno no ponto do trecho; a fonte direta só quando o detalhe do acervo não bastar. +- **Quantos trechos e quão longos?** **Opções:** A) sempre 1 | B) 1–3 conforme o pedido | C) até N com janela fixa. **Decisão do gate (2026-09-14): B** — 1–3 trechos conforme o pedido, trecho contínuo curto o bastante para peça; a política fina de janela fica no plano de implementação. + +## Referências + +- GitHub Issue: #982 +- Rascunho UI (gate): N/A — sem UI +- Planos irmãos: [`sollinha-tool-urls-navegacao.md`](sollinha-tool-urls-navegacao.md) (B162 — links no chat), [`sollinha-tools-eleitorais-leader-lockdown.md`](sollinha-tools-eleitorais-leader-lockdown.md) (B180 — gate fail-closed), [`sollinha-liderancas-pendentes-abordagem.md`](sollinha-liderancas-pendentes-abordagem.md) (B185 — retorno com critério), [`acervo-videos-comunicacao.md`](acervo-videos-comunicacao.md) (C154 — acervo e RBAC), [`catalogo-falas-solla.md`](catalogo-falas-solla.md) (C153), [`backfill-acervo-falas.md`](backfill-acervo-falas.md) (C155). +- Arquivos-chave: `src/app/(campaign)/campanha/api/ai-chat/route.ts`, `src/utilities/ai/`, `src/utilities/speech/`, `src/lib/campaignRoles.ts`. +- `AGENTS.md` — rotas `/campanha`, leader lockdown e RBAC. diff --git a/docs/plans/sollinha-para-comunicacao.md b/docs/plans/sollinha-para-comunicacao.md new file mode 100644 index 00000000..4c2ce236 --- /dev/null +++ b/docs/plans/sollinha-para-comunicacao.md @@ -0,0 +1,79 @@ +# Sollinha na assessoria de comunicação (chat escopado ao acervo) + +Status: plano — registrado (blocked até plano em main) +Atualizado em: 2026-09-14 +Issue: #983 +Priority: P2 +Impeccable: A — N/A (as superfícies do chat já existem; habilitadas por papel, sem design novo) +Rascunho UI: N/A — sem UI +Appetite: ~0,5–1 dia eng; habilitar a superfície do Sollinha para o `communicator` com escopo de tools, orientação de prompt e testes; sem migration, collection ou Consent +Responsável: — + +## Intenção + +A assessoria de comunicação é quem produz os vídeos e reels da campanha — e é quem mais precisa garimpar falas do Solla. Hoje ela não tem Sollinha: desde o C154 todas as superfícies do assistente são escondidas do papel `communicator`, decisão deliberada daquela entrega. Com o C158, o Sollinha passa a saber pesquisar o acervo de falas e sugerir trechos; sem este item, justamente a persona que precisa disso não consegue abrir o chat. + +Este item reabre aquela decisão de forma estreita: o `communicator` ganha o Sollinha, mas escopado ao acervo — as demais tools negam com mensagem clara, sem vazar dados de campanha nem estourar erro técnico. + +## Persona e fluxo + +- **Persona / contexto:** assessoria de comunicação (jornalista/videomaker) dentro da vertical `/campanha/comunicacao`, com prazo curto de produção, alternando entre a busca do Acervo e o chat. +- **Job principal:** pedir uma fala para uma peça em linguagem natural e receber trechos do acervo para levar ao corte. +- **Fluxo desejado:** entra na vertical → abre o Sollinha → pergunta "o que o Solla já falou sobre Farmácia Popular?" → recebe trechos com contexto e link para o Acervo → pergunta algo fora do escopo ("quantos votos tivemos em Ilhéus?") → lê uma negativa clara e educada, sem erro técnico. +- **Anti-goals de produto:** não é assistente geral da campanha; não vê dados de campanha, eleitorais ou de municípios; não substitui a busca do Acervo (a superfície principal segue sendo o C154); não vira copiloto de pauta, agenda ou demandas. + +## Objetivo e aceite + +- O `communicator` vê e abre o Sollinha na vertical (FAB, drawer e botão do header), como qualquer outro papel habilitado. +- Uma pergunta de acervo (ex.: a pergunta-exemplo do C158) responde com trechos de falas e caminho para o Acervo — a primeira prova de valor. +- Pergunta fora do escopo recebe negativa clara e educada — nunca erro técnico, nunca dado de campanha, eleitoral ou de município. +- Os chips de abertura do `communicator` são perguntas de acervo, respondíveis com as tools dele. +- **Guardrails:** leader lockdown intocado; `advisor` inalterado (segue sem acervo e sem mudança no chat); nav do `communicator` intacta (só Comunicação); rate limit e limites atuais de conversa valem igual. + +## Dados (intenção) + +- **Vou apresentar dados?** Não — o item é acesso/superfície. Quem apresenta os trechos é a tool do C158, dentro do chat que já existe. +- **Decisões desbloqueadas:** nenhuma nova — escolher qual fala cortar já é do fluxo C154/C158. +- **Forma:** _adiada ao plano de implementação_ — sem restrição de produto nova neste item. + +## Dados da decisão (literais) + +- N/A — nenhum valor fixo de dados. O escopo deriva dos predicados de papel já existentes (`canReadSpeechCatalog` e `canUseCampaignAssistant`, em `src/lib/campaignRoles.ts`); sem tabelas, thresholds ou envs novos. + +## Direção no codebase (hipótese) + +- **Áreas prováveis:** o predicado de superfície em `src/lib/campaignRoles.ts:34` e seus dois consumidores no shell (`src/components/campaign/shell/ai/CampaignAISidebarShell.tsx:45`, `src/components/campaign/shell/CampaignDesktopHeader.tsx:29`); o prompt global `src/utilities/ai/systemPrompt.ts` (sem regra para `communicator` hoje); a montagem de tools (`src/utilities/ai/tools/index.ts`) e a rota `src/app/(campaign)/campanha/api/ai-chat/route.ts` (só auth + rate limit, sem filtro de papel); os chips em `src/lib/sollinhaOpeningQuestions.ts:45-50`; e `src/utilities/ai/campaignNavigationUrls.ts` (links negados com erro claro). +- **Precedente a olhar:** C154 (escondeu o chat deste papel — este item reabre), C158 (tool de busca no acervo, dependência dura), B180 (`docs/plans/sollinha-tools-eleitorais-leader-lockdown.md`) e B185 (`docs/plans/sollinha-liderancas-pendentes-abordagem.md`), além do access do acervo do C153. +- **Risco de acoplamento:** lockdown do leader e negativa do `advisor` no acervo não podem regredir; o `communicator` não ganha municípios nem dados eleitorais; `maxDuration = 60` e o rate limit de 50 msg/15 min seguem iguais. + +## Dependências + +- **C158** (dura, #982) — a tool de busca no acervo; sem ela o chat do `communicator` responde pouca coisa útil. +- C153, C154 e C155 entregues (acervo no banco, vertical e busca). + +## Fora de escopo + +- Abrir o acervo (ou o chat pleno) para `advisor`/`leader` — decisão C153 mantida; sucessor só com nova evidência. +- Assistente de pauta, agenda ou demandas da comunicação — item futuro, sem ID. +- Chat do Sollinha no site público ou fora da vertical — não. +- Novas tools além do escopo de acervo; redesign do drawer ou da persona. + +## Rabbit holes de produto + +- **"Já que abriu, vira assistente completo da comunicação."** Se alguém "só completar": pauta, agenda, demandas, clipping. **Corte neste item:** só acervo no escopo; o resto nega. +- **"Aproveita e abre o acervo para o advisor/leader."** Se alguém "só completar": muda a decisão C153 de escopo de leitura. **Corte neste item:** decisão mantida; ninguém novo entra. +- **"Refaz o prompt/persona do zero para o communicator."** Se alguém "só completar": reescrita global do prompt e das superfícies. **Corte neste item:** orientação de escopo pontual no prompt, sem design novo. + +## Questões em aberto (produto) + +- **Qual o escopo de tools do `communicator`?** **Opções:** A | só a tool do acervo + o mínimo (calculadora e links do que ele acessa), e as demais negam claramente; B | assistente completo com gate por tool. **Decisão do gate (2026-09-14): A** — escopo mínimo; o valor está no acervo. +- **Tools que hoje lançam `Forbidden` ou devolvem vazio devem passar a responder negativa clara?** **Opções:** A | sim, sempre negativa clara em linguagem de produto, com ajuste pontual nos donos das tools; B | manter como está. **Decisão do gate (2026-09-14): A** — a resposta ao `communicator` nunca pode virar erro técnico. +- **Chips de abertura do `communicator`?** **Opções:** A | curadoria própria de perguntas de acervo, por capacidade real (padrão B191/C154); B | reaproveitar o conjunto do leader. **Decisão do gate (2026-09-14): A** — chips de acervo que ele consegue responder de verdade. + +## Referências + +- GitHub Issue: #983 +- Rascunho UI (gate): N/A — sem UI +- Planos: `docs/plans/acervo-videos-comunicacao.md` (C154), `docs/plans/catalogo-falas-solla.md` (C153), `docs/plans/sollinha-tools-eleitorais-leader-lockdown.md` (B180), `docs/plans/sollinha-liderancas-pendentes-abordagem.md` (B185); C158 #982 (tool de busca no acervo). +- Pistas de teste: `tests/unit/campaignNav.unit.spec.ts:65-71`, `tests/unit/campaignSollinhaOpeningQuestions.unit.spec.ts:20-51`, `tests/int/speechCatalog.int.spec.ts:123-155`, `tests/e2e/campaignSpeechAcervo.e2e.spec.ts:70-107`, `tests/e2e/campaignAiChatOpeningChips.e2e.spec.ts:103` e o mock `mockSollinhaChat` em `tests/e2e/fixtures/campaignE2EFixtures.ts:604-612`. +- `AGENTS.md` — convenções de papel/access e o registro da decisão C154.