AI Debrief — proposta de interface estruturada

1. Problema atual e solução proposta

O AI Debrief é uma das funcionalidades mais ricas do Savings. Ele combina as respostas do módulo e devolve uma reflexão personalizada, fazendo o conteúdo parecer conectado à realidade de cada aluno. Essa personalização é um dos principais diferenciais da experiência.

Problema de entrega

Hoje esse valor chega ao aluno como um bloco longo de texto corrido. O conteúdo pode ser relevante, mas a apresentação esconde essa riqueza: é difícil de escanear no celular, parece genérica e não evidencia como as respostas do aluno foram usadas. O resultado tem pouco valor percebido e baixa probabilidade de leitura.

Objetivo de produto

Manter a qualidade e o conteúdo personalizado do debrief, mas transformar a entrega em uma experiência visual mais clara, escaneável e coerente com a importância da funcionalidade.

Critério da solução

Buscar um meio-termo entre viabilidade de implementação e liberdade criativa. A solução precisa permitir composições diferentes conforme o conteúdo, sem entregar ao LLM o controle livre sobre HTML, layout ou identidade visual.

Tecnicamente, o problema começa porque o LLM devolve todo o debrief em uma única string. A interface recebe esse texto como um parágrafo e não sabe quais trechos representam a fala do aluno, a síntese principal, um grupo de respostas, uma reflexão ou o encerramento.

Captura da versão atual do AI Debrief com o resultado apresentado como um bloco de texto — Versão atual

Funcionamento atual

{
  "debrief": "You shared that..."
}

→

<p>{debrief}</p>

A interface só consegue formatar o texto como um bloco.
Não existe uma hierarquia visual estável.
Não é possível resolver ícones ou componentes a partir do significado.
Pedir ao modelo para gerar HTML ou formatação deixaria o resultado imprevisível.

Solução proposta

{
  "sections": [
    { "type": "learner_statement", ... },
    { "type": "answer_highlights", ... },
    { "type": "answer_group", ... },
    { "type": "closing", ... }
  ]
}

→

registry[section.type]

learner_statement → LearnerStatement
answer_group → AnswerGroup

O LLM devolve um documento semântico dentro de um contrato fechado.
A aplicação valida o documento antes de renderizar.
Cada tipo de seção corresponde a um componente conhecido.
O LLM seleciona somente tokens de ícone e cor previstos no catálogo.
A aplicação controla layout, labels e a implementação visual dos tokens.

Fronteira entre o LLM e a aplicação

A proposta não é gerar uma imagem, HTML ou uma interface livre com o LLM. O modelo preenche um documento com estruturas permitidas; a aplicação valida esse documento e decide como cada estrutura será apresentada.

LLM

Responsável pelo conteúdo

Seleciona as respostas mais relevantes para o debrief.
Escreve todos os títulos, labels e textos exibidos.
Escolhe somente estruturas previstas no contrato.
Seleciona tokens permitidos de ícone e cor.

Aplicação

Responsável pela experiência

Valida estrutura, textos, limites, ordem e safety.
Mapeia cada tipo para um componente conhecido.
Resolve tokens nos SVGs e valores da paleta correspondentes.
Controla layout, labels, estilos e fallbacks.

2. Princípio central: um catálogo de componentes, ícones e cores conhecido pelo LLM e pela aplicação

Antes de o LLM entrar no fluxo, produto, design e engenharia precisam definir um sistema fechado de apresentação: quais componentes podem ser usados, quais ícones estão disponíveis e quais combinações de cor funcionam dentro da paleta do projeto. Cada opção recebe um identificador semântico e regras de uso. Esse mesmo catálogo é apresentado ao LLM e implementado pela aplicação.

1. O time define o sistema disponível

Produto, design e engenharia pensam a componentização, organizam o banco de ícones e transformam a paleta do projeto em opções semânticas reutilizáveis.

components: callout, answer_group...
icons: star, shield, target...
colors: violet, blue, indigo...

2. O LLM combina opções permitidas

