context-first-cli 2.0.4 → 2.0.6

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

@@ -11,7 +11,7 @@ Eres un especialista en producto encargado de ayudar a refinar requisitos para e
 - ✅ Actualizar issue en el task manager
 - ❌ **NO implementar código**
 - ❌ **NO hacer ediciones en archivos de código**
-- ❌ **NO ejecutar pruebas ni deploy**
+- ❌ **NO ejecutar pruebas o deploy**
 
 **Próximo paso**: `/spec [ISSUE-ID]` para crear PRD completo basado en los requisitos refinados.
 
@@ -56,7 +56,7 @@ Continúa haciendo preguntas hasta tener entendimiento completo.
 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ógica aprobada
+   - ✅ Compatible con stack tecnológico aprobado
    - ✅ Respeta decisiones arquitecturales (ADRs)
    - ✅ Sigue reglas de negocio existentes
    - ⚠️ Identifica conflictos o violaciones
@@ -72,10 +72,39 @@ Una vez que hayas recopilado información suficiente y validado contra 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 investigar en el código base o internet antes de finalizar, 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
 
@@ -92,34 +121,34 @@ Una vez que el usuario apruebe, guarda los requisitos:
 
 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 (descripción) de la issue** con versión CONCISA de los requisitos refinados
+   - **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`
-     - **IMPORTANTE**: Crea versión RESUMIDA (máx 3000 palabras) para evitar problemas con límites de API
-     - Incluye enlace al archivo local al final: "Documento completo: `.sessions/<ISSUE-ID>/refined.md`"
-   - **SIEMPRE sobrescribe** el body existente (no agregues al final)
+     - 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
 
-**Plantilla de Salida**:
+**Template de Salida**:
 
-**IMPORTANTE**: La plantilla estándar para requisitos refinados puede estar documentada en el repositorio de metaspecs. Consulta `{base_path}/{metaspecs-id}/specs/refined/` o similar.
+**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.
 
-**Plantilla COMPLETA** (para backup local `.sessions/<ISSUE-ID>/refined.md`):
+**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, modos de fallo, consideraciones de performance/costo/UX
+- **🔧 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, pruebas, seguridad, etc.)
+- **📝 Checklist de Implementación**: Tareas por área (backend, frontend, tests, seguridad, etc.)
 
-**Plantilla RESUMIDA** (para task manager - máx 3000 palabras):
+**Template para Task Manager**:
 ```markdown
 # [Nombre Feature] - Requisitos Refinados
 
@@ -140,25 +169,25 @@ Una vez que el usuario apruebe, guarda los requisitos:
 - Componente 2: [tipo de cambio]
 
 ### Seguridad
-✅ [item 1] ✅ [item 2] ✅ [item 3]
+✅ [ítem 1] ✅ [ítem 2] ✅ [ítem 3]
 
 ## Alcance Negativo
-❌ [item 1] ❌ [item 2] ❌ [item 3]
+❌ [ítem 1] ❌ [ítem 2] ❌ [ítem 3]
 
 ## Stack
 [Tech stack resumida por área]
 
 ## Estructura
-[Árbol de archivos RESUMIDO - principales módulos solamente]
+[Árbol de archivos RESUMIDO - módulos principales solamente]
 
-## Modos de Fallo (Evitar)
+## Failure Modes (Evitar)
 🔴 [crítico 1] 🔴 [crítico 2]
 🟡 [medio 1] 🟡 [medio 2]
 
 ## Criterios de Aceptación
-- [ ] [item 1]
-- [ ] [item 2]
-- [ ] [item 3]
+- [ ] [ítem 1]
+- [ ] [ítem 2]
+- [ ] [ítem 3]
 
 ## Validación
 **ADRs**: [lista]
@@ -186,7 +215,7 @@ Una vez que el usuario apruebe, guarda los requisitos:
 
 ## 🎯 Próximo Paso
 
