context-first-cli 2.0.3 → 2.0.5

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

@@ -1,209 +1,211 @@
 # Requirements Refinement
 
-This command refines a collected issue, transforming it into clear and validated requirements.
+You are a product expert tasked with helping to refine requirements for the project.
 
 ## ⚠️ IMPORTANT: This Command DOES NOT Implement Code
 
-**This command is ONLY for requirements refinement:**
-- ✅ Refine and validate requirements
-- ✅ Update issue in the task manager via MCP
-- ✅ **READ** files from main repositories (read-only)
+**This command is ONLY for planning and documentation:**
+- ✅ Validate requirements against metaspecs
+- ✅ Create refined specification
+- ✅ Save documentation in `.sessions/`
+- ✅ Update issue in task manager
 - ❌ **DO NOT implement code**
 - ❌ **DO NOT edit code files**
-- ❌ **DO NOT checkout branches in main repositories**
-- ❌ **DO NOT make commits**
+- ❌ **DO NOT run tests or deploy**
 
-**Next step**: `/spec [ISSUE-ID]` to create the complete specification (PRD).
+**Next step**: `/spec [ISSUE-ID]` to create a complete PRD based on the refined requirements.
 
 ---
 
-## 📋 Prerequisites
+## Objective
 
-- Issue already collected via `/collect`
-- Project context will be loaded automatically (see "Load MetaSpecs" section below)
+Transform an initial requirement into a refined and validated specification, ready to become a complete PRD.
 
-## 🎯 Objective
+## Process
 
-Refine the collected issue, clarifying:
-- Exact scope (what is included and what is not)
-- Clear acceptance criteria
-- Impact on each repository
-- Technical dependencies
-- Risks and constraints
+### 1. Clarification Phase
 
-## 📝 Refinement Process
+Read the initial requirement and ask questions to achieve full clarity about:
+- **Objective**: Why build this?
+- **Business Value**: Which metric/persona does it impact?
+- **Scope**: What is included and what is NOT included?
+- **Interactions**: Which existing features/components are affected?
 
-### 1. Load Issue
+Keep asking questions until you have complete understanding.
 
-**PRIORITY 1: Use MCP (Model Context Protocol)**
+### 2. Validation Against Metaspecs
 
-- Read `ai.properties.md` from the orchestrator to identify the `task_management_system`
-- Use the appropriate MCP to fetch the issue:
-  - `task_management_system=jira`: Use Jira MCP
-  - `task_management_system=linear`: Use Linear MCP
-  - `task_management_system=github`: Use GitHub MCP
-- Load all issue data (title, description, labels, etc.)
+**IMPORTANT**: First read `ai.properties.md` to obtain the `base_path`. The indexes should ALREADY be in context (you ran `/warm-up`). Consult the indexes and read ONLY the relevant documents to validate the requirement.
 
-**FALLBACK: If MCP is unavailable or fails**
-
-- Read `./.sessions/<ISSUE-ID>/collect.md`
-- If the file does not exist, inform the user of the error
-
-### 2. Load MetaSpecs
-
-**Automatically locate MetaSpecs**:
-1. Read `context-manifest.json` from the orchestrator
-2. Find the repository with `"role": "metaspecs"`
-3. Read `ai.properties.md` to get the `base_path`
-4. The metaspecs are located at: `{base_path}/{metaspecs-repo-id}/`
-5. Read relevant `index.md` files to understand:
-   - System architecture
-   - Design patterns
-   - Technical constraints
-   - Project conventions
-
-### 3. Scope Analysis
-
-Clearly define:
-
-**What IS in scope**:
-- Specific functionalities to be implemented
-- Repositories that will be modified
-- Necessary integrations
-
-**What IS NOT in scope**:
-- Related functionalities deferred for later
-- Future optimizations
-- "Nice to have" features
-
-### 4. Acceptance Criteria
-
-Define measurable and testable criteria:
-
-```markdown
-## Acceptance Criteria
-
-### Functional
-- [ ] [Criterion 1 - specific and testable]
-- [ ] [Criterion 2 - specific and testable]
-
-### Technical
-- [ ] [Technical criterion 1]
-- [ ] [Technical criterion 2]
-
-### Quality
-- [ ] Unit tests implemented
-- [ ] Integration tests implemented
-- [ ] Documentation updated
-```
-
-### 5. Impact Analysis
-
-For each affected repository:
+**Validation Process**:
 
