O que é uma sessão no estudo guiado

Definição curta

No estudo guiado, uma sessão é o ciclo de leitura guiada de um documento Markdown específico aberto no Reader. Ela combina duas coisas:

a análise estática da estrutura do documento carregado naquele momento;
o estado de engajamento do leitor enquanto ele percorre as seções.

Em outras palavras, sessão não é uma conversa aberta com o produto nem uma memória global do usuário. Sessão é o recorte de trabalho do estudo guiado sobre um documento concreto.

Quando a sessão começa

Uma sessão começa quando três condições já estão satisfeitas:

existe um documento carregado no Reader;
esse documento já foi renderizado em HTML;
o usuário ativa o estudo guiado.

Nesse ponto, o estudo guiado lê a versão atual do documento e monta sua estrutura de trabalho. Ele identifica as seções, gera as perguntas heurísticas e cria o mapa inicial de engajamento por seção.

O que faz parte de uma sessão

Dentro de uma sessão, o estudo guiado passa a operar sobre um conjunto estável de elementos:

a lista de seções detectadas a partir dos headings do documento;
a posição de cada seção no todo, como abertura, meio ou fechamento;
sinais estruturais de cada seção, como listas, blocos de código, termos em negrito e blockquotes;
as perguntas de previsão, questionamento e conclusão geradas para cada seção;
o progresso do leitor em cada etapa;
as notas produzidas durante a leitura;
o Mapa de Compreensão gerado ao final do percurso.

Na prática, a sessão é o encontro entre o esqueleto do documento e as ações do leitor sobre esse esqueleto.

Por que a análise é estática

O estudo guiado não interpreta semanticamente o documento como um modelo de linguagem faria. Ele usa análise estática da estrutura renderizada do Markdown.

Isso significa que o estudo guiado olha para características como:

títulos H2 e H3;
posição relativa da seção no documento;
presença e quantidade de blocos de código;
presença de listas ordenadas ou não ordenadas;
quantidade de itens em listas;
termos destacados em negrito;
presença de citações;
um trecho curto de texto para representar a seção.

Com base nisso, ele escolhe templates de perguntas. A pergunta muda conforme a estrutura detectada, não conforme uma compreensão semântica profunda do conteúdo.

Quando uma seção qualifica para estudo guiado

Ter um heading não é suficiente. Para uma seção virar unidade do estudo guiado e exibir o gatilho “Ativar estudo”, ela precisa também ter corpo mínimo capaz de sustentar pelo menos uma das três fases:

Previsão (anchor): seção com pelo menos 40 palavras;
Questionamento (friction): seção com sinal estrutural (lista, bloco de código ou termo em negrito), conector adversativo na prosa, ou ao menos 120 palavras;
Conclusão (synthesis): seção com 2 ou mais parágrafos, ou ao menos 80 palavras.

Se nenhuma fase é detectável, a seção continua visível no Reader e no TOC, mas não entra no estudo guiado. Esse filtro evita “Ativar estudo” em headings vazios ou com uma única frase, onde não há material para a pergunta socrática operar.

Quando o `.md` está mal estruturado

O estudo guiado é tolerante a Markdown imperfeito, mas ele não corrige a estrutura do documento. Ele apenas trabalha com a hierarquia que encontra.

A regra prática da implementação atual é:

H1 funciona como título do documento, não como unidade de seção do estudo guiado;
H2 abre uma seção principal candidata;
H3 abre uma subseção candidata;
H4, H5 e H6 não viram seções do estudo guiado;
sem H2 ou H3, não existe sessão seccional para estudo guiado, cards e TOC;
mesmo com H2/H3, a seção só vira unidade de estudo se atender ao critério de fase descrito acima.

O que fazer em cada cenário

Cenário	Como o produto se comporta	O que fazer
Apenas `H2`	Funciona bem. O estudo guiado trata cada `H2` como seção principal.	Pode manter assim. Só adicione `H1` se quiser um título explícito para o documento.
`H1` e depois `H2`	Este é o cenário mais saudável. `H1` nomeia o documento e `H2` organiza a sessão.	Tratar como estrutura recomendada.
Apenas `H1`	O Reader renderiza o texto, mas estudo guiado, cards e `TOC` não detectam seções. A apresentação cai em fallback de slide único.	Adicionar `H2` ou `H3` para dividir o documento.
`H1` e depois `H3`, sem `H2`	O sistema ainda detecta seção, mas a hierarquia fica degradada: o `H3` vira subseção sem pai lógico.	Promover esse `H3` para `H2` ou inserir um `H2` pai.
`H2` e depois `H4`, pulando `H3`	O `H4` continua visível no Reader, mas não abre uma nova seção para estudo guiado, `TOC` ou slides.	Se essa parte precisar ser navegável, promover `H4` para `H3`.
Só `H4`, `H5` ou `H6`	O texto renderiza, mas a experiência orientada por seção praticamente não existe.	Promover os títulos estruturais para `H2` ou `H3`.
Texto introdutório antes do primeiro `H2` ou `H3`	O conteúdo aparece no Reader, mas fica fora do modelo de sessão. Não vira bloco próprio no estudo guiado.	Se a introdução precisar entrar no fluxo do estudo guiado, criar uma seção como `## Introdução`.
`H2` ou `H3` repetidos com o mesmo texto	O sistema evita colisão de IDs internamente, então não quebra. Mesmo assim, TOC, mapa e notas ficam ambíguos para o leitor.	Renomear headings repetidos para que cada seção tenha uma função clara.
Heading tecnicamente válido, mas mal redigido, como “Mais”, “Coisas”, “Parte 2”	O estudo guiado funciona, mas gera perguntas piores e produz um mapa menos informativo.	Reescrever o heading para nomear a intenção real da seção.
`H2` ou `H3` com corpo curto (uma frase, sem listas/código/negrito)	A seção aparece no Reader e no `TOC`, mas não vira unidade do estudo guiado: “Ativar estudo” não é exibido.	Expandir o corpo até atingir um dos limiares de fase, ou agrupar com a seção vizinha.

Casos que parecem erro, mas não são

Do ponto de vista do estudo guiado:

um documento com apenas H2 não está malformado;
um documento com H1 seguido de vários H2 é o formato ideal;
H3 só faz sentido quando realmente representa uma subdivisão de uma seção maior;
uma seção com heading mas sem corpo suficiente não exibir “Ativar estudo” não é bug — é o filtro de qualificação evitando perguntas vazias.

O problema começa quando a hierarquia visual do autor não coincide com a hierarquia estrutural que o produto consegue usar.

Regra editorial para recuperar um `.md` ruim

Se o documento chegou desorganizado, a correção mais segura é:

garantir um título geral em H1, quando fizer sentido;
transformar cada bloco principal do texto em H2;
usar H3 apenas para subdivisões reais dentro de um H2;
promover H4+ para H3 quando eles precisarem aparecer no fluxo de leitura;
criar um ## Introdução se existir abertura solta antes da primeira seção;
trocar headings vagos por headings que digam o tema ou a função da seção.

O que acontece durante a sessão

Depois de ativado, o estudo guiado organiza a leitura seção por seção. Cada seção pode atravessar fases como:

anchor: provocação antes da leitura;
reading: seção liberada para leitura;
friction: pergunta de atrito cognitivo;
synthesis: registro da conclusão do leitor;
done: seção concluída dentro da sessão.

Essas fases pertencem à sessão porque são o estado vivo da interação do leitor com aquele documento.

Quando a sessão termina

Do ponto de vista do produto, a sessão deixa de valer como contexto ativo quando o documento muda ou quando o fluxo de leitura é abandonado. Trocar o documento significa iniciar outro contexto de sessão, porque a estrutura analisada já é outra.

Desativar o painel do estudo guiado não precisa encerrar a sessão. Na implementação atual, o estado pode ser retomado localmente ao reabrir o modo para o mesmo documento.

Persistência local: retomada, não inteligência

Existe um ponto importante aqui: o fato de o estudo guiado salvar estado localmente não muda a definição de sessão.

Persistência local serve para retomar o andamento de leitura de um documento. Ela não transforma o estudo guiado em um sistema com memória interpretativa entre documentos, nem em um agente que aprende semanticamente com sessões anteriores.

Uma forma prática de descrever isso é:

O estudo guiado pode reabrir o estado de uma sessão, mas continua operando sobre a análise estática do documento atual.

O que uma sessão não é

Uma sessão no estudo guiado não é:

uma conta de usuário;
um histórico global de tudo o que a pessoa já leu;
uma análise semântica profunda do texto;
um chat contextual com o documento;
uma memória compartilhada entre documentos diferentes.

Essa distinção é importante porque o estudo guiado foi desenhado para ser local, previsível e barato: ele reage à estrutura do Markdown e ao engajamento do leitor, não a um backend de interpretação.

Frase pronta para usar na documentação

Se precisar de uma definição curta para produto, spec ou README, esta formulação é a mais fiel:

Uma sessão de estudo guiado é o ciclo de leitura guiada de um documento Markdown específico aberto no Reader, construído a partir de uma análise estática da estrutura do documento e enriquecido pelas interações do leitor seção por seção.

Consequência de design

Definir sessão dessa maneira traz três implicações diretas para o produto:

o estudo guiado depende de documento estruturado em seções, não de texto solto;
mudar o documento implica nova análise estrutural;
o valor do estudo guiado está menos em “entender o texto” e mais em organizar um ritual de leitura ativa sobre a estrutura que o autor já forneceu.