ai-flow-dev 2.8.1 → 2.9.0

package/prompts/frontend/flow-finish.md

@@ -255,8 +255,73 @@ STORY_POINTS=${STORY_POINTS:-0}
 DURATION_HOURS=$(( DURATION_MIN / 60 ))
 DURATION_MINS=$(( DURATION_MIN % 60 ))
 
-# 2. Build JSON analytics
-ANALYTICS_JSON="{\"task\":\"$TASK_FOLDER\",\"type\":\"$TASK_TYPE\",\"src\":\"$TASK_SOURCE\",\"dur\":$DURATION_MIN,\"start\":\"$CREATED_AT\",\"end\":\"$COMPLETED_AT\",\"tasks\":$TOTAL_TASKS,\"sp\":$STORY_POINTS,\"commits\":$COMMIT_COUNT,\"valid\":$VALIDATION_PASSED}"
+# Extract new analytics fields (Phase 1)
+# 1. User name
+USER_NAME=$(git config user.name 2>/dev/null || echo "Unknown")
+
+# 2. Task summary (first line after ## Objective in work.md)
+if [ -f "$TASK_PATH/work.md" ]; then
+  SUMMARY=$(grep -A 1 "^## Objective" "$TASK_PATH/work.md" | tail -1 | sed 's/^[[:space:]]*//' | cut -c 1-80)
+  SUMMARY=${SUMMARY:-"No description"}
+else
+  SUMMARY="No description"
+fi
+
+# 3. Complexity (COMPLEX if status.json exists, otherwise MEDIUM)
+if [ -f "$TASK_PATH/status.json" ]; then
+  COMPLEXITY="COMPLEX"
+else
+  COMPLEXITY="MEDIUM"
+fi
+
+# 4. Branch name
+BRANCH_NAME=$(git branch --show-current 2>/dev/null || echo "unknown")
+
+# 5. Tags (infer from changed files)
+CHANGED_PATHS=$(git diff --name-only main..HEAD 2>/dev/null | head -10)
+TAGS=()
+
+if echo "$CHANGED_PATHS" | grep -qiE 'controller|route|endpoint|api'; then
+  TAGS+=("API")
+fi
+if echo "$CHANGED_PATHS" | grep -qiE 'service|module|core|backend'; then
+  TAGS+=("Backend")
+fi
+if echo "$CHANGED_PATHS" | grep -qiE 'component|page|view|frontend'; then
+  TAGS+=("Frontend")
+fi
+if echo "$CHANGED_PATHS" | grep -qiE 'test|spec'; then
+  TAGS+=("Testing")
+fi
+if echo "$CHANGED_PATHS" | grep -qiE 'database|migration|schema|model'; then
+  TAGS+=("Database")
+fi
+
+# Convert tags array to JSON
+if [ ${#TAGS[@]} -eq 0 ]; then
+  TAGS_JSON="[]"
+else
+  TAGS_JSON=$(printf '%s\n' "${TAGS[@]}" | jq -R . | jq -s .)
+fi
+
+# 2. Build JSON analytics using jq for proper structure
+ANALYTICS_JSON=$(jq -n \
+  --arg task "$TASK_FOLDER" \
+  --arg type "$TASK_TYPE" \
+  --arg src "$TASK_SOURCE" \
+  --arg start "$CREATED_AT" \
+  --arg end "$COMPLETED_AT" \
+  --argjson dur "$DURATION_MIN" \
+  --argjson sp "$STORY_POINTS" \
+  --argjson tasks "$TOTAL_TASKS" \
+  --argjson commits "$COMMIT_COUNT" \
+  --argjson valid "$VALIDATION_PASSED" \
+  --arg user "$USER_NAME" \
+  --arg summary "$SUMMARY" \
+  --arg complexity "$COMPLEXITY" \
+  --arg branch "$BRANCH_NAME" \
+  --argjson tags "$TAGS_JSON" \
+  '{task, type, src, start, end, dur, sp, tasks, commits, valid, user, summary, complexity, branch, tags}')
 
 # 3. Append to analytics.jsonl
 mkdir -p .ai-flow/archive
@@ -591,9 +656,15 @@ function generate_commit_links() {
       fi
 
       if [ -n "$COMMIT_URL_PATTERN" ]; then
-        COMMIT_HASHES_SUMMARY+="[${hash}](${COMMIT_URL_PATTERN}${hash})"
+        # Build markdown link in parts to avoid VSCode link detection
+        COMMIT_HASHES_SUMMARY+="["
+        COMMIT_HASHES_SUMMARY+="$hash"
+        COMMIT_HASHES_SUMMARY+="]("
+        COMMIT_HASHES_SUMMARY+="$COMMIT_URL_PATTERN"
+        COMMIT_HASHES_SUMMARY+="$hash"
+        COMMIT_HASHES_SUMMARY+=")"
       else
-        COMMIT_HASHES_SUMMARY+="\`${hash}\`"
+        COMMIT_HASHES_SUMMARY+='`'"${hash}"'`'
       fi
     fi
     count=$((count + 1))
@@ -703,108 +774,378 @@ Read the structured summary from `/tmp/ai-context-summary.md` (400-600 words) an
 **AI Prompt:**
 
 ```markdown
-Genera dos descripciones profesionales (PR y Jira) basándote en este resumen estructurado:
+Genera dos descripciones profesionales (PR y Jira) usando el TEMPLATE OFICIAL en `.ai-flow/templates/pr-description.template.md`.
 
 <context-summary>
 $(cat /tmp/ai-context-summary.md)
 </context-summary>
 
-<commit-links>
-Platform: $PLATFORM
-Base URL Pattern: $COMMIT_URL_PATTERN
-Commit Hashes Summary: $COMMIT_HASHES_SUMMARY
-</commit-links>
+<template-variables>
+## Core Variables
+TASK_TYPE=$TASK_TYPE
+TASK_TITLE=[Extrae de WORK_OBJECTIVE]
+BRANCH_NAME=$CURRENT_BRANCH
+STORY_POINTS=$STORY_POINTS
+DURATION=${DURATION_HOURS}h ${DURATION_MINS}min
+IMPACT_AREA=$IMPACT_AREA
+PLATFORM=$PLATFORM
+COMMIT_HASHES_SUMMARY=$COMMIT_HASHES_SUMMARY
 
-<formatting-requirements>
-- Área de impacto detectada: $IMPACT_AREA
-- Mostrar deployment notes: $([ "$SHOW_DEPLOYMENT_NOTES" = "true" ] && echo "SÍ" || echo "NO")
-- Breaking changes: $([ "$HAS_BREAKING_CHANGES" = "true" ] && echo "SÍ (resaltar con ⚠️)" || echo "NO")
-- Branch: $CURRENT_BRANCH
-- Story Points: $STORY_POINTS SP
-- Duration: ${DURATION_HOURS}h ${DURATION_MINS}min
-</formatting-requirements>
-
-**Requisitos:**
-
-1. **PR Description (GitHub/GitLab/Bitbucket):**
-   - Título: ## ${TASK_TYPE^}: [nombre descriptivo basado en objective]
-   - Header con branch, SP, duration
-   - Sección "Área de Impacto" con valor: $IMPACT_AREA
-   - Contexto: Resume el problema/necesidad en 2-3 líneas (extrae de objective)
-   - Solución Implementada: Resume enfoque técnico en 2-3 líneas (infiere de commits)
-   - Cambios principales: Lista 5-7 cambios significativos (analiza commit subjects)
-   - Validación: Tabla con Tests, Coverage, Lint, Docs
-   - Métricas: Tabla con Commits, Archivos, Breaking Changes
-   - Deployment Notes: Solo SI $SHOW_DEPLOYMENT_NOTES=true, incluir requirements específicos
-   - Referencias: Commits con links usando $COMMIT_HASHES_SUMMARY
-   - Reviewer checklist
-
-2. **Jira Description (Markdown estándar):**
-   - Similar estructura pero más concisa
-   - Enfoque en resultado de negocio
-   - Métricas en tabla
-   - Deployment notes si aplica
-   - Referencias con commits
+## Change Type Detection (marca con 'x' el que aplique)
+
+IS_FEATURE=$([ "$TASK_TYPE" = "feature" ] && echo "x" || echo " ")
+IS_FIX=$([ "$TASK_TYPE" = "fix" ] && echo "x" || echo " ")
+IS_REFACTOR=$([ "$TASK_TYPE" = "refactor" ] && echo "x" || echo " ")
+IS_DOCS=$([ "$TASK_TYPE" = "docs" ] && echo "x" || echo " ")
+IS_PERF=$([ "$TASK_TYPE" = "perf" ] && echo "x" || echo " ")
+IS_TEST=$([ "$TASK_TYPE" = "test" ] && echo "x" || echo " ")
+
+## Context & Solution (genera desde context-summary)
+
+CONTEXT=[Resume el problema/necesidad en 2-3 líneas del WORK_OBJECTIVE]
+SOLUTION=[Resume el enfoque técnico en 2-3 líneas analizando COMMIT_SUBJECTS]
+MAIN_CHANGES=[Lista 5-7 cambios como bullets, infiere de COMMIT_SUBJECTS]
+TEST_STEPS=[Genera 3-5 pasos específicos para probar, infiere de WORK_TASKS y TASK_TYPE]
+
+## Validation Metrics
+
+TESTS_PASSED=$TESTS_PASSED
+TESTS_TOTAL=$TESTS_TOTAL
+TESTS_NEW=$TESTS_NEW
+COVERAGE=$COVERAGE
+DOCS_STATUS=$([ -n "$(git diff --name-only main..HEAD | grep '\.md$')" ] && echo "✅ Actualizada" || echo "⚠️ Revisar")
+
+## Code Metrics
+
+TOTAL_COMMITS=$TOTAL_COMMITS
+FILES_COUNT=$FILES_COUNT
+LINES_ADDED=$LINES_ADDED
+LINES_DELETED=$LINES_DELETED
+
+## Breaking Changes
+
+HAS_BREAKING_CHANGES=$HAS_BREAKING_CHANGES
+BREAKING_CHANGES_STATUS=$([ "$HAS_BREAKING_CHANGES" = "true" ] && echo "⚠️ SÍ (ver abajo)" || echo "✅ No")
+BREAKING_CHANGES_LIST=$([ "$HAS_BREAKING_CHANGES" = "true" ] && echo "$COMMIT_BREAKING" || echo "")
+MIGRATION_GUIDE=$([ "$HAS_BREAKING_CHANGES" = "true" ] && echo "[TODO: Usuario debe completar guía de migración]" || echo "")
+
+## Deployment
+
+SHOW_DEPLOYMENT_NOTES=$SHOW_DEPLOYMENT_NOTES
+HAS_MIGRATIONS=$HAS_MIGRATIONS
+MIGRATION_FILES=$MIGRATION_FILES
+NEW_ENV_VARS=$NEW_ENV_VARS
+HAS_NEW_DEPS=$HAS_NEW_DEPS
+INSTALL_CMD=$INSTALL_CMD
+NEW_DEPENDENCIES=[Lista las dependencias nuevas del diff de package.json/requirements.txt/etc]
+
+## Issues & Screenshots
+
+RELATED_ISSUES=[Busca en commits patrones como "Closes #123", "Fixes #456", extráelos]
+HAS_ISSUES=$([ -n "$RELATED_ISSUES" ] && echo "true" || echo "false")
+HAS_UI_CHANGES=$(echo "$FILES_BY_CATEGORY" | grep -qi 'frontend' && echo "true" || echo "false")
+SCREENSHOTS_SECTION=$([ "$HAS_UI_CHANGES" = "true" ] && echo "## 📸 Screenshots\n\n💡 **Recomendación:** Agrega screenshots mostrando los cambios visuales (antes/después)" || echo "")
+
+## Jira-Specific Variables (para comentario compacto)
+
+BUSINESS_SUMMARY=[Genera 1-2 líneas describiendo el VALOR DE NEGOCIO entregado, no detalles técnicos. Perspectiva de usuario/stakeholder]
+
+# PR Link construction (considera que el PR aún NO existe al ejecutar /flow-finish)
+
+PR_LINK=[SIEMPRE usa este formato exacto: "🔗 PR: [PEGAR_LINK_AQUI]"]
+PR_CREATION_COMMANDS=[Genera comandos específicos según $PLATFORM:
+
+- GitHub: "gh pr create --title \"$TASK_TYPE: $TASK_FOLDER\" --body-file <(echo \"Ver PR description arriba\")"
+- GitLab: "glab mr create --title \"$TASK_TYPE: $TASK_FOLDER\" --description \"Ver PR description arriba\""
+- Bitbucket: "bb pr create --title \"$TASK_TYPE: $TASK_FOLDER\""
+- Genérico: "Crear PR manualmente en: ${COMMIT_URL_PATTERN%/commit/\*}/pulls"]
+
+DEPLOYMENT_STATUS=[Detecta: "✅ Disponible en dev" si es local, "⏳ Pendiente staging/prod" si no hay push, "🚀 En producción" si tag release]
+DEPLOYMENT_NOTES_COMPACT=[Si SHOW_DEPLOYMENT_NOTES=true, versión ultra-compacta: "⚠️ Requiere: nuevas env vars + npm install" en 1 línea]
+QA_NOTES=[SOLO si hay algo crítico que QA debe saber: breaking changes, configuración especial, comportamiento no obvio. Si no hay nada especial, omitir completamente]
+
+# Screenshots (OBLIGATORIO para frontend - formato simple con espacio para adjuntar)
+
+SCREENSHOTS*REMINDER="\n## 📸 Screenshots\n\n### Before\n[Adjuntar imagen]\n\n### After\n[Adjuntar imagen]\n\n_Incluir: diferentes estados (hover, active, disabled), responsive (mobile/tablet/desktop)*"
+
+## 2026 Standard Sections (Security, Performance, Observability)
+
+SECURITY_IMPACT=[Analiza el código y evalúa:
+
+- Si hay cambios en auth/permisos → "- ✅ Auth/permissions changes reviewed and validated"
+- Si hay exposición de datos → "- ✅ Data exposure risk mitigated with validation"
+- Si hay nuevas deps → "- ✅ Dependencies scanned (npm audit / snyk)"
+- Si hay endpoints públicos → "- ✅ API rate limiting implemented"
+- Si no hay riesgos → "- ✅ No security implications"
+  Formato: lista de checkboxes con lo que aplica]
+
+PERFORMANCE_IMPACT=[Analiza si el cambio afecta performance:
+
+- Si es feature/refactor con queries → "**Database:** Query optimized with indexes (+50% faster)\n**Load tested:** ✅ 1000 concurrent requests"
+- Si es fix de performance → "**Before:** {{métrica}} ms\n**After:** {{métrica}} ms ({{%}} improvement)"
+- Si es UI → "**Bundle size:** +5KB (minified+gzip)\n**Lighthouse:** Performance 95/100"
+- Si no hay impacto significativo → "No significant performance impact expected."
+  Sé específico con métricas reales si están en work.md]
+
+OBSERVABILITY=[Analiza qué logging/monitoring se agregó o debe considerarse:
+
+- Si hay logs nuevos → "- ✅ Structured logging added for {{feature}}"
+- Si hay métricas → "- ✅ Metrics: {{metric_names}}"
+- Si debe agregar alerts → "- ⚠️ Consider adding alert for {{condition}}"
+- Si no aplica → "- ℹ️ No observability changes ({{reason: refactor/docs/etc}})"
+  Enfócate en lo que REALMENTE se agregó o es necesario]
+
+</template-variables>
+
+<instructions>
+**Lee el template en `.ai-flow/templates/pr-description.template.md`** y genera DOS descripciones siguiendo EXACTAMENTE esa estructura:
+
+1. **PR Description (GitHub/GitLab/Bitbucket) - TÉCNICO, COMPLETO:**
+   - Usa TODAS las secciones del template
+   - Renderiza variables con valores reales
+   - Audiencia: Desarrolladores y Reviewers
+   - Enfoque: "Cómo se implementó" (detalles técnicos)
+   - Incluye secciones condicionales SOLO si aplican:
+     - Breaking Changes Details (si HAS_BREAKING_CHANGES=true)
+     - Deployment Notes (si SHOW_DEPLOYMENT_NOTES=true)
+     - Screenshots (si HAS_UI_CHANGES=true)
+   - Genera TEST_STEPS específicos del contexto (no genéricos)
+
+2. **Jira Comment (Task Update) - BUSINESS-ORIENTED, COMPACTO:**
+   - Audiencia: QA, PM, Stakeholders + Devs
+   - Enfoque: "Qué se logró y cómo probarlo" (resultado de negocio)
+   - Máximo 20-25 líneas (escaneable en 30 segundos)
+   - BUSINESS_SUMMARY es lo MÁS IMPORTANTE: debe explicar el valor sin términos técnicos
+   - TEST_STEPS deben ser actionables para QA (no requieren conocimiento de código)
+   - SCREENSHOTS_REMINDER siempre presente para frontend (cambios visuales esperados)
+   - DEPLOYMENT_NOTES_COMPACT solo si es crítico (1 línea máximo)
+   - QA_NOTES solo si hay algo no obvio que QA debe saber
 
 **Reglas Importantes:**
 
-- Usa lenguaje profesional pero claro
-- Sé específico con cambios técnicos
+- Usa lenguaje profesional pero claro (nivel senior engineer)
+- Sé específico con cambios técnicos (usa nombres reales de archivos/módulos)
 - Usa los commit links ya formateados en $COMMIT_HASHES_SUMMARY
-- Escapa caracteres especiales para Markdown válido (backticks, pipes, asteriscos)
-- Usa separadores `---` (no `━━━━`)
-- Si breaking changes, resáltalos con ⚠️ en sección Métricas
-- Si deployment notes, sé específico con cada requirement
+- Genera TEST_STEPS específicos del tipo de cambio (no pasos genéricos)
+- Si MIGRATION_GUIDE está vacío y hay breaking changes, recomienda al usuario completarlo
+- Escapa caracteres especiales correctamente para Markdown válido
+- Usa separadores `---` (no `━━━━` o caracteres Unicode)
+- Si NEW_DEPENDENCIES está vacío pero HAS_NEW_DEPS=true, detecta del diff
+
+**Output Format:**
+
+IMPORTANTE: Responde directamente con este formato EXACTO usando 5 BACKTICKS (máxima robustez):
+
+---
+
+## 📋 PULL REQUEST DESCRIPTION
+
+\`\`\`\`\`markdown
+
+## {{TASK_TYPE}}: {{TASK_TITLE}}
+
+> **Branch:** `{{BRANCH_NAME}}` • **Story Points:** {{STORY_POINTS}} SP • **Duration:** {{DURATION}}
+
+---
+
+## 🎯 Tipo de Cambio
+
+- [{{IS_FEATURE}}] ✨ Feature (nueva funcionalidad)
+- [{{IS_FIX}}] 🐛 Fix (corrección de bug)
+- [{{IS_REFACTOR}}] ♻️ Refactor (sin cambio funcional)
+- [{{IS_DOCS}}] 📝 Docs (solo documentación)
+- [{{IS_PERF}}] ⚡ Performance (mejora)
+- [{{IS_TEST}}] 🧪 Test (agregar/mejorar tests)
+
+## 🎯 Área de Impacto
+
+**{{IMPACT_AREA}}**
+
+## 💡 Contexto
+
+{{CONTEXT}}
+
+{{RELATED_ISSUES}}
+
+## ✅ Solución Implementada
+
+{{SOLUTION}}
+
+## 🔧 Cambios Principales
 
-**Output en formato (CRÍTICO - respetar delimitadores):**
+{{MAIN_CHANGES}}
 
-\`\`\`markdown
+## 🧪 Cómo Probar
 
-<!-- PR_DESCRIPTION_START -->
+{{TEST_STEPS}}
 
-[contenido completo de PR description aquí]
+{{SCREENSHOTS_SECTION}}
 
-<!-- PR_DESCRIPTION_END -->
+## � Security Impact
 
-<!-- JIRA_DESCRIPTION_START -->
+{{SECURITY_IMPACT}}
 
-[contenido completo de Jira description aquí]
+## ⚡ Performance Impact
 
-<!-- JIRA_DESCRIPTION_END -->
+{{PERFORMANCE_IMPACT}}
 
-\`\`\`
+## 🔍 Observability
+
+{{OBSERVABILITY}}
+
+## �📊 Validación
+
+| Aspecto | Resultado |
+|---------|-----------||
+| 🧪 Tests | {{TESTS_PASSED}}/{{TESTS_TOTAL}} passing (+{{TESTS_NEW}} nuevos) |
+| 📈 Coverage | {{COVERAGE}}% |
+| 🔍 Lint | ✅ Sin errores |
+| 📝 Docs | {{DOCS_STATUS}} |
+
+## 📈 Métricas
+
+| Métrica             | Valor                                                                    |
+| ------------------- | ------------------------------------------------------------------------ |
+| 💾 Commits          | {{TOTAL_COMMITS}} ([ver commits]({{COMMIT_HASHES_SUMMARY}}))             |
+| 📁 Archivos         | {{FILES_COUNT}} modificados (+{{LINES_ADDED}}/-{{LINES_DELETED}} líneas) |
+| ⚠️ Breaking Changes | {{BREAKING_CHANGES_STATUS}}                                              |
+| ⏱️ Duración         | {{DURATION}} ({{STORY_POINTS}} SP)                                       |
+
+{{BREAKING_CHANGES_DETAILS}}
+
+{{DEPLOYMENT_NOTES}}
+
+## 📦 Dependencias
+
+{{DEPENDENCIES_SECTION}}
+
+## 🔗 Referencias
+
+- **Commits:** {{COMMIT_HASHES_SUMMARY}}
+- **Platform:** {{PLATFORM}}
+  {{ISSUE_LINKS}}
+
+## ✅ Reviewer Checklist
+
+- [ ] El código sigue los estándares del proyecto
+- [ ] La lógica es clara y está bien documentada
+- [ ] Los tests cubren casos críticos y edge cases
+- [ ] No hay riesgos de seguridad o performance
+- [ ] La documentación está actualizada
+- [ ] Los cambios no introducen breaking changes no documentados
+- [ ] El PR es del tamaño adecuado (no demasiado grande)
+
+---
+
+**Generated by AI Flow**
+\`\`\`\`\`
+
+---
+
+## 🎫 JIRA COMMENT (Task Update)
+
+\`\`\`\`\`markdown
+🚀 {{TASK_TYPE^}}: {{TASK_TITLE}}
+
+---
+
+## 📝 Resumen Ejecutivo
+
+{{BUSINESS_SUMMARY}}
+
+---
+
+## 🔧 Solución Técnica
+
+{{SOLUTION}}
+
+---
+
+## 🧪 Cómo Probar (QA)
+
+{{TEST_STEPS}}
+
+{{SCREENSHOTS_REMINDER}}
+
+---
+
+## 📊 Evidencia Técnica
+
+| Aspecto         | Detalle                                                                  |
+| --------------- | ------------------------------------------------------------------------ |
+| 🔗 Pull Request | {{PR_LINK}}                                                              |
+| 🌿 Branch       | `{{BRANCH_NAME}}`                                                        |
+| ✅ Tests        | {{TESTS_PASSED}}/{{TESTS_TOTAL}} passing (+{{TESTS_NEW}} nuevos)         |
+| 📈 Coverage     | {{COVERAGE}}%                                                            |
+| 💾 Commits      | {{TOTAL_COMMITS}} commits                                                |
+| 📁 Archivos     | {{FILES_COUNT}} modificados (+{{LINES_ADDED}}/-{{LINES_DELETED}} líneas) |
+
+---
+
+## 📋 Métricas de Desarrollo
+
+- **Story Points:** {{STORY_POINTS}} SP
+- **Tiempo real:** {{DURATION}}
+- **Estado:** {{DEPLOYMENT_STATUS}}
+
+{{DEPLOYMENT_NOTES_COMPACT}}
+
+{{QA_NOTES}}
+
+---
+
+## 🚀 Siguiente Paso (Crear PR)
+
+{{PR_CREATION_COMMANDS}}
+
+💡 _Después de crear el PR, reemplaza `[PEGAR_LINK_AQUI]` con el link real._
+
+---
+
+_Generado automáticamente por AI Flow • Platform: {{PLATFORM}}_
+\`\`\`\`\`
+
+---
+
+**Listo para copiar y pegar** 📋
+
+**Diferencias clave entre los dos formatos:**
+
+| Aspecto | PR Description | Jira Comment |
+|---------|----------------|--------------||
+| **Audiencia** | Desarrolladores/Reviewers | QA, PM, Stakeholders |
+| **Propósito** | Code review técnico | Status update + QA handoff |
+| **Longitud** | 40-60 líneas (completo) | 20-25 líneas (compacto) |
+| **Enfoque** | "Cómo se implementó" | "Qué se logró" |
+| **Uso** | Pegar en GitHub/GitLab PR | Agregar como comentario en Jira |
+
+**CRÍTICO PARA EVITAR CONFLICTOS:**
+
+1. Los encabezados "## 📋 PULL REQUEST DESCRIPTION" y "## 🎫 JIRA COMMENT" deben estar FUERA de los bloques de código
+2. USA EXACTAMENTE 5 BACKTICKS (\`\`\`\`\`) para abrir/cerrar cada bloque
+3. ¿Por qué 5? Cubre hasta 4 backticks internos (bloques anidados) sin conflictos
+4. Renderiza TODAS las variables con valores reales del contexto
+5. Secciones condicionales ({{BREAKING_CHANGES_DETAILS}}, {{DEPLOYMENT_NOTES}}, etc.) SOLO si aplican
+6. BUSINESS_SUMMARY en Jira debe ser NO-TÉCNICO (lenguaje de negocio)
+7. SCREENSHOTS_REMINDER siempre presente para frontend
 
 Analiza el contexto y genera las descripciones óptimas ahora.
 ```
 
-**After AI generates the descriptions, extract and save them:**
+**After AI generates the descriptions:**
 
 ```bash
-# Extract PR description
-sed -n '/<!-- PR_DESCRIPTION_START -->/,/<!-- PR_DESCRIPTION_END -->/p' /tmp/ai-output.md | \
-  sed '1d;$d' > /tmp/pr-description.md
-
-# Extract Jira description
-sed -n '/<!-- JIRA_DESCRIPTION_START -->/,/<!-- JIRA_DESCRIPTION_END -->/p' /tmp/ai-output.md | \
-  sed '1d;$d' > /tmp/jira-description.md
-
-# Display descriptions
+# La IA responde directamente en el chat con las descripciones
+# en formato markdown listo para copiar y pegar.
+# No requiere post-procesamiento ni archivos temporales.
 echo ""
-echo "---"
-echo "📋 DESCRIPCIÓN PARA PULL REQUEST (GitHub/GitLab/Bitbucket)"
-echo "---"
+echo "✅ Descripciones generadas correctamente"
 echo ""
-cat /tmp/pr-description.md
+echo "📋 Dos formatos disponibles arriba:"
+echo "   1️⃣  PR Description → Para GitHub/GitLab (completo, técnico)"
+echo "   2️⃣  Jira Comment → Para agregar en tarea de Jira (compacto, business-oriented)"
 echo ""
-echo ""
-echo "---"
-echo "🎫 DESCRIPCIÓN PARA JIRA/CLICKUP/LINEAR (Markdown)"
-echo "---"
-echo ""
-cat /tmp/jira-description.md
-echo ""
-echo ""
-echo "💡 Copia las descripciones de arriba para tus tickets"
+echo "📋 Copia directamente el contenido de los bloques markdown."
 echo ""
 ```
 
@@ -838,20 +1179,16 @@ if [[ "$CONFIRM_PUSH" =~ ^[Yy]$ ]]; then
     echo "---"
     echo ""
     echo "📊 Trabajo completado y subido correctamente"
-    echo "🌿 Branch: $CURRENT_BRANCH (pushed)"
-    echo ""
-    echo "💡 Siguiente paso: Crear Pull Request"
-    echo ""
-    echo "   GitHub CLI:"
-    echo "   gh pr create --title \"$TASK_TYPE: $TASK_FOLDER\" --body-file /tmp/pr-description.md"
+    echo "🌿 Branch: $CURRENT_BRANCH (pushed a origin)"
     echo ""
-    echo "   GitLab CLI:"
-    echo "   glab mr create --title \"$TASK_TYPE: $TASK_FOLDER\" --description \"\$(cat /tmp/pr-description.md)\""
+    echo "📋 Siguiente paso opcional: Crear Pull Request para revisión"
     echo ""
-    echo "   Bitbucket CLI:"
-    echo "   bb pr create --title \"$TASK_TYPE: $TASK_FOLDER\" --description \"\$(cat /tmp/pr-description.md)\""
+    echo "   GitHub CLI:     gh pr create --title \"$TASK_TYPE: $TASK_FOLDER\""
+    echo "   GitLab CLI:     glab mr create --title \"$TASK_TYPE: $TASK_FOLDER\""
+    echo "   Bitbucket CLI:  bb pr create --title \"$TASK_TYPE: $TASK_FOLDER\""
+    echo "   Web UI:         Abre repositorio → 'New Pull Request'"
     echo ""
-    echo "   O abre tu repositorio web y crea el PR manualmente"
+    echo "💡 Si creaste el PR, copia el link y actualiza el comentario de Jira"
     echo ""
   else
     echo ""

package/prompts/frontend/flow-work-api.md

@@ -43,12 +43,14 @@ Parse OpenAPI backend specification and return structured analysis data that `fl
 2. Execute CRUD implementation with project-specific patterns
 3. Ensure type-safety between frontend and backend
 
-**⚠️ CRITICAL: Do NOT create separate analysis files**
+**⚠️ CRITICAL: Do NOT create ANY files in this sub-prompt**
 
 - This sub-prompt ONLY returns a JSON object (`OpenAPIAnalysisResult`)
-- NO files like `.ai-flow/analysis/*.md` or `.ai-flow/work/[task]/analysis.md` should be created
-- The parent prompt (`flow-work`) handles all file creation (only `work.md` and `status.json`)
-- All analysis data is stored in memory and used to populate `work.md`
+- ❌ NO files like `.ai-flow/analysis/*.md` should be created
+- ❌ NO files like `.ai-flow/work/[task]/analysis.md` should be created
+- ❌ NO files like `.ai-flow/work/[task]/work.md` should be created here
+- ✅ The parent prompt (`flow-work`) will create `.ai-flow/work/[task]/work.md` and `status.json` in Phase 2
+- All analysis data is returned as JSON and will be embedded into `work.md` by the parent prompt
 
 ---
 

package/prompts/frontend/flow-work.md

@@ -492,10 +492,14 @@ await saveToCache(cacheFile, {
   projectType: 'frontend',
 });
 
-// ⚠️ IMPORTANT: Do NOT create separate analysis files
+// ⚠️ IMPORTANT: Do NOT create SEPARATE ANALYSIS FILES
 // The analysis result is stored in memory (workflow_context.analysis)
-// and will be used to generate the comprehensive work.md file.
-// NO files like .ai-flow/analysis/*.md or .ai-flow/work/[task]/analysis.md
+// and will be merged into work.md during Phase 2.
+//
+// ❌ DO NOT CREATE: .ai-flow/analysis/*.md or .ai-flow/work/[task]/analysis.md
+// ✅ MUST CREATE (in Phase 2): .ai-flow/work/[task]/work.md and status.json
+//
+// The analysis data is included INSIDE work.md, not as a separate file.
 ```
 
 **IF `analysisResult.success === false`:**
@@ -890,7 +894,15 @@ Find similar features/patterns in codebase:
 - The `work.md` file should be comprehensive and self-contained
 - For COMPLEX tasks with API analysis, include all OpenAPI metadata directly in `work.md`
 
-**IF complexity == "MEDIUM":**
+**📦 For API_MODULE mode specifically:**
+
+- The analysis from `flow-work-api.md` sub-prompt is stored in `workflow_context.analysis`
+- ✅ YOU MUST CREATE `.ai-flow/work/api-[module-name]/work.md` with all analysis data embedded
+- ✅ YOU MUST CREATE `.ai-flow/work/api-[module-name]/status.json` (API modules are COMPLEX)
+- Include OpenAPI endpoints, schemas, field specs, validation rules, and relationships in `work.md`
+- Do NOT skip file creation just because you received pre-analyzed data
+
+**IF complexity == "MEDIUM":\*\***
 
 - Create simplified `.ai-flow/work/[task-name]/work.md` (~15-20 lines)
 - Skip status.json