+1. **Consult the loaded indexes** from `/warm-up`:
+   - Read `context-manifest.json` to find the repository with `role: "metaspecs"`
+   - Obtain the `id` of that repository (e.g., "my-project-metaspecs")
+   - Read `ai.properties.md` to get the `base_path`
+   - The metaspecs repository is at: `{base_path}/{metaspecs-id}/`
+   - Consult `{base_path}/{metaspecs-id}/index.md` - Project overview
+   - Consult specific indexes (e.g., `specs/business/index.md`, `specs/technical/index.md`)
+
+2. **Identify relevant documents** for this specific requirement:
+   - In `specs/business/`: Which business documents are relevant?
+   - In `specs/technical/`: Which technical documents are relevant?
+
+3. **Read ONLY the identified relevant documents** (do not read everything!)
+
+4. **Validate the requirement** against the read metaspecs:
+   - ✅ Alignment with product strategy and vision
+   - ✅ Meets needs of the correct personas
+   - ✅ Compatible with approved technology stack
+   - ✅ Respects architectural decisions (ADRs)
+   - ✅ Follows existing business rules
+   - ⚠️ Identify conflicts or violations
+
+**If you identify violations**: 🛑 **STOP** and ask the user for clarification before proceeding (Jidoka Principle).
+
+### 3. Summary and Approval Phase
+
+Once you have gathered sufficient information and validated against metaspecs, present a structured summary with:
+- **Feature**: Feature name
+- **Objective**: Why build it (1-2 sentences)
+- **Business Value**: Metric, persona, roadmap phase (consult metaspecs)
+- **Scope**: What it INCLUDES and what it DOES NOT INCLUDE
+- **Affected Components**: List based on current architecture (consult technical metaspecs)
+- **Validation against Metaspecs**: ✅ Approved / ⚠️ Attention needed
+- **Effort Estimate**: Small (< 1 day) / Medium (1-3 days) / Large (3-5 days) / Very Large (> 5 days)
+
+**Complexity Assessment and Suggestion to Break Down**:
+
+**If the implementation seems large** (> 5 days estimated effort):
+- 🚨 **Suggest breaking into multiple smaller issues**
+- Explain the rationale for the breakdown (e.g., "This feature involves 3 distinct areas that can be implemented independently")
+- Propose a **logical** breakdown based on:
+  - Independent functionalities
+  - Different repositories
+  - Application layers (backend, frontend, infra)
+  - Implementation phases (MVP, improvements, optimizations)
+- Example breakdown:
+  ```
+  Original Issue: "Multi-channel notification system"
+  
+  Suggested Breakdown:
+  - FIN-201: Queue and worker infrastructure (backend)
+  - FIN-202: Email notifications (backend + templates)
+  - FIN-203: Push notifications (backend + mobile)
+  - FIN-204: Notification preferences (frontend + backend)
+  ```
+- **Important**: The final decision is the user's - they may accept the breakdown or keep it as a single issue
+
+**If the user accepts the breakdown**:
+- Document each issue separately
+- Add cross-references between related issues
+- Suggest implementation order if dependencies exist
+- Each broken-down issue must go through the same refinement process
+
+Request user approval and incorporate feedback if necessary.
+
+**Tip**: You may search the codebase or internet before finalizing, if needed.
+
+### 4. Saving the Refined Requirements
+
+Once the user approves, save the requirements:
+
+**IMPORTANT**: Always create a local backup AND update the task manager (if configured).
+
+**Saving Process**:
+
+1. **ALWAYS create local backup first**:
+   - Create a complete file at `./.sessions/<ISSUE-ID>/refined.md` (e.g., `./.sessions/FIN-5/refined.md`)
+   - Where `<ISSUE-ID>` is the issue ID (e.g., FIN-5, FIN-123)
+   - Include ALL refinement details (full backup)
+
+2. **If task manager is configured** (read `ai.properties.md` to identify `task_management_system`):
+   - Identify the MCP tool of the task manager
+   - **Update the BODY (description) of the issue** with a CONCISE version of the refined requirements
+     - For Jira: Use Jira MCP with `description` field
+     - For Linear: Use Linear MCP with `description` field
+     - For GitHub: Use GitHub MCP with `body` field
+     - Include all refined content in the issue description/body field
+     - If content is too long and API errors occur, consider creating a summarized version
+   - **ALWAYS overwrite** the existing body (do not append)
+
+**Note**:
+- The local backup is ALWAYS saved and complete
+- If API error occurs, manually verify if the issue was updated in the task manager
+
+**Output Template**:
+
+**IMPORTANT**: The standard template for refined requirements may be documented in the metaspecs repository. Check `{base_path}/{metaspecs-id}/specs/refined/` or similar.
+
+**FULL Template** (for local backup `.sessions/<ISSUE-ID>/refined.md`):
+- **Metadata**: Issue, ID, Task Manager, Project, Date, Sprint, Priority
+- **🎯 WHY**: Reasons, business value, metric, persona, strategic alignment
+- **📦 WHAT**: Detailed features, affected components, integrations, full negative scope
+- **🔧 HOW**: Stack, coding standards, file structure, dependencies, implementation order, failure modes, performance/cost/UX considerations
+- **✅ Validation against Metaspecs**: Consulted documents (business and technical), verified ADRs, validation result
+- **📊 Success Metrics**: Technical, product/UX, acceptance criteria
+- **🔄 Product Impact**: Alignment with objectives, enablers, mitigated risks
+- **⚠️ Known Limitations**: MVP limitations
+- **📝 Implementation Checklist**: Tasks by area (backend, frontend, testing, security, etc.)
+
+**Task Manager Template**:
 ```markdown
-## Impact by Repository
-
-### <repo-1>
-- **Affected components**: [list]
-- **Type of change**: New feature / Modification / Refactoring
-- **Estimated complexity**: Low / Medium / High
-- **Risks**: [specific risks]
-
-### <repo-2>
-- **Affected components**: [list]
-- **Type of change**: New feature / Modification / Refactoring
-- **Estimated complexity**: Low / Medium / High
-- **Risks**: [specific risks]
-```
-
-### 6. Dependencies and Constraints
-
-Identify:
-- Dependencies between repositories
-- Dependencies on other features/issues
-- Technical constraints
-- Business constraints
-- Known blockers
-
-### 7. Initial Estimate
+# [Feature Name] - Refined Requirements
 