O schema e o prompt apresentam os identificadores e suas regras ao modelo. O retorno seleciona um componente, um ícone e uma cor permitidos, além de preencher somente os campos aceitos por aquele componente.

{
  "type": "callout",
  "iconToken": "star",
  "colorToken": "violet",
  "text": "Recognizing what feels heavy is progress."
}

3. A aplicação resolve e renderiza

A aplicação valida as escolhas e converte cada identificador na sua implementação real: componente React, arquivo de ícone e tokens de cor do design system.

componentRegistry["callout"]
iconRegistry["star"]
colorTokens["violet"]
  ↓
<Callout />

O mecanismo central

O LLM ganha liberdade para compor uma experiência usando apenas peças aprovadas. Ele pode escolher identificadores como callout, star e violet, mas nunca devolve React, HTML, SVG, CSS ou códigos hexadecimais. A aplicação usa os mesmos identificadores para localizar os componentes e assets corretos. Assim, ampliar a liberdade criativa significa evoluir o catálogo, sem abrir mão da consistência visual e do controle técnico.

3. Funcionamento da proposta

O processo é sequencial: cada etapa produz uma saída que serve de entrada para a etapa seguinte. Nenhuma resposta do LLM é enviada diretamente para a interface.

1
Preparar as entradas
Responsável: Aplicação
Reúne as respostas do aluno, o contexto pedagógico do módulo e o catálogo permitido de componentes, ícones e cores.
↓
Saída: Prompt + JSON Schema + respostas
2
Gerar o documento semântico
Responsável: LLM
Seleciona componentes do catálogo e devolve todos os títulos, labels e textos prontos para exibição, além dos tokens visuais.
↓
Saída: Documento JSON
3
Validar a resposta
Responsável: Aplicação
Verifica estrutura, campos obrigatórios, limites, ordem, tokens permitidos, política pedagógica e safety.
↓
Saída: Documento validado
4
Montar a interface
Responsável: Renderer
Associa section.type ao componente e resolve iconToken e colorToken nos assets e estilos definidos pelo produto.

4. Demonstração do contrato

Edite o JSON para verificar como o documento é validado e renderizado. Os cenários salvos tornam a apresentação independente da API.

Documento completo com todo o conteúdo visível no próprio JSON.

Interface renderizada

MÓDULO 1

AI Debrief

The future you want

“I want money to feel calmer and less overwhelming. I want to enjoy life without worrying about every decision.”

What we heard

Current pattern

The Avoider

Direction

Building security

Goal

Buying a car

Making sense of it

An honest starting point

Feeling open but unsure fits with the beginning of a journey; clarity does not have to arrive all at once.

A direction that feels real

Buying a car gives your learning a concrete direction without turning that dream into a promise or deadline.

Recognizing what feels heavy and naming what you want instead are meaningful forms of progress.

You are beginning with awareness, a personal direction, and permission to move at a pace that feels manageable.

Resposta JSON do LLM

{
  "schemaVersion": "2.0",
  "sections": [
    {
      "type": "learner_statement",
      "title": "The future you want",
      "text": "I want money to feel calmer and less overwhelming. I want to enjoy life without worrying about every decision.",
      "iconToken": "shield",
      "colorToken": "violet"
    },
    {
      "type": "answer_highlights",
      "title": "What we heard",
      "items": [
        {
          "label": "Current pattern",
          "text": "The Avoider",
          "iconToken": "person",
          "colorToken": "violet"
        },
        {
          "label": "Direction",
          "text": "Building security",
          "iconToken": "shield",
          "colorToken": "violet"
        },
        {
          "label": "Goal",
          "text": "Buying a car",
          "iconToken": "target",
          "colorToken": "blue"
        }
      ]
    },
    {
      "type": "reflection_cards",
      "title": "Making sense of it",
      "items": [
        {
          "title": "An honest starting point",
          "text": "Feeling open but unsure fits with the beginning of a journey; clarity does not have to arrive all at once.",
          "iconToken": "compass",
          "colorToken": "violet"
        },
        {
          "title": "A direction that feels real",
          "text": "Buying a car gives your learning a concrete direction without turning that dream into a promise or deadline.",
          "iconToken": "target",
          "colorToken": "blue"
        }
      ]
    },
    {
      "type": "callout",
      "text": "Recognizing what feels heavy and naming what you want instead are meaningful forms of progress.",
      "iconToken": "star",
      "colorToken": "violet"
    },
    {
      "type": "closing",
      "text": "You are beginning with awareness, a personal direction, and permission to move at a pace that feels manageable.",
      "iconToken": "sparkles",
      "colorToken": "indigo"
    }
  ]
}

