historias-taiga

Historias de Taiga

No hay control de navegador. Las subidas se realizan a través de la API REST de Taiga con scripts/taiga_stories.py, que solo usa la biblioteca estándar de Python. La misma herramienta funciona para cualquier proyecto de Taiga, configurado en .env.

Configuración (una vez por repositorio)

1. Copia .env.example a .env en la raíz del repositorio y establece TAIGA_PROJECT_URL con el enlace del proyecto, por ejemplo, https://taiga.example.com/project/mi-proyecto.
2. Opcionalmente, establece STORIES_DIR (por defecto stories).

.env no contiene secretos y está ignorado por git. El token nunca va en él.

Escritura de historias

Cada historia es un archivo .md en stories/, siguiendo story-template.md.

• Nombre de archivo: minúsculas, sin acentos, palabras separadas por guiones (slug-automatico.md).

• Primera línea: # Historia: <título>. El texto después de "Historia:" se convierte en el título de Taiga. Para correcciones de errores, usa Corrección — <lo que ocurría>.

• Encabezado: **Proyecto:**, **Branch:**, **Versión:**, **Período:** y **Puntos:**, uno por línea.

• Puntos: no hay valor por defecto. Antes de guardar una nueva historia en stories/, estima sus puntos con la skill story-points (historial de commits de CODE_REPO_PATH) y pide al usuario que los confirme. Escribe el valor en **Puntos:**. Debe ser un nombre en la escala de puntos del proyecto (1, 2, 3, 5, 8, 13, 21 ).

• Secciones, en este orden: ## Historia de usuario (Como / quiero / para, cada uno en negrita en su propia línea), ## Descripción (prosa para el propietario del producto, sin jerga técnica), ## Criterios de aceptación (- [ ] lista de verificación, [x] para lo que está hecho y probado), ## Tareas y ## Observaciones para implantación (o ## Observaciones cuando no se trata de implantación).

• Tareas: agrupa bajo ### Backend, ### Frontend, ### Pruebas y ### Documentación, en ese orden, omitiendo grupos vacíos. Cada tarea es N. **Título** con su descripción sangrada en la línea siguiente. La numeración es continua entre grupos.

• Idioma: escribe toda la historia, incluidos los encabezados, en el idioma de la solicitud del usuario. Una solicitud en portugués recibe una historia en portugués. Ambos conjuntos de encabezados se analizan:

  Español	Portugués
  # Historia:	# História:
  **Proyecto:** / **Branch:** / **Versión:** / **Período:** / **Puntos:**	**Projeto:** / **Branch:** / **Versão:** / **Período:** / **Pontos:**
  ## Historia de usuario (Como / quiero / para)	## História de usuário (Como / quero / para)
  ## Descripción	## Descrição
  ## Criterios de aceptación	## Critérios de aceite
  ## Tareas (### Backend, ### Frontend, ### Pruebas, ### Documentación)	## Tarefas (### Backend, ### Frontend, ### Testes, ### Documentação)
  ## Observaciones para implantación / ## Observaciones	## Observações para implantação / ## Observações
  Corrección — ...	Correção — ...

• Texto amigable con el firewall: en las descripciones, evita un ; justo antes de código (usa un punto final), etiquetas literales como <script> (escribe "la etiqueta script") y cadenas de Clase::método junto a rutas. El script evita estos problemas, pero el texto empeora.

Comprueba el formato (sin red, sin token):

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

Corrige errores. Una tarea sin descripción es una advertencia aceptable. Una falta de **Puntos:** solo es una advertencia aquí, pero bloquea la subida.

Subir a Taiga

Pregunta siempre primero, en el chat, cada vez

Usa AskUserQuestion, o una pregunta simple si no está disponible. No reutilices respuestas anteriores:

1. Destino: qué sprint (nombre exacto, por ej. Sprint 34) o backlog.
2. Token de sesión: en la pestaña abierta de Taiga, F12 > Consola > localStorage.getItem("token"). Úsalo solo como una variable de entorno en línea para el comando. Nunca lo escribas en .env ni en ningún archivo.
3. Puntos faltantes: si alguna historia a subir no tiene **Puntos:** (el --dry-run muestra FALTANTE), estima esos puntos con la skill story-points y pide al usuario que los confirme, enumerándolas por título. Escribe cada valor en la línea **Puntos:** de la historia, justo después de **Período:**. Las historias que ya tienen puntos no se vuelven a estimar. La subida se detiene antes de crear nada mientras alguna historia carezca de un valor válido.

Si falta .env, también pregunta por el enlace del proyecto de Taiga y crea .env a partir de .env.example.

Pasos

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

Pasa nombres de archivo al final para subir solo algunas historias. Luego informa al usuario cuántas historias y tareas se crearon, además de cualquier texto que el script reescribió (y cualquier tarea cuya descripción se eliminó).

Valores predeterminados: el propietario del token es el asignado de historias y tareas, los estados son los valores predeterminados del proyecto, y los puntos provienen del campo **Puntos:** de cada historia, sobre el rol computable del proyecto.

El script:

• omite historias cuyo título ya existe en el proyecto. Usa --force solo si el usuario lo solicita;
• reanuda una ejecución interrumpida sin duplicar (estado en stories/.taiga_state.json). Si se detiene, simplemente vuelve a ejecutarlo;
• reescribe textos bloqueados por el firewall y los enumera al final.

No encadenes otros comandos de creación con ; después de un paso que pueda fallar. Un fallo a medio camino puede crear duplicados.

Lecciones aprendidas

• Cloudflare 403 con un cuerpo HTML ("Un momento...") significa que el WAF bloqueó el texto, no un problema de permisos. El script reintenta con variantes más simples. Si una tarea termina sin descripción, reescríbela como prosa simple (sin acentos graves, sin ::) y haz un PATCH, enviando la version actual.
• 403 con JSON PermissionDenied es un error de permiso real. Los miembros regulares pueden no poder eliminar historias de usuario (las tareas están bien), así que evita duplicados. Si ocurre uno, reutiliza la historia con PATCH (subject, description, points, milestone, assigned_to, version) en lugar de eliminarla.
• Los puntos van en points: {"<id del rol computable>": <id del punto>}, y el id del punto se busca por su nombre en la escala del proyecto.
• En Windows, Python no ve /tmp de Git Bash. Usa rutas de Windows y ejecuta Python con -X utf8 para que los acentos se impriman correctamente.