siesa-agents 2.1.42 → 2.1.44

package/bmad/bmm/workflows/5-documentation/create-user-guide/steps/step-03-analisis-fuentes.md

@@ -0,0 +1,308 @@
+---
+name: 'step-03-analisis-fuentes'
+description: 'Analyze source artifacts (PRDs, epics, architecture) to extract context for user guide'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/5-documentation/create-user-guide'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-03-analisis-fuentes.md'
+nextStepFile: '{workflow_path}/steps/step-04-elicitacion.md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFileSpanish: '{output_folder}/documentation-artifacts/user-guide/es/{audience}-guide.md'
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+
+# Config
+bmmConfig: '{project-root}/_bmad/bmm/config.yaml'
+---
+
+# Step 3: Análisis de Fuentes
+
+## STEP GOAL:
+
+Leer y analizar todos los artefactos de documentación del proyecto (PRDs, épicas seleccionadas, arquitectura, workflows) para extraer información clave que se utilizará en la generación de la guía de usuario. Este es un step autónomo donde el agente trabaja sin requerir input constante del usuario.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a technical writer and documentation analyst
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring analytical and synthesis skills, user brings project artifacts
+- ✅ Maintain collaborative professional tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on reading and analyzing artifacts (INTENT-BASED execution)
+- 🚫 FORBIDDEN to generate user guide content yet (that happens in step-05)
+- 💬 Work autonomously but provide progress updates
+- 📊 Extract key information: features, user roles, workflows, concepts
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Read all selected artifacts completely
+- 💾 Append "## Contexto del Proyecto" section to outputFile
+- 📖 Set `stepsCompleted: [1, 2, 3]` before loading next step
+- 🚫 FORBIDDEN to skip artifact reading
+
+## CONTEXT BOUNDARIES:
+
+- Epics selected in step-02 (from frontmatter.epics_selected)
+- Target audience from frontmatter.target_audience
+- This is autonomous work - minimal user interaction
+- Information extracted here feeds into step-04 and step-05
+
+## EXECUTION APPROACH (INTENT-BASED):
+
+This step uses INTENT-BASED execution. You have flexibility in HOW you analyze, but must accomplish the GOAL of extracting comprehensive project context.
+
+### Core Analysis Goals:
+
+1. **Understand the Product:**
+   - What is the system/application about?
+   - What problem does it solve?
+   - Who are the users?
+
+2. **Identify Key Features:**
+   - What are the main functionalities?
+   - Which features are documented in the selected epics?
+   - What acceptance criteria exist?
+
+3. **Map User Workflows:**
+   - What are the common user journeys?
+   - What processes do users follow?
+   - What are the critical paths?
+
+4. **Extract Technical Context:**
+   - What is the architecture?
+   - What are the key components?
+   - What technologies are used?
+
+5. **Understand User Roles:**
+   - What types of users exist?
+   - What permissions/capabilities do they have?
+   - How do roles differ?
+
+## EXECUTION SEQUENCE:
+
+### 1. Announce Analysis Start
+
+"🔍 **Iniciando Análisis de Documentación**
+
+Voy a leer y analizar todos los artefactos del proyecto para extraer la información necesaria para tu guía de usuario.
+
+**Artefactos a analizar:**
+- PRD documents (goals, requirements, UI design)
+- {count} épicas seleccionadas
+- Architecture documentation
+- Workflow documentation (si existe)
+
+Esto puede tomar un momento. Te mantendré informado del progreso..."
+
+### 2. Discover and Read PRD Documents
+
+**Scan locations (in priority order):**
+
+- `{planning_artifacts}/goals-and-background-context.md`
+- `{planning_artifacts}/requirements.md`
+- `{planning_artifacts}/user-interface-design-goals.md`
+
+**For each PRD found:**
+- Read complete file
+- Extract: system purpose, goals, target users, key requirements
+- Add to frontmatter.source_artifacts.prd_docs
+
+**Progress update:**
+"✓ PRD analysis completado - {count} documentos leídos"
+
+### 3. Read Selected Epics from Consolidated File
+
+**Load consolidated epics file:**
+- Read complete epics.md file from frontmatter.source_artifacts.epics_file
+- Parse file to locate each epic section (identified by H3 headers: `### Epic X:`)
+- For each epic number in frontmatter.epics_selected:
+  - Extract the complete epic section (from its H3 header to the next epic's H3 header or end of file)
+  - Parse within that section:
+    - Epic title and description
+    - User stories with acceptance criteria
+    - Features described
+    - User workflows/journeys
+    - Technical requirements
+- Compile comprehensive list of features and their sources
+
+**Progress update:**
+"✓ Epic analysis completado - {count} épicas procesadas desde archivo consolidado, {features_count} features identificadas"
+
+### 4. Read Architecture Documentation
+
+**Scan locations:**
+
+- `{planning_artifacts}/core-workflows.md`
+- `{planning_artifacts}/components.md`
+- `{planning_artifacts}/architecture-*.md`
+
+**For each architecture doc found:**
+- Read complete file
+- Extract: system workflows, component structure, technical stack
+- Add to frontmatter.source_artifacts.architecture_docs
+
+**Progress update:**
+"✓ Architecture analysis completado"
+
+### 5. Read Workflow Documentation (Optional)
+
+**If core-workflows.md exists:**
+- Read complete file
+- Extract: detailed user workflows, step-by-step processes
+- Add to frontmatter.source_artifacts.workflow_docs
+
+### 6. Synthesize Project Context
+
+Create a synthesis of analyzed information:
+
+**Key Information Extracted:**
+- System name and purpose
+- Target users and roles
+- Core features (with epic/story references)
+- Main user workflows
+- Technical architecture overview
+- UI components (if documented)
+
+### 7. Append Context Section to Output
+
+Append to `{outputFileSpanish}` after the frontmatter:
+
+```markdown
+## Contexto del Proyecto
+
+### Propósito del Sistema
+
+[Brief description from PRD goals]
+
+### Usuarios Objetivo
+
+[User types and roles from PRD and epics]
+
+### Funcionalidades Principales Identificadas
+
+Las siguientes funcionalidades han sido identificadas desde la documentación del proyecto:
+
+{for each feature}
+- **{Feature Name}** [Source: Epic {number} Story {number}]
+  Brief description if available
+{end for}
+
+**Total:** {features_count} funcionalidades identificadas para documentar
+
+### Workflows Identificados
+
+{for each workflow}
+- **{Workflow Name}** [Source: {source}]
+  Brief description
+{end for}
+
+**Nota:** Los detalles completos de cada funcionalidad y workflow se documentarán en las secciones siguientes de esta guía.
+
+---
+```
+
+### 8. Update Frontmatter
+
+Update frontmatter with discovered information:
+
+```yaml
+source_artifacts:
+  prd_docs: [list of PRD files read]
+  epics_file: "path/to/epics.md"  # Single consolidated epics file
+  architecture_docs: [list of architecture files read]
+  workflow_docs: [list of workflow files read]
+
+# Preliminary counts (will be updated in step-05)
+features_documented: 0  # Will be populated during generation
+workflows_documented: 0  # Will be populated during generation
+```
+
+### 9. Analysis Complete Message
+
+"✅ **Análisis de Documentación Completado**
+
+**Resumen del Análisis:**
+- PRD documents: {prd_count} leídos
+- Épicas analizadas: {epic_count}
+- Funcionalidades identificadas: {features_count}
+- Workflows identificados: {workflow_count}
+- Architecture docs: {arch_count} leídos
+
+He agregado una sección de "Contexto del Proyecto" al documento de la guía con un resumen de toda la información encontrada.
+
+**Siguiente paso:** Elicitación de información adicional con el usuario para refinar el alcance y estilo de la guía.
+
+¿Listo para continuar?"
+
+### 10. Update State Before Next Step
+
+Before loading next step:
+- Ensure frontmatter.stepsCompleted = [1, 2, 3]
+- Ensure frontmatter.currentStep = "step-04-elicitacion"
+- Save outputFileSpanish with new context section
+
+### 11. Present MENU OPTIONS
+
+Display: **Select an Option:** [R] Re-scan [C] Continue
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+#### Menu Handling Logic:
+
+- IF R: Re-scan and re-analyze all artifacts, return to step 2
+- IF C: Update frontmatter, then load, read entire file, then execute `{nextStepFile}`
+- IF Any other: Respond and redisplay menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and analysis is complete with context section appended, will you then load, read entire file, then execute `{nextStepFile}` to begin information elicitation.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All artifact locations scanned
+- All selected epics read completely
+- PRD documents read and analyzed
+- Architecture docs read
+- Features identified with source citations
+- Workflows identified
+- Context section appended to outputFile
+- Frontmatter updated with source_artifacts
+- frontmatter.stepsCompleted = [1, 2, 3]
+- User informed of analysis results
+- Ready to proceed to step 4
+
+### ❌ SYSTEM FAILURE:
+
+- Skipping artifact reading
+- Not reading complete files
+- Missing source locations
+- Not extracting features comprehensively
+- Not appending context section
+- Not updating frontmatter
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/bmad/bmm/workflows/5-documentation/create-user-guide/steps/step-04-elicitacion.md

@@ -0,0 +1,332 @@
+---
+name: 'step-04-elicitacion'
+description: 'Elicit additional information from user to refine user guide scope and style'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/5-documentation/create-user-guide'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-04-elicitacion.md'
+nextStepFile: '{workflow_path}/steps/step-05-generacion-espanol.md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFileSpanish: '{output_folder}/documentation-artifacts/user-guide/es/{audience}-guide.md'
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+
+# Config
+bmmConfig: '{project-root}/_bmad/bmm/config.yaml'
+---
+
+# Step 4: Elicitación de Información
+
+## STEP GOAL:
+
+Realizar elicitación conversacional con el usuario para refinar el alcance de la guía, determinar nivel técnico de la audiencia, identificar escenarios críticos a documentar y decidir sobre secciones opcionales (ej: troubleshooting). Registrar todas las preferencias en frontmatter para uso en steps de generación.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a technical writer and requirements elicitation specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring elicitation expertise and documentation best practices
+- ✅ Maintain collaborative conversational tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on elicitation and preference gathering (INTENT-BASED)
+- 🚫 FORBIDDEN to generate guide content yet
+- 💬 Engage conversationally, adapt questions to context
+- 📊 Capture user preferences for generation steps
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Use conversational elicitation, not interrogation
+- 💾 Update frontmatter with all user preferences
+- 📖 Set `stepsCompleted: [1, 2, 3, 4]` before loading next step
+- 🚫 FORBIDDEN to skip elicitation topics
+
+## CONTEXT BOUNDARIES:
+
+- Features identified in step-03 (from context section)
+- Target audience from frontmatter
+- This is collaborative - requires active user participation
+- Preferences captured here directly influence content generation
+
+## EXECUTION APPROACH (INTENT-BASED):
+
+This step uses INTENT-BASED execution. Adapt your elicitation style to the user's responses. Be conversational, not mechanical. The goal is to understand the user's vision for the guide.
+
+### Core Elicitation Goals:
+
+1. **Feature Scope Refinement:**
+   - Which features should be prioritized?
+   - Any features to exclude or de-emphasize?
+   - Any features missing that should be added?
+
+2. **Critical Use Cases:**
+   - What are the most important user scenarios?
+   - Which workflows are most frequently used?
+   - What pain points should be addressed?
+
+3. **Technical Level:**
+   - How technically savvy is the target audience?
+   - What can we assume they know?
+   - What needs detailed explanation?
+
+4. **Known Issues & Limitations:**
+   - Are there limitations users should know about?
+   - Common pitfalls or warnings?
+   - Workarounds for known issues?
+
+5. **Optional Sections:**
+   - Should we include troubleshooting section?
+   - Need for advanced configuration section?
+   - API integration examples (if applicable)?
+
+## EXECUTION SEQUENCE:
+
+### 1. Present Features Summary
+
+"📋 **Funcionalidades Identificadas para Documentar**
+
+Basándome en el análisis de las {epic_count} épicas seleccionadas, he identificado las siguientes funcionalidades:
+
+{List top 10-15 features with sources, grouped by category if possible}
+
+Antes de comenzar a generar la guía, necesito tu input en algunas áreas clave para asegurar que la documentación sea exactamente lo que necesitas..."
+
+### 2. Elicit Feature Scope Refinement
+
+**Conversational Approach:**
+
+"**Refinamiento del Alcance:**
+
+De todas estas funcionalidades identificadas:
+
+1. ¿Hay alguna que NO debería documentarse en esta guía de usuario? (Por ejemplo, features deprecadas, experimentales, o no relevantes para {audience_name})
+
+2. ¿Hay alguna funcionalidad que debería tener prioridad o documentarse con mayor detalle?
+
+3. ¿Falta alguna funcionalidad importante que no aparece en la lista pero que debería incluirse?
+
+No hay respuestas incorrectas - estoy aquí para adaptar la guía a tus necesidades específicas."
+
+**Wait for user response and discuss.**
+
+**Capture:**
+- features_to_exclude: [list]
+- features_to_prioritize: [list]
+- features_to_add_manually: [list with descriptions]
+
+### 3. Elicit Critical Scenarios
+
+**Conversational Approach:**
+
+"**Escenarios de Uso Críticos:**
+
+Para hacer la guía más útil, quiero enfocarme en los escenarios reales que tus usuarios enfrentan.
+
+1. ¿Cuáles son los 3-5 casos de uso más comunes o importantes para documentar en detalle?
+
+2. ¿Hay workflows específicos que causan confusión actualmente y necesitan documentación clara?
+
+3. ¿Hay integraciones con otros sistemas o procesos externos que deberíamos explicar?
+
+Puedes ser tan específico o general como desees."
+
+**Wait for user response and discuss.**
+
+**Capture:**
+- additional_scenarios: [list of scenarios described by user]
+
+### 4. Determine Technical Level
+
+**Conversational Approach:**
+
+"**Nivel Técnico de la Audiencia:**
+
+Para ajustar el tono y profundidad de la guía, necesito entender mejor a tus usuarios finales.
+
+La audiencia objetivo es: **{audience_name}**
+
+¿Cómo describirías su nivel técnico?
+
+- **Novato:** Usuarios sin experiencia técnica, necesitan explicaciones paso a paso muy detalladas
+- **Intermedio:** Usuarios cómodos con tecnología, pueden seguir instrucciones técnicas con contexto adecuado
+- **Avanzado:** Usuarios técnicamente expertos, prefieren información concisa y directa
+- **Mixto:** Audiencia variada, necesitamos balancear explicaciones básicas con información avanzada
+
+¿Qué nivel(es) aplica mejor?"
+
+**Wait for user response.**
+
+**Capture:**
+- technical_level: "novice" | "intermediate" | "advanced" | "mixed"
+
+### 5. Elicit Warnings and Limitations
+
+**Conversational Approach:**
+
+"**Limitaciones y Advertencias:**
+
+1. ¿Hay limitaciones conocidas del sistema que los usuarios deberían conocer desde el principio?
+
+2. ¿Hay configuraciones o acciones que podrían causar problemas si se hacen incorrectamente?
+
+3. ¿Hay dependencias externas o requisitos especiales que impacten el uso?
+
+Esta información nos ayudará a incluir advertencias y notas importantes en los lugares correctos."
+
+**Wait for user response and discuss.**
+
+**Capture:**
+- known_limitations: [list]
+- critical_warnings: [list]
+
+### 6. Decide on Troubleshooting Section
+
+**Direct Question:**
+
+"**Sección de Troubleshooting:**
+
+¿Deseas incluir una sección de "Solución de Problemas" (Troubleshooting) al final de la guía?
+
+Esta sección incluiría:
+- Problemas comunes y sus soluciones
+- Mensajes de error típicos y cómo resolverlos
+- Preguntas frecuentes relacionadas con issues
+
+**[S]** Sí, incluir troubleshooting
+**[N]** No, solo FAQ es suficiente
+
+¿Qué prefieres?"
+
+**Wait for user response.**
+
+**Capture:**
+- include_troubleshooting: true | false
+
+### 7. Synthesis and Confirmation
+
+"✅ **Resumen de Preferencias Capturadas:**
+
+Voy a generar la guía de usuario con las siguientes configuraciones:
+
+**Alcance:**
+- Funcionalidades a documentar: {count} (excluyendo {excluded_count})
+- Funcionalidades priorizadas: {prioritized_list if any}
+- Escenarios adicionales: {scenario_count}
+
+**Estilo:**
+- Nivel técnico: **{technical_level_name}**
+- Troubleshooting: **{yes/no}**
+
+**Consideraciones especiales:**
+- Limitaciones conocidas: {limitations_count}
+- Advertencias críticas: {warnings_count}
+
+¿Todo correcto o necesitas ajustar algo?"
+
+**Wait for confirmation. If adjustments needed, revisit relevant sections.**
+
+### 8. Update Frontmatter
+
+Update `{outputFileSpanish}` frontmatter with all captured preferences:
+
+```yaml
+# User preferences (populated in step-04)
+technical_level: "intermediate"  # Example
+include_troubleshooting: true
+additional_scenarios:
+  - "Scenario 1 description"
+  - "Scenario 2 description"
+features_to_exclude:
+  - "Feature X"
+features_to_prioritize:
+  - "Feature Y"
+  - "Feature Z"
+known_limitations:
+  - "Limitation 1"
+critical_warnings:
+  - "Warning 1"
+```
+
+### 9. Transition Message
+
+"✅ **Elicitación Completada**
+
+Tengo toda la información que necesito para generar una guía de usuario comprehensiva y adaptada a tus necesidades.
+
+**Próximo paso:** Generación del contenido en español.
+
+El agente trabajará de manera autónoma para crear todas las secciones de la guía, incluyendo:
+- Diagramas Mermaid para cada feature y workflow
+- Screenshot placeholders con índice
+- Source citations para trazabilidad
+- Estructura navegable
+
+Esto puede tomar algunos minutos. ¿Listo para continuar?"
+
+### 10. Update State Before Next Step
+
+Before loading next step:
+- Ensure frontmatter.stepsCompleted = [1, 2, 3, 4]
+- Ensure frontmatter.currentStep = "step-05-generacion-espanol"
+- Save outputFileSpanish
+
+### 11. Present MENU OPTIONS
+
+Display: **Select an Option:** [C] Continue
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+
+#### Menu Handling Logic:
+
+- IF C: Update frontmatter, then load, read entire file, then execute `{nextStepFile}`
+- IF Any other: Respond and redisplay menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and all preferences are captured in frontmatter, will you then load, read entire file, then execute `{nextStepFile}` to begin Spanish content generation.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Features summary presented to user
+- Feature scope refined conversationally
+- Critical scenarios identified
+- Technical level determined
+- Warnings and limitations captured
+- Troubleshooting decision made
+- All preferences stored in frontmatter
+- frontmatter.stepsCompleted = [1, 2, 3, 4]
+- User confirmed preferences
+- Ready to proceed to step 5
+
+### ❌ SYSTEM FAILURE:
+
+- Using interrogation instead of conversation
+- Skipping elicitation topics
+- Not adapting to user responses
+- Not capturing preferences in frontmatter
+- Proceeding without user confirmation
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.