-Provide effort estimate:
-- **Small**: < 1 day
-- **Medium**: 1-3 days
-- **Large**: 3-5 days
-- **Very Large**: > 5 days (consider breaking into smaller issues)
+**Sprint X** | **Y days** | **Priority**
 
-### 8. Pending Questions
+## Objective
+[1-2 paragraphs: what it is and why]
 
-List questions that still need answers before starting implementation.
-
-## 📄 Saving the Refinement
+## Scope
 
-**PRIORITY 1: Update via MCP**
+### Main Features
+- Feature 1: [summary]
+- Feature 2: [summary]
+- Validations/Guards: [summary]
 
-- Use the task manager MCP to update the issue
-- Add acceptance criteria as a comment or custom field
-- Update labels/tags if necessary (e.g., "refined", "ready-for-spec")
-- Add estimate if supported by the task manager
-- Inform the user: "✅ Issue [ID] updated with refinement"
+### Affected Components
+- Component 1: [type of change]
+- Component 2: [type of change]
 
-**FALLBACK: Create .md file only if MCP fails**
+### Security
+✅ [item 1] ✅ [item 2] ✅ [item 3]
 
-If MCP is unavailable or fails, create/update `./.sessions/<ISSUE-ID>/refine.md`:
+## Negative Scope
+❌ [item 1] ❌ [item 2] ❌ [item 3]
 
