siesa-agents 2.1.92 → 2.1.94

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.
Files changed (9) hide show
  1. package/claude/skills/sa-user-guide-builder/SKILL.md +6 -0
  2. package/package.json +1 -1
  3. package/siesa-agents/bmm/data/git-flow-siesa.md +95 -9
  4. package/siesa-agents/bmm/workflows/4-implementation/code-review/steps/step-07-commit-push.md +19 -7
  5. package/siesa-agents/sa/sa-user-guide-builder/SKILL.md +158 -0
  6. package/siesa-agents/sa/sa-user-guide-builder/references/templates.md +267 -0
  7. package/siesa-agents/sa/sa-user-guide-builder/references/writing-style.md +54 -0
  8. package/claude/skills/sa-create-user-guide/SKILL.md +0 -6
  9. package/claude/skills/sa-delivery-guides/SKILL.md +0 -240
package/claude/skills/sa-user-guide-builder/SKILL.md ADDED
@@ -0,0 +1,6 @@
1
+ ---
2
+ name: sa-user-guide-builder
3
+ description: 'Build and maintain a project''s consolidated end-user guide in ONE process, driven by the sprint status. It validates in _bmad-output/implementation-artifacts/sprint-status.yaml which features already have their epics and stories developed (each epic''s -source entry points to the epic file that identifies the feature) — no RAG indexing step needed. Produces a folder of linked Spanish markdown chapters with a central index.md, Mermaid diagrams and screenshot placeholders. On the first run it lists the developed features and lets the engineer document all or a selection; on later runs it offers to document new features (integrated coherently into the existing guide) or re-document existing ones by inspecting the commits made since they were last documented. All decisions go through the AskUserQuestion tool. Use this skill whenever someone wants to create, extend, update or regenerate the user guide / guía de usuario of a project — trigger on /sa-user-guide-builder, "documentar features", "generar guía de usuario", "actualizar la guía de usuario", "documentar un nuevo feature", "re-documentar un feature", or any request to turn finished features into end-user documentation, even if the skill is not named. Replaces the old two-step sa-create-user-guide + sa-delivery-guides process.'
4
+ ---
5
+
6
+ IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_siesa-agents/sa/sa-user-guide-builder/SKILL.md, READ its entire contents and follow its directions exactly!
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "siesa-agents",
3
- "version": "2.1.92",
3
+ "version": "2.1.94",
4
4
  "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
5
5
  "main": "index.js",
