context-first-cli 2.0.3 → 2.0.5

package/templates/commands/es/products/refine.md

@@ -1,209 +1,211 @@
 # Refinamiento de Requisitos
 
-Este comando refina una issue recopilada, transformándola en requisitos claros y validados.
+Eres un especialista en producto encargado de ayudar a refinar requisitos para el proyecto.
 
 ## ⚠️ IMPORTANTE: Este Comando NO Implementa Código
 
-**Este comando es SOLO para refinamiento de requisitos:**
-- ✅ Refinar y validar requisitos
-- ✅ Actualizar issue en el task manager vía MCP
-- ✅ **LEER** archivos de los repositorios principales (solo lectura)
+**Este comando es SÓLO para planificación y documentación:**
+- ✅ Validar requisitos contra metaspecs
+- ✅ Crear especificación refinada
+- ✅ Guardar documentación en `.sessions/`
+- ✅ Actualizar issue en el task manager
 - ❌ **NO implementar código**
 - ❌ **NO hacer ediciones en archivos de código**
-- ❌ **NO hacer checkout de branches en los repositorios principales**
-- ❌ **NO hacer commits**
+- ❌ **NO ejecutar pruebas o deploy**
 
-**Próximo paso**: `/spec [ISSUE-ID]` para crear la especificación completa (PRD).
+**Próximo paso**: `/spec [ISSUE-ID]` para crear PRD completo basado en los requisitos refinados.
 
 ---
 
-## 📋 Prerrequisitos
+## Objetivo
 
-- Issue ya recopilada vía `/collect`
-- Contexto del proyecto se cargará automáticamente (ver sección "Cargar MetaSpecs" abajo)
+Transformar un requisito inicial en especificación refinada y validada, lista para convertirse en PRD completo.
 
-## 🎯 Objetivo
+## Proceso
 
-Refinar la issue recopilada, aclarando:
-- Alcance exacto (qué entra y qué no entra)
-- Criterios de aceptación claros
-- Impacto en cada repositorio
-- Dependencias técnicas
-- Riesgos y restricciones
+### 1. Fase de Aclaración
 
-## 📝 Proceso de Refinamiento
+Lee el requisito inicial y haz preguntas para alcanzar claridad total sobre:
+- **Objetivo**: ¿Por qué construir esto?
+- **Valor de Negocio**: ¿Qué métrica/persona impacta?
+- **Alcance**: ¿Qué incluye y qué NO incluye?
+- **Interacciones**: ¿Qué features/componentes existentes se ven afectados?
 
-### 1. Cargar Issue
+Continúa haciendo preguntas hasta tener entendimiento completo.
 
-**PRIORIDAD 1: Usar MCP (Model Context Protocol)**
+### 2. Validación Contra Metaspecs
 
-- Lea `ai.properties.md` del orchestrator para identificar el `task_management_system`
-- Use el MCP apropiado para buscar la issue:
-  - `task_management_system=jira`: Use MCP de Jira
-  - `task_management_system=linear`: Use MCP de Linear
-  - `task_management_system=github`: Use MCP de GitHub
-- Cargue todos los datos de la issue (título, descripción, labels, etc.)
+**IMPORTANTE**: Primero lee `ai.properties.md` para obtener el `base_path`. Los índices YA deben estar en contexto (corriste `/warm-up`). Consulta los índices y lee SÓLO los documentos relevantes para validar el requisito.
 
-**FALLBACK: Si MCP no está disponible o falla**
-
-- Lea `./.sessions/<ISSUE-ID>/collect.md`
-- Si el archivo no existe, informe el error al usuario
-
-### 2. Cargar MetaSpecs
-
-**Localizar MetaSpecs automáticamente**:
-1. Lea `context-manifest.json` del orchestrator
-2. Encuentre el repositorio con `"role": "metaspecs"`
-3. Lea `ai.properties.md` para obtener el `base_path`
-4. El metaspecs está en: `{base_path}/{metaspecs-repo-id}/`
-5. Lea los archivos `index.md` relevantes para entender:
-   - Arquitectura del sistema
-   - Patrones de diseño
-   - Restricciones técnicas
-   - Convenciones del proyecto
-
-### 3. Análisis de Alcance
-
-Defina claramente:
-
-**Qué ESTÁ en el alcance**:
-- Funcionalidades específicas a implementar
-- Repositorios que serán modificados
-- Integraciones necesarias
-
-**Qué NO ESTÁ en el alcance**:
-- Funcionalidades relacionadas pero que quedan para después
-- Optimizaciones futuras
-- Features "nice to have"
-
-### 4. Criterios de Aceptación
-
-Defina criterios medibles y comprobables:
-
-```markdown
-## Criterios de Aceptación
-
-### Funcional
-- [ ] [Criterio 1 - específico y comprobable]
-- [ ] [Criterio 2 - específico y comprobable]
-
-### Técnico
-- [ ] [Criterio técnico 1]
-- [ ] [Criterio técnico 2]
-
-### Calidad
-- [ ] Pruebas unitarias implementadas
-- [ ] Pruebas de integración implementadas
-- [ ] Documentación actualizada
-```
-
-### 5. Análisis de Impacto
-
-Para cada repositorio afectado:
+**Proceso de Validación**:
 
