| name | colher-duvidas |
| description | Colhe dúvidas de leitura (callouts `> [!duvida]`) de uma nota ou galho e transforma cada uma em melhoria de texto — consertando o fluxo (essencial) ou promovendo a um `> [!question]` polido (tangente). É a ponta que RESOLVE dúvidas; quem as PLANTA proativamente é a /plantar-duvidas. |
Skill: colher-duvidas
Fecha o loop capturar → colher → evoluir do padrão [[feedback-padrao-capitulo-livro|capítulo de livro]].
A dúvida real do leitor (um > [!duvida] largado no ponto exato em que ele travou) vira combustível
para o texto — não scaffolding jogado fora. É a versão sistematizada de "tirar dúvida no chat e usar
pra evoluir a nota".
O eixo é a decisão editorial, não responder por responder: dúvida sobre algo essencial conserta o
fluxo; dúvida tangente vira conversa permanente ([!question]). Nunca remendar conceito load-bearing
num FAQ.
Invocação
/colher-duvidas [path] [dúvidas soltas]
- Sem
path: pergunta a nota/galho.
path de nota: processa aquela nota.path de pasta (galho): varre todas as notas do galho.- Dúvidas soltas (texto livre): dúvidas ditas na conversa entram no pool junto com os marcadores do
texto (rota conversacional — você não precisa ter marcado no arquivo).
[!note] Para PLANTAR dúvidas, use a [[plantar-duvidas|/plantar-duvidas]]
Esta skill só resolve dúvidas que já existem (marcadas no texto ou ditas na conversa). Para uma
leitura cética que encontra e planta os pontos confusos antes de você travar, rode a
/plantar-duvidas primeiro — e depois colha aqui.
Os dois callouts (regra rígida)
| Callout | Papel | Publica? |
|---|
> [!duvida] | matéria-prima — a confusão crua, estado de trabalho | Não (limpar antes de deploy) |
> [!question] | produto — a conversa que fica, dúvida + resposta | Sim |
Formato do marcador de captura:
> [!duvida] <a pergunta, como o leitor a faria>
> <opcional: o que exatamente confundiu / "parece lista de ingredientes aqui">
[!warning] [!duvida] é transitório
Marcadores [!duvida] não devem sobreviver a um git push/deploy — eles renderizam no site. Rode a
colheita antes de publicar. Quem controla o deploy é o usuário (push manual).
Fases
Fase 1 — Localizar alvo
- Valida
path. Se for pasta, lista as notas (*.md, exceto MOC/index).
- Lê a(s) nota(s) inteira(s) e o frontmatter (
fase: calibra a régua — default Magus).
Fase 2 — Coletar dúvidas
Monta o pool a partir de:
- Marcadores no texto: todo bloco
> [!duvida] (com nota + localização da seção).
- Dúvidas soltas passadas na invocação.
- (Opcional) Arcana: se o usuário citar cards reprovados, cada um vira uma dúvida.
Se o pool estiver vazio e não houver dúvidas soltas → sugere rodar --cetico e encerra.
Fase 3 — Resolver
Para cada dúvida: responde com precisão. Se precisar de fato externo, faz WebSearch dirigido e guarda
a fonte ([[feedback-enriquecimento-feynman|registro Feynman]] na redação). Cruza com o resto do galho
para não duplicar ([[feedback-redundancia-entre-notas|redundância é reforço]] — linkar, não podar).
Fase 4 — Decisão editorial (o coração da skill)
Classifica cada dúvida resolvida:
| Classe | Sinal | Ação |
|---|
| Essencial | É sobre algo que o leitor precisa entender pra seguir; a confusão nasceu de um salto/peça-solta no fluxo principal | Conserta o fluxo: reescreve o trecho, adiciona o passo de encaixe ou um exemplo trabalhado. O [!duvida] é removido (curado). |
| Tangente | É um "você deve estar se perguntando" legítimo, interessante mas não load-bearing | Promove a [!question] (dúvida + resposta) no ponto certo. |
| Já coberta | A resposta já está no texto, o leitor só não conectou | Pequeno ajuste de sinalização/transição; remove o [!duvida]. |
Regra de ouro: callout é para o que é interessante saber; o fluxo é para o que é preciso saber.
Na dúvida entre as duas classes, prefira consertar o fluxo.
Fase 5 — Plano
Apresenta agrupado por nota, com diff antes→depois para reescritas e o texto do novo [!question]
para tangentes. Cada item marca a classe e a fonte (se houver). Confirmação obrigatória.
Fase 6 — Execução
Relê o arquivo antes de cada edição. Para cada item aprovado: aplica a reescrita ou insere o
[!question], e remove o [!duvida] correspondente. Atualiza updated: no frontmatter.
Fase 7 — Relatório
COLHIDO — <nota/galho>
✓ <n> dúvidas resolvidas → <a> consertos de fluxo, <b> novos [!question], <c> já cobertas
✓ <k> fontes adicionadas
– <m> dúvidas adiadas (sem resolução clara) — marcadas, ficam no texto
Convenções rígidas
- Confirmação antes de executar — nenhuma edição sem plano aprovado.
- Essencial → fluxo; tangente →
[!question]. Nunca remendar conceito central num FAQ colapsado.
- Aditivo + reescrita-com-diff — não reorganiza a nota inteira; reescrita só via diff aprovado item a item.
- Nunca remove um
[!duvida] sem resolvê-lo (ou sem o usuário mandar adiar).
- Proveniência para fatos novos (fonte na seção Referências, nunca no corpo).
- Não cria notas novas — exceto quando a decisão for "isto virou um broto" (aí segue
[[project-broto-galho-convention]]) e o usuário aprovar.
- Casa com
/enriquecer-nota (pode encadear), com o padrão [[feedback-padrao-capitulo-livro]] e o
registro [[feedback-enriquecimento-feynman]].
Edge cases
| Caso | Comportamento |
|---|
Nenhum [!duvida] e sem dúvidas soltas | Sugere rodar /plantar-duvidas; encerra |
| Dúvida sem resolução confiável | Não inventa; mantém o [!duvida], reporta como adiada |
Reescrita: trecho antes não casa exato | Pula o item, avisa; não edita às cegas |
| WebSearch offline | Resolve com o que dá; marca o que ficou sem fonte |
| Dúvida revela que a nota cobre 2 assuntos | Propõe split/broto ([[project-broto-galho-convention]]); não força no FAQ |
path é MOC/index | Avisa que MOC não recebe [!duvida]; pede a nota de conteúdo |