-```markdown
-# [Issue Title] - Refinement
+## Stack
+[Tech stack summary by area]
 
-## Scope
+## Structure
+[SUMMARIZED file tree - main modules only]
 
-### Included
-- [Item 1]
-- [Item 2]
-
-### Excluded
-- [Item 1]
-- [Item 2]
+## Failure Modes (To Avoid)
+🔴 [critical 1] 🔴 [critical 2]
+🟡 [medium 1] 🟡 [medium 2]
 
 ## Acceptance Criteria
-[As per section 3 above]
-
-## Impact by Repository
-[As per section 4 above]
-
-## Dependencies
-- [Dependency 1]
-- [Dependency 2]
-
-## Constraints
-- [Constraint 1]
-- [Constraint 2]
+- [ ] [item 1]
+- [ ] [item 2]
+- [ ] [item 3]
 
-## Estimate
-[Small/Medium/Large/Very Large] - [Justification]
+## Validation
+**ADRs**: [list]
+**Specs**: [main]
+**Status**: ✅ Approved
 
-## Pending Questions
-1. [Question 1]
-2. [Question 2]
+**Impact**: [summary]
+**Limitations**: [summary]
 
-## Identified Risks
-- [Risk 1 and mitigation]
-- [Risk 2 and mitigation]
+---
+📄 **Full document**: `.sessions/<ISSUE-ID>/refined.md`
 ```
 
-Inform the user: "⚠️ Refinement saved locally in .sessions/ (task manager not available)"
-
-## 🔍 Validation
-
-Validate the refinement against:
-- Product strategy (if documented)
-- Technical architecture (if documented)
-- Team capacity
-- Roadmap priorities
+**Audience**: AI Developer with capabilities similar to yours. Be concise but complete.
 
 ---
 