+1. **Consulta los índices cargados** por `/warm-up`:
+   - Lee `context-manifest.json` para encontrar el repositorio con `role: "metaspecs"`
+   - Obtén el `id` de ese repositorio (ej: "my-project-metaspecs")
+   - Lee `ai.properties.md` para obtener el `base_path`
+   - El repositorio de metaspecs está en: `{base_path}/{metaspecs-id}/`
+   - Consulta `{base_path}/{metaspecs-id}/index.md` - Visión general del proyecto
+   - Consulta índices específicos (ej: `specs/business/index.md`, `specs/technical/index.md`)
+
+2. **Identifica documentos relevantes** para este requisito específico:
+   - En `specs/business/`: ¿Qué documentos de negocio son relevantes?
+   - En `specs/technical/`: ¿Qué documentos técnicos son relevantes?
+
+3. **Lee SÓLO los documentos relevantes** identificados (¡no leas todo!)
+
+4. **Valida el requisito** contra las metaspecs leídas:
+   - ✅ Alineación con estrategia y visión de producto
+   - ✅ Atiende necesidades de las personas correctas
+   - ✅ Compatible con stack tecnológico aprobado
+   - ✅ Respeta decisiones arquitecturales (ADRs)
+   - ✅ Sigue reglas de negocio existentes
+   - ⚠️ Identifica conflictos o violaciones
+
+**Si identificas violaciones**: 🛑 **DETENTE** y pide aclaración al usuario antes de continuar (Principio Jidoka).
+
+### 3. Fase de Resumen y Aprobación
+
+Una vez que hayas recopilado información suficiente y validado contra metaspecs, presenta un resumen estructurado con:
+- **Feature**: Nombre de la funcionalidad
+- **Objetivo**: Por qué construir (1-2 frases)
+- **Valor de Negocio**: Métrica, persona, fase del roadmap (consulta metaspecs)
+- **Alcance**: Qué INCLUYE y qué NO INCLUYE
+- **Componentes Afectados**: Lista basada en la arquitectura actual (consulta metaspecs técnicas)
+- **Validación contra Metaspecs**: ✅ Aprobado / ⚠️ Atención necesaria
+- **Estimación de Esfuerzo**: Pequeño (< 1 día) / Medio (1-3 días) / Grande (3-5 días) / Muy Grande (> 5 días)
+
+**Evaluación de Complejidad y Sugerencia de División**:
+
+**Si la implementación parece grande** (> 5 días de esfuerzo estimado):
+- 🚨 **Sugiere dividir en múltiples issues menores**
+- Explica el racional de la división (ej: "Esta feature involucra 3 áreas distintas que pueden implementarse independientemente")
+- Propón una división **lógica** basada en:
+  - Funcionalidades independientes
+  - Repositorios diferentes
+  - Capas de la aplicación (backend, frontend, infra)
+  - Fases de implementación (MVP, mejoras, optimizaciones)
+- Ejemplo de división:
+  ```
+  Issue Original: "Sistema de notificaciones multi-canal"
+  
+  División Sugerida:
+  - FIN-201: Infraestructura de colas y workers (backend)
+  - FIN-202: Notificaciones por email (backend + templates)
+  - FIN-203: Notificaciones push (backend + mobile)
+  - FIN-204: Preferencias de notificación (frontend + backend)
+  ```
+- **Importante**: La decisión final es del usuario - puede aceptar la división o mantener como issue única
+
+**Si el usuario acepta la división**:
+- Documenta cada issue por separado
+- Añade referencias cruzadas entre las issues relacionadas
+- Sugiere orden de implementación si hay dependencias
+- Cada issue dividida debe pasar por el mismo proceso de refinamiento
+
+Pide aprobación del usuario e incorpora feedback si es necesario.
+
+**Consejo**: Puedes buscar en el código base o internet antes de finalizar, si es necesario.
+
+### 4. Guardado de los Requisitos Refinados
+
+Una vez que el usuario apruebe, guarda los requisitos:
+
+**IMPORTANTE**: Siempre crea backup local Y actualiza el task manager (si está configurado).
+
+**Proceso de Guardado**:
+
+1. **SIEMPRE crear backup local primero**:
+   - Crea archivo completo en `./.sessions/<ISSUE-ID>/refined.md` (ej: `./.sessions/FIN-5/refined.md`)
+   - Donde `<ISSUE-ID>` es el ID de la issue (ej: FIN-5, FIN-123)
+   - Incluye TODOS los detalles del refinamiento (backup completo)
+
+2. **Si el task manager está configurado** (lee `ai.properties.md` para identificar `task_management_system`):
+   - Identifica la herramienta MCP del task manager
+   - **Actualiza el BODY (description) de la issue** con versión CONCISA de los requisitos refinados
+     - Para Jira: Usa MCP de Jira con campo `description`
+     - Para Linear: Usa MCP de Linear con campo `description`
+     - Para GitHub: Usa MCP de GitHub con campo `body`
+     - Incluye todo el contenido refinado en el campo description/body de la issue
+     - Si el contenido es muy extenso y hay error de API, considera crear versión resumida
+   - **SIEMPRE sobrescribe** el body existente (no agregar al final)
+
+**Observación**:
+- El backup local SIEMPRE está guardado y completo
+- Si hay error de API, verifica manualmente si la issue fue actualizada en el task manager
+
+**Template de Salida**:
+
+**IMPORTANTE**: El template estándar para requisitos refinados puede estar documentado en el repositorio de metaspecs. Consulta `{base_path}/{metaspecs-id}/specs/refined/` o similar.
+
+**Template COMPLETO** (para backup local `.sessions/<ISSUE-ID>/refined.md`):
+- **Metadatos**: Issue, ID, Task Manager, Proyecto, Fecha, Sprint, Prioridad
+- **🎯 POR QUÉ**: Razones, valor de negocio, métrica, persona, alineamiento estratégico
+- **📦 QUÉ**: Funcionalidades detalladas, componentes afectados, integraciones, alcance negativo completo
+- **🔧 CÓMO**: Stack, patrones de código, estructura de archivos, dependencias, orden de implementación, failure modes, consideraciones de performance/costo/UX
+- **✅ Validación contra Metaspecs**: Documentos consultados (business y technical), ADRs verificados, resultado de la validación
+- **📊 Métricas de Éxito**: Técnicas, producto/UX, criterios de aceptación
+- **🔄 Impacto en el Producto**: Alineamiento con objetivos, habilitadores, riesgos mitigados
+- **⚠️ Limitaciones Conocidas**: Limitaciones del MVP
+- **📝 Checklist de Implementación**: Tareas por área (backend, frontend, tests, seguridad, etc.)
+
+**Template para Task Manager**:
 ```markdown
-## Impacto por Repositorio
-
-### <repo-1>
-- **Componentes afectados**: [lista]
-- **Tipo de cambio**: Nueva feature / Modificación / Refactorización
-- **Complejidad estimada**: Baja / Media / Alta
-- **Riesgos**: [riesgos específicos]
-
-### <repo-2>
-- **Componentes afectados**: [lista]
-- **Tipo de cambio**: Nueva feature / Modificación / Refactorización
-- **Complejidad estimada**: Baja / Media / Alta
-- **Riesgos**: [riesgos específicos]
-```
-
-### 6. Dependencias y Restricciones
-
-Identifique:
-- Dependencias entre repositorios
-- Dependencias de otras features/issues
-- Restricciones técnicas
-- Restricciones de negocio
-- Bloqueadores conocidos
-
-### 7. Estimación Inicial
+# [Nombre Feature] - Requisitos Refinados
 