6
6
  "bin": {
package/siesa-agents/bmm/data/git-flow-siesa.md CHANGED
@@ -34,16 +34,56 @@ Identificar el folder actual para usarlo en la generacion del worktree de la sig
34
34
  ---
35
35
 
36
36
  ## 3. Estándar de Mensajes de Commit
37
- Se adopta el formato de **Conventional Commits** para mejorar la legibilidad y automatización.
37
+ Se adopta **Conventional Commits** enriquecido con trazabilidad obligatoria a **feature** y **épica**. Todo commit generado por un agente debe seguir EXACTAMENTE esta plantilla. Ningún campo se inventa: todos se derivan del `story_key` (ver Sección 6).
38
38
 
39
- | Tipo | Formato del Mensaje | Uso |
40
- | :--- | :--- | :--- |
41
- | **Feature** | `feat: descripción clara del cambio` | Nuevas funcionalidades. |
42
- | **Fix** | `fix: descripción del error corregido` | Corrección de errores (bugs). |
39
+ ### 3.1. Plantilla obligatoria
40
+
41
+ ```
42
+ <tipo>(<feature_scope>): <descripción>
43
+
44
+ Epic: <NNN>-<E> — <título de la épica>
45
+ Story: <NNN>-<E>.<HH> — <título de la historia>
46
+ ```
47
+
48
+ | Parte | Valor |
49
+ | :--- | :--- |
50
+ | `<tipo>` | `feat` (nueva funcionalidad) o `fix` (corrección de bug). Ante la duda → `feat`. |
51
+ | `<feature_scope>` | **Feature** de origen. **Prioridad:** el código de sincronización con Jira `FEATURE_CODE_JIRA` (issue key real, ej: `PROY-123`) **si ya fue sincronizado**; si no, el fallback `feat-<NNN3>`. Ver Sección 6. |
52
+ | `Epic:` | **Épica** (trailer obligatorio): `<NNN>-<E>` + título literal de la épica. |
53
+ | `Story:` | Historia (trailer obligatorio): `<NNN>-<E>.<HH>` + título literal de la historia. |
54
+
55
+ - La **descripción** va en minúsculas, en imperativo y ≤ 72 caracteres.
56
+ - Los trailers `Epic:` y `Story:` son máquina-parseables (`git log --format=%(trailers)`); NO se omiten ni se reordenan.
57
+ - El `—` es un guión largo (em dash). Si no se conoce el título literal de la épica, usar solo `Epic: <NNN>-<E>` sin `— título` (NUNCA inventar un título).
58
+
59
+ ### 3.2. Ejemplo — feature YA sincronizado con Jira (`FEATURE_CODE_JIRA=PROY-123`)
60
+
61
+ story_key `16-1.01`, épica `16-1: Company Retrieval Feature`. El scope usa el issue key de Jira:
62
+
63
+ ```
64
+ feat(PROY-123): establecer dominio y esquema de company
65
+
66
+ Epic: 16-1 — Company Retrieval Feature
67
+ Story: 16-1.01 — Establish Company Domain & Schema
68
+ ```
69
+
70
+ Comando:
71
+ ```bash
72
+ git commit -m "feat(PROY-123): establecer dominio y esquema de company" \
73
+ -m "Epic: 16-1 — Company Retrieval Feature" \
74
+ -m "Story: 16-1.01 — Establish Company Domain & Schema"
75
+ ```
76
+
77
+ ### 3.3. Ejemplo — feature NO sincronizado (`FEATURE_CODE_JIRA=PENDING:...` o ausente → fallback)
78
+
79
+ story_key `83-3.05`. Al no haber issue key de Jira, el scope cae al fallback `feat-<NNN3>`:
43
80
 
44
- **Ejemplos:**
45
- * `git commit -m "feat: implementar validación de identidad mediante SSO"`.
46
- * `git commit -m "fix: corregir cálculo de nómina en rama legacy"`.
81
+ ```
82
+ fix(feat-083): corregir cálculo de nómina en rama legacy
83
+
84
+ Epic: 83-3 — Payroll Corrections
85
+ Story: 83-3.05 — Fix Overtime Rounding
86
+ ```
47
87
 
48
88
  ---
49
89
  ## 4. Cambio de ramas
@@ -67,4 +107,50 @@ cambio de rama:
67
107
  * **Protección de Ramas:** `main` y `develop` están protegidas; el push directo está prohibido.
68
108
  * **Cuando realizar commit** Los commits deberan hacerce por historia en el code review, especificamente cuando este en status done la historia.
69
109
  * **Generacion de ramas** Las ramas se deben generar por epicas o por features nunca por historia.
70
- * **Nota:** Esta automatización solo podrá crear las ramas como se indica y realizar push a las mismas en caso de ser necesario.
110
+ * **Nota:** Esta automatización solo podrá crear las ramas como se indica y realizar push a las mismas en caso de ser necesario.
111
+
112
+ ---
113
+ ## 6. Derivación Determinista del Mensaje de Commit (Anti-Alucinación)
114
+
115
+ > El agente **NO inventa** feature ni épica: los **parsea** del `story_key`, que sigue la convención `@_siesa-agents/resources/conventions/epic-story-naming-convention.md` (`{NNN}-{E}.{HH}`).
116
+
117
+ **Regla de parseo del `story_key`** (ej: `16-1.01`):
118
+ - `NNN` = texto antes del **primer** `-` → `16` (el feature)
119
+ - `E` = texto entre el `-` y el `.` → `1` (la épica)
120
+ - `HH` = texto después del `.` → `01` (la historia)
121
+
122
+ ### 6.1. Resolución de `<feature_scope>` (código Jira primero, doc como fallback)
123
+
124
+ El agente **DEBE** verificar primero si el feature ya fue sincronizado con Jira. Orden de prioridad:
125
+
126
+ 1. **Buscar `FEATURE_CODE_JIRA`** con este orden de búsqueda (igual que el sync de épicas):
127
+ 1. En el **shard de la épica** (`planning-artifacts/epics/epic-feat-<NNN>-*.md`): primera línea `<!-- FEATURE_CODE_JIRA=... -->` o frontmatter YAML `FEATURE_CODE_JIRA:` / `FEATURE_ID:`.
128
+ 2. Si no está ahí → en el **shard del PRD** correspondiente (`prd/f<N>-*.md`).
129
+ 2. **Evaluar el valor encontrado:**
130
+ - Si existe y **NO** empieza con `PENDING:` (es un issue key real, ej: `PROY-123`) → **`<feature_scope>` = ese issue key.** (Feature YA sincronizado.)
131
+ - Si vale `PENDING:...`, o no se encontró ningún `FEATURE_CODE_JIRA` → **`<feature_scope>` = `feat-<NNN3>`** (fallback documental).
132
+
133
+ > ⚠️ NUNCA usar el literal `PENDING:...` como scope. `PENDING` ⇒ fallback `feat-<NNN3>`.
134
+
135
+ **Tabla de fuentes** — cada campo tiene UNA fuente; si la fuente no existe, aplica la regla de "si falta":
136
+
137
+ | Campo | Fuente única | Si falta |
138
+ | :--- | :--- | :--- |
139
+ | `<tipo>` | `## Change Log` / naturaleza de la historia | usar `feat` |
140
+ | `<feature_scope>` | `FEATURE_CODE_JIRA` sincronizado (§6.1) → issue key real | fallback `feat-<NNN3>` |
141
+ | `NNN` | `story_key`, segmento antes del 1er `-` | ABORTAR: `story_key` inválido |
142
+ | `NNN3` | `NNN` con padding a 3 dígitos (`16`→`016`, `3`→`003`, `123`→`123`) | — |
143
+ | `E` | `story_key`, entre `-` y `.` | ABORTAR: `story_key` inválido |
144
+ | `HH` | `story_key`, después del `.` | ABORTAR: `story_key` inválido |
145
+ | título épica | H2/H3 del epic file (`### Epic <NNN>-<E>: <título>`) | omitir `— título`, dejar solo `Epic: <NNN>-<E>` |
146
+ | título historia | H1 del story file (`# Story <NNN>-<E>.<HH>: <título>`) | omitir `— título`, dejar solo `Story: <NNN>-<E>.<HH>` |
147
+ | descripción | resumen de la historia | derivar del título de la historia, minúsculas, imperativo, ≤72 chars |
148
+
149
+ **Checklist de validación antes de ejecutar `git commit`** (todos deben ser ✅):
150
+ 1. El asunto casa con `^(feat|fix)\(.+\): .{1,72}$` y el scope es **o** un issue key de Jira sincronizado **o** `feat-<NNN3>` — **nunca** `PENDING:...`.
151
+ 2. Si el feature estaba sincronizado, el scope es exactamente el `FEATURE_CODE_JIRA` (no el fallback).
152
+ 3. Existe una línea `Epic: <NNN>-<E>` y su `<NNN>-<E>` coincide con el prefijo del `story_key`.
153
+ 4. Existe una línea `Story: <NNN>-<E>.<HH>` idéntica al `story_key`.
154
+ 5. Ningún título fue inventado: si no había fuente, el `— título` se omitió.
155
+
156
+ Si algún punto falla → NO commitear, reportar el campo faltante.
package/siesa-agents/bmm/workflows/4-implementation/code-review/steps/step-07-commit-push.md CHANGED
@@ -98,18 +98,30 @@ To securely persist the verified and approved code changes to the repository fol
98
98
 
99
99
  2. **Construct Commit Message**:
100
100
  <action>
101
- Per Section 3 of `{gitFlowGuide}`, use Conventional Commits format:
102
- - For features: `feat: {description}`
103
- - For fixes: `fix: {description}`
104
-
105
- Derive type from story context and construct message.
101
+ Build the message STRICTLY from Section 3 (template) and Section 6 (deterministic
102
+ derivation) of `{gitFlowGuide}`. Do NOT redefine or invent the format here — the
103
+ guide is the single source of truth.
104
+
105
+ 1. Parse `{{story_key}}` into `NNN`, `E`, `HH` per Section 6.
106
+ 2. Resolve `<feature_scope>` per Section 6.1: FIRST look up `FEATURE_CODE_JIRA` in the
107
+ epic shard (then the PRD shard). If it is a real synced Jira issue key (NOT
108
+ `PENDING:...`) → use it as the scope. Otherwise fall back to `feat-<NNN3>`.
109
+ 3. Fill the template:
110
+ `<tipo>(<feature_scope>): <descripción>` + `Epic:` and `Story:` trailers.
111
+ 4. Take epic/story titles literally from the epic/story files; if absent, omit the
112
+ `— título` (never invent one).
113
+ 5. Run the Section 6 validation checklist. If any item fails, STOP and report the
114
+ missing field instead of committing.
115
+
116
+ Store the result as `{{commit_message}}` (subject + trailers).
106
117
  </action>
107
118
 
108
119
  3. **User Confirmation**:
109
120
  <output>
110
121
  READY TO COMMIT:
111
122
  - Branch: {{current_branch}}
112
- - Message: "feat: implementation for story {{story_key}}"
123
+ - Message:
124
+ {{commit_message}}
113
125
 
114
126
  Do you want to proceed with the commit and push?
115
127
  </output>
@@ -129,7 +141,7 @@ To securely persist the verified and approved code changes to the repository fol
129
141
  </logic>
130
142
 
131
143
  4. **Commit Changes**:
132
- <action>Run command `git commit -m "feat: implementation for story {{story_key}}"`</action>
144
+ <action>Commit using `{{commit_message}}` (one `-m` for the subject and one `-m` per trailer line, per the example in Section 3.2 of `{gitFlowGuide}`).</action>
133
145
  <check if="Commit failed (no changes?)">
134
146
  <output>ℹ️ No changes to commit.</output>
135
147
  </check>
package/siesa-agents/sa/sa-user-guide-builder/SKILL.md ADDED
@@ -0,0 +1,158 @@
1
+ ---
2
+ name: sa-user-guide-builder
3
+ description: Build and maintain a project's consolidated end-user guide in ONE process, driven by the sprint status. It validates in _bmad-output/implementation-artifacts/sprint-status.yaml which features already have their epics and stories developed (each epic's -source entry points to the epic file that identifies the feature) — no RAG indexing step needed. Produces a folder of linked Spanish markdown chapters with a central index.md, Mermaid diagrams and screenshot placeholders. On the first run it lists the developed features and lets the engineer document all or a selection; on later runs it offers to document new features (integrated coherently into the existing guide) or re-document existing ones by inspecting the commits made since they were last documented. All decisions go through the AskUserQuestion tool. Use this skill whenever someone wants to create, extend, update or regenerate the user guide / guía de usuario of a project — trigger on /sa-user-guide-builder, "documentar features", "generar guía de usuario", "actualizar la guía de usuario", "documentar un nuevo feature", "re-documentar un feature", or any request to turn finished features into end-user documentation, even if the skill is not named. Replaces the old two-step sa-create-user-guide + sa-delivery-guides process.
4
+ ---
5
+
6
+ # SA User Guide Builder
7
+
8
+ One process, one deliverable: a **folder** with the set of linked Spanish markdown files that form the project's end-user guide. The developer who finished the features runs this skill and the guide comes out already consolidated — there is no separate "dev documents, delivery consolidates" hand-off, and no RAG/MCP indexing in between.
9
+
10
+ **Sources (local project artifacts, never the MCP):**
11
+ - `{implementation_artifacts}/sprint-status.yaml` — the single source of truth for which epics and stories are actually developed, and for which epic file belongs to which feature (via each epic's `-source` path)
12
+ - The epic files referenced by `epic-*-source` — stories, acceptance criteria, GWT scenarios (these become the step-by-step workflows)
13
+ - `{planning_artifacts}/prd/feature-{slug}.md` — feature descriptions, FRs, key behaviors (read it when it exists for the feature)
14
+ - General context if present: `prd/goals.md`, `prd/background-context.md`, `prd/user-interface-design-goals.md`, `architecture.md`
15
+
16
+ **Deliverable:**
17
+
18
+ ```
19
+ {output_folder}/documentation-artifacts/user-guide/
20
+ ├── _guide-manifest.yaml ← state: which features are documented, where, at which commit
21
+ ├── index.md ← cover + linked table of contents
22
+ ├── 01-introduccion.md
23
+ ├── 02-primeros-pasos.md
24
+ ├── 03-{tema-1}.md ... NN-{tema-n}.md ← thematic chapters (related features grouped)
25
+ ├── NN-solucion-de-problemas.md ← merged across all features
26
+ ├── NN-preguntas-frecuentes.md ← merged across all features
27
+ └── NN-glosario.md ← merged across all features
28
+ ```
29
+
30
+ Never produce a single monolithic file — the guide would be too large to read and maintain. Never produce one file per feature either — group related features into thematic chapters so the folder stays navigable. The chapter architecture is the point of the consolidation.
31
+
32
+ File templates (manifest, index, chapters, shared files) live in `{project-root}/_siesa-agents/sa/sa-user-guide-builder/references/templates.md`. Writing rules and the technical→plain-language transformation table live in `{project-root}/_siesa-agents/sa/sa-user-guide-builder/references/writing-style.md`. Read both before generating any content.
33
+
34
+ ---
35
+
36
+ ## Setup
37
+
38
+ 1. Load `{project-root}/_bmad/bmm/config.yaml` and resolve: `project_name`, `communication_language`, `planning_artifacts`, `implementation_artifacts`, `output_folder`. Talk to the user in `{communication_language}` (typically Spanish); all generated guide content is Spanish for a non-technical end user.
39
+ 2. Set `{guide_folder}` = `{output_folder}/documentation-artifacts/user-guide/` — the guide files always land directly here, with no per-project subfolder.
40
+ 3. Greet with one warm, non-technical sentence. Don't narrate tool calls or file scans — the user cares about their guide, not the plumbing.
41
+ 4. Check whether `{guide_folder}/_guide-manifest.yaml` exists:
42
+ - **Missing → First run** (the guide doesn't exist yet)
43
+ - **Present → Maintenance run** (the guide exists; offer to grow or refresh it)
44
+
45
+ ## Interaction rules (both modes)
46
+
47
+ Every decision the user makes goes through **AskUserQuestion** — never free-text prompts like "type the IDs separated by commas". Practical constraints of that tool and how to work within them:
48
+
49
+ - Max 4 questions per call and max 4 options per question; an "Other" free-text option is always added automatically.
50
+ - To let the user pick features when there are more than 4: use `multiSelect: true` and split the feature list into groups of 4 options across up to 4 questions in one call ("Features (1/3)", "Features (2/3)", …). If there are more than 16, make additional AskUserQuestion calls. Selecting nothing in a group is fine.
51
+ - Option `label` = the feature title (short); `description` = one business-friendly line. Never surface technical noise (chunk counts, file paths, SHAs) in labels.
52
+
53
+ ---
54
+
55
+ ## First run
56
+
57
+ ### 1. Discover developed features from the sprint status
58
+
59
+ Read `{implementation_artifacts}/sprint-status.yaml`. If it doesn't exist, stop and tell the user it's required (it is produced by sprint-planning). This file is the only trustworthy signal of what is actually developed — never infer completion from feature-status.yaml, commit messages or file existence.
60
+
61
+ How to read `development_status`:
62
+ - Epic entries: `epic-{F}-{E}: backlog | in-progress | done` — `done` means all of the epic's stories were developed.
63
+ - Every epic has an `epic-{F}-{E}-source:` entry with the path of its epic file. That path is how you identify the feature: all epics sharing the feature number `{F}` point to the same `epic-feat-{F}-{name}.md`, and the `{name}` slug is the feature's name (the `# ===== Feature N — ... =====` header comments confirm the mapping).
64
+ - Story entries: `{F}-{E}.{HH}-{slug}: status` — collect the story IDs of `done` epics; they go into the manifest and later drive the re-documentation git filter.
65
+
66
+ Group the epics by feature number and classify each feature:
67
+ - **Documentable** — all its epics are `done`.
68
+ - **Partial** — some epics `done`, others still `backlog`/`in-progress`. Offer it labeled "parcial"; only the `done` epics feed the guide (never document behavior from unfinished stories).
69
+ - **Pending** — no `done` epics. Mention it as not yet documentable, don't offer it.
70
+
71
+ If nothing is documentable, say so clearly and stop.
72
+
73
+ Show the documentable (and partial) features as a short table (feature, epics done/total, last update), then ask with AskUserQuestion:
74
+
75
+ - **Question:** "¿Qué quieres documentar?" — options: **"Documentar todo (N features)"** / **"Elegir cuáles documentar"**.
76
+ - If the user chooses to pick: follow the multiSelect batching pattern above to collect the exact set.
77
+
78
+ ### 2. Analyze sources
79
+
80
+ For each selected feature, read the epic file(s) referenced by its `epic-*-source` entries (only the `done` epics), plus the PRD feature file if one exists for that slug, plus the general context docs once. Extract per feature: what it does for the user, key behaviors, step-by-step workflows (from GWT scenarios of the done stories), warnings/limitations, and the source paths + story IDs (you'll record them in frontmatter and the manifest). Give one short progress line per feature — this step is autonomous.
81
+
82
+ ### 3. Design the chapter plan
83
+
84
+ Group related features into thematic chapters (e.g. "Suscripciones y planes", "Facturación y pagos") — a user-need-oriented structure, not one chapter per feature. Two small related features share a chapter; a large feature can own one. Keep the file count manageable.
85
+
86
+ Present the plan as one line per file (filename → chapters/features it covers) and confirm with AskUserQuestion: **"¿Aprobar este plan de capítulos?"** — options "Aprobar" / "Ajustar" (the user describes adjustments via Other or a follow-up question). Iterate until approved.
87
+
88
+ ### 4. Generate the guide
89
+
90
+ Read `_siesa-agents/sa/sa-user-guide-builder/references/templates.md` and `_siesa-agents/sa/sa-user-guide-builder/references/writing-style.md`, then write every file. The consolidation rules that make this ONE coherent manual instead of stitched-together feature docs:
91
+
92
+ - Shared concepts are explained **once** — access/login/navigation in `02-primeros-pasos.md`, terminology in the glossary — and chapters link to them instead of repeating.
93
+ - Troubleshooting, FAQ and glossary entries from all features are **merged** into their single files, deduplicated.
94
+ - Every file links back to `index.md` and to its previous/next sibling.
95
+ - Each feature section includes: plain description, numbered steps, ⚠️ inline warnings, a Mermaid diagram with Spanish labels for non-trivial flows, and 📸 screenshot placeholders (`UPPER_SNAKE_CASE` unique IDs) with a screenshot index section per file.
96
+
97
+ ### 5. Record state
98
+
99
+ Write `_guide-manifest.yaml` (template in `references/templates.md`): one entry per documented feature with its chapter file, the epics and story IDs it covered (as they appear in `sprint-status.yaml`), sources, date, and `documented_at_commit` = current `git rev-parse HEAD`. The SHA and the story IDs are what make future re-documentation diffs possible — don't skip them.
100
+
101
+ ### 6. Validate, then confirm
102
+
103
+ Self-check before presenting (fix silently, don't ask the user to review defects):
104
+ - Every planned file exists, is non-empty, and is reachable from `index.md`; the prev/next chain is unbroken.
105
+ - Every selected feature appears in exactly one chapter.
106
+ - Mermaid blocks are syntactically valid with Spanish labels; screenshot IDs are unique, `UPPER_SNAKE_CASE`, and all listed in their file's screenshot index.
107
+ - No TODO/TBD markers or empty sections; manifest matches what's on disk.
108
+
109
+ Close with a summary: folder path, file list, chapter→features mapping, totals (diagrams, screenshots), and the reminder that re-running the skill adds new features or refreshes existing ones.
110
+
111
+ ---
112
+
113
+ ## Maintenance run
114
+
115
+ ### 1. Show guide state
116
+
117
+ Read `_guide-manifest.yaml` and summarize briefly: N features documented across M chapters, last update date.
118
+
119
+ ### 2. Ask what to do
120
+
121
+ AskUserQuestion — **"Ya existe una guía para {project}. ¿Qué deseas hacer?"**:
122
+ - **"Documentar nuevos features"** — add features completed since the guide was built
123
+ - **"Re-documentar un feature existente"** — refresh features whose behavior may have changed
124
+ - **"Salir"** — nothing to do
125
+
126
+ ### 3a. Document new features
127
+
128
+ Re-read `sprint-status.yaml` and find what became documentable since the guide was built: features with `done` epics that are **not** in the manifest, and also new `done` epics of features already documented (offer those as "ampliar {feature}" — their content folds into the feature's existing chapter, and their story IDs are appended to the manifest entry). If there are no candidates, say so and offer re-documentation instead. Otherwise reuse the first-run selection UX (all / pick).
129
+
130
+ Integrate **coherently with the existing guide** — this is the difference from a first run:
131
+ - Read the existing `index.md` and chapter files first to match tone, terminology and structure.
132
+ - Decide per feature: does it belong in an existing chapter (append a section there) or does it justify a new chapter file? If new, insert it before the troubleshooting file and renumber the trailing files — then fix every affected link (index, prev/next chain). Broken links are the most common failure of incremental updates; verify the chain explicitly.
133
+ - Merge the feature's FAQ/troubleshooting/glossary entries into the shared files without duplicating existing entries.
134
+ - Add the feature to the manifest with today's date and the current HEAD SHA.
135
+
136
+ ### 3b. Re-document existing features
137
+
138
+ Let the user pick which documented feature(s) to refresh (multiSelect batches from the manifest list).
139
+
140
+ For each one, inspect what changed since it was documented:
141
+ 1. Take `documented_at_commit` from the manifest.
142
+ 2. Look for related commits: `git log --oneline {sha}..HEAD` filtered by the feature's slug, its story IDs from the manifest (sprint-status format, e.g. `1-4.02`), or its epic IDs (e.g. `epic-1-4`); plus direct diffs of its source docs: `git diff {sha}..HEAD -- {epic file} {prd file}`; plus a comparison of the feature's story list in `sprint-status.yaml` against the manifest (new `done` stories = new behavior to document). (If the feature's code lives in another repo, the doc-file diff and the sprint-status comparison are still the reliable signals — say so rather than guessing.)
143
+ 3. **No relevant changes found:** tell the user, and ask via AskUserQuestion whether to regenerate anyway ("Regenerar de todas formas" / "Omitir").
144
+ 4. **Changes found:** summarize them in business terms (what behavior changed, not which files), then update only the affected sections of the feature's chapter and the shared files. Don't rewrite untouched chapters.
145
+ 5. Update the manifest entry (new date, new SHA).
146
+
147
+ ### 4. Validate and confirm
148
+
149
+ Run the same self-check as the first run (link chain, uniqueness, no markers, manifest consistency) and close with a summary of what was added/updated.
150
+
151
+ ---
152
+
153
+ ## Guardrails
154
+
155
+ - The manifest (`_guide-manifest.yaml`) is internal state — never link it from `index.md` or mention it in guide content.
156
+ - Generated content is always Spanish, always for a non-technical end user; the transformation table in `_siesa-agents/sa/sa-user-guide-builder/references/writing-style.md` governs how technical concepts are rewritten. Component names, `[Source:]` tags and other implementation details never appear in the body — traceability lives in frontmatter `sources:` and in the manifest.
157
+ - Don't invent features or behaviors not present in the sources. If a source is ambiguous, prefer omitting a claim over guessing.
158
+ - Never modify the source artifacts (sprint-status.yaml, PRDs, epics) — this skill only reads them.
package/siesa-agents/sa/sa-user-guide-builder/references/templates.md ADDED
@@ -0,0 +1,267 @@
1
+ # Templates — sa-user-guide-builder
2
+
3
+ All generated content is Spanish. Placeholders in `{curly braces}` are resolved at generation time.
4
+
5
+ ## Table of contents
6
+
7
+ 1. [`_guide-manifest.yaml`](#_guide-manifestyaml)
8
+ 2. [`index.md`](#indexmd)
9
+ 3. [`01-introduccion.md`](#01-introduccionmd)
10
+ 4. [`02-primeros-pasos.md`](#02-primeros-pasosmd)
11
+ 5. [Thematic chapter file](#thematic-chapter-file)
12
+ 6. [Shared tail files (troubleshooting / FAQ / glossary)](#shared-tail-files)
13
+
14
+ ---
15
+
16
+ ## `_guide-manifest.yaml`
17
+
18
+ Internal state file. Never linked from the guide, never shown to the end user.
19
+
20
+ ```yaml
21
+ project_name: "{Project Name}"
22
+ created: "{YYYY-MM-DD}"
23
+ last_updated: "{YYYY-MM-DD}"
24
+ files:
25
+ - index.md
26
+ - 01-introduccion.md
27
+ - 02-primeros-pasos.md
28
+ - 03-{tema-1}.md
29
+ # ... every file of the guide, in order
30
+ features:
31
+ - feature: 1
32
+ slug: "calendar" # from the epic source filename: epic-feat-{F}-{slug}.md
33
+ title: "Calendario"
34
+ chapter_file: "03-calendario.md"
35
+ documented_date: "{YYYY-MM-DD}"
36
+ documented_at_commit: "{full git SHA of HEAD when documented}"
37
+ epics_documented: ["epic-1-1", "epic-1-2", "epic-1-3", "epic-1-4"] # only the epics that were `done` in sprint-status.yaml
38
+ sources:
39
+ - "_bmad-output/planning-artifacts/epics/epic-feat-1-calendar.md" # from epic-{F}-{E}-source
40
+ - "_bmad-output/planning-artifacts/prd/feature-calendar.md" # only if it exists
41
+ story_ids: ["1-1.01", "1-1.02", "1-2.01"] # sprint-status format {F}-{E}.{HH} — used to filter git log on re-documentation
42
+ ```
43
+
44
+ `documented_at_commit`, `epics_documented` and `story_ids` are what make the re-documentation diff and the "new done epics" detection possible; fill them for every feature, every time.
45
+
46
+ ---
47
+
48
+ ## `index.md`
49
+
50
+ ```markdown
51
+ ---
52
+ project: {project_name}
53
+ generated_date: {YYYY-MM-DD}
54
+ last_updated: {YYYY-MM-DD}
55
+ audience: Usuario final no técnico
56
+ type: indice-guia-usuario
57
+ ---
58
+
59
+ # Guía de Usuario de {Proyecto}
60
+
61
+ Manual de usuario final. Esta guía reúne, de forma coherente, toda la documentación de uso del sistema.
62
+
63
+ ## ¿Qué es {Proyecto}?
64
+
65
+ {2-3 frases. Qué hace y para quién es. Sin términos técnicos.}
66
+
67
+ ## Contenido
68
+
69
+ 1. [Introducción](01-introduccion.md)
70
+ 2. [Primeros Pasos](02-primeros-pasos.md)
71
+ 3. [{Capítulo temático 1}](03-{tema-1}.md)
72
+ 4. [{Capítulo temático 2}](04-{tema-2}.md)
73
+ {...}
74
+ N. [Solución de Problemas](NN-solucion-de-problemas.md)
75
+ N. [Preguntas Frecuentes](NN-preguntas-frecuentes.md)
76
+ N. [Glosario](NN-glosario.md)
77
+ ```
78
+
79
+ ---
80
+
81
+ ## `01-introduccion.md`
82
+
83
+ ```markdown
84
+ ---
85
+ project: {project_name}
86
+ chapter: Introducción
87
+ generated_date: {YYYY-MM-DD}
88
+ audience: Usuario final no técnico
89
+ sources:
90
+ - {source-path-1}
91
+ ---
92
+
93
+ [⬅️ Índice](index.md)
94
+
95
+ # Introducción
96
+
97
+ ## ¿Qué es {Proyecto}?
98
+
99
+ {2-3 párrafos: qué hace, qué problema resuelve, valor para el usuario.}
100
+
101
+ ## ¿Para quién es esta guía?
102
+
103
+ {1 párrafo. Perfil del lector: profesional de negocio cómodo con aplicaciones, sin perfil técnico.}
104
+
105
+ ## Cómo usar esta guía
106
+
107
+ {Estructura de la guía y cómo navegar entre capítulos.}
108
+
109
+ **Convenciones:**
110
+ - 📸 **[Screenshot: ID — Descripción]**: lugar donde irá una captura de pantalla
111
+ - ⚠️ **Advertencia**: información importante antes de realizar una acción
112
+ - 💡 **Tip**: consejo útil
113
+
114
+ ---
115
+ [Índice](index.md) · [Siguiente ➡️](02-primeros-pasos.md)
116
+ ```
117
+
118
+ ---
119
+
120
+ ## `02-primeros-pasos.md`
121
+
122
+ Access, login and navigation live here **once** — chapters link here instead of repeating it.
123
+
124
+ ```markdown
125
+ ---
126
+ project: {project_name}
127
+ chapter: Primeros Pasos
128
+ generated_date: {YYYY-MM-DD}
129
+ audience: Usuario final no técnico
130
+ sources:
131
+ - {source-path-1}
132
+ ---
133
+
134
+ [⬅️ Índice](index.md)
135
+
136
+ # Primeros Pasos
137
+
138
+ ## Acceso al sistema
139
+
140
+ {Pasos numerados: URL/aplicación, inicio de sesión.}
141
+
142
+ 📸 [Screenshot: UI_LOGIN — Pantalla de inicio de sesión]
143
+
144
+ ## Navegación general
145
+
146
+ {Cómo está organizada la pantalla principal, en lenguaje visual simple.}
147
+
148
+ 📸 [Screenshot: UI_DASHBOARD — Vista general]
149
+
150
+ ```mermaid
151
+ flowchart LR
152
+ A[Iniciar sesión] --> B[Pantalla principal]
153
+ B --> C[{Módulo 1}]
154
+ B --> D[{Módulo 2}]
155
+ ```
156
+
157
+ ## Índice de capturas de este capítulo
158
+
159
+ | ID | Descripción | Estado |
160
+ |----|-------------|--------|
161
+ | UI_LOGIN | Pantalla de inicio de sesión | Pendiente |
162
+ | UI_DASHBOARD | Vista general | Pendiente |
163
+
164
+ ---
165
+ [⬅️ Anterior](01-introduccion.md) · [Índice](index.md) · [Siguiente ➡️](03-{tema-1}.md)
166
+ ```
167
+
168
+ ---
169
+
170
+ ## Thematic chapter file
171
+
172
+ One file per thematic chapter (`03-{tema}.md`, `04-{tema}.md`, …). Groups one or more related features.
173
+
174
+ ```markdown
175
+ ---
176
+ project: {project_name}
177
+ chapter: {Nombre del capítulo}
178
+ generated_date: {YYYY-MM-DD}
179
+ last_updated: {YYYY-MM-DD}
180
+ audience: Usuario final no técnico
181
+ features: [{F1}, {F4}]
182
+ sources:
183
+ - {source-path-1}
184
+ - {source-path-2}
185
+ ---
186
+
187
+ [⬅️ Índice](index.md)
188
+
189
+ # {Nombre del Capítulo}
190
+
191
+ {1-2 frases: qué cubre este capítulo y cuándo lo necesitas.}
192
+
193
+ ## {Funcionalidad 1}
194
+
195
+ ### ¿Qué es?
196
+ {Un párrafo. Descripción simple.}
197
+
198
+ ### ¿Para qué sirve?
199
+ {El beneficio práctico para el usuario.}
200
+
201
+ ### ¿Cómo se usa?
202
+ 1. {Acción clara por paso.}
203
+ 2. ⚠️ {Advertencia en línea justo antes del paso riesgoso, si aplica.}
204
+ 3. {...}
205
+
206
+ 📸 [Screenshot: {FEATURE_ID}_{PASO} — Descripción]
207
+
208
+ {Si el flujo tiene decisiones o ramas, incluye un diagrama con labels en español:}
209
+
210
+ ```mermaid
211
+ flowchart TD
212
+ Inicio --> Paso1[{Acción 1}]
213
+ Paso1 --> Decision{{"¿Condición?"}}
214
+ Decision -->|Sí| Paso2[{Acción 2}]
215
+ Decision -->|No| Fin
216
+ Paso2 --> Fin
217
+ ```
218
+
219
+ ## {Funcionalidad 2}
220
+ {misma estructura}
221
+
222
+ ## Índice de capturas de este capítulo
223
+
224
+ | ID | Descripción | Estado |
225
+ |----|-------------|--------|
226
+ | {ID} | {Descripción} | Pendiente |
227
+
228
+ ---
229
+ [⬅️ Anterior]({archivo-anterior}.md) · [Índice](index.md) · [Siguiente ➡️]({archivo-siguiente}.md)
230
+ ```
231
+
232
+ ---
233
+
234
+ ## Shared tail files
235
+
236
+ ### `NN-solucion-de-problemas.md`
237
+
238
+ Merged from ALL features, deduplicated, grouped by symptom the user experiences (not by feature).
239
+
240
+ ```markdown
241
+ [⬅️ Índice](index.md)
242
+
243
+ # Solución de Problemas
244
+
245
+ ## {Problema en palabras del usuario}
246
+
247
+ **Qué ves:** {síntoma}
248
+ **Qué hacer:**
249
+ 1. {paso}
250
+ 2. {paso}
251
+
252
+ ## Mensajes comunes
253
+
254
+ | Mensaje que aparece | Qué significa | Qué hacer |
255
+ |---|---|---|
256
+ | {mensaje} | {significado simple} | {acción} |
257
+ ```
258
+
259
+ ### `NN-preguntas-frecuentes.md`
260
+
261
+ Merged FAQ, no repeated questions, grouped by topic. Format: `**P:** … / **R:** …`. When an answer needs detail, link to the relevant chapter instead of repeating it.
262
+
263
+ ### `NN-glosario.md`
264
+
265
+ Alphabetical, one plain-Spanish definition per term. Every term that appears in more than one chapter belongs here; chapters use the term and rely on the glossary rather than redefining it.
266
+
267
+ All three tail files carry the same frontmatter shape as chapters (with merged `sources:`) and end with the prev/next/index navigation footer.
package/siesa-agents/sa/sa-user-guide-builder/references/writing-style.md ADDED
@@ -0,0 +1,54 @@
1
+ # Writing Style — sa-user-guide-builder
2
+
3
+ The reader is comfortable with a smartphone but has no software background. Everything below exists to protect that reader.
4
+
5
+ ## Voice and language
6
+
7
+ - Spanish, active voice, direct instructions: "Haz clic en…", "Escribe…", "Selecciona…".
8
+ - Short sentences. If a sentence needs a comma to explain a technical concept, rewrite it.
9
+ - One clear action per numbered step.
10
+ - If a concept gives the end user no practical value, drop it.
11
+ - ⚠️ warnings go inline, immediately **before** the step that can cause the problem — a warning after the mistake is decoration.
12
+ - Explain a term the first time it appears (or link to the glossary); after that, just use it.
13
+
14
+ ## What to keep, transform, and omit from the sources
15
+
16
+ **Keep (rewritten in plain language):** feature purpose, step-by-step flows, key concepts, troubleshooting, FAQ, and the practical implication of every warning.
17
+
18
+ **Transform:**
19
+
20
+ | Source element | Treatment in the guide |
21
+ |---|---|
22
+ | `deep linking` / unique URL per record | "Cada registro tiene su propia dirección web que puedes guardar o compartir" |
23
+ | Component names (`ContactManager`, `EmptyState`, `ErrorPanel`, …) | Remove the name; describe what the user sees |
24
+ | `NIT/RUC` | Keep it — explain once: "número de identificación tributaria (NIT/RUC)" |
25
+ | `Toast` notification | "mensaje de confirmación que aparece brevemente en pantalla" |
26
+ | Retry button on error | "si aparece un error, haz clic en Reintentar" |
27
+ | Two-column panel | "La pantalla se divide en dos partes: a la izquierda la lista, a la derecha el detalle" |
28
+ | Inline validation | "mensajes de error junto al campo que necesita corrección" |
29
+ | GWT scenarios (Given/When/Then) | Rewrite as numbered user steps — never show the GWT wording |
30
+
31
+ **Omit from the body (traceability lives in frontmatter `sources:` and the manifest):**
32
+ - `[Source: FX Story Y.Z]` tags
33
+ - Implementation details, API names, architecture references
34
+ - `*Generado: ...*` footers from source docs
35
+
36
+ ## Mermaid diagrams
37
+
38
+ - Include a diagram only when the flow has decisions, branches, or 4+ steps — a linear 2-step action doesn't need one.
39
+ - All node labels in Spanish, phrased as user actions or screens ("Iniciar sesión", "¿Guardar cambios?"), never component or endpoint names.
40
+ - Keep diagrams small: if a flow needs more than ~10 nodes, split the section instead.
41
+
42
+ ## Screenshot placeholders
43
+
44
+ - Format: `📸 [Screenshot: ID — Descripción en español]`
45
+ - IDs in `UPPER_SNAKE_CASE`, unique across the whole guide, prefixed by context: `UI_` (general screens), `{FEATURE_ID}_` (feature steps, e.g. `F3_CREAR_CLIENTE`), `ERROR_` (error states).
46
+ - Place one at each visually meaningful step — the screen the user must recognize before acting.
47
+ - Every file that contains placeholders ends its content with an "Índice de capturas de este capítulo" table (ID, Descripción, Estado: Pendiente) so the delivery team can capture them without hunting through the text.
48
+
49
+ ## Coherence across files (the point of consolidation)
50
+
51
+ - Access, login and navigation are explained once in `02-primeros-pasos.md`; chapters link there.
52
+ - Shared concepts are defined once (introduction or glossary) and referenced with relative links.
53
+ - FAQ, troubleshooting and glossary are single merged files — before adding an entry during maintenance, check it isn't already there under different wording.
54
+ - Consistent terminology: if one chapter says "cliente", no other chapter says "tercero" for the same thing. When re-documenting, match the vocabulary already used in the guide.
package/claude/skills/sa-create-user-guide/SKILL.md DELETED
@@ -1,6 +0,0 @@
1
- ---
2
- name: sa-create-user-guide
3
- description: 'Genera guías de usuario comprehensivas en español e inglés desde épicas y PRDs, con diagramas Mermaid y trazabilidad completa'
4
- ---
5
-
6
- IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_siesa-agents/bmm/workflows/5-documentation/create-user-guide/workflow.md, READ its entire contents and follow its directions exactly!
package/claude/skills/sa-delivery-guides/SKILL.md DELETED
@@ -1,240 +0,0 @@
1
- ---
2
- name: sa-delivery-guides
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
- ---
5
-
6
- # Delivery Agent Guides — Consolidador
7
-
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
-
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.**
13
-
14
- ---
15
-
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>" }`).
23
-
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
- ---
27
-
28
- ## Flujo
29
-
30
- ### Paso 1: Descubrir proyectos con guías de usuario (automático)
31
-
32
- Apenas se invoca la skill, sin preguntar primero:
33
-
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ú).
49
-
50
- ---
51
-
52
- ### Paso 2: Mapear las guías por feature del proyecto
53
-
54
- Objetivo: saber qué features/áreas cubre el proyecto, recuperando los chunks de sus guías de usuario.
55
-
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.
64
-
65
- ---
66
-
67
- ### Paso 3: Diseñar la estructura del manual (capítulos)
68
-
69
- Aplica una arquitectura de información orientada a la **necesidad del usuario** (Diátaxis simplificado), no un archivo por feature suelto:
70
-
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).
82
-
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.
84
-
85
- ---
86
-
87
- ### Paso 4: Generar los archivos del manual
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:**
115
- ```markdown
116
- ---
117
- project: {proyecto}
118
- chapter: {nombre del capítulo}
119
- generated_date: {YYYY-MM-DD}
120
- audience: Usuario final no técnico
121
- sources:
122
- - {mcp-path-1}
123
- - {mcp-path-2}
124
- ---
125
-
126
- [⬅️ Índice](index.md)
127
-
128
- # {Nombre del Capítulo}
129
-
130
- ## {Funcionalidad 1}
131
-
132
- ### ¿Qué es?
133
- Un párrafo. Descripción simple.
134
-
135
- ### ¿Para qué sirve?
136
- El beneficio práctico para el usuario.
137
-
138
- ### ¿Cómo se usa?
139
- Pasos numerados. Una acción clara por paso.
140
- Incluye advertencias en línea (⚠️ ...) justo antes del paso que puede causar un problema.
141
-
142
- ## {Funcionalidad 2}
143
- (misma estructura)
144
-
145
- ---
146
- [⬅️ Anterior]({archivo-anterior}.md) · [Índice](index.md) · [Siguiente ➡️]({archivo-siguiente}.md)
147
- ```
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}
159
- ---
160
-
161
- # Guía de Usuario de {Proyecto}
162
-
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)
178
- ```
179
-
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.
185
-
186
- ---
187
-
188
- ### Paso 5: Guardar y confirmar
189
-
190
- Guarda todo en la carpeta del proyecto:
191
- ```
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
201
- ```
202
-
203
- Crea la carpeta si no existe.
204
-
205
- Luego confirma:
206
- ```
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
215
-
216
- Capítulos / features incluidos:
217
- - {capítulo 1}: {features que agrupa}
218
- - {capítulo 2}: {features que agrupa}
219
-
220
- Fuentes del MCP:
221
- - {mcp-path-1}
222
- - {mcp-path-2}
223
- ```
224
-
225
- ---
226
-
227
- ## Referencia de Transformación
228
-
229
- | Elemento técnico | Tratamiento en la guía |
230
- |---|---|
231
- | `deep linking` / URL única por registro | "Cada registro tiene su propia dirección web que puedes guardar o compartir" |
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" |
236
- | Panel de dos columnas | "La pantalla se divide en dos partes: a la izquierda la lista, a la derecha el detalle" |
237
- | Validación inline | "mensajes de error junto al campo que necesita corrección" |
238
- | Bloque de código Mermaid | Una o dos frases que describan el flujo |
239
- | `[Source: FX Story Y.Z]` | Omitir |
240
- | `📸 [Screenshot: ...]` | Omitir |