-**Provided arguments**:
+**Requirement to Refine**:
 
 ```
 #$ARGUMENTS
@@ -213,10 +215,12 @@ Validate the refinement against:
 
 ## 🎯 Next Step
 
-After approved refinement:
+**After user approval and saving the refined requirements**, the natural flow is:
 
 ```bash
 /spec [ISSUE-ID]
 ```
 
-This command will create the complete feature specification (PRD).
+**Example**: `/spec FIN-3`
+
+This command will create a complete PRD (Product Requirements Document) based on the refined requirements, detailing features, user stories, acceptance criteria, and final validations.

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

@@ -1,16 +1,16 @@
 # Recolección de Ideas y Requisitos
 
-Usted es un experto en producto responsable de recopilar y documentar nuevas ideas, features o bugs.
+Eres un especialista en producto responsable de recopilar y documentar nuevas ideas, funcionalidades o bugs.
 
 ## ⚠️ IMPORTANTE: Este Comando NO Implementa Código
 
-**Este comando es SOLO para planificación y documentación:**
+**Este comando es SÓLO para planificación y documentación:**
 - ✅ Recopilar y entender requisitos
-- ✅ Crear issue en el task manager vía MCP
+- ✅ Crear issue en el gestor de tareas vía MCP
 - ✅ Hacer preguntas de aclaración
 - ✅ **LEER** archivos de los repositorios principales (solo lectura)
 - ❌ **NO implementar código**
-- ❌ **NO editar archivos de código**
+- ❌ **NO hacer ediciones en archivos de código**
 - ❌ **NO hacer checkout de branches en los repositorios principales**
 - ❌ **NO hacer commits**
 
@@ -20,29 +20,29 @@ Usted es un experto en producto responsable de recopilar y documentar nuevas ide
 
 ## Contexto del Proyecto
 
-Antes de iniciar, cargue el contexto consultando:
+Antes de comenzar, carga el contexto consultando:
 
 1. **Localizar MetaSpecs automáticamente**:
-   - Lea `context-manifest.json` del orchestrator
-   - Encuentre el repositorio con `"role": "metaspecs"`
-   - Lea `ai.properties.md` para obtener el `base_path`
+   - Lee `context-manifest.json` del orquestador
+   - Encuentra el repositorio con `"role": "metaspecs"`
+   - Lee `ai.properties.md` para obtener el `base_path`
    - El metaspecs está en: `{base_path}/{metaspecs-repo-id}/`
-   - Lea los archivos `index.md` como referencia
+   - Lee los archivos `index.md` como referencia
 
 2. **Estructura del proyecto**:
    - `context-manifest.json` - Lista de repositorios y sus funciones
    - `README.md` de los repositorios involucrados
 
-## Su Objetivo
+## Tu Objetivo
 
-Entender la solicitud del usuario y capturarla como issue en el task manager (vía MCP).
+Entender la solicitud del usuario y capturarla como issue en el gestor de tareas (vía MCP).
 
-**En esta fase, usted NO necesita:**
+**En esta fase, NO necesitas:**
 - ❌ Escribir especificación completa
 - ❌ Validar contra metaspecs (esto se hace en `/refine` o `/spec`)
 - ❌ Detallar implementación técnica
 
-Solo asegúrese de que la idea esté **adecuadamente comprendida**.
+Solo asegúrate de que la idea esté **adecuadamente comprendida**.
 
 ## Formato de la Issue
 
@@ -50,20 +50,20 @@ Solo asegúrese de que la idea esté **adecuadamente comprendida**.
 # [Título Claro y Descriptivo]
 
 ## Descripción
-[2-3 párrafos explicando qué es la feature/bug y por qué es importante]
+[2-3 párrafos explicando qué es la funcionalidad/bug y por qué es importante]
 
 ## Tipo
-- [ ] Nueva Feature
-- [ ] Mejora de Feature Existente
+- [ ] Nueva Funcionalidad
+- [ ] Mejora de Funcionalidad Existente
 - [ ] Bug
-- [ ] Tech Debt
+- [ ] Deuda Técnica
 - [ ] Documentación
 
 ## Contexto Adicional
-[Información relevante: dónde ocurre el bug, inspiración para la feature, etc.]
+[Información relevante: dónde ocurre el bug, inspiración para la funcionalidad, etc.]
 
 ## Repositorios Afectados
-[Liste qué repositorios del proyecto serán impactados]
+[Lista de los repositorios del proyecto que serán impactados]
 
 ## Prioridad Sugerida
 - [ ] 🔴 Crítica
@@ -75,9 +75,9 @@ Solo asegúrese de que la idea esté **adecuadamente comprendida**.
 ## Proceso de Recolección
 
 1. **Entendimiento Inicial**
-   - Haga preguntas de aclaración si es necesario
-   - Identifique: ¿Es feature nueva? ¿Mejora? ¿Bug?
-   - Identifique qué repositorios serán afectados
+   - Haz preguntas de aclaración si es necesario
+   - Identifica: ¿Es funcionalidad nueva? ¿Mejora? ¿Bug?
+   - Identifica qué repositorios serán afectados
 
 2. **Borrador de la Issue**
    - Título claro (máximo 10 palabras)
@@ -86,47 +86,71 @@ Solo asegúrese de que la idea esté **adecuadamente comprendida**.
    - Repositorios afectados
    - Prioridad sugerida
 
-3. **Aprobación del Usuario**
-   - Presente el borrador
-   - Haga ajustes según feedback
-   - Obtenga aprobación final
+3. **Evaluación de Complejidad y Sugerencia de División**
+   
+   Antes de finalizar, evalúa la complejidad de la issue:
+   
+   **Si la implementación parece grande** (> 5 días de esfuerzo estimado):
+   - 🚨 **Sugiere dividir en múltiples issues más pequeñas**
+   - Explica la razón de la división (ej: "Esta funcionalidad involucra 3 áreas distintas: autenticación, procesamiento y notificación")
+   - Propón una división **lógica** (por funcionalidad, por repositorio, por capa, etc.)
+   - Ejemplo de división:
+     ```
+     Issue Original: "Sistema completo de pagos"
+     
+     División Sugerida:
+     - FIN-101: Integración con gateway de pago (backend)
+     - FIN-102: Interfaz de checkout (frontend)
+     - FIN-103: Webhook de confirmación y notificaciones (backend + jobs)
+     ```
+   - **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**:
+   - Crea cada issue por separado usando el mismo proceso
+   - Añade referencias cruzadas entre las issues relacionadas
+   - Sugiere orden de implementación si hay dependencias
+
+4. **Aprobación del Usuario**
+   - Presenta el borrador (o borradores, si hay división)
+   - Realiza ajustes según feedback
+   - Obtén aprobación final
 
-4. **Guardado de la Issue**
+5. **Guardado de la Issue**
 
    **PRIORIDAD 1: Usar MCP (Model Context Protocol)**
    
-   Verifique si hay MCP configurado para task manager:
-   - Lea `ai.properties.md` del orchestrator para identificar el `task_management_system`
-   - Si `task_management_system=jira`: Use MCP de Jira para crear la issue
-   - Si `task_management_system=linear`: Use MCP de Linear para crear la issue
-   - Si `task_management_system=github`: Use MCP de GitHub para crear la issue
+   Verifica si hay MCP configurado para el gestor de tareas:
+   - Lee `ai.properties.md` del orquestador para identificar el `task_management_system`
+   - Si `task_management_system=jira`: Usa MCP de Jira para crear la issue
+   - Si `task_management_system=linear`: Usa MCP de Linear para crear la issue
+   - Si `task_management_system=github`: Usa MCP de GitHub para crear la issue
    
    **Al usar MCP:**
-   - Cree la issue directamente en el task manager
-   - Obtenga el ID de la issue creada (ej: FIN-123, LIN-456)
-   - Informe al usuario: "✅ Issue [ID] creada en [task manager]"
-   - **NO cree archivo .md**
+   - Crea la issue directamente en el gestor de tareas
+   - Obtén el ID de la issue creada (ej: FIN-123, LIN-456)
+   - Informa al usuario: "✅ Issue [ID] creada en [task manager]"
+   - **NO crees archivo .md**
    
-   **FALLBACK: Crear archivo .md solo si MCP falla**
+   **FALLBACK: Crear archivo .md sólo si MCP falla**
    
-   Si el MCP no está disponible o falla:
-   - Cree archivo en `./.sessions/<ISSUE-ID>/collect.md`
-   - Use formato de ID manual: `LOCAL-001`, `LOCAL-002`, etc.
-   - Incluya fecha, tipo y contenido completo
-   - Informe al usuario: "⚠️ Issue guardada localmente en .sessions/ (task manager no disponible)"
+   Si MCP no está disponible o falla:
+   - Crea archivo en `./.sessions/<ISSUE-ID>/collect.md`
+   - Usa formato de ID manual: `LOCAL-001`, `LOCAL-002`, etc.
+   - Incluye fecha, tipo y contenido completo
+   - Informa al usuario: "⚠️ Issue guardada localmente en .sessions/ (gestor de tareas no disponible)"
 
 ## Preguntas de Aclaración
 
-**Para Features**:
+**Para Funcionalidades**:
 - ¿Qué problema resuelve?
 - ¿Quién se beneficia?
 - ¿Es funcionalidad visible o infraestructura?
-- ¿Tiene relación con alguna feature existente?
+- ¿Tiene relación con alguna funcionalidad existente?
 - ¿Qué repositorios necesitan ser modificados?
 
 **Para Bugs**:
 - ¿Dónde ocurre el bug? (repositorio, componente, flujo)
-- ¿Cómo reproducir?
+- ¿Cómo reproducirlo?
 - ¿Cuál es el comportamiento esperado vs actual?
 - ¿Severidad del impacto?
 
@@ -147,10 +171,10 @@ Solo asegúrese de que la idea esté **adecuadamente comprendida**.
 
 ## 🎯 Próximo Paso
 
-Después de aprobación y guardado de la issue:
+Tras la aprobación y guardado de la issue:
 
 ```bash
 /refine [ISSUE-ID]
 ```
 
-Este comando transformará la issue recopilada en requisitos refinados y validados.
+Este comando transformará la issue recopilada en requisitos refinados y validados.