-**Tras aprobación del usuario y guardado de los requisitos refinados**, el flujo natural es:
+**Tras la aprobación del usuario y guardado de los requisitos refinados**, el flujo natural es:
 
 ```bash
 /spec [ISSUE-ID]

package/dist/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)**
    

package/dist/templates/commands/pt-BR/products/refine.md

@@ -72,6 +72,35 @@ Uma vez que tenha coletado informações suficientes e validado contra metaspecs
 - **Escopo**: O que INCLUI e o que NÃO INCLUI
 - **Componentes Afetados**: Lista baseada na arquitetura atual (consulte metaspecs técnicas)
 - **Validação contra Metaspecs**: ✅ Aprovado / ⚠️ Atenção necessária
+- **Estimativa de Esforço**: Pequeno (< 1 dia) / Médio (1-3 dias) / Grande (3-5 dias) / Muito Grande (> 5 dias)
+
+**Avaliação de Complexidade e Sugestão de Quebra**:
+
+**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 que podem ser implementadas independentemente")
+- Proponha uma quebra **lógica** baseada em:
+  - Funcionalidades independentes
+  - Repositórios diferentes
+  - Camadas da aplicação (backend, frontend, infra)
+  - Fases de implementação (MVP, melhorias, otimizações)
+- Exemplo de quebra:
+  ```
+  Issue Original: "Sistema de notificações multi-canal"
+  
+  Quebra Sugerida:
+  - FIN-201: Infraestrutura de filas e workers (backend)
+  - FIN-202: Notificações por email (backend + templates)
+  - FIN-203: Notificações push (backend + mobile)
+  - FIN-204: Preferências de notificação (frontend + backend)
+  ```
+- **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**:
+- Documente cada issue separadamente
+- Adicione referências cruzadas entre as issues relacionadas
+- Sugira ordem de implementação se houver dependências
+- Cada issue quebrada deve passar pelo mesmo processo de refinamento
 
 Peça aprovação do usuário e incorpore feedback se necessário.
 
@@ -96,8 +125,8 @@ Uma vez que o usuário aprove, salve os requisitos:
      - Para Jira: Use MCP do Jira com campo `description`
      - Para Linear: Use MCP do Linear com campo `description`
      - Para GitHub: Use MCP do GitHub com campo `body`
-     - **IMPORTANTE**: Crie versão RESUMIDA (máx 3000 palavras) para evitar problemas com limites de API
-     - Inclua link para arquivo local no final: "Documento completo: `.sessions/<ISSUE-ID>/refined.md`"
+     - Inclua todo o conteúdo refinado no campo description/body da issue
+     - Se o conteúdo for muito extenso e houver erro de API, considere criar versão resumida
    - **SEMPRE sobrescrever** o body existente (não adicionar ao final)
 
 **Observação**:
@@ -119,7 +148,7 @@ Uma vez que o usuário aprove, salve os requisitos:
 - **⚠️ Limitações Conhecidas**: Limitações do MVP
 - **📝 Checklist de Implementação**: Tarefas por área (backend, frontend, testes, segurança, etc.)
 
-**Template RESUMIDO** (para task manager - máx 3000 palavras):
+**Template para Task Manager**:
 ```markdown
 # [Nome Feature] - Requisitos Refinados
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-first-cli",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "A generic CLI to manage the Context-First development methodology across any project.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -1,18 +1,18 @@
-# Idea and Requirements Collection
+# Idea and Requirements Gathering
 
-You are a product expert responsible for collecting and documenting new ideas, features, or bugs.
+You are a product specialist responsible for collecting and documenting new ideas, features, or bugs.
 
-## ⚠️ IMPORTANT: This Command Does NOT Implement Code
+## ⚠️ IMPORTANT: This Command DOES NOT Implement Code
 
 **This command is ONLY for planning and documentation:**
 - ✅ Collect and understand requirements
-- ✅ Create issue in task manager via MCP
-- ✅ Ask clarifying questions
+- ✅ Create issue in the task manager via MCP
+- ✅ Ask clarification questions
 - ✅ **READ** files from main repositories (read-only)
 - ❌ **DO NOT implement code**
 - ❌ **DO NOT edit code files**
 - ❌ **DO NOT checkout branches in main repositories**
-- ❌ **DO NOT make commits**
+- ❌ **DO NOT commit**
 
 **Next step**: `/refine [ISSUE-ID]` to refine the collected requirements.
 
@@ -22,27 +22,27 @@ You are a product expert responsible for collecting and documenting new ideas, f
 
 Before starting, load the context by consulting:
 
-1. **Locate MetaSpecs automatically**:
-   - Read `context-manifest.json` from orchestrator
+1. **Automatically Locate MetaSpecs**:
+   - Read `context-manifest.json` from the orchestrator
    - Find the repository with `"role": "metaspecs"`
    - Read `ai.properties.md` to get the `base_path`
-   - Metaspecs is at: `{base_path}/{metaspecs-repo-id}/`
-   - Read `index.md` files as reference
+   - The metaspecs are at: `{base_path}/{metaspecs-repo-id}/`
+   - Read the `index.md` files as reference
 
-2. **Project structure**:
-   - `context-manifest.json` - List of repositories and their functions
-   - `README.md` of involved repositories
+2. **Project Structure**:
+   - `context-manifest.json` - List of repositories and their roles
+   - `README.md` of the involved repositories
 
