ai-flow-dev 2.8.2 → 2.9.1

package/prompts/backend/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
@@ -708,59 +773,168 @@ 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:
+```markdown
+Generate two professional descriptions (PR in **ENGLISH**, Jira in **SPANISH**) using the OFFICIAL TEMPLATE in `.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
-
-**Reglas Importantes:**
-
-- Usa lenguaje profesional pero claro
-- Sé específico con cambios técnicos
-- 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
+## 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 "✅ Updated" || echo "⚠️ Review needed")
+
+## 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 "⚠️ YES (see below)" || 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: migraciones DB + 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 (para cambios visuales - formato simple con espacio para adjuntar)
+
+SCREENSHOTS*REMINDER=$([ "$HAS_UI_CHANGES" = "true" ] && echo "\n## 📸 Screenshots\n\n### Before\n[Adjuntar imagen]\n\n### After\n[Adjuntar imagen]\n\n_Incluir: diferentes estados (hover, active, disabled), viewports si aplica*" || echo "")
+
+## 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>
+**Read the template in `.ai-flow/templates/pr-description.template.md`** and generate TWO descriptions following EXACTLY that structure:
+
+1. **PR Description (GitHub/GitLab/Bitbucket) - TECHNICAL, COMPLETE, IN ENGLISH:**
+   - Use ALL sections from the template
+   - Render variables with real values
+   - Audience: Developers and Reviewers
+   - Focus: "How it was implemented" (technical details)
+   - **LANGUAGE: English (all text, headers, descriptions)**
+   - Include conditional sections ONLY if applicable:
+     - Breaking Changes Details (if HAS_BREAKING_CHANGES=true)
+     - Deployment Notes (if SHOW_DEPLOYMENT_NOTES=true)
+     - Screenshots (if HAS_UI_CHANGES=true)
+   - Generate context-specific TEST_STEPS (not generic)
+
+2. **Jira Comment (Task Update) - BUSINESS-ORIENTED, COMPACT, IN SPANISH:**
+   - Audience: QA, PM, Stakeholders + Devs
+   - Focus: "What was achieved and how to test it" (business outcome)
+   - Maximum 20-25 lines (scannable in 30 seconds)
+   - **LANGUAGE: Spanish (all text, headers, descriptions)**
+   - BUSINESS_SUMMARY is MOST IMPORTANT: must explain value without technical jargon
+   - TEST_STEPS must be actionable for QA (no code knowledge required)
+   - DEPLOYMENT_NOTES_COMPACT only if critical (1 line max)
+   - QA_NOTES only if there's something non-obvious QA should know
+
+**Important Rules:**
+
+- Use professional but clear language (senior engineer level)
+- Be specific with technical changes (use real file/module names)
+- Use commit links already formatted in $COMMIT_HASHES_SUMMARY
+- Generate context-specific TEST_STEPS (not generic steps)
+- If MIGRATION_GUIDE is empty and there are breaking changes, recommend user to complete it
+- Escape special characters correctly for valid Markdown
+- Use `---` separators (not `━━━━` or Unicode characters)
+- If NEW_DEPENDENCIES is empty but HAS_NEW_DEPS=true, detect from diff
+- **PR Description: 100% English**
+- **Jira Comment: 100% Spanish**
+- **NO SIGNATURES**: Do not include "Generated by AI Flow" or similar footers
 
 **Output Format:**
 
@@ -771,31 +945,189 @@ IMPORTANTE: Responde directamente con este formato EXACTO usando 5 BACKTICKS (m
 ## 📋 PULL REQUEST DESCRIPTION
 
 \`\`\`\`\`markdown
-[Aquí va el contenido completo de la PR description, empezando con ## Refactor: ...]
+
+## {{TASK_TYPE}}: {{TASK_TITLE}}
+
+> **Branch:** `{{BRANCH_NAME}}` • **Story Points:** {{STORY_POINTS}} SP • **Duration:** {{DURATION}}
+
+---
+
+## 🎯 Change Type
+
+- [{{IS_FEATURE}}] ✨ Feature (new functionality)
+- [{{IS_FIX}}] 🐛 Fix (bug fix)
+- [{{IS_REFACTOR}}] ♻️ Refactor (no functional change)
+- [{{IS_DOCS}}] 📝 Docs (documentation only)
+- [{{IS_PERF}}] ⚡ Performance (improvement)
+- [{{IS_TEST}}] 🧪 Test (add/improve tests)
+
+## 🎯 Impact Area
+
+**{{IMPACT_AREA}}**
+
+## 💡 Context
+
+{{CONTEXT}}
+
+{{RELATED_ISSUES}}
+
+## ✅ Implemented Solution
+
+{{SOLUTION}}
+
+## 🔧 Main Changes
+
+{{MAIN_CHANGES}}
+
+## 🧪 How to Test
+
+{{TEST_STEPS}}
+
+{{SCREENSHOTS_SECTION}}
+
+## 🔒 Security Impact
+
+{{SECURITY_IMPACT}}
+
+## ⚡ Performance Impact
+
+{{PERFORMANCE_IMPACT}}
+
+## 🔍 Observability
+
+{{OBSERVABILITY}}
+
+## 📊 Validation
+
+| Aspect      | Result                                                        |
+| ----------- | ------------------------------------------------------------- |
+| 🧪 Tests    | {{TESTS_PASSED}}/{{TESTS_TOTAL}} passing (+{{TESTS_NEW}} new) |
+| 📈 Coverage | {{COVERAGE}}%                                                 |
+| 🔍 Lint     | ✅ No errors                                                  |
+| 📝 Docs     | {{DOCS_STATUS}}                                               |
+
+## 📈 Metrics
+
+| Metric              | Value                                                                |
+| ------------------- | -------------------------------------------------------------------- |
+| 💾 Commits          | {{TOTAL_COMMITS}} ([view commits]({{COMMIT_HASHES_SUMMARY}}))        |
+| 📁 Files            | {{FILES_COUNT}} modified (+{{LINES_ADDED}}/-{{LINES_DELETED}} lines) |
+| ⚠️ Breaking Changes | {{BREAKING_CHANGES_STATUS}}                                          |
+| ⏱️ Duration         | {{DURATION}} ({{STORY_POINTS}} SP)                                   |
+
+{{BREAKING_CHANGES_DETAILS}}
+
+{{DEPLOYMENT_NOTES}}
+
+## 📦 Dependencies
+
+{{DEPENDENCIES_SECTION}}
+
+## 🔗 References
+
+- **Commits:** {{COMMIT_HASHES_SUMMARY}}
+- **Platform:** {{PLATFORM}}
+  {{ISSUE_LINKS}}
+
+## ✅ Reviewer Checklist
+
+- [ ] Code follows project standards
+- [ ] Logic is clear and well documented
+- [ ] Tests cover critical and edge cases
+- [ ] No security or performance risks
+- [ ] Documentation is up to date
+- [ ] No undocumented breaking changes
+- [ ] PR size is appropriate (not too large)
+
 \`\`\`\`\`
 
 ---
 
-## 🎫 JIRA DESCRIPTION
+## 🎫 JIRA COMMENT (Task Update)
 
 \`\`\`\`\`markdown
-[Aquí va el contenido completo de la Jira description, empezando con ## Refactor: ...]
+🚀 {{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._
+
 \`\`\`\`\`
 
 ---
 
-**Listo para copiar y pegar** 📋 Solo copia el contenido dentro de los bloques de código markdown.
+**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 DESCRIPTION" deben estar FUERA de los bloques de código
+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. Código normal usa 3 (```), nested usa 4 (````), entonces 5 (``````) es prácticamente imposible de conflictuar
-5. Más de 5 es innecesario (over-engineering)
+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)
 
 Analiza el contexto y genera las descripciones óptimas ahora.
