ZekerTop/build-story

BuildStory

BuildStory ajuda uma pessoa a ver como um projeto foi construído, não apenas o que foi entregue. Ela reconstrói um conjunto pequeno de pontos de virada, identifica retrabalho repetido e prováveis sumidouros de tempo, analisa a alinhamento humano-IA com base em evidências quando transcrições são autorizadas, e transforma as evidências em lições e material de carreira.

Princípios inegociáveis

• Trate Git e logs de sessão como evidência, não como leitura de mente. Rotule inferências e nível de confiança.
• Lidere com a história do projeto. Mantenha contagens brutas de commits, histórico completo e cálculos numéricos como evidência de suporte.
• Mostre o ritmo do projeto como atividade observável, nunca como uma medida de diligência ou produtividade. Use "dia mais ativo", não "dia mais trabalhador".
• Selecione no máximo sete pontos de virada por padrão. Um log completo de Git é evidência, não uma narrativa.
• Nunca colapse o projeto em uma única pontuação total. Mostre um perfil irregular entre as dimensões.
• Não iguale iteração a desperdício. Chame padrões suspeitos de "candidatos a loop" até que a evidência ou o usuário os confirme.
• Prefira um insight de jornada no nível do tema sobre uma estatística no nível do arquivo. Um caminho e taxa de rotatividade são evidência; não são a conclusão.
• Classifique trabalho repetido apenas como blocked-loop, necessary-exploration ou direction-change, então peça ao usuário para confirmar a causa.
• Não invente impacto de negócio, propriedade, tamanho da equipe, ganhos de desempenho ou métricas de currículo.
• Analise a interação, nunca pontue ou diagnostique a habilidade de comunicação do usuário. Não calcule uma pontuação total de qualidade do prompt.
• Um prompt repetido não é evidência de redação pouco clara. Exija uma cadeia de usuário → assistente → correção do usuário na mesma sessão antes de criar um insight de comunicação.
• Mantenha falhas de execução da IA, incompatibilidade de significado de termos, evolução de requisitos e evidência insuficiente distintos. Nunca atribua padrão ao usuário.
• Trate commits de Git próximos a um esclarecimento como evidência próxima, não prova de que o esclarecimento causou o commit.
• Leia apenas o projeto atual por padrão. Pergunte antes de ler arquivos de sessão fora do espaço de trabalho autorizado.
• Mantenha a análise local a menos que o usuário solicite explicitamente um serviço externo.
• Nunca carregue ou reproduza uma transcrição completa. Mantenha apenas os pequenos trechos necessários para explicar uma conclusão.
• Não modifique arquivos fonte do projeto. Escreva os resultados em um diretório de saída dedicado.

Fluxo de trabalho padrão

1. Estabelecer escopo

Identifique a raiz do repositório e o objetivo do usuário. Padrão para a branch atual e o histórico completo do Git alcançável a partir de HEAD.

Use transcrições de sessão apenas quando elas já são fornecidas ou o usuário autoriza seus caminhos. Relatórios apenas com Git são úteis, mas devem marcar estimativas de tempo e conclusões de nível de intenção como baixa confiança.

2. Coletar evidências determinísticas

Execute o analisador incluído:

python3 <diretório-da-skill>/scripts/build_story.py <caminho-do-repo> \
  --output <caminho-do-repo>/relatorio-build-story \
  --language <pt|en>

Adicione uma ou mais fontes de transcrição quando autorizado:

python3 <diretório-da-skill>/scripts/build_story.py <caminho-do-repo> \
  --session <arquivo-ou-diretório-de-sessão-autorizado> \
  --output <caminho-do-repo>/relatorio-build-story \
  --language <pt|en>

Quando o contexto confirmado pelo usuário estiver disponível, salve-o no diretório de saída do relatório e execute novamente com --context:

{
  "pt": {
    "role": "sua responsabilidade real no projeto",
    "outcome": "o resultado verificado",
    "key_decision": "a decisão que melhor demonstra sua capacidade",
    "summary": "a história do projeto em uma linha",
    "resume_bullets": ["um bullet de currículo confirmado"],
    "insight_confirmations": {
      "caminho:src/sync.py": {
        "classification": "direction-change",
        "reason": "A sincronização automática violou a simplicidade voltada para iniciantes.",
        "lesson": "Quando um recurso introduz continuamente mecanismos de recuperação, reavalie se ele vale a pena existir."
      }
    },
    "communication_confirmations": {
      "comunicação:id-de-exemplo": {
        "attribution": "ai-ignored-explicit-requirement",
        "reason": "O requisito original já especificava claramente que a troca de idioma deveria ser mantida.",
        "analysis": "Isso parece mais uma falha de execução da IA, não que o usuário precisasse se alongar mais.",
        "lesson": "Quando limites claros ainda são ignorados, verifique primeiro a execução da IA."
      }
    },
    "translations": {
      "Initialize project": "Inicializar projeto",
      "Add the requested feature": "Adicionar o recurso solicitado"
    }
  },
  "en": {
    "role": "your real responsibility",
    "outcome": "the verified result",
    "key_decision": "the decision that best demonstrates your ability",
    "summary": "the one-line project story",
    "resume_bullets": ["a confirmed resume bullet"]
  }
}

python3 <diretório-da-skill>/scripts/build_story.py <caminho-do-repo> \
  --context <caminho-do-repo>/relatorio-build-story/context.json \
  --output <caminho-do-repo>/relatorio-build-story \
  --language <pt|en>

O script gera um relatório padrão mais variantes em português e inglês:

• evidence.json: evidência legível por máquina e métricas transparentes
• report.md: relatório de texto portátil
• report.html: relatório visual autocontido com um seletor PT / EN
• evidence.en.json, report.en.md, report.en.html: saídas em inglês
• evidence.pt.json, report.pt.md, report.pt.html: saídas em português

3. Inspecione a evidência antes de narrar

Leia evidence.json e verifique:

• journey_insights primeiro: seu tópico, classificação tentativa, cadeia de evidência, confiança e pergunta de confirmação;
• communication_insights quando transcrições são autorizadas: no máximo três cartões, cada um fundamentado em uma solicitação do usuário, resposta do assistente e correção posterior do usuário;
• cada atribuição de comunicação permanece distinta: informações esclarecidas posteriormente, IA ignorou um requisito explícito, significado do termo diferiu, requisito evoluiu ou evidência é insuficiente;
• fontes de dados e limitações declaradas;
• datas do projeto, contagens de commits, autores e contagens de arquivos;
• se a história da primeira tela é suportada pelos pontos de virada selecionados;
• se o período do projeto, dias ativos, maior sequência e o dia mais ativo correspondem aos dados de evidência subjacentes com data;
• reversões explícitas versus loops de alta rotatividade inferidos;
• se as estimativas de tempo vieram de Git ou sessões com carimbo de data/hora;
• a evidência e a confiança por trás de cada pontuação de dimensão.

Não lidere o chat com src/foo.py, contagens de commits ou percentagens de rotatividade. Traduza o insight mais forte para linguagem simples primeiro:

1. o que o usuário parece ter tentado;
2. se atualmente parece um loop bloqueado, exploração necessária ou mudança de direção;
3. quais commits suportam essa interpretação;
4. o único fato humano ausente que poderia mudar a conclusão.

Se os dados contradizem a descrição do usuário, mostre a discrepância e pergunte, em vez de escolher silenciosamente uma versão.

Para um relatório em português, inspecione os títulos visíveis dos pontos de virada e trechos de conversa. Se o material de origem estiver em outro idioma, adicione entradas exatas de fonte-para-português sob pt.translations e execute novamente. Mantenha o texto original nos dados de evidência, mas não faça o usuário ler uma história de desenvolvimento em inglês dentro de uma interface em português.

Quando transcrições autorizadas existem, use a breve solicitação do usuário e a resposta da IA anexadas a cada ponto de virada. Prefira esse diálogo legível por humanos a apresentar um assunto de commit como a história completa.

4. Confirme a jornada antes de escrever a realização

Faça no máximo três perguntas de confirmação no total. Escolha-as entre os journey_insights não confirmados de maior confiança e, apenas quando o usuário solicitou revisão de comunicação, um ou dois communication_insights. Não peça ao usuário para editar manualmente nenhum dos objetos de confirmação. Após o usuário responder, escreva a confirmação da jornada em insight_confirmations ou confirmação de comunicação em communication_confirmations, execute o analisador novamente e verifique se o relatório mostra a interpretação confirmada.

Somente após a jornada ser confirmada, pergunte por qualquer contexto de carreira restante. Não transforme o fluxo de trabalho em uma entrevista. Os fatos ausentes usuais são:

1. Qual era a responsabilidade real do usuário?
2. Qual resultado o projeto criou para o usuário ou para si mesmo?
3. Qual decisão melhor demonstra a capacidade do usuário?

Pule perguntas cujas respostas já estão documentadas no repositório.

Para saída de carreira, portfólio, realização ou entrevista, não deixe essas respostas como contexto apenas no chat. Salve-as em context.json, execute o analisador novamente e verifique o material reutilizável resultante. O relatório HTML é o artefato durável, não um substituto para a conversa de confirmação.

5. Produza a história solicitada

Use a evidência para uma ou mais destas saídas:

• Retrospectiva do projeto: linha do tempo, pontos de virada, atritos, lições, mudanças para a próxima execução.
• Revisão de comunicação: redação original, interpretação do assistente, correção posterior, atribuição neutra e, apenas quando suportado, uma reescrita pronta para cópia e padrão reutilizável. Mostre no máximo três cartões e nunca dê uma pontuação de prompt.
• Estudo de caso de portfólio: problema, restrições, decisões, implementação, validação, resultado.
• Bullets de currículo: ação + escopo + método + resultado verificado. Deixe um placeholder explícito quando o impacto é desconhecido.
• História de entrevista: estrutura STAR fundamentada em commits, diffs, testes, lançamentos e contexto confirmado pelo usuário.
• Registro de realização: cartões de evidência duráveis que explicam o que o usuário realmente fez.

Leia references/narrative-guide.md ao produzir escrita de carreira ou portfólio. Leia references/methodology.md ao explicar pontuações, estimativas de tempo ou detecção de loops.

Padrão de qualidade da saída

Um relatório BuildStory finalizado deve permitir que o usuário responda:

1. Qual é a história em uma frase deste projeto?
2. Em que período de tempo o trabalho observável ocorreu, em quantos dias, e o que aconteceu no dia mais ativo?
3. Quais cinco a sete viradas mudaram sua direção, risco, entendimento ou estado de entrega?
4. Onde o trabalho repetidamente fez loop ou reversão?
5. Cada área repetida foi um loop bloqueado, exploração necessária ou mudança de direção, e o que ainda precisa de confirmação?
6. Quais áreas absorveram mais atenção, e quão confiante é essa estimativa?
7. O que o usuário demonstravelmente aprendeu ou melhorou?
8. Que realização credível pode ser reutilizada em um currículo, portfólio, entrevista ou registro pessoal?
9. Quais detalhes se tornaram claros apenas depois que a IA já havia agido, como a causa deve ser atribuída, e o que poderia ser dito mais cedo na próxima vez?

Se a evidência disponível não puder responder a uma dessas, declare o que está faltando. Uma história honesta e menor é melhor do que uma ficcional impressionante.