Sessões de planejamento

O planejamento é onde a maioria dos projetos fracassa. Não por falta de ideias ou talento, mas porque as equipes partem diretamente para a construção sem validar premissas, questionar o escopo ou identificar os riscos à frente.

As Planning Sessions no Almirant não são uma ferramenta de geração de tarefas. Elas são seu parceiro de sparring de IA, que desafia, questiona e obriga você a pensar antes de escrever uma única linha de código.

O que são as Planning Sessions

Uma Planning Session é uma conversa de vários turnos com a IA. Não é um único prompt que produz uma lista de itens: é um diálogo iterativo em que a IA atua como parceira de sparring, desafiando cada decisão que você toma:

• Questiona premissas que você considera certas
• Identifica riscos no seu planejamento
• Propõe alternativas que você não havia considerado
• Refina o escopo para deixar claro o que entra e o que fica de fora

O resultado não é apenas uma lista de work items: é um escopo validado e premissas questionadas.

Sua parceira de sparring, não uma geradora

A diferença é fundamental. Uma geradora recebe sua entrada e produz uma saída. Uma parceira de sparring questiona sua entrada. Ela pergunta por quê, quais alternativas você considerou e onde estão os riscos.

Iniciar uma sessão

1. Acesse a rota /plan a partir do projeto que deseja planejar.
2. Selecione o board de destino onde os work items resultantes serão criados.
3. Opcionalmente, selecione seeds de ideação para fornecer contexto inicial.
4. Escreva uma mensagem inicial descrevendo o que deseja alcançar.
5. Inicie a conversa.

Título da sessão

Ao iniciar, você pode atribuir um título descritivo à sessão. Esse título ajudará você a identificar a sessão no histórico. Exemplos:

• "Planejamento de autenticação OAuth"
• "Análise de migração do banco de dados"
• "Design do sistema de notificações"

Fluxo conversacional

A sessão segue um fluxo natural de diálogo:

1. Você apresenta sua ideia

Você descreve o que deseja alcançar. Não precisa ter tudo claro: é exatamente para isso que serve a parceira de sparring.

2. A IA questiona

Em vez de gerar itens imediatamente, a IA faz perguntas:

• Por que isso é necessário?
• Quais alternativas você considerou?
• Onde estão os pontos cegos?
• O que acontece se isso falhar?

3. Você defende ou reconsidera

Você responde às perguntas. Às vezes defende sua posição, às vezes percebe que há uma abordagem melhor.

4. O escopo é refinado

A cada iteração, o escopo fica mais claro. A IA entende melhor seu contexto, e você entende melhor os riscos.

5. Geração de work items

Quando o escopo é validado, a IA gera work items estruturados: epics, features, stories e tasks com definições de conclusão.

6. Revisão e aceitação

Você revisa cada item sugerido. Aceita os que se aplicam e rejeita os que não se aplicam. Os itens aceitos são criados automaticamente no board selecionado.

Fases da sessão

Cada sessão passa por diferentes fases que você pode ver na interface:

Fase	Descrição
idle	Aguardando você iniciar a conversa
booting	Preparando a sessão e o contexto
chatting	Trocando mensagens com a IA
streaming	Recebendo a resposta em tempo real
thinking	A IA processa e raciocina (modo thinking ativo)
waiting_for_answer	A IA aguarda sua resposta a uma pergunta
reviewing	Revisando itens sugeridos para aceitar ou rejeitar
completed	Sessão finalizada com itens criados
paused	Sessão pausada para continuar mais tarde

Selecionar seeds de ideação

Antes de iniciar o diálogo, você pode selecionar seeds: ideias anteriores registradas no Almirant que servem como ponto de partida. Os seeds fornecem contexto inicial para a sessão:

• Notas de brainstorming salvas
• Ideias de sessões anteriores
• Requisitos registrados em conversas com stakeholders
• Feedback processado de usuários

Quando você seleciona seeds, a IA os analisa como parte do contexto inicial, permitindo um planejamento mais informado.

Como selecionar seeds

1. Na tela de início da sessão, você verá a seção Seeds disponíveis.
2. Marque os seeds relevantes para este planejamento.
3. Os seeds selecionados serão incluídos no contexto inicial da sessão.

O campo seedsProcessed no resultado da sessão indica quantos seeds foram analisados.

Gerar work items

Quando a conversa chega a um ponto em que o escopo está claro, a IA gera uma proposta de work items estruturados:

Tipos de itens gerados

Tipo	Descrição
Epic	Iniciativa grande que agrupa múltiplas features
Feature	Funcionalidade concreta que gera valor
Story	História de usuário com critérios de aceitação
Task	Tarefa técnica específica e acionável

Estrutura de cada item

Cada item proposto inclui:

• Título descritivo e acionável
• Descrição detalhada com contexto
• Prioridade sugerida (urgent, high, medium, low)
• Hierarquia (parentTempId indica o item pai)
• Origem (fromSeedId se veio de um seed específico)

Revisar e aceitar

Na fase de revisão, você pode:

• Aceitar itens individuais
• Rejeitar itens que não se aplicam
• Aceitar todos se a proposta completa convencer você

Os itens aceitos são criados automaticamente no board selecionado, respeitando a hierarquia proposta.

Histórico de sessões

Todas as sessões são salvas automaticamente e você pode acessá-las depois:

Status	Descrição
active	Sessão em andamento. Você pode continuar o diálogo.
completed	Sessão finalizada. Itens criados no board.
archived	Sessão salva para referência futura.

No histórico, você pode:

• Ver o diálogo completo de qualquer sessão
• Consultar os itens que foram criados
• Reativar uma sessão arquivada para continuar

Acompanhamento de custos

Cada sessão registra métricas de uso para que você possa otimizar o consumo da sua quota:

Métrica	Descrição
totalInputTokens	Tokens enviados à IA
totalOutputTokens	Tokens recebidos da IA
estimatedCost	Custo estimado da sessão
durationMs	Duração total da sessão

Essas métricas permitem entender quanto cada sessão consome e otimizar seu uso da quota de IA.

Configuração da sessão

Cada sessão pode ter sua própria configuração:

Campo	Descrição
model	Modelo de IA a usar (e.g., claude-3-opus)
provider	Provedor de IA (anthropic, openai, etc.)
systemPrompt	Prompt de sistema personalizado
temperature	Temperatura para a geração (0.0 - 1.0)

A configuração padrão vem dos ajustes da organização, mas você pode personalizá-la para sessões específicas.

Modos de resposta

A IA pode operar em diferentes modos dependendo da complexidade do que você está discutindo:

Streaming

Você vê a resposta enquanto ela é gerada. Ideal para iteração rápida e diálogo fluido.

Thinking

A IA raciocina passo a passo antes de responder. É melhor para problemas complexos que exigem uma análise profunda.

Você pode alternar entre os modos durante a sessão.

Escrever prompts eficazes

Sua primeira mensagem importa. Estes são exemplos de bons pontos de partida:

Bons pontos de partida

Prompt	Por que funciona
"Quero adicionar autenticação social, mas não sei se o esforço vale a pena em comparação com magic links"	Convida a IA a comparar alternativas
"Preciso melhorar o desempenho da lista de produtos, os usuários reclamam de lentidão"	Define o problema real, não a solução presumida
"Temos que migrar de REST para GraphQL, a equipe diz que é melhor, mas não estou convencido"	Abre espaço para questionar a decisão

Evitar

Prompt	Problema
"Gere tasks para autenticação"	Fecha o espaço para diálogo, pede uma saída direta
"Faça um CRUD de usuários"	Não há problema a resolver, apenas mecânica
"Melhore todo o sistema"	Sem foco, impossível questionar

Pré-requisitos

Para usar as Planning Sessions, você precisa de:

• Um provedor de IA configurado com uma API key válida
• Quota disponível na sua organização
• Um projeto com pelo menos um board ativo onde os itens serão criados

Para desenvolvedores

Estrutura de dados

A sessão é armazenada com os seguintes campos principais:

Campo	Tipo	Descrição
id	uuid	Identificador único
organizationId	text	Organização proprietária
projectId	uuid	Projeto associado
boardId	uuid	Board onde os itens são criados
title	text	Título da sessão
status	enum	active, completed, archived
config	json	model, provider, systemPrompt, temperature
result	json	summary, workItemsCreated, seedsProcessed

Mensagens da sessão

Cada mensagem da conversa tem:

Campo	Tipo	Descrição
role	enum	user, assistant, system
content	text	Conteúdo da mensagem
messageType	varchar	Tipo de mensagem
inputTokens	integer	Tokens de entrada
outputTokens	integer	Tokens de saída

Ferramentas MCP

Tool	Descrição	Parâmetros principais
record_ai_session	Registra uma sessão de planejamento	projectId, prompt, response, tokensUsed
get_ai_sessions	Obtém o histórico de sessões de um projeto	projectId, limit

Exemplo: registrar uma sessão

Tool: record_ai_session
Parametros:
  projectId: "uuid-del-proyecto"
  prompt: "Necesito un sistema de notificaciones push"
  response: "Propuesta generada por la IA..."
  tokensUsed: 1250

Rota de acesso

A rota principal para as Planning Sessions é /plan. A partir dela, você pode iniciar novas sessões, ver o histórico e continuar sessões pausadas.