-```````
+```
 
 **After AI generates the descriptions:**
 
@@ -804,7 +1136,12 @@ Analiza el contexto y genera las descripciones óptimas ahora.
 # en formato markdown listo para copiar y pegar.
 # No requiere post-procesamiento ni archivos temporales.
 echo ""
-echo "💡 Las descripciones han sido generadas arriba en el chat."
+echo "✅ Descripciones generadas correctamente"
+echo ""
+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 "📋 Copia directamente el contenido de los bloques markdown."
 echo ""
 ```
@@ -839,20 +1176,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/desktop/flow-build-phase-8.md

@@ -62,7 +62,23 @@ Check that all required documents exist:
 
 ### 8.1.2 Generate .gitignore
 
+**Action: Intelligent Merge Strategy**
+
+**Step 1: Detect existing .gitignore**
+
+```bash
+if [ -f ".gitignore" ]; then
+  echo "📋 Existing .gitignore detected"
+  GITIGNORE_EXISTS=true
+else
+  echo "📄 Creating new .gitignore"
+  GITIGNORE_EXISTS=false
+fi
 ```
+
+**Step 2: Select base patterns for Java Desktop**
+
+```gitignore
 # Generated .gitignore for Desktop Java Project
 
 # Build outputs
@@ -117,10 +133,63 @@ Thumbs.db
 *.sqlite
 *.h2.db
 
-# Keep .ai-flow but ignore work
-.ai-flow/work/
-.ai-flow/archive/
+# ============================================================
+# AI Flow - Workspace Management
+# ============================================================
+# Ignore temporary cache (regenerable)
 .ai-flow/cache/
+
+# Ignore work-in-progress state (personal, deleted on completion)
+.ai-flow/work/
+
+# COMMIT .ai-flow/archive/ by default (contains team metrics)
+# ============================================================
+```
+
+**Step 3: Merge or Create**
+
+**If .gitignore exists (Existing Project):**
+
+```bash
+# Check if AI Flow rules already present
+if grep -q ".ai-flow/cache/" .gitignore; then
+  echo "✅ AI Flow rules already configured"
+else
+  echo "" >> .gitignore
+  echo "# ============================================================" >> .gitignore
+  echo "# AI Flow - Workspace Management" >> .gitignore
+  echo "# ============================================================" >> .gitignore
+  echo "# Ignore temporary cache (regenerable)" >> .gitignore
+  echo ".ai-flow/cache/" >> .gitignore
+  echo "" >> .gitignore
+  echo "# Ignore work-in-progress state (personal, deleted on completion)" >> .gitignore
+  echo ".ai-flow/work/" >> .gitignore
+  echo "" >> .gitignore
+  echo "# COMMIT .ai-flow/archive/ by default (contains team metrics)" >> .gitignore
+  echo "# ============================================================" >> .gitignore
+
+  echo "✅ Added AI Flow rules to existing .gitignore"
+fi
+```
+
+**If .gitignore does NOT exist (New Project):**
+
+```bash
+# Create complete .gitignore with all patterns
+cat > .gitignore << 'EOF'
+[Insert complete template above]
+EOF
+
+echo "✅ Created new .gitignore"
+```
+
+**Output Summary:**
+
+```
+✅ .gitignore configured successfully!
+   Base patterns: Java Desktop + [NetBeans/Eclipse] + [Maven/Gradle/Ant]
+   AI Flow rules: ✅ Added (.ai-flow/cache/, .ai-flow/work/)
+   Status: [Created new | Updated existing]
 ```
 
 ### 8.1.3 Generate README.md