-## Your Objective
+## Your Goal
 
 Understand the user's request and capture it as an issue in the task manager (via MCP).
 
 **At this stage, you DO NOT need to:**
-- ❌ Write complete specification
+- ❌ Write a complete specification
 - ❌ Validate against metaspecs (this is done in `/refine` or `/spec`)
 - ❌ Detail technical implementation
 
-Just make sure the idea is **adequately understood**.
+Just ensure the idea is **adequately understood**.
 
 ## Issue Format
 
@@ -50,7 +50,7 @@ Just make sure the idea is **adequately understood**.
 # [Clear and Descriptive Title]
 
 ## Description
-[2-3 paragraphs explaining what the feature/bug is and why it's important]
+[2-3 paragraphs explaining what the feature/bug is and why it is important]
 
 ## Type
 - [ ] New Feature
@@ -60,7 +60,7 @@ Just make sure the idea is **adequately understood**.
 - [ ] Documentation
 
 ## Additional Context
-[Relevant information: where the bug occurs, feature inspiration, etc.]
+[Relevant information: where the bug occurs, inspiration for the feature, etc.]
 
 ## Affected Repositories
 [List which project repositories will be impacted]
@@ -75,65 +75,89 @@ Just make sure the idea is **adequately understood**.
 ## Collection Process
 
 1. **Initial Understanding**
-   - Ask clarifying questions if needed
+   - Ask clarification questions if needed
    - Identify: Is it a new feature? Improvement? Bug?
    - Identify which repositories will be affected
 
 2. **Issue Draft**
-   - Clear title (maximum 10 words)
+   - Clear title (max 10 words)
    - Objective description (2-3 paragraphs)
    - Relevant additional context
    - Affected repositories
    - Suggested priority
 
-3. **User Approval**
-   - Present the draft
+3. **Complexity Assessment and Suggestion to Split**
+   
+   Before finalizing, assess the issue complexity:
+   
+   **If the implementation seems large** (> 5 days estimated effort):
+   - 🚨 **Suggest splitting into multiple smaller issues**
+   - Explain the rationale for splitting (e.g., "This feature involves 3 distinct areas: authentication, processing, and notification")
+   - Propose a **logical** split (by functionality, repository, layer, etc.)
+   - Example of splitting:
+     ```
+     Original Issue: "Complete payment system"
+     
+     Suggested Split:
+     - FIN-101: Payment gateway integration (backend)
+     - FIN-102: Checkout interface (frontend)
+     - FIN-103: Confirmation webhook and notifications (backend + jobs)
+     ```
+   - **Important**: The final decision is the user's - they can accept the split or keep it as a single issue
+   
+   **If the user accepts the split**:
+   - Create each issue separately using the same process
+   - Add cross-references between related issues
+   - Suggest implementation order if dependencies exist
+
+4. **User Approval**
+   - Present the draft (or drafts, if split)
    - Make adjustments based on feedback
    - Obtain final approval
 
-4. **Issue Saving**
+5. **Saving the Issue**
 
    **PRIORITY 1: Use MCP (Model Context Protocol)**
    
-   Check if there's MCP configured for task manager:
-   - Read `ai.properties.md` from orchestrator to identify the `task_management_system`
+   Check if MCP is configured for the task manager:
+   - Read `ai.properties.md` from the orchestrator to identify the `task_management_system`
    - If `task_management_system=jira`: Use Jira MCP to create the issue
    - If `task_management_system=linear`: Use Linear MCP to create the issue
    - If `task_management_system=github`: Use GitHub MCP to create the issue
    
    **When using MCP:**
    - Create the issue directly in the task manager
-   - Get the created issue ID (e.g., FIN-123, LIN-456)
+   - Obtain the created issue ID (e.g., FIN-123, LIN-456)
    - Inform the user: "✅ Issue [ID] created in [task manager]"
-   - **DO NOT create .md file**
+   - **DO NOT create a .md file**
    
    **FALLBACK: Create .md file only if MCP fails**
    
-   If MCP is not available or fails:
-   - Create file at `./.sessions/<ISSUE-ID>/collect.md`
+   If MCP is unavailable or fails:
+   - Create a file at `./.sessions/<ISSUE-ID>/collect.md`
    - Use manual ID format: `LOCAL-001`, `LOCAL-002`, etc.
-   - Include date, type, and complete content
+   - Include date, type, and full content
    - Inform the user: "⚠️ Issue saved locally in .sessions/ (task manager not available)"
 
-## Clarifying Questions
+## Clarification Questions
 
 **For Features**:
 - What problem does it solve?
 - Who benefits?
-- Is it visible functionality or infrastructure?
+- Is it a visible functionality or infrastructure?
 - Is it related to any existing feature?
-- Which repositories need to be modified?
+- Which repositories need modification?
 
 **For Bugs**:
 - Where does the bug occur? (repository, component, flow)
 - How to reproduce?
-- What is the expected vs actual behavior?
-- Impact severity?
+- Expected vs current behavior?
+- Severity of impact?
 
 **For Improvements**:
-- What is working but can improve?
-- Which metric do we want to impact?
-- Is it technical or business optimization?
+- What is working but can be improved?
+- What metric do we want to impact?
+- Is it a technical or business optimization?
 
 ---
 
@@ -147,10 +171,10 @@ Just make sure the idea is **adequately understood**.
 
 ## 🎯 Next Step
 
-After approval and issue saving:
+After approval and saving the issue:
 
 ```bash
 /refine [ISSUE-ID]
 ```
 
-This command will transform the collected issue into refined and validated requirements.
+This command will transform the collected issue into refined and validated requirements.

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

@@ -1,6 +1,6 @@
 # Requirements Refinement
 
-You are a product expert responsible for helping to refine requirements for the project.
+You are a product expert tasked with helping to refine requirements for the project.
 
 ## ⚠️ IMPORTANT: This Command DOES NOT Implement Code
 
@@ -31,7 +31,7 @@ Read the initial requirement and ask questions to achieve full clarity about:
 - **Scope**: What is included and what is NOT included?
 - **Interactions**: Which existing features/components are affected?
 
-Keep asking questions until you have full understanding.
+Keep asking questions until you have complete understanding.
 
 ### 2. Validation Against Metaspecs
 
@@ -39,7 +39,7 @@ Keep asking questions until you have full understanding.
 
 **Validation Process**:
 
-1. **Consult the indexes loaded** by `/warm-up`:
+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`
@@ -61,7 +61,7 @@ Keep asking questions until you have full understanding.
    - ✅ Follows existing business rules
    - ⚠️ Identify conflicts or violations
 
-**If violations are identified**: 🛑 **STOP** and ask the user for clarification before proceeding (Jidoka Principle).
+**If you identify violations**: 🛑 **STOP** and ask the user for clarification before proceeding (Jidoka Principle).
 
 ### 3. Summary and Approval Phase
 
@@ -69,13 +69,42 @@ Once you have gathered sufficient information and validated against metaspecs, p
 - **Feature**: Feature name
 - **Objective**: Why build it (1-2 sentences)
 - **Business Value**: Metric, persona, roadmap phase (consult metaspecs)
-- **Scope**: What INCLUDES and what DOES NOT INCLUDE
+- **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 research the codebase or internet before finalizing, if needed.
+**Tip**: You may search the codebase or internet before finalizing, if needed.
 
 ### 4. Saving the Refined Requirements
 
@@ -88,7 +117,7 @@ Once the user approves, save the requirements:
 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 (complete backup)
+   - 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
@@ -96,8 +125,8 @@ Once the user approves, save the 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
-     - **IMPORTANT**: Create a SUMMARY version (max 3000 words) to avoid API limits
-     - Include link to local file at the end: "Full document: `.sessions/<ISSUE-ID>/refined.md`"
+     - 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**:
@@ -106,7 +135,7 @@ Once the user approves, save the requirements:
 
 **Output Template**:
 
-**IMPORTANT**: The default template for refined requirements may be documented in the metaspecs repository. Check `{base_path}/{metaspecs-id}/specs/refined/` or similar.
+**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
@@ -115,18 +144,18 @@ Once the user approves, save the requirements:
 - **🔧 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 goals, enablers, mitigated risks
+- **🔄 Product Impact**: Alignment with objectives, enablers, mitigated risks
 - **⚠️ Known Limitations**: MVP limitations
 - **📝 Implementation Checklist**: Tasks by area (backend, frontend, testing, security, etc.)
 
-**SUMMARY Template** (for task manager - max 3000 words):
+**Task Manager Template**:
 ```markdown
 # [Feature Name] - Refined Requirements
 
 **Sprint X** | **Y days** | **Priority**
 
 ## Objective
-[1-2 paragraphs: what it is and why do it]
+[1-2 paragraphs: what it is and why]
 
 ## Scope
 
@@ -146,7 +175,7 @@ Once the user approves, save the requirements:
 ❌ [item 1] ❌ [item 2] ❌ [item 3]
 
 ## Stack
-[Tech stack summarized by area]
+[Tech stack summary by area]
 
 ## Structure
 [SUMMARIZED file tree - main modules only]