JuanOrtizOvied/construir-portafolio

Construir portfólio (modo guiado)

O objetivo é que a pessoa termine com um dashboard do seu portfólio classificado nas 6 seções do modelo e todas as suas subcategorias, com o Excel como download opcional. Muitas pessoas chegam com informações incompletas, então o portfólio é montado por partes: a cada etapa, processa-se o que foi enviado, mostra-se o progresso e pede-se o próximo item.

Arquivos desta skill (caminhos relativos ao diretório base):

Arquivo	Finalidade
references/guia-passo-a-passo.md	Como guiar a pessoa: ordem das seções, perguntas e tom. Leia ao começar.
references/regras-classificacao.md	Como decidir a categoria de cada produto. Leia antes de classificar.
references/formato-entrada.md	Formato do estado.json, o arquivo de progresso.
assets/categorias.json	Códigos de categoria válidos ↔ células do modelo.
assets/tema.json	Cores e marca do dashboard.
assets/modelo-portfolio-final.xlsx	Modelo oficial; nunca edite manualmente.
scripts/gerar_dashboard.py	Gera o dashboard HTML (também com progresso parcial).
scripts/preencher_modelo.py	Gera o Excel final com o modelo preenchido.
scripts/importar_excel.py	Recupera o progresso a partir de um Excel gerado anteriormente.

Ciclo de cada etapa

1. Retomar ou começar.

   • Se já existir estado.json no diretório de trabalho, carregue-o.
   • Se a pessoa enviar um Excel gerado anteriormente por este plugin, recupere o progresso com python <dir-skill>/scripts/importar_excel.py arquivo.xlsx estado.json.
   • Se não houver nada, crie estado.json com cliente, data_corte, secoes (as 6 em pendente) e posicoes: [], e dê as boas-vindas conforme o guia.

2. Processar o novo. Leia todos os arquivos enviados nesta etapa. Extraia cada posição com seu valor de mercado, moeda, instituição e página ou localização. Verifique também as seções de caixa e "outros ativos". Não adivinhe números ilegíveis: pergunte-os.

3. Classificar. Atribua a cada posição um código de assets/categorias.json conforme references/regras-classificacao.md. Se não reconhecer um ticker, ISIN ou fundo, pesquise antes de classificá-lo. Divida fundos globais ou mistos de acordo com seu fact sheet. Explique em nota toda classificação que não for óbvia.

4. Salvar. Adicione as posições ao estado.json. Se chegar um documento mais recente da mesma conta, substitua as posições anteriores dessa conta e avise. Atualize secoes apenas com o que a pessoa confirmou.

5. Mostrar o progresso.

   python <dir-skill>/scripts/gerar_dashboard.py estado.json dashboard.html
   

   Publique dashboard.html como artifact se você tiver a ferramenta (e nas etapas seguintes atualize esse mesmo artifact); caso contrário, envie-o como arquivo. Acompanhe com um resumo curto: o que foi adicionado, as dúvidas pontuais e a próxima pergunta da lista de verificação do guia.

6. Finalizar quando as 6 seções estiverem em completa ou nao_aplica:

   python <dir-skill>/scripts/preencher_modelo.py estado.json "Portfolio_<Nome>_<AAAA-MM-DD>.xlsx"
   python <dir-skill>/scripts/gerar_dashboard.py estado.json dashboard.html --excel "Portfolio_<Nome>_<AAAA-MM-DD>.xlsx"
   

   • Se preencher_modelo.py imprimir soma_pct diferente de 100 (± 0,05), revise antes de entregar.
   • Se você tiver a skill de Excel (xlsx) com recalc.py, recalcule o arquivo e confirme que não há erros e que Sheet1!D94 = 100%.
   • Entregue o dashboard como resultado principal, com o botão "Baixar Excel" incluído, e o Excel também como arquivo separado.
   • Lembre à pessoa que no Excel ela deve completar as colunas em branco (retornos e portfólio desejado) e seguir as instruções de envio do modelo.

A pessoa pode solicitar o Excel a qualquer momento, mesmo que incompleto: gere-o e avise quais seções faltam.

Regras

• Nunca invente valores. Todo número vem de um documento ou da pessoa.
• Use sempre valor de mercado na data de corte, não o custo.
• As porcentagens são calculadas sobre o Portfólio de Investimento; EMPRESA_PRIVADA e EXCLUIR não entram nesse total.
• Uma seção só é marcada completa ou nao_aplica quando a pessoa confirma.
• Os documentos contêm dados financeiros pessoais: não os compartilhe fora da conversa.
• As cores e a marca do dashboard vêm de assets/tema.json; não as altere por conta própria.