Resultado da validação

Contrato válido

Estrutura aceita pelo contrato
Ordem dos componentes válida
Ícones e cores pertencem aos catálogos permitidos
Títulos, labels e textos estão prontos para exibição
Limites de texto e itens respeitados

Validações além da estrutura

Conteúdo respeita a política pedagógica.
Texto gerado passa pela moderação.
Documento não contém referências para resolver conteúdo depois.

5. Catálogo detalhado de componentes

A versão inicial propõe oito componentes. Cada linha mostra o renderer, o fragmento JSON e a divisão de responsabilidade.

summary

Resumo

Apresenta a síntese principal das respostas do aluno.

Your debrief

You named a clear hope: to feel less worried about money and more at ease in your life.

FRAGMENTO JSON

{
  "type": "summary",
  "title": "Your debrief",
  "text": "You named a clear hope: to feel less worried about money and more at ease in your life.",
  "iconToken": "sparkles",
  "colorToken": "violet"
}

RESPONSABILIDADE

LLM: Título, texto e tokens permitidos de ícone e cor.
Aplicação: Componente, SVG, paleta, tipografia, espaçamento e limites.

REGRAS

Alternativa à fala do aluno
Sempre o primeiro
20–240 caracteres

learner_statement

Fala do aluno

Destaca no próprio JSON uma fala relevante do aluno.

The future you want

“I want money to feel calmer and less overwhelming. I want to enjoy life without worrying about every decision.”

FRAGMENTO JSON

{
  "type": "learner_statement",
  "title": "The future you want",
  "text": "I want money to feel calmer and less overwhelming. I want to enjoy life without worrying about every decision.",
  "iconToken": "shield",
  "colorToken": "violet"
}

RESPONSABILIDADE

LLM: Título, texto exibido e tokens permitidos de ícone e cor.
Aplicação: Componente, SVG, paleta, aspas, tipografia e limites.

REGRAS

Alternativa ao resumo
Sempre o primeiro
Texto pronto para exibição

answer_highlights

Destaques das respostas

Exibe uma seção titulada com labels e textos já prontos para renderização.

What we heard

Current pattern

The Avoider

Direction

Building security

Goal

Buying a car

FRAGMENTO JSON

{
  "type": "answer_highlights",
  "title": "What we heard",
  "items": [
    {
      "label": "Current pattern",
      "text": "The Avoider",
      "iconToken": "person",
      "colorToken": "violet"
    },
    {
      "label": "Direction",
      "text": "Building security",
      "iconToken": "shield",
      "colorToken": "violet"
    },
    {
      "label": "Goal",
      "text": "Buying a car",
      "iconToken": "target",
      "colorToken": "blue"
    }
  ]
}

RESPONSABILIDADE

LLM: Título da seção, labels, textos e tokens de cada item.
Aplicação: Componente, SVG, paleta, layout e limites.

REGRAS

1–3 itens
Todo o texto aparece no JSON
Sem lookup durante a renderização

answer_group

Grupo de respostas

Apresenta uma lista de textos sem depender de IDs ou dados externos.

Triggers you noticed

Bored or stressed
Tired or on autopilot
Ads or push notifications
Mindless scrolling

FRAGMENTO JSON

