siesa-agents 2.1.87 → 2.1.89
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/claude/skills/sa-delivery-guides/SKILL.md +165 -87
- package/package.json +1 -1
- package/siesa-agents/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md +6 -4
- package/siesa-agents/bmm/workflows/3-solutioning/create-epics-and-stories/workflow_ext.md +27 -26
- package/siesa-agents/core/tasks/shard-doc.md +17 -14
- package/siesa-agents/resources/conventions/epic-story-naming-convention.md +130 -0
|
@@ -1,143 +1,221 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sa-delivery-guides
|
|
3
|
-
description:
|
|
3
|
+
description: Consolidate the per-feature user-guide documents indexed in the mcp-siesa-docs MCP into ONE coherent, end-user friendly guide per project — a folder of linked Spanish markdown files with a central index. Use this skill when a delivery team member needs to turn the scattered per-feature user guides of a project into a single navigable end-user manual. Always trigger on /sa-delivery-guides. Also trigger when the user says "generar guía de entrega", "consolidar guías de usuario", "guía para el cliente", "documentación de entrega para [project]", "guía consolidada de usuario final", "guía para usuario final", or describes wanting to merge the indexed per-feature user guides into one coherent manual a non-technical client can read.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
# Delivery Agent Guides
|
|
6
|
+
# Delivery Agent Guides — Consolidador
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Toma las guías de usuario **por feature** de un proyecto (que viven en el RAG y se consultan vía el MCP `mcp-siesa-docs`) y produce **una guía de usuario final consolidada y coherente**: una **carpeta con el nombre del proyecto** que contiene varios archivos Markdown enlazados entre sí y un `index.md` central que actúa como tabla de contenidos.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
El resultado **no** es un solo documento gigante ni una copia 1:1 de cada feature. Es un manual **sintetizado**: se agrupan features afines en capítulos temáticos, se unifican los conceptos repetidos (acceso, navegación, glosario, FAQ) y se redacta una narrativa continua en español, para usuario final no técnico.
|
|
11
|
+
|
|
12
|
+
**El MCP es la única fuente de contenido. No se escanea el sistema de archivos local.**
|
|
11
13
|
|
|
12
14
|
---
|
|
13
15
|
|
|
14
|
-
##
|
|
16
|
+
## Herramientas del MCP disponibles (úsalas tal cual)
|
|
17
|
+
|
|
18
|
+
El servidor `mcp-siesa-docs` expone **solo tres** herramientas. **No existe `get_document`** — no la llames.
|
|
19
|
+
|
|
20
|
+
- `list_collections()` → inventario de colecciones. La colección indexada es **`siesa-docs`** (el nombre `mcp-siesa-docs` es el del servidor, no el de la colección).
|
|
21
|
+
- `list_projects()` → proyectos indexados con banderas `has_user_guide`, `has_technical_knowledge` y `document_count`. **Esta es la fuente para saber qué proyectos tienen guías de usuario.**
|
|
22
|
+
- `search_docs({ query, top_k, filter })` → recuperación híbrida que devuelve **chunks** relevantes (máx. `top_k` = 50). `filter` es un diccionario opcional de pares string→string (p. ej. `{ "project": "<proyecto>" }`).
|
|
15
23
|
|
|
16
|
-
|
|
24
|
+
> ⚠️ Como no hay `get_document`, el contenido de cada guía se reconstruye **a partir de chunks** vía `search_docs`. Por eso se hacen varias búsquedas temáticas con `top_k` alto, en vez de una sola.
|
|
25
|
+
|
|
26
|
+
---
|
|
17
27
|
|
|
18
|
-
|
|
28
|
+
## Flujo
|
|
19
29
|
|
|
20
|
-
1
|
|
21
|
-
2. Call `search_docs("user guide proyectos disponibles")` to find projects whose indexed docs include a `user-guide` directory.
|
|
22
|
-
3. Build the candidate list: **only include projects that have at least one document in their `user-guide` directory**. Projects with only feature specs, épicas, stories, or architecture docs are excluded (Option A).
|
|
23
|
-
4. Present the list to the user:
|
|
24
|
-
```
|
|
25
|
-
Proyectos con guías de usuario disponibles:
|
|
26
|
-
[1] {project-name-1}
|
|
27
|
-
[2] {project-name-2}
|
|
28
|
-
...
|
|
30
|
+
### Paso 1: Descubrir proyectos con guías de usuario (automático)
|
|
29
31
|
|
|
30
|
-
|
|
31
|
-
```
|
|
32
|
-
5. The user replies with a number or project name.
|
|
32
|
+
Apenas se invoca la skill, sin preguntar primero:
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
1. **Saluda con un mensaje de bienvenida** antes de cualquier llamada técnica. Una sola frase cálida y no técnica, p. ej.:
|
|
35
|
+
> 👋 Bienvenido al generador de Guías de Usuario de Siesa. Voy a consultar los proyectos disponibles y te dejaré elegir uno para construir su manual de usuario final.
|
|
36
|
+
|
|
37
|
+
No narres las llamadas al MCP ("voy a cargar las herramientas", "llamando a list_collections…"). Mantén el tono de cara al usuario: limpio y orientado a negocio.
|
|
38
|
+
2. `list_collections()` para confirmar que **`siesa-docs`** está disponible.
|
|
39
|
+
3. `list_projects()` y filtra los que tengan **`has_user_guide: true`**.
|
|
40
|
+
4. Presenta los proyectos usando la herramienta **`AskUserQuestion`** (menú con selección por flechas, el usuario no escribe su opción):
|
|
41
|
+
- `header`: "Proyecto"
|
|
42
|
+
- `question`: "¿Para cuál proyecto quieres generar la guía consolidada de usuario final?"
|
|
43
|
+
- `options`: una por cada proyecto con `has_user_guide: true`. El `label` es **solo el nombre del proyecto** (sin conteos ni datos técnicos). El `description` puede ser una frase breve y no técnica (p. ej. "Guía de usuario final del sistema {proyecto}").
|
|
44
|
+
- `multiSelect`: false
|
|
45
|
+
- **Nunca** muestres el número de fragmentos ni `document_count` — es un dato técnico que no le interesa al usuario.
|
|
46
|
+
5. Toma la respuesta del menú como el proyecto seleccionado.
|
|
47
|
+
|
|
48
|
+
Si ninguno califica, dilo claramente ("No encontré proyectos con guías de usuario indexadas en el MCP") y detente (no presentes el menú).
|
|
35
49
|
|
|
36
50
|
---
|
|
37
51
|
|
|
38
|
-
###
|
|
52
|
+
### Paso 2: Mapear las guías por feature del proyecto
|
|
39
53
|
|
|
40
|
-
|
|
41
|
-
2. For each result, call `get_document(path)` to fetch the full content.
|
|
42
|
-
3. **Strict filter**: process only documents whose `path` is inside the project's `user-guide` directory. Ignore feature specs, épicas, stories, architecture, or any other technical doc, even if they show up in results.
|
|
54
|
+
Objetivo: saber qué features/áreas cubre el proyecto, recuperando los chunks de sus guías de usuario.
|
|
43
55
|
|
|
44
|
-
|
|
56
|
+
1. Lanza un barrido de `search_docs` con `filter: { "project": "<proyecto>" }` y `top_k: 50`. Usa varias consultas amplias en español para maximizar cobertura, por ejemplo:
|
|
57
|
+
- `"guía de usuario funcionalidades del sistema"`
|
|
58
|
+
- `"cómo se usa pasos flujos de trabajo"`
|
|
59
|
+
- `"preguntas frecuentes y solución de problemas"`
|
|
60
|
+
2. De los resultados, quédate **solo con chunks de guías de usuario** (su `path`/origen está bajo `user-guide/`). Ignora chunks de specs técnicas, arquitectura, stories o épicas aunque aparezcan.
|
|
61
|
+
3. Construye la lista de **features/áreas** detectadas (agrupa los chunks por su documento/feature de origen). Conserva los `path` de origen — los citarás al final.
|
|
62
|
+
|
|
63
|
+
Si el barrido devuelve muy pocos chunks, repite con consultas más específicas por nombre de feature detectado.
|
|
45
64
|
|
|
46
65
|
---
|
|
47
66
|
|
|
48
|
-
###
|
|
67
|
+
### Paso 3: Diseñar la estructura del manual (capítulos)
|
|
49
68
|
|
|
50
|
-
|
|
69
|
+
Aplica una arquitectura de información orientada a la **necesidad del usuario** (Diátaxis simplificado), no un archivo por feature suelto:
|
|
51
70
|
|
|
52
|
-
**
|
|
53
|
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
71
|
+
1. **Agrupa las features afines en capítulos temáticos.** Ejemplo (ilustrativo, depende del proyecto): "Suscripciones y planes", "Saldos y consumo", "Facturación y pagos", "Portal y notificaciones".
|
|
72
|
+
2. Define el conjunto de archivos a crear. Estructura recomendada (ajústala al tamaño real del proyecto):
|
|
73
|
+
- `index.md` — portada + tabla de contenidos enlazada
|
|
74
|
+
- `01-introduccion.md` — qué es el sistema y para qué sirve
|
|
75
|
+
- `02-primeros-pasos.md` — acceso, primer ingreso, navegación general
|
|
76
|
+
- `03-{area-1}.md`, `04-{area-2}.md`, … — un archivo por capítulo temático
|
|
77
|
+
- `NN-solucion-de-problemas.md`
|
|
78
|
+
- `NN-preguntas-frecuentes.md`
|
|
79
|
+
- `NN-glosario.md`
|
|
80
|
+
3. **Mantén la cantidad de archivos manejable**: agrupa, no generes un archivo por cada feature. Si dos features son pequeñas y relacionadas, van en el mismo capítulo.
|
|
81
|
+
4. Muestra al usuario el plan de capítulos propuesto **en una línea por archivo** y continúa (no requiere aprobación explícita salvo que el usuario quiera ajustar).
|
|
58
82
|
|
|
59
|
-
**
|
|
60
|
-
- Mermaid diagrams → rewrite as one or two plain sentences describing the flow. Never emit Mermaid syntax.
|
|
83
|
+
> ❌ **Nunca** generes un único archivo monolítico (`delivery-guide.md`) con todo el contenido. El entregable es **siempre** la carpeta con varios archivos enlazados. Un solo documento gigante es justo el comportamiento a evitar.
|
|
61
84
|
|
|
62
|
-
|
|
63
|
-
- `📸 [Screenshot: ...]` placeholders
|
|
64
|
-
- `[Source: FX Story Y.Z]` traceability references
|
|
65
|
-
- Screenshot index tables
|
|
66
|
-
- Implementation component names (ContactManager, EmptyState, ErrorPanel, etc.) — describe the behavior instead
|
|
67
|
-
- `*Generado: ...` footers
|
|
85
|
+
---
|
|
68
86
|
|
|
69
|
-
|
|
87
|
+
### Paso 4: Generar los archivos del manual
|
|
70
88
|
|
|
89
|
+
Para **cada capítulo temático**, antes de redactar, recupera su contenido con `search_docs` enfocado (consulta con el nombre del área/feature, `filter` del proyecto, `top_k` alto). Luego escribe el archivo `.md` en español, con contenido **coherente y sintetizado** (no copiado por feature).
|
|
90
|
+
|
|
91
|
+
**Contenido a conservar y reescribir en lenguaje sencillo:**
|
|
92
|
+
- Nombre y propósito de cada funcionalidad
|
|
93
|
+
- Flujos paso a paso
|
|
94
|
+
- Conceptos clave y definiciones (simplificadas)
|
|
95
|
+
- Solución de problemas y FAQ
|
|
96
|
+
- Advertencias (⚠️) — reformula sin detalle técnico; conserva la implicación práctica
|
|
97
|
+
|
|
98
|
+
**Contenido a transformar:**
|
|
99
|
+
- Diagramas Mermaid → reescríbelos como una o dos frases que describan el flujo. **Nunca emitas sintaxis Mermaid.**
|
|
100
|
+
|
|
101
|
+
**Contenido a omitir:**
|
|
102
|
+
- Placeholders `📸 [Screenshot: ...]`
|
|
103
|
+
- Referencias de trazabilidad `[Source: FX Story Y.Z]`
|
|
104
|
+
- Tablas de índice de capturas
|
|
105
|
+
- Nombres de componentes de implementación (ContactManager, EmptyState, ErrorPanel, etc.) — describe el comportamiento
|
|
106
|
+
- Pies `*Generado: ...`
|
|
107
|
+
|
|
108
|
+
**Coherencia entre archivos (clave de la consolidación):**
|
|
109
|
+
- Los conceptos y términos repetidos en varias features se explican **una sola vez** (en `01-introduccion.md` o en `glosario.md`) y los capítulos los referencian con un enlace relativo.
|
|
110
|
+
- El acceso/login/navegación va **una vez** en `02-primeros-pasos.md`, no en cada capítulo.
|
|
111
|
+
- FAQ y Solución de Problemas se **fusionan** de todas las features en sus archivos únicos, sin repetir preguntas.
|
|
112
|
+
- Cada archivo enlaza al anterior/siguiente y de vuelta al `index.md` con enlaces relativos Markdown.
|
|
113
|
+
|
|
114
|
+
**Plantilla de un archivo de capítulo:**
|
|
71
115
|
```markdown
|
|
72
116
|
---
|
|
73
|
-
project: {
|
|
117
|
+
project: {proyecto}
|
|
118
|
+
chapter: {nombre del capítulo}
|
|
74
119
|
generated_date: {YYYY-MM-DD}
|
|
120
|
+
audience: Usuario final no técnico
|
|
75
121
|
sources:
|
|
76
122
|
- {mcp-path-1}
|
|
77
123
|
- {mcp-path-2}
|
|
78
|
-
audience: Usuario final no técnico
|
|
79
124
|
---
|
|
80
125
|
|
|
81
|
-
|
|
126
|
+
[⬅️ Índice](index.md)
|
|
82
127
|
|
|
83
|
-
|
|
84
|
-
2-3 sentences. What the app does and who it is for. No technical terms.
|
|
128
|
+
# {Nombre del Capítulo}
|
|
85
129
|
|
|
86
|
-
##
|
|
87
|
-
What problems it solves, from the user's perspective.
|
|
88
|
-
|
|
89
|
-
---
|
|
90
|
-
|
|
91
|
-
## {Feature 1}
|
|
130
|
+
## {Funcionalidad 1}
|
|
92
131
|
|
|
93
132
|
### ¿Qué es?
|
|
94
|
-
|
|
133
|
+
Un párrafo. Descripción simple.
|
|
95
134
|
|
|
96
135
|
### ¿Para qué sirve?
|
|
97
|
-
|
|
136
|
+
El beneficio práctico para el usuario.
|
|
98
137
|
|
|
99
138
|
### ¿Cómo se usa?
|
|
100
|
-
|
|
101
|
-
|
|
139
|
+
Pasos numerados. Una acción clara por paso.
|
|
140
|
+
Incluye advertencias en línea (⚠️ ...) justo antes del paso que puede causar un problema.
|
|
102
141
|
|
|
103
|
-
|
|
142
|
+
## {Funcionalidad 2}
|
|
143
|
+
(misma estructura)
|
|
104
144
|
|
|
105
|
-
|
|
106
|
-
(
|
|
145
|
+
---
|
|
146
|
+
[⬅️ Anterior]({archivo-anterior}.md) · [Índice](index.md) · [Siguiente ➡️]({archivo-siguiente}.md)
|
|
147
|
+
```
|
|
107
148
|
|
|
149
|
+
**Plantilla de `index.md`:**
|
|
150
|
+
```markdown
|
|
151
|
+
---
|
|
152
|
+
project: {proyecto}
|
|
153
|
+
generated_date: {YYYY-MM-DD}
|
|
154
|
+
audience: Usuario final no técnico
|
|
155
|
+
type: indice-consolidado
|
|
156
|
+
sources:
|
|
157
|
+
- {mcp-path-1}
|
|
158
|
+
- {mcp-path-2}
|
|
108
159
|
---
|
|
109
160
|
|
|
110
|
-
|
|
111
|
-
Plain Q&A: "¿Qué hago si...? → ..."
|
|
161
|
+
# Guía de Usuario de {Proyecto}
|
|
112
162
|
|
|
113
|
-
|
|
114
|
-
|
|
163
|
+
Manual de usuario final. Esta guía reúne, de forma coherente, toda la documentación de uso del sistema.
|
|
164
|
+
|
|
165
|
+
## ¿Qué es {Proyecto}?
|
|
166
|
+
2-3 frases. Qué hace y para quién es. Sin términos técnicos.
|
|
167
|
+
|
|
168
|
+
## Contenido
|
|
169
|
+
|
|
170
|
+
1. [Introducción](01-introduccion.md)
|
|
171
|
+
2. [Primeros Pasos](02-primeros-pasos.md)
|
|
172
|
+
3. [{Capítulo temático 1}](03-{area-1}.md)
|
|
173
|
+
4. [{Capítulo temático 2}](04-{area-2}.md)
|
|
174
|
+
...
|
|
175
|
+
N. [Solución de Problemas](NN-solucion-de-problemas.md)
|
|
176
|
+
N. [Preguntas Frecuentes](NN-preguntas-frecuentes.md)
|
|
177
|
+
N. [Glosario](NN-glosario.md)
|
|
115
178
|
```
|
|
116
179
|
|
|
117
|
-
**
|
|
118
|
-
-
|
|
119
|
-
-
|
|
120
|
-
-
|
|
121
|
-
-
|
|
180
|
+
**Guías de redacción:**
|
|
181
|
+
- Lector cómodo con un smartphone pero sin formación en software.
|
|
182
|
+
- Voz activa, instrucciones directas: "Haz clic en...", "Escribe...", "Selecciona..."
|
|
183
|
+
- Frases cortas. Si una frase necesita una coma para explicar un concepto técnico, reescríbela.
|
|
184
|
+
- Si un concepto no aporta valor práctico al usuario final, elimínalo.
|
|
122
185
|
|
|
123
186
|
---
|
|
124
187
|
|
|
125
|
-
###
|
|
188
|
+
### Paso 5: Guardar y confirmar
|
|
126
189
|
|
|
127
|
-
|
|
190
|
+
Guarda todo en la carpeta del proyecto:
|
|
128
191
|
```
|
|
129
|
-
_bmad-output/documentation-artifacts/delivery-guides/{
|
|
192
|
+
_bmad-output/documentation-artifacts/delivery-guides/{proyecto}/
|
|
193
|
+
├── index.md
|
|
194
|
+
├── 01-introduccion.md
|
|
195
|
+
├── 02-primeros-pasos.md
|
|
196
|
+
├── 03-{area-1}.md
|
|
197
|
+
├── ...
|
|
198
|
+
├── NN-solucion-de-problemas.md
|
|
199
|
+
├── NN-preguntas-frecuentes.md
|
|
200
|
+
└── NN-glosario.md
|
|
130
201
|
```
|
|
131
202
|
|
|
132
|
-
|
|
203
|
+
Crea la carpeta si no existe.
|
|
133
204
|
|
|
134
|
-
|
|
205
|
+
Luego confirma:
|
|
135
206
|
```
|
|
136
|
-
Guía guardada en: _bmad-output/documentation-artifacts/delivery-guides/{
|
|
207
|
+
Guía consolidada guardada en: _bmad-output/documentation-artifacts/delivery-guides/{proyecto}/
|
|
208
|
+
|
|
209
|
+
Archivos generados:
|
|
210
|
+
- index.md
|
|
211
|
+
- 01-introduccion.md
|
|
212
|
+
- 02-primeros-pasos.md
|
|
213
|
+
- {capítulos...}
|
|
214
|
+
- NN-glosario.md
|
|
137
215
|
|
|
138
|
-
|
|
139
|
-
- {
|
|
140
|
-
- {
|
|
216
|
+
Capítulos / features incluidos:
|
|
217
|
+
- {capítulo 1}: {features que agrupa}
|
|
218
|
+
- {capítulo 2}: {features que agrupa}
|
|
141
219
|
|
|
142
220
|
Fuentes del MCP:
|
|
143
221
|
- {mcp-path-1}
|
|
@@ -146,17 +224,17 @@ Fuentes del MCP:
|
|
|
146
224
|
|
|
147
225
|
---
|
|
148
226
|
|
|
149
|
-
##
|
|
227
|
+
## Referencia de Transformación
|
|
150
228
|
|
|
151
|
-
|
|
|
229
|
+
| Elemento técnico | Tratamiento en la guía |
|
|
152
230
|
|---|---|
|
|
153
231
|
| `deep linking` / URL única por registro | "Cada registro tiene su propia dirección web que puedes guardar o compartir" |
|
|
154
|
-
| `ContactManager`, `EmptyState`, `ErrorPanel` |
|
|
155
|
-
| `NIT/RUC` |
|
|
156
|
-
| `Toast`
|
|
157
|
-
| Reintentar
|
|
232
|
+
| `ContactManager`, `EmptyState`, `ErrorPanel` | Quita el nombre; describe lo que el usuario ve |
|
|
233
|
+
| `NIT/RUC` | Consérvalo — explícalo una vez: "número de identificación tributaria (NIT/RUC)" |
|
|
234
|
+
| Notificación `Toast` | "mensaje de confirmación que aparece brevemente en pantalla" |
|
|
235
|
+
| Botón Reintentar ante error | "si aparece un error, haz clic en Reintentar" |
|
|
158
236
|
| Panel de dos columnas | "La pantalla se divide en dos partes: a la izquierda la lista, a la derecha el detalle" |
|
|
159
237
|
| Validación inline | "mensajes de error junto al campo que necesita corrección" |
|
|
160
|
-
|
|
|
161
|
-
| `[Source: FX Story Y.Z]` |
|
|
162
|
-
| `📸 [Screenshot: ...]` |
|
|
238
|
+
| Bloque de código Mermaid | Una o dos frases que describan el flujo |
|
|
239
|
+
| `[Source: FX Story Y.Z]` | Omitir |
|
|
240
|
+
| `📸 [Screenshot: ...]` | Omitir |
|
package/package.json
CHANGED
|
@@ -16,9 +16,9 @@ Add the following block inside each Epic section, **after the Epic goal statemen
|
|
|
16
16
|
These criteria validate the COMPLETE epic functionality.
|
|
17
17
|
-->
|
|
18
18
|
|
|
19
|
-
- [ ] **AC-E{{
|
|
20
|
-
- [ ] **AC-E{{
|
|
21
|
-
- [ ] **AC-E{{
|
|
19
|
+
- [ ] **AC-E{{NNN}}-{{E}}.1:** {{high_level_criterion_1}}
|
|
20
|
+
- [ ] **AC-E{{NNN}}-{{E}}.2:** {{high_level_criterion_2}}
|
|
21
|
+
- [ ] **AC-E{{NNN}}-{{E}}.3:** {{high_level_criterion_3}}
|
|
22
22
|
|
|
23
23
|
**FRs covered:** {{epic_frs}}
|
|
24
24
|
```
|
|
@@ -41,6 +41,8 @@ Add the following block inside each Epic section, **after the Epic goal statemen
|
|
|
41
41
|
|
|
42
42
|
## Numbering Convention
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
Epic and story IDs follow the centralized convention in `@_siesa-agents/resources/conventions/epic-story-naming-convention.md`.
|
|
45
|
+
|
|
46
|
+
- Epic `{NNN}-{E}` → criteria are `AC-E{NNN}-{E}.1`, `AC-E{NNN}-{E}.2`, `AC-E{NNN}-{E}.3` (e.g., Epic 16-1 → `AC-E16-1.1`)
|
|
45
47
|
- Minimum 3, maximum 5 criteria per epic
|
|
46
48
|
- Each criterion must map to at least one story within the epic
|
|
@@ -52,27 +52,26 @@ Una vez confirmada la lista de features, inyectar las siguientes reglas de estru
|
|
|
52
52
|
|
|
53
53
|
### Reglas de estructura para el documento `epics.md`:
|
|
54
54
|
|
|
55
|
+
> **Convención de IDs (OBLIGATORIA):** Los IDs de épicas e historias siguen la convención centralizada definida en `@_siesa-agents/resources/conventions/epic-story-naming-convention.md`. Formato: épicas `{NNN}-{E}`, historias `{NNN}-{E}.{HH}`, donde `NNN` es el número del feature (sin ceros a la izquierda, tomado del PRD/shard `feat-{NNN}-*`).
|
|
56
|
+
|
|
55
57
|
1. **Agrupación por Feature**: Cada feature confirmado será un heading `##` en el documento. Las épicas de ese feature van DENTRO como `###`. Las stories van como `####`.
|
|
56
58
|
|
|
57
59
|
2. **Jerarquía de headings obligatoria**:
|
|
58
60
|
- `## {Feature Name}` — agrupa las épicas de un feature
|
|
59
|
-
- `### Epic {
|
|
60
|
-
- `#### Story {
|
|
61
|
+
- `### Epic {NNN}-{E}: {Title}` — cada épica dentro del feature (ej: `### Epic 16-1: ...`)
|
|
62
|
+
- `#### Story {NNN}-{E}.{HH}: {Title}` — cada story dentro de la épica (ej: `#### Story 16-1.01: ...`)
|
|
61
63
|
|
|
62
64
|
Nota: La generación del documento de epicas no se realiza por DOMINIO sino por FEATURE.
|
|
63
65
|
|
|
64
|
-
3. **Numeración de épicas
|
|
66
|
+
3. **Numeración de épicas POR FEATURE con prefijo de feature**: El número de épica (`E`) es secuencial DENTRO de cada feature, comenzando en `1`. El prefijo `{NNN}-` garantiza la unicidad global del ID. Ejemplo (feature 16 y feature 17):
|
|
65
67
|
```
|
|
66
|
-
## Measurement Units
|
|
67
|
-
### Epic 1: ...
|
|
68
|
-
### Epic 2: ...
|
|
69
|
-
|
|
70
|
-
## Cost Models
|
|
71
|
-
### Epic 3: ... ← continúa desde 3, NO reinicia en 1
|
|
72
|
-
### Epic 4: ...
|
|
68
|
+
## Measurement Units ← feat-016
|
|
69
|
+
### Epic 16-1: ...
|
|
70
|
+
### Epic 16-2: ...
|
|
73
71
|
|
|
74
|
-
##
|
|
75
|
-
### Epic
|
|
72
|
+
## Cost Models ← feat-017
|
|
73
|
+
### Epic 17-1: ... ← reinicia en 1, el prefijo 17- lo hace único
|
|
74
|
+
### Epic 17-2: ...
|
|
76
75
|
```
|
|
77
76
|
|
|
78
77
|
4. **Secciones generales** (`## Overview`, `## Requirements Inventory`, etc.) permanecen igual que en el template estándar, al nivel `##`.
|
|
@@ -82,16 +81,16 @@ Una vez confirmada la lista de features, inyectar las siguientes reglas de estru
|
|
|
82
81
|
```
|
|
83
82
|
## Epic List
|
|
84
83
|
|
|
85
|
-
### {Feature Name 1}
|
|
86
|
-
- Epic 1: [Title] — FRs: FR1, FR2
|
|
87
|
-
- Epic 2: [Title] — FRs: FR3
|
|
84
|
+
### {Feature Name 1} ← feat-016
|
|
85
|
+
- Epic 16-1: [Title] — FRs: FR1, FR2
|
|
86
|
+
- Epic 16-2: [Title] — FRs: FR3
|
|
88
87
|
|
|
89
|
-
### {Feature Name 2}
|
|
90
|
-
- Epic
|
|
91
|
-
- Epic
|
|
88
|
+
### {Feature Name 2} ← feat-017
|
|
89
|
+
- Epic 17-1: [Title] — FRs: FR4, FR5
|
|
90
|
+
- Epic 17-2: [Title] — FRs: FR6
|
|
92
91
|
```
|
|
93
92
|
|
|
94
|
-
6. **Step 3 (Stories)**: Al generar épicas y stories, escribir cada feature como sección `##`, con sus épicas como `###` y stories como `####`. La numeración de stories sigue el patrón `{
|
|
93
|
+
6. **Step 3 (Stories)**: Al generar épicas y stories, escribir cada feature como sección `##`, con sus épicas como `###` y stories como `####`. La numeración de stories sigue el patrón `{NNN}-{E}.{HH}` con `HH` de dos dígitos (ej: Story 16-3.01, Story 16-3.02 para Epic 16-3).
|
|
95
94
|
|
|
96
95
|
7. **Marcador `FEATURE_CODE_JIRA`**: Cada archivo shard de épica debe comenzar con la siguiente línea como **primera línea del archivo**, antes de cualquier heading:
|
|
97
96
|
```
|
|
@@ -159,11 +158,13 @@ For EACH epic, after the goal statement, add **3-5 high-level Acceptance Criteri
|
|
|
159
158
|
|
|
160
159
|
```markdown
|
|
161
160
|
#### Acceptance Criteria (QA Validation)
|
|
162
|
-
- [ ] **AC-E{
|
|
163
|
-
- [ ] **AC-E{
|
|
164
|
-
- [ ] **AC-E{
|
|
161
|
+
- [ ] **AC-E{NNN}-{E}.1:** [High-level criterion from user perspective]
|
|
162
|
+
- [ ] **AC-E{NNN}-{E}.2:** [High-level criterion from user perspective]
|
|
163
|
+
- [ ] **AC-E{NNN}-{E}.3:** [High-level criterion from user perspective]
|
|
165
164
|
```
|
|
166
165
|
|
|
166
|
+
Donde `{NNN}-{E}` es el ID de la épica según la convención centralizada (ej: `AC-E16-1.1`, `AC-E16-1.2`). Ver `@_siesa-agents/resources/conventions/epic-story-naming-convention.md`.
|
|
167
|
+
|
|
167
168
|
**🎯 WRITING GUIDELINES:**
|
|
168
169
|
|
|
169
170
|
✅ **DO (Business language, user perspective):**
|
|
@@ -190,10 +191,10 @@ Template reference: `@_siesa-agents/bmm/workflows/3-solutioning/create-epics-and
|
|
|
190
191
|
After all epics and stories are generated, validate that every Epic AC has at least one supporting story:
|
|
191
192
|
|
|
192
193
|
```
|
|
193
|
-
Epic
|
|
194
|
-
├── AC-
|
|
195
|
-
├── AC-
|
|
196
|
-
└── AC-
|
|
194
|
+
Epic 16-1: [Title]
|
|
195
|
+
├── AC-E16-1.1: [Criterion] → Supported by: Story 16-1.01, Story 16-1.02
|
|
196
|
+
├── AC-E16-1.2: [Criterion] → Supported by: Story 16-1.03
|
|
197
|
+
└── AC-E16-1.3: [Criterion] → Supported by: Story 16-1.01, Story 16-1.04
|
|
197
198
|
```
|
|
198
199
|
|
|
199
200
|
**🚨 VALIDATION RULES:**
|
|
@@ -24,7 +24,7 @@ The agent determines the sharding mode by analyzing the document content:
|
|
|
24
24
|
| Signal | Detected Mode |
|
|
25
25
|
|--------|--------------|
|
|
26
26
|
| Contains `### feature —` or `### feature -` headings | **PRD Mode** |
|
|
27
|
-
| Contains
|
|
27
|
+
| Contains `### Epic` headings with story subsections (`#### Story`) | **Epic Mode** |
|
|
28
28
|
| Neither detected | **Generic Mode** (standard `##` level sharding) |
|
|
29
29
|
|
|
30
30
|
The agent MUST confirm the detected mode with the user before proceeding.
|
|
@@ -119,32 +119,34 @@ Section Map (PRD Mode):
|
|
|
119
119
|
|
|
120
120
|
## Mode 2: Epic Sharding
|
|
121
121
|
|
|
122
|
+
> **Epic/Story ID convention (MANDATORY):** Epic and story IDs follow the centralized convention defined in `@_siesa-agents/resources/conventions/epic-story-naming-convention.md`: epics `{NNN}-{E}`, stories `{NNN}-{E}.{HH}` (e.g., `Epic 16-1`, `Story 16-1.01`). Sharding MUST preserve these IDs as-is in the shard content and use them in the index.
|
|
123
|
+
|
|
122
124
|
### When It Applies
|
|
123
125
|
|
|
124
126
|
The source document is an epics breakdown organized by feature, where each feature groups its epics under a `##` heading:
|
|
125
127
|
|
|
126
128
|
```markdown
|
|
127
|
-
# Project Name - Epic Breakdown
|
|
129
|
+
# feat-016 — Project Name - Epic Breakdown
|
|
128
130
|
|
|
129
131
|
## Overview
|
|
130
132
|
...
|
|
131
133
|
|
|
132
134
|
## Measurement Units
|
|
133
135
|
|
|
134
|
-
### Epic 1: Core Entity & CRUD API
|
|
135
|
-
#### Story 1.
|
|
136
|
+
### Epic 16-1: Core Entity & CRUD API
|
|
137
|
+
#### Story 16-1.01: Domain Entity & Database Schema
|
|
136
138
|
...
|
|
137
|
-
#### Story 1.
|
|
139
|
+
#### Story 16-1.02: API Setup & Secure Create Endpoint
|
|
138
140
|
...
|
|
139
141
|
|
|
140
|
-
### Epic 2: Business Rules & Integrity
|
|
141
|
-
#### Story 2.
|
|
142
|
+
### Epic 16-2: Business Rules & Integrity
|
|
143
|
+
#### Story 16-2.01: Usage Detection Service
|
|
142
144
|
...
|
|
143
145
|
|
|
144
146
|
## Cost Models
|
|
145
147
|
|
|
146
|
-
### Epic
|
|
147
|
-
#### Story
|
|
148
|
+
### Epic 16-3: Entity & Creation API
|
|
149
|
+
#### Story 16-3.01: Database & Entity Infrastructure
|
|
148
150
|
...
|
|
149
151
|
```
|
|
150
152
|
|
|
@@ -152,9 +154,10 @@ The source document is an epics breakdown organized by feature, where each featu
|
|
|
152
154
|
|
|
153
155
|
Before generating filenames, the agent MUST resolve the feature number (`NNN`) by following this priority order:
|
|
154
156
|
|
|
155
|
-
1. **
|
|
156
|
-
2. **
|
|
157
|
-
3. **
|
|
157
|
+
1. **Epic ID prefix**: If the epic headings already follow the centralized convention (`### Epic {NNN}-{E}: ...`, e.g., `### Epic 16-1:`), take `NNN` directly from the epic IDs. If different `##` sections carry different `NNN` prefixes (multi-feature document), resolve `NNN` **per section** from its own epic IDs.
|
|
158
|
+
2. **Source filename pattern**: Look for `feat-{digits}` in the filename (e.g., `epics-feat-016-name.md` → `16`, `epic-feat-083.md` → `83`). Strip leading zeros.
|
|
159
|
+
3. **Document title**: Look for `feat-{digits}` in the first `#` heading (e.g., `# feat-016 — Proyecciones Financieros` → `16`).
|
|
160
|
+
4. **Not found**: Ask the user: *"¿Cuál es el número del feature (`NNN`) para este documento de épicas?"*
|
|
158
161
|
|
|
159
162
|
### Naming Convention
|
|
160
163
|
|
|
@@ -322,7 +325,7 @@ Intelligent Shard Complete ({MODE} Mode):
|
|
|
322
325
|
|
|
323
326
|
Applied to heading text to generate filenames:
|
|
324
327
|
|
|
325
|
-
1. Remove the prefix (`feature — `, `Epic
|
|
328
|
+
1. Remove the prefix (`feature — `, `Epic {NNN}-{E}:`, numbering like `1.`, `2.`, etc.)
|
|
326
329
|
2. Lowercase all text
|
|
327
330
|
3. Replace spaces with hyphens
|
|
328
331
|
4. Remove special characters: `&`, `,`, `(`, `)`, `/`, `'`, `"`, `:`, `;`
|
|
@@ -338,4 +341,4 @@ Applied to heading text to generate filenames:
|
|
|
338
341
|
3. **Mixed content before first subsection**: Include intro text in index.md
|
|
339
342
|
4. **Empty sections**: Skip sections with no content (heading only)
|
|
340
343
|
5. **Deep nesting**: Only shard at the detection level. Everything below stays inside the shard
|
|
341
|
-
6. **Epic feature number (`NNN`) not detectable**: If
|
|
344
|
+
6. **Epic feature number (`NNN`) not detectable**: If none of the detection sources (epic ID prefixes, filename, document title) yield a feature number, the agent MUST ask the user before proceeding — never assume or default to `0`.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# Convención de Nomenclatura para Épicas e Historias
|
|
2
|
+
|
|
3
|
+
> **Fuente centralizada.** Todo workflow, task o skill que genere, shardee o referencie épicas e historias DEBE seguir esta convención. Referenciar este archivo como:
|
|
4
|
+
> `@_siesa-agents/resources/conventions/epic-story-naming-convention.md`
|
|
5
|
+
|
|
6
|
+
## Objetivo
|
|
7
|
+
|
|
8
|
+
Definir un estándar de numeración que vincule cada épica e historia con su feature de origen, garantizando trazabilidad y unicidad global en todo el proyecto. Cada ID es auto-descriptivo: al leer `16-3.02` se sabe inmediatamente que pertenece al Feature 016, Épica 3, Historia 02.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 1. Formato de IDs
|
|
13
|
+
|
|
14
|
+
### Épicas
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
{NNN}-{E}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
| Componente | Descripción | Ejemplo |
|
|
21
|
+
|------------|-------------|---------|
|
|
22
|
+
| `NNN` | Número del feature (sin ceros a la izquierda) | `16` |
|
|
23
|
+
| `E` | Número secuencial de la épica dentro del feature | `1`, `48`, `56` |
|
|
24
|
+
|
|
25
|
+
**Ejemplos:** `16-1`, `16-48`, `83-1`
|
|
26
|
+
|
|
27
|
+
### Historias
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
{NNN}-{E}.{HH}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
| Componente | Descripción | Ejemplo |
|
|
34
|
+
|------------|-------------|---------|
|
|
35
|
+
| `NNN` | Número del feature (sin ceros a la izquierda) | `16` |
|
|
36
|
+
| `E` | Número de la épica dentro del feature | `1`, `48` |
|
|
37
|
+
| `HH` | Número secuencial de la historia (con cero a la izquierda si < 10) | `01`, `12` |
|
|
38
|
+
|
|
39
|
+
**Ejemplos:** `16-1.01`, `16-48.02`, `83-3.05`
|
|
40
|
+
|
|
41
|
+
### Acceptance Criteria de épica
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
AC-E{NNN}-{E}.{X}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**Ejemplos:** `AC-E16-49.1`, `AC-E16-56.5`
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 2. Ejemplo Visual Completo
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
feat-016 — Proyecciones Financieros Segmentos
|
|
55
|
+
|
|
56
|
+
Epic 16-1: Company Retrieval Feature
|
|
57
|
+
Historia 16-1.01: Establish Company Domain & Schema
|
|
58
|
+
Historia 16-1.02: List Companies Endpoint
|
|
59
|
+
Historia 16-1.03: Get & Search Endpoints
|
|
60
|
+
|
|
61
|
+
Epic 16-2: Operation Center Core Availability
|
|
62
|
+
Historia 16-2.01: Domain Entity & DB Schema
|
|
63
|
+
Historia 16-2.02: Read-Only Repository
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 3. Nombres de Archivo por Artefacto
|
|
69
|
+
|
|
70
|
+
| Artefacto | Ubicación | Patrón |
|
|
71
|
+
|-----------|-----------|--------|
|
|
72
|
+
| Épicas consolidadas (shard por feature) | `planning-artifacts/epics/` | `epic-feat-{NNN}-{slug}.md` |
|
|
73
|
+
| Stories | `implementation-artifacts/stories/` | `story-{NNN}-{E}.{HH}-{slug}.md` |
|
|
74
|
+
| Reviews | `implementation-artifacts/reviews/` | `review-{NNN}-{E}.{HH}-{slug}.md` |
|
|
75
|
+
|
|
76
|
+
**Ejemplos:**
|
|
77
|
+
- `epic-feat-16-measurement-units.md`
|
|
78
|
+
- `story-16-1.01-establish-company-domain-schema.md`
|
|
79
|
+
- `review-16-1.01-company-domain-schema.md`
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 4. Uso del ID en el Contenido
|
|
84
|
+
|
|
85
|
+
### Encabezados en el documento de épicas
|
|
86
|
+
|
|
87
|
+
```markdown
|
|
88
|
+
### Epic 16-1: Company Retrieval Feature
|
|
89
|
+
#### Story 16-1.01: Establish Company Domain & Schema
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Rangos de épicas (frontmatter, secciones, tablas)
|
|
93
|
+
|
|
94
|
+
```markdown
|
|
95
|
+
activeEpics: "16-49 to 16-56"
|
|
96
|
+
## §4.2 Accounting Infrastructure (Epics 16-1 – 16-4)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Título de una story individual
|
|
100
|
+
|
|
101
|
+
```markdown
|
|
102
|
+
# Story 16-1.01: Establish Company Domain & Schema
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### IDs en YAML (`sprint-status.yaml`)
|
|
106
|
+
|
|
107
|
+
```yaml
|
|
108
|
+
- id: "16-1" # épica — SIEMPRE entre comillas (contiene guión)
|
|
109
|
+
stories:
|
|
110
|
+
- id: "16-1.01"
|
|
111
|
+
file: "story-16-1.01-establish-company-domain-schema.md"
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Labels de Acceptance Criteria dentro de una story
|
|
115
|
+
|
|
116
|
+
```markdown
|
|
117
|
+
1. **Entity Definition:** ... [AC: 16-1.01.1]
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## 5. Reglas
|
|
123
|
+
|
|
124
|
+
1. **El número del feature (`NNN`) se toma del PRD** correspondiente (ej: `feat-016` → `16`, `feat-083` → `83`). Se escribe sin ceros a la izquierda en los IDs.
|
|
125
|
+
2. **La numeración de épicas (`E`) es secuencial dentro de cada feature**, comenzando en `1`. NO es un consecutivo global del documento: el prefijo `{NNN}-` garantiza la unicidad global.
|
|
126
|
+
3. **La numeración de historias (`HH`) es secuencial dentro de cada épica**, comenzando en `01` (con cero a la izquierda para valores < 10).
|
|
127
|
+
4. **No se reutilizan números** de épicas o historias eliminadas.
|
|
128
|
+
5. **Los IDs en YAML deben ir entre comillas** (`"16-1"`) ya que contienen guión.
|
|
129
|
+
6. **Las referencias posicionales internas** (`AC: 1, 2, 3` dentro de subtasks de la misma story) **no se modifican** — solo usan el formato completo las referencias con ID de épica/historia (`{NNN}-{E}` o `{NNN}-{E}.{HH}`).
|
|
130
|
+
7. **Consistencia total:** la convención aplica a todos los artefactos (épicas, stories, reviews, sprint-status, referencias cruzadas), no solo a archivos individuales.
|