Módulo 4.3 · Orquestração, retomada e diagramas

🎛️ O orquestrador de pipeline

O orquestrador é o maestro: ele dispara Pesquisa → Síntese → Geração em ordem, e cada etapa confirma a conclusão antes da próxima começar. Nada avança no escuro — se a Fase 1 não fechou, a Fase 2 não roda.

Recebe entradas. Nome + descrição da empresa (e a profundidade da pesquisa).

Pesquisa, sintetiza, gera. As três fases em sequência, cada uma alimentando a próxima.

Confirma e empacota. Renderiza diagramas, organiza pastas e fecha o pacote para download.

💡 Confirmar por etapa é o que salva

A confirmação por fase não é burocracia: é o que torna o pipeline retomável. Como cada etapa marca "concluída", uma queda no meio não força refazer (nem repagar) o que já estava pronto.

Maestro

dispara as fases

Sequência

1 → 2 → 3

Confirma

antes de seguir

Auditável

cada passo registrado

💾 Checkpoints e state.json

O state.json é a memória da Fábrica. Ele vive em output/{empresa}/ e guarda a fase atual, o status de cada um dos entregáveis e o custo total acumulado da sessão.

// output/stripe/state.json

{
  "company_name": "Stripe",
  "current_phase": "synthesis",
  "phases": {
    "research":   { "status": "complete" },
    "synthesis":  { "status": "in_progress" },
    "generation": { "status": "pending" }
  },
  "deliverables": {
    "01_tech_inventory": { "status": "complete", "path": "..." },
    "06_quick_wins":     { "status": "pending" }
  },
  "total_cost": 0.0773
}

📍 Fase atual

current_phase diz exatamente onde a Fábrica parou.

✅ Status por entregável

Cada um dos 15+ docs marca complete / pending / failed.

💵 Custo acumulado

total_cost soma cada chamada — o controle de orçamento em tempo real.

💡 Sem checkpoint, sem retomada

O state.json é a condição para tudo o que vem a seguir. É ele que transforma "deu erro, perdi tudo" em "deu erro, continuo de onde parei". Cada entregável que conclui é gravado na hora.

Memória

em disco

Fase

onde parou

Custo

acumulado

Base

da retomada

🔁 Retomar quando o contexto enche

Sessões longas do Claude Code estouram o contexto — aconteceu duas vezes na construção da Fábrica original. A solução não é torcer para não acontecer; é abrir uma sessão nova e retomar pela lista de tarefas armazenada no state.json.

// o contexto encheu? nova sessão, mesmo comando

# ver onde parou
python -m strategy_factory.main status "Stripe"

# retomar de onde o state.json marcou
python -m strategy_factory.main resume "Stripe"
# → pula research (complete), continua synthesis, depois generation

✓ Com retomada

✓Nova sessão lê o state.json e continua
✓Pula fases já complete — não repaga
✓Usa o research_cache.json em vez de re-pesquisar

✗ Sem retomada

✗Contexto enche → começa tudo do zero
✗Paga a pesquisa de novo a cada queda
✗Sessões longas viram beco sem saída

💡 Documentação é barata em tokens

Mesmo no plano de US$20 da Anthropic dá para fazer muito — desde que você divida os pedidos. Construir em público é mostrar a bagunça: limites de contexto, erros de API, nome de modelo errado na doc. Retomar pela lista de tarefas é a habilidade que faz você terminar mesmo quando trava.

Encheu?

nova sessão

resume

continua o estado

Dividir

pedidos menores

Termina

sem travar

🪢 Mermaid: estado atual vs futuro

O prompt de diagramas gera dois flowcharts que contam a história da transformação: o estado atual (o stack de hoje, com os gargalos marcados) e o estado futuro (a arquitetura habilitada por IA). É o "antes e depois" que vende.

// exemplo de Mermaid: estado atual vs futuro

flowchart TB
  subgraph Atual["Estado Atual"]
    DS1[Planilhas soltas] --> CS1[CRM legado]
    CS1 --> U1[Vendas]
    CS1 -. gargalo .-> X[(Dados em silos)]
  end

  subgraph Futuro["Estado Futuro · IA"]
    DL[Plataforma de Dados Unificada] --> AI1[Copiloto de Vendas]
    DL --> AI2[Previsão de Churn]
    AI1 --> U2[Vendas]
    AI2 --> U3[Sucesso do Cliente]
  end

  Atual ==>|transformação| Futuro

📉 Estado atual

•Fontes de dados e sistemas legados
•Pontos de integração frágeis
•Gargalos conhecidos marcados em vermelho

📈 Estado futuro (IA)

•Plataforma de dados unificada
•Camada de serviços de IA/ML
•Aplicações turbinadas e fluxos automatizados

💡 O slide que decide

Um executivo não lê três páginas de texto, mas entende o "antes e depois" em cinco segundos. Marcar os gargalos no estado atual cria a tensão; mostrar o estado futuro resolve. Esse par de diagramas costuma ser o slide que aprova o projeto.

Atual

com gargalos

Futuro

habilitado por IA

Contraste

antes e depois

Vende

decide o board

🖼️ Renderizar Mermaid → PNG

Cliente não abre um arquivo .mmd — ele abre uma imagem no slide. O mermaid_renderer transforma o código em PNG real para entrar no PPTX. E se a renderização falhar, a degradação graciosa entra: pula a imagem e mantém o markdown.

`mermaid_renderer` (no pipeline)

Pega o código gerado pelo prompt de diagramas e exporta PNG para mermaid_images/. É o caminho automático da Fábrica.

Skill `beautiful-mermaid`

Renderiza Mermaid como SVG e PNG com acabamento caprichado — ideal quando você quer o diagrama bonito, fora do pipeline.

`eraser.io`

Editor online para ajustar o diagrama na mão e exportar — bom para um retoque rápido antes da reunião.

💡 PNG no slide, fonte versionada

Guarde o .mmd em recursos/diagramas/ (versionável) e entregue o PNG no deck. Assim você edita o texto do diagrama quando o projeto muda, sem refazer a imagem do zero.

Renderer

PNG no pipeline

beautiful-mermaid

acabamento

eraser.io

retoque manual

Falhou?

mantém o md

📦 Empacotar para download

A Fase 3 fecha o ciclo: organiza tudo em pastas e empacota o pacote completo para download. Entregar é metade do trabalho — um pacote bem organizado é o que faz o cliente sentir que pagou por algo sério.

// output/{empresa-slug}/ — a estrutura entregue

output/stripe/
├── markdown/          # 15 .md (os entregáveis)
├── presentations/     # 2 .pptx (resumo + achados)
├── documents/         # 2 .docx (relatório + SOW)
├── mermaid_images/    # PNGs dos diagramas
├── research_cache.json
└── state.json

Salva os markdown. Os 15 entregáveis em markdown/, o conhecimento interno.

Gera PPTX e DOCX. Deck executivo, achados completos, relatório final e SOW — a entrega refinada.

Empacota tudo. Diagramas renderizados juntos, pronto para download na webapp.

💡 Entrada mínima, saída máxima — fechada

Duas caixas de texto entraram lá no começo; agora sai uma pasta com 19 entregáveis profissionais por menos de US$1. Esse é o ciclo completo da Fábrica — e o que você leva para a Trilha 5, onde vira oferta e vai parar nas mãos do cliente.

Pastas

organizado

19 peças

md+pptx+docx

Download

um clique

< US$1

o ciclo todo

✅ Resumo do módulo

✓

O orquestrador confirma cada etapa — Pesquisa → Síntese → Geração, nada avança no escuro.

✓

state.json é a memória — fase, status por entregável e custo acumulado.

✓

Contexto encheu? resume — nova sessão continua de onde parou, sem repagar.

✓

Mermaid atual vs futuro vende — renderizado em PNG, empacotado no pacote final.

🎯 Missão 4.3 — A Fábrica ponta a ponta + diagramas

Rode o pipeline completo para a empresa das missões anteriores e gere os diagramas de estado atual vs futuro.

Peça ao Claude Code para rodar a Fábrica ponta a ponta (Pesquisa → Síntese → Geração).
Se o contexto encher, abra nova sessão e use resume "Empresa" — confirme que ele pulou o que já estava pronto.
Abra o state.json e veja todas as fases em complete e o total_cost.
Renderize os diagramas (renderer, beautiful-mermaid ou eraser.io) e cheque os PNGs em mermaid_images/.

Sucesso: a pasta output/{empresa}/ com os 19 entregáveis e os diagramas renderizados, por < US$1. O que você ganhou: a Fábrica funcionando ponta a ponta — o motor que a Trilha 5 transforma em oferta e leva ao cliente.

Próxima trilha:

Trilha 5 · Da Fábrica ao Cliente — empacotar com a sua marca, posicionar, precificar e fechar a venda (capstone).

← Voltar para Trilha Próxima trilha: Consultor →