{
  "type": "answer_group",
  "title": "Triggers you noticed",
  "items": [
    "Bored or stressed",
    "Tired or on autopilot",
    "Ads or push notifications",
    "Mindless scrolling"
  ],
  "iconToken": "pause",
  "colorToken": "violet"
}

RESPONSABILIDADE

LLM: Título, itens exibidos e tokens permitidos de ícone e cor.
Aplicação: Componente, SVG, paleta, organização e limites.

REGRAS

1–6 itens
Textos prontos para exibição
Sem referências externas

reflection_cards

Cards de reflexão

Conecta respostas em reflexões curtas e escaneáveis.

Making sense of it

An honest starting point

Feeling open but unsure fits with the beginning of a journey; clarity does not have to arrive all at once.

A direction that feels real

Buying a car gives your learning a concrete direction without turning that dream into a promise or deadline.

FRAGMENTO JSON

{
  "type": "reflection_cards",
  "title": "Making sense of it",
  "items": [
    {
      "title": "An honest starting point",
      "text": "Feeling open but unsure fits with the beginning of a journey; clarity does not have to arrive all at once.",
      "iconToken": "compass",
      "colorToken": "violet"
    },
    {
      "title": "A direction that feels real",
      "text": "Buying a car gives your learning a concrete direction without turning that dream into a promise or deadline.",
      "iconToken": "target",
      "colorToken": "blue"
    }
  ]
}

RESPONSABILIDADE

LLM: Título da seção, títulos, textos e tokens de cada card.
Aplicação: Componentes, SVGs, paleta, layout e responsividade.

REGRAS

1–2 cards
Sem aconselhamento financeiro
Texto de até 180 caracteres

numbered_items

Itens numerados

Organiza intenções ou aprendizados quando a sequência agrega significado.

What you’re carrying forward

Awareness is already present

You can name both the weight you feel now and the calmer relationship with money that you would like to build over time.

Your dream creates direction

The idea of buying a car makes the journey tangible while still leaving room for uncertainty, exploration, and a pace that fits your life.

FRAGMENTO JSON

{
  "type": "numbered_items",
  "title": "What you’re carrying forward",
  "items": [
    {
      "title": "Awareness is already present",
      "text": "You can name both the weight you feel now and the calmer relationship with money that you would like to build over time.",
      "iconToken": "check",
      "colorToken": "violet"
    },
    {
      "title": "Your dream creates direction",
      "text": "The idea of buying a car makes the journey tangible while still leaving room for uncertainty, exploration, and a pace that fits your life.",
      "iconToken": "target",
      "colorToken": "blue"
    }
  ]
}

RESPONSABILIDADE

LLM: Título da seção, títulos, textos e tokens de cada item.
Aplicação: Numeração, componentes, SVGs, paleta e layout.

REGRAS

1–3 itens
Não funciona como plano de ação genérico
Textos prontos para exibição

callout

Destaque

Destaca uma observação curta de apoio ou contextualização.

Recognizing what feels heavy and naming what you want instead are meaningful forms of progress.

FRAGMENTO JSON

{
  "type": "callout",
  "text": "Recognizing what feels heavy and naming what you want instead are meaningful forms of progress.",
  "iconToken": "star",
  "colorToken": "violet"
}

RESPONSABILIDADE

LLM: Texto exibido e tokens permitidos de ícone e cor.
Aplicação: Componente, SVG, paleta e formatação.

REGRAS

Uma observação curta
Tokens limitados aos enums
Sem propriedades visuais arbitrárias

closing

Encerramento

Encerra com uma reflexão pronta para exibição.

You are beginning with awareness, a personal direction, and permission to move at a pace that feels manageable.

FRAGMENTO JSON

{
  "type": "closing",
  "text": "You are beginning with awareness, a personal direction, and permission to move at a pace that feels manageable.",
  "iconToken": "sparkles",
  "colorToken": "indigo"
}

RESPONSABILIDADE

LLM: Texto final e tokens permitidos de ícone e cor.
Aplicação: Componente, SVG, paleta, posição e acessibilidade.

