sistema-vivo

# Sistema Vivo — gate de arquitetura

Esta skill é o **gate operacional**. A lei está em `docs/doctrine/sistema-vivo.md`; o racional completo, no manual `docs/doctrine/sistema-vivo/`.

> **Portabilidade:** as seções 1 a 6 são universais — valem em qualquer sistema que adote a doutrina. A seção 7 (*Binding*) é o que muda de repositório para repositório. Ao levar esta skill para outro sistema, **reescreva só a seção 7**.

---

## 1. O princípio em uma frase

O sistema é responsável pela **linha do tempo inteira de cada demanda** — alguém interessado ou alguém com um problema — até a resolução ou o encerramento declarado pela própria pessoa.

Nada morre por falta de resposta, de resolução, ou porque ninguém viu. Toda peça é um polvo: recebe e distribui.

---

## 2. O checklist — responda ANTES de declarar pronto

```
Living System Checklist — <nome da peça>

[ ] 1. Quem me alimenta?          → aresta de entrada; fonte real e confiável
[ ] 2. Quem eu alimento?          → aresta de saída; "ninguém" = ilha
[ ] 3. Que registro eu emito?     → atividade / auditoria / evento
[ ] 4. Onde eu apareço na tela?   → registro só no banco é registro morto
[ ] 5. Por qual porta se chega?   → ter tela ≠ ser alcançável
[ ] 6. Qual meu anti-morte?       → próximo passo garantido, ou justificativa
[ ] 7. Onde se configura?         → ver + mudar + o que aparece se faltar
[ ] 8. Qual a continuidade?       → IA↔humano, nas DUAS direções
[ ] 9. Qual meu laço de retorno?  → o que muda no sistema quando eu erro
[ ] 10. Atualizei o mapa?         → peça nova entra com ≥2 arestas
```

**Como se responde mal, e é o padrão:** respondendo o que a peça *poderia* fazer. A resposta válida **nomeia o artefato concreto** — o consumidor real, a tela real, o log real. *"Vai aparecer no painel"* não é resposta; *"aparece na timeline do lead, renderizada por `<componente>`"* é.

**"Nenhum" é aceitável** nas perguntas 6 e 9, **com justificativa escrita**. Peça de leitura pura não tem anti-morte. Dívida declarada não é defeito; dívida presumida é.

---

## 3. Os 7 invariantes

| # | Invariante | Violação típica |
|---|---|---|
| 1 | **Nada é ilha** — ≥1 aresta de entrada e ≥1 de saída | CRUD disfarçado de feature |
| 2 | **Continuidade nas duas direções** — IA→humano entrega contexto pronto; humano→IA deixa input estruturado | Handoff que entrega conversa crua: transferiu custo, não contexto |
| 3 | **Log universal e visível** — emite atividade E aparece na tela | Log só no banco: ninguém lê, não muda decisão |
| 4 | **Nenhuma demanda sem próximo passo** — follow-up é o anti-morte | Silêncio tratado como neutro. Não é: é a perda mais comum e a mais invisível |
| 5 | **Informação com propósito** — todo dado responde "e daí?" | Painel de vaidade: números que sobem e não mudam nada |
| 6 | **Configuração tem superfície** — ver + mudar + falha visível | Mecanismo invisível que funciona; quando falha, falha sem culpado |
| 7 | **Todo laço se fecha** — decisão automática tem retorno que altera decisão futura | Esteira: 1–6 satisfeitos e o sistema não aprende nada |

**O 7 é o mais fácil de perder.** O 1 garante *caminho*; o 7 garante *ciclo*. A pergunta que expõe: **quando o sistema erra, o que muda nele?** Se a resposta é "fica no log", o log é estoque morto.

---

## 4. A regra do tempo

> **Observação em tempo real. Ação no tempo apropriado ao humano do outro lado.**

- **Observar** em realtime é direito do humano: painel, inbox, fila, falha, conversa ao vivo. Informação atrasada faz o anti-morte (invariante 4) chegar atrasado junto.
- **Agir** em realtime costuma ser errado. Quanto mais irreversível o efeito, maior o intervalo entre decidir e consumar. **Enviar mensagem a uma pessoa é irreversível** e nunca é operação comum.
- **Interruptibilidade:** o sistema nunca deve ser mais rápido do que o humano consegue interromper.

Nunca escreva "tudo em realtime" numa spec. Diga *quem observa* e *o que age*.

---

## 5. Receitas

### Implementar uma peça nova

1. **Localize antes de criar** — descubra de quem recebe e quem deve alimentar. Metade das ilhas nasce de desconhecimento do que já existe.
2. **Escreva as duas arestas primeiro** — antes da lógica interna. Se não consegue nomear as duas, a peça ainda não tem lugar no sistema.
3. **Log no mesmo commit da mutação** — log adicionado depois nunca é adicionado.
4. **Leve até a tela** — peça que funciona e não aparece falha sem culpado.
5. **Dê a porta** — registre o destino na navegação.
6. **Nomeie o laço** — o que muda quando ela acerta? e quando erra?
7. **Atualize o mapa** — arquitetura sem mapa é ilha de informação.

### Desilhar uma peça existente

1. **Meça antes de opinar** — quem chama, quem lê. Por ferramenta, não por memória.
2. **Ache o consumidor natural** — quase sempre já existe alguém que deveria ler aquilo.
3. **Uma aresta real vale mais que duas decorativas.**
4. **Sem consumidor, o caminho é remover.** Peça sem consumidor é dívida com aparência de recurso.

---

## 6. Red flags — pare e reconecte

| Sinal | Invariante ferido |
|---|---|
| "É só um CRUD de X" | 1 — X vivo tem métrica, log, destino de handoff, timeline |
| Mutação sem atividade emitida | 3 |
| Dado na tela que não muda decisão | 5 — ruído compete com o que importava |
| Demanda aberta sem próximo passo | 4 — algo vai morrer sem ninguém ver |
| Peça nova fora do diagrama | 3, aplicado à documentação |
| Handoff entrega conversa crua | 2 |
| Configuração só alterável no banco | 6 |
| Decisão automática sem sinal de retorno | 7 |
| "Vamos medir depois" | Nunca. A instrumentação some entre a intenção e o merge |
| Métrica de eficiência sem contra-métrica de dano | 5 — o sistema vai se otimizar contra si mesmo |

---

## 7. Binding — DeskcommCRM

> Reescreva **apenas esta seção** ao levar a skill para outro sistema.

| Pergunta do checklist | Neste repo |
|---|---|
| Que registro eu emito? | `event_log` (side effects) · `audit()` de `lib/audit/` → `api_audit_log` · `crm_lead_activities` (timeline do lead) |