-Proporcione estimación de esfuerzo:
-- **Pequeño**: < 1 día
-- **Medio**: 1-3 días
-- **Grande**: 3-5 días
-- **Muy Grande**: > 5 días (considere dividir en issues más pequeñas)
+**Sprint X** | **Y días** | **Prioridad**
 
-### 8. Preguntas Pendientes
+## Objetivo
+[1-2 párrafos: qué es y por qué hacerlo]
 
-Liste preguntas que aún necesitan respuesta antes de iniciar la implementación.
-
-## 📄 Guardado del Refinamiento
+## Alcance
 
-**PRIORIDAD 1: Actualizar vía MCP**
+### Funcionalidades Principales
+- Funcionalidad 1: [resumen]
+- Funcionalidad 2: [resumen]
+- Validaciones/Guards: [resumen]
 
-- Use el MCP del task manager para actualizar la issue
-- Añada los criterios de aceptación como comentario o campo personalizado
-- Actualice labels/tags si es necesario (ej: "refined", "ready-for-spec")
-- Añada estimación si el task manager lo soporta
-- Informe al usuario: "✅ Issue [ID] actualizada con refinamiento"
+### Componentes Afectados
+- Componente 1: [tipo de cambio]
+- Componente 2: [tipo de cambio]
 
-**FALLBACK: Crear archivo .md solo si MCP falla**
+### Seguridad
+✅ [ítem 1] ✅ [ítem 2] ✅ [ítem 3]
 
-Si el MCP no está disponible o falla, cree/actualice `./.sessions/<ISSUE-ID>/refine.md`:
+## Alcance Negativo
+❌ [ítem 1] ❌ [ítem 2] ❌ [ítem 3]
 
-```markdown
-# [Título de la Issue] - Refinamiento
+## Stack
+[Tech stack resumida por área]
 
-## Alcance
+## Estructura
+[Árbol de archivos RESUMIDO - módulos principales solamente]
 
-### Incluido
-- [Ítem 1]
-- [Ítem 2]
-
-### Excluido
-- [Ítem 1]
-- [Ítem 2]
+## Failure Modes (Evitar)
+🔴 [crítico 1] 🔴 [crítico 2]
+🟡 [medio 1] 🟡 [medio 2]
 
 ## Criterios de Aceptación
-[Según sección 3 arriba]
-
-## Impacto por Repositorio
-[Según sección 4 arriba]
-
-## Dependencias
-- [Dependencia 1]
-- [Dependencia 2]
-
-## Restricciones
-- [Restricción 1]
-- [Restricción 2]
+- [ ] [ítem 1]
+- [ ] [ítem 2]
+- [ ] [ítem 3]
 
-## Estimación
-[Pequeño/Medio/Grande/Muy Grande] - [Justificación]
+## Validación
+**ADRs**: [lista]
+**Specs**: [principales]
+**Estado**: ✅ Aprobado
 
-## Preguntas Pendientes
-1. [Pregunta 1]
-2. [Pregunta 2]
+**Impacto**: [resumen]
+**Limitaciones**: [resumen]
 
-## Riesgos Identificados
-- [Riesgo 1 y mitigación]
-- [Riesgo 2 y mitigación]
+---
+📄 **Documento completo**: `.sessions/<ISSUE-ID>/refined.md`
 ```
 
-Informe al usuario: "⚠️ Refinamiento guardado localmente en .sessions/ (task manager no disponible)"
-
-## 🔍 Validación
-
-Valide el refinamiento contra:
-- Estrategia del producto (si está documentada)
-- Arquitectura técnica (si está documentada)
-- Capacidad del equipo
-- Prioridades del roadmap
+**Audiencia**: Desarrollador IA con capacidades similares a las tuyas. Sé conciso pero completo.
 
 ---
 
-**Argumentos proporcionados**:
+**Requisito para Refinar**:
 
 ```
 #$ARGUMENTS
@@ -213,10 +215,12 @@ Valide el refinamiento contra:
 
 ## 🎯 Próximo Paso
 
-Después de aprobar el refinamiento:
+**Tras la aprobación del usuario y guardado de los requisitos refinados**, el flujo natural es:
 
 ```bash
 /spec [ISSUE-ID]
 ```
 
-Este comando creará la especificación completa (PRD) de la feature.
+**Ejemplo**: `/spec FIN-3`
+
+Este comando creará un PRD (Product Requirements Document) completo basado en los requisitos refinados, detallando funcionalidades, user stories, criterios de aceptación y validaciones finales.

package/templates/commands/pt-BR/products/collect.md

@@ -86,12 +86,36 @@ Apenas certifique-se de que a ideia esteja **adequadamente compreendida**.
    - Repositórios afetados
    - Prioridade sugerida
 
-3. **Aprovação do Usuário**
-   - Apresente o rascunho
+3. **Avaliação de Complexidade e Sugestão de Quebra**
+   
+   Antes de finalizar, avalie a complexidade da issue:
+   
+   **Se a implementação parecer grande** (> 5 dias de esforço estimado):
+   - 🚨 **Sugira quebrar em múltiplas issues menores**
+   - Explique o racional da quebra (ex: "Esta feature envolve 3 áreas distintas: autenticação, processamento e notificação")
+   - Proponha uma quebra **lógica** (por funcionalidade, por repositório, por camada, etc.)
+   - Exemplo de quebra:
+     ```
+     Issue Original: "Sistema de pagamentos completo"
+     
+     Quebra Sugerida:
+     - FIN-101: Integração com gateway de pagamento (backend)
+     - FIN-102: Interface de checkout (frontend)
+     - FIN-103: Webhook de confirmação e notificações (backend + jobs)
+     ```
+   - **Importante**: A decisão final é do usuário - ele pode aceitar a quebra ou manter como issue única
+   
+   **Se o usuário aceitar a quebra**:
+   - Crie cada issue separadamente usando o mesmo processo
+   - Adicione referências cruzadas entre as issues relacionadas
+   - Sugira ordem de implementação se houver dependências
+
+4. **Aprovação do Usuário**
+   - Apresente o rascunho (ou rascunhos, se houver quebra)
    - Faça ajustes conforme feedback
    - Obtenha aprovação final
 
-4. **Salvamento da Issue**
+5. **Salvamento da Issue**
 
    **PRIORIDADE 1: Usar MCP (Model Context Protocol)**