REGRAS

Exatamente um
Sempre o último
12–180 caracteres

6. Sugestão de banco inicial de ícones

Proposta inicial com 60 tokens distribuídos em seis categorias. O objetivo é cobrir os principais contextos do debrief sem entregar ao LLM um catálogo amplo demais ou com opções visualmente redundantes.

Como usar esta sugestão

O token é a parte estável do contrato. Os ícones Lucide abaixo servem apenas como referência visual para a PoC; engenharia pode mapear os mesmos tokens para a biblioteca adotada pelo design system. A lista final deve ser validada por produto e design antes de entrar no schema enviado ao LLM.

Dinheiro e finanças

Contextos financeiros concretos sem representar produtos específicos.

Carteira
wallet
Poupança
piggy_bank
Dinheiro
banknote
Moedas
coins
Cartão
credit_card
Recibo
receipt
Instituição
bank
Valor
money_circle
Orçamento
money_badge
Recursos
hand_coins

Objetivos e direção

Aspirações, metas e movimentos em direção ao futuro desejado.

Meta
target
Marco
flag
Conquista
trophy
Prioridade
star
Possibilidade
sparkles
Avanço
rocket
Jornada
mountain
Direção
compass
Caminho
map
Próxima etapa
milestone

Ações e progresso

Passos, decisões e continuidade sem sugerir aconselhamento financeiro.

Concluído
check
Confirmação
check_circle
Lista
checklist
Passos
steps
Planejado
calendar_check
Tempo
clock
Começar
play
Pausa
pause
Recomeçar
reset
Continuar
arrow_right

Emoções e reflexão

Sentimentos, percepções e estados internos mencionados no debrief.

Cuidado
heart
Positivo
smile
Difícil
sad
Neutro
neutral
Reflexão
brain
Insight
idea
Incerteza
cloud
Clareza
sun
Calma
moon
Motivação
energy

Segurança e atenção

Proteção, confiança, alertas e necessidade de suporte ou contexto.

Segurança
shield
Protegido
shield_check
Privado
lock
Acesso
unlock
Chave
key
Visível
visible
Oculto
hidden
Lembrete
notification
Atenção
warning
Ajuda
help

Vida e contexto pessoal

Pessoas, necessidades e objetivos concretos citados pelo aluno.

Pessoa
person
Família
people
Casa
home
Carro
car
Educação
education
Trabalho
work
Compras
shopping
Alimentação
food
Viagem
travel
Presente
gift

Token no contrato

Usar nomes semânticos e estáveis, como piggy_bank ou calendar_check.

Implementação na aplicação

Um registro interno converte cada token no SVG aprovado e define tamanho, espessura e acessibilidade.

Controle do catálogo

Tokens novos entram por versionamento do contrato; o LLM nunca informa nomes de arquivos ou ícones fora da lista.

1. Problema atual e solução proposta

Problema de entrega

Objetivo de produto

Critério da solução

Funcionamento atual

Solução proposta

Fronteira entre o LLM e a aplicação

LLM

Aplicação

2. Princípio central: um catálogo de componentes, ícones e cores conhecido pelo LLM e pela aplicação

O mecanismo central

3. Funcionamento da proposta

Preparar as entradas

Gerar o documento semântico

Validar a resposta

Montar a interface

4. Demonstração do contrato

Interface renderizada

What we heard

Making sense of it

An honest starting point

A direction that feels real

Resposta JSON do LLM

Resultado da validação

5. Catálogo detalhado de componentes

Resumo

Fala do aluno

Destaques das respostas

What we heard

Grupo de respostas

Triggers you noticed

Cards de reflexão

Making sense of it

An honest starting point

A direction that feels real

Itens numerados

What you’re carrying forward

Awareness is already present

Your dream creates direction

Destaque

Encerramento

6. Sugestão de banco inicial de ícones

Dinheiro e finanças

Objetivos e direção

Ações e progresso

Emoções e reflexão

Segurança e atenção

Vida e contexto pessoal