histórias-taiga

Histórias do Taiga

Não há controle de navegador. Os envios ocorrem através da API REST do Taiga com scripts/taiga_stories.py, que usa apenas a biblioteca padrão do Python. As mesmas ferramentas funcionam para qualquer projeto Taiga, que é configurado no .env.

Configuração (uma vez por repositório)

1. Copie .env.example para .env na raiz do repositório e defina TAIGA_PROJECT_URL com o link do projeto, ex.: https://taiga.exemplo.com/project/meu-projeto.
2. Opcionalmente, defina STORIES_DIR (padrão stories).

.env não contém segredos e é ignorado pelo git. O token nunca vai nele.

Escrevendo histórias

Cada história é um arquivo .md em stories/, seguindo o story-template.md.

• Nome do arquivo: minúsculas, sem acentos, palavras separadas por hífen (slug-automatico.md).

• Primeira linha: # História: <título>. O texto após "História:" vira o título no Taiga. Para correções de bugs, use Correção — <o que estava acontecendo>.

• Cabeçalho: **Projeto:**, **Branch:**, **Versão:**, **Período:** e **Pontos:**, um por linha.

• Pontos: não há padrão. Antes de salvar uma nova história em stories/, estime seus pontos com a skill story-points (histórico de commits do CODE_REPO_PATH) e peça confirmação ao usuário. Escreva o valor em **Pontos:**. Deve ser um nome na escala de pontos do projeto (1, 2, 3, 5, 8, 13, 21).

• Seções, nesta ordem: ## História de usuário (Como / quero / para, cada um em negrito em sua própria linha), ## Descrição (texto para o product owner, sem jargão de código), ## Critérios de aceite (- [ ] checklist, [x] para o que está feito e testado), ## Tarefas e ## Observações para implantação (ou ## Observações quando não for sobre implantação).

• Tarefas: agrupe-as sob ### Backend, ### Frontend, ### Testes e ### Documentação, nessa ordem, omitindo grupos vazios. Cada tarefa é N. **Título** com sua descrição indentada na linha seguinte. A numeração é contínua entre os grupos.

• Idioma: escreva toda a história, incluindo cabeçalhos, no idioma da solicitação do usuário. Uma solicitação em português gera uma história em português. Ambos os conjuntos de cabeçalhos são analisados:

  Inglês	Português
  # Story:	# História:
  **Project:** / **Branch:** / **Version:** / **Date:** / **Points:**	**Projeto:** / **Branch:** / **Versão:** / **Período:** / **Pontos:**
  ## User story (As / I want / so that)	## História de usuário (Como / quero / para)
  ## Description	## Descrição
  ## Acceptance criteria	## Critérios de aceite
  ## Tasks (### Backend, ### Frontend, ### Tests, ### Documentation)	## Tarefas (### Backend, ### Frontend, ### Testes, ### Documentação)
  ## Deployment notes / ## Notes	## Observações para implantação / ## Observações
  Fix — ...	Correção — ...

• Texto amigável ao firewall: nas descrições, evite ; antes de code (use ponto final), tags literais como <script> (escreva "a tag script") e cadeias de Classe::método próximas a rotas. O script contorna isso, mas o texto fica pior.

Verifique o formato (sem rede, sem token):

python -X utf8 .claude/skills/taiga-stories/scripts/taiga_stories.py validar [arquivo.md ...]

Corrija erros. Uma tarefa sem descrição é um aviso aceitável. A ausência de **Pontos:** é apenas um aviso aqui, mas impede o upload.

Enviando para o Taiga

Sempre pergunte primeiro, no chat, a cada vez

Use AskUserQuestion, ou uma pergunta simples se não estiver disponível. Não reutilize respostas anteriores:

1. Destino: qual sprint (nome exato, ex.: Sprint 34) ou backlog.
2. Token de sessão: na aba aberta do Taiga, F12 > Console > localStorage.getItem("token"). Use apenas como variável de ambiente inline para o comando. Nunca o escreva no .env ou em qualquer arquivo.
3. Pontos faltantes: se alguma história a ser enviada não tiver **Pontos:** (o --dry-run mostra FALTANDO), estime esses pontos com a skill story-points e peça confirmação ao usuário, listando-as por título. Escreva cada valor na linha **Pontos:** da história, logo após **Período:**. Histórias que já têm pontos não são estimadas novamente. O upload para antes de criar qualquer coisa enquanto alguma história não tiver um valor válido.

Se o .env estiver faltando, pergunte também pelo link do projeto Taiga e crie o .env a partir do .env.example.

Passos

S=.claude/skills/taiga-stories/scripts/taiga_stories.py
python -X utf8 $S validar
python -X utf8 $S enviar --sprint "Sprint 34" --dry-run        # ou --backlog
TAIGA_TOKEN='<token>' python -X utf8 $S enviar --sprint "Sprint 34"

Passe nomes de arquivo no final para enviar apenas algumas histórias. Em seguida, reporte ao usuário quantas histórias e tarefas foram criadas, além de quaisquer textos que o script reescreveu (e qualquer tarefa cuja descrição foi descartada).

Padrões: o dono do token é o responsável pelas histórias e tarefas, os status são os padrões do projeto, e os pontos vêm do campo **Pontos:** de cada história, no perfil computável do projeto.

O script:

• pula histórias cujo título já existe no projeto. Use --force apenas se o usuário pedir;
• retoma uma execução interrompida sem duplicar (estado em stories/.taiga_state.json). Se parar, apenas execute-o novamente;
• reescreve textos bloqueados pelo firewall e os lista ao final.

Não encadeie outros comandos de criação com ; após uma etapa que pode falhar. Uma falha no meio do caminho pode criar duplicatas.

Lições aprendidas

• Cloudflare 403 com corpo HTML ("Just a moment...") significa que o WAF bloqueou o texto, não um problema de permissão. O script tenta novamente com variantes mais simples. Se uma tarefa ficar sem descrição, reescreva-a como texto simples (sem crases, sem ::) e faça PATCH, enviando a version atual.
• 403 com JSON PermissionDenied é um erro de permissão real. Membros comuns podem não conseguir excluir histórias de usuário (tarefas são ok), então evite duplicatas. Se uma acontecer, reutilize a história com PATCH (assunto, descrição, pontos, milestone, assigned_to, version) em vez de excluí-la.
• Pontos vão em points: {"<id do perfil computável>": <id do ponto>}, e o id do ponto é consultado pelo nome na escala do projeto.
• No Windows, o Python não vê o /tmp do Git Bash. Use caminhos do Windows e execute Python com -X utf8 para que os acentos sejam impressos corretamente.