siesa-agents 2.1.93 → 2.1.94

package/claude/skills/sa-user-guide-builder/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: sa-user-guide-builder
+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.'
+---
+
+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

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.93",
+  "version": "2.1.94",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {

package/siesa-agents/sa/sa-user-guide-builder/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: sa-user-guide-builder
+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.
+---
+
+# SA User Guide Builder
+
+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.
+
+**Sources (local project artifacts, never the MCP):**
+- `{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)
+- The epic files referenced by `epic-*-source` — stories, acceptance criteria, GWT scenarios (these become the step-by-step workflows)
+- `{planning_artifacts}/prd/feature-{slug}.md` — feature descriptions, FRs, key behaviors (read it when it exists for the feature)
+- General context if present: `prd/goals.md`, `prd/background-context.md`, `prd/user-interface-design-goals.md`, `architecture.md`
+
+**Deliverable:**
+
+```
+{output_folder}/documentation-artifacts/user-guide/
+├── _guide-manifest.yaml          ← state: which features are documented, where, at which commit
+├── index.md                      ← cover + linked table of contents
+├── 01-introduccion.md
+├── 02-primeros-pasos.md
+├── 03-{tema-1}.md ... NN-{tema-n}.md   ← thematic chapters (related features grouped)
+├── NN-solucion-de-problemas.md   ← merged across all features
+├── NN-preguntas-frecuentes.md    ← merged across all features
+└── NN-glosario.md                ← merged across all features
+```
+
+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.
+
+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.
+
+---
+
+## Setup
+
+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.
+2. Set `{guide_folder}` = `{output_folder}/documentation-artifacts/user-guide/` — the guide files always land directly here, with no per-project subfolder.
+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.
+4. Check whether `{guide_folder}/_guide-manifest.yaml` exists:
+   - **Missing → First run** (the guide doesn't exist yet)
+   - **Present → Maintenance run** (the guide exists; offer to grow or refresh it)
+
+## Interaction rules (both modes)
+
+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:
+
+- Max 4 questions per call and max 4 options per question; an "Other" free-text option is always added automatically.
+- 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.
+- Option `label` = the feature title (short); `description` = one business-friendly line. Never surface technical noise (chunk counts, file paths, SHAs) in labels.
+
+---
+
+## First run
+
+### 1. Discover developed features from the sprint status
+
+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.
+
+How to read `development_status`:
+- Epic entries: `epic-{F}-{E}: backlog | in-progress | done` — `done` means all of the epic's stories were developed.
+- 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).
+- 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.
+
+Group the epics by feature number and classify each feature:
+- **Documentable** — all its epics are `done`.
+- **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).
+- **Pending** — no `done` epics. Mention it as not yet documentable, don't offer it.
+
+If nothing is documentable, say so clearly and stop.
+
+Show the documentable (and partial) features as a short table (feature, epics done/total, last update), then ask with AskUserQuestion:
+
+- **Question:** "¿Qué quieres documentar?" — options: **"Documentar todo (N features)"** / **"Elegir cuáles documentar"**.
+- If the user chooses to pick: follow the multiSelect batching pattern above to collect the exact set.
+
+### 2. Analyze sources
+
+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.
+
+### 3. Design the chapter plan
+
+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.
+
+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.
+
+### 4. Generate the guide
+
+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:
+
+- 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.
+- Troubleshooting, FAQ and glossary entries from all features are **merged** into their single files, deduplicated.
+- Every file links back to `index.md` and to its previous/next sibling.
+- 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.
+
+### 5. Record state
+
+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.
+
+### 6. Validate, then confirm
+
+Self-check before presenting (fix silently, don't ask the user to review defects):
+- Every planned file exists, is non-empty, and is reachable from `index.md`; the prev/next chain is unbroken.
+- Every selected feature appears in exactly one chapter.
+- Mermaid blocks are syntactically valid with Spanish labels; screenshot IDs are unique, `UPPER_SNAKE_CASE`, and all listed in their file's screenshot index.
+- No TODO/TBD markers or empty sections; manifest matches what's on disk.
+
+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.
+
+---
+
+## Maintenance run
+
+### 1. Show guide state
+
+Read `_guide-manifest.yaml` and summarize briefly: N features documented across M chapters, last update date.
+
+### 2. Ask what to do
+
+AskUserQuestion — **"Ya existe una guía para {project}. ¿Qué deseas hacer?"**:
+- **"Documentar nuevos features"** — add features completed since the guide was built
+- **"Re-documentar un feature existente"** — refresh features whose behavior may have changed
+- **"Salir"** — nothing to do
+
+### 3a. Document new features
+
+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).
+
+Integrate **coherently with the existing guide** — this is the difference from a first run:
+- Read the existing `index.md` and chapter files first to match tone, terminology and structure.
+- 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.
+- Merge the feature's FAQ/troubleshooting/glossary entries into the shared files without duplicating existing entries.
+- Add the feature to the manifest with today's date and the current HEAD SHA.
+
+### 3b. Re-document existing features
+
+Let the user pick which documented feature(s) to refresh (multiSelect batches from the manifest list).
+
+For each one, inspect what changed since it was documented:
+1. Take `documented_at_commit` from the manifest.
+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.)
+3. **No relevant changes found:** tell the user, and ask via AskUserQuestion whether to regenerate anyway ("Regenerar de todas formas" / "Omitir").
+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.
+5. Update the manifest entry (new date, new SHA).
+
+### 4. Validate and confirm
+
+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.
+
+---
+
+## Guardrails
+
+- The manifest (`_guide-manifest.yaml`) is internal state — never link it from `index.md` or mention it in guide content.
+- 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.
+- Don't invent features or behaviors not present in the sources. If a source is ambiguous, prefer omitting a claim over guessing.
+- 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

@@ -0,0 +1,267 @@
+# Templates — sa-user-guide-builder
+
+All generated content is Spanish. Placeholders in `{curly braces}` are resolved at generation time.
+
+## Table of contents
+
+1. [`_guide-manifest.yaml`](#_guide-manifestyaml)
+2. [`index.md`](#indexmd)
+3. [`01-introduccion.md`](#01-introduccionmd)
+4. [`02-primeros-pasos.md`](#02-primeros-pasosmd)
+5. [Thematic chapter file](#thematic-chapter-file)
+6. [Shared tail files (troubleshooting / FAQ / glossary)](#shared-tail-files)
+
+---
+
+## `_guide-manifest.yaml`
+
+Internal state file. Never linked from the guide, never shown to the end user.
+
+```yaml
+project_name: "{Project Name}"
+created: "{YYYY-MM-DD}"
+last_updated: "{YYYY-MM-DD}"
+files:
+  - index.md
+  - 01-introduccion.md
+  - 02-primeros-pasos.md
+  - 03-{tema-1}.md
+  # ... every file of the guide, in order
+features:
+  - feature: 1
+    slug: "calendar"                    # from the epic source filename: epic-feat-{F}-{slug}.md
+    title: "Calendario"
+    chapter_file: "03-calendario.md"
+    documented_date: "{YYYY-MM-DD}"
+    documented_at_commit: "{full git SHA of HEAD when documented}"
+    epics_documented: ["epic-1-1", "epic-1-2", "epic-1-3", "epic-1-4"]   # only the epics that were `done` in sprint-status.yaml
+    sources:
+      - "_bmad-output/planning-artifacts/epics/epic-feat-1-calendar.md"  # from epic-{F}-{E}-source
+      - "_bmad-output/planning-artifacts/prd/feature-calendar.md"        # only if it exists
+    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
+```
+
+`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.
+
+---
+
+## `index.md`
+
+```markdown
+---
+project: {project_name}
+generated_date: {YYYY-MM-DD}
+last_updated: {YYYY-MM-DD}
+audience: Usuario final no técnico
+type: indice-guia-usuario
+---
+
+# Guía de Usuario de {Proyecto}
+
+Manual de usuario final. Esta guía reúne, de forma coherente, toda la documentación de uso del sistema.
+
+## ¿Qué es {Proyecto}?
+
+{2-3 frases. Qué hace y para quién es. Sin términos técnicos.}
+
+## Contenido
+
+1. [Introducción](01-introduccion.md)
+2. [Primeros Pasos](02-primeros-pasos.md)
+3. [{Capítulo temático 1}](03-{tema-1}.md)
+4. [{Capítulo temático 2}](04-{tema-2}.md)
+{...}
+N. [Solución de Problemas](NN-solucion-de-problemas.md)
+N. [Preguntas Frecuentes](NN-preguntas-frecuentes.md)
+N. [Glosario](NN-glosario.md)
+```
+
+---
+
+## `01-introduccion.md`
+
+```markdown
+---
+project: {project_name}
+chapter: Introducción
+generated_date: {YYYY-MM-DD}
+audience: Usuario final no técnico
+sources:
+  - {source-path-1}
+---
+
+[⬅️ Índice](index.md)
+
+# Introducción
+
+## ¿Qué es {Proyecto}?
+
+{2-3 párrafos: qué hace, qué problema resuelve, valor para el usuario.}
+
+## ¿Para quién es esta guía?
+
+{1 párrafo. Perfil del lector: profesional de negocio cómodo con aplicaciones, sin perfil técnico.}
+
+## Cómo usar esta guía
+
+{Estructura de la guía y cómo navegar entre capítulos.}
+
+**Convenciones:**
+- 📸 **[Screenshot: ID — Descripción]**: lugar donde irá una captura de pantalla
+- ⚠️ **Advertencia**: información importante antes de realizar una acción
+- 💡 **Tip**: consejo útil
+
+---
+[Índice](index.md) · [Siguiente ➡️](02-primeros-pasos.md)
+```
+
+---
+
+## `02-primeros-pasos.md`
+
+Access, login and navigation live here **once** — chapters link here instead of repeating it.
+
+```markdown
+---
+project: {project_name}
+chapter: Primeros Pasos
+generated_date: {YYYY-MM-DD}
+audience: Usuario final no técnico
+sources:
+  - {source-path-1}
+---
+
+[⬅️ Índice](index.md)
+
+# Primeros Pasos
+
+## Acceso al sistema
+
+{Pasos numerados: URL/aplicación, inicio de sesión.}
+
+📸 [Screenshot: UI_LOGIN — Pantalla de inicio de sesión]
+
+## Navegación general
+
+{Cómo está organizada la pantalla principal, en lenguaje visual simple.}
+
+📸 [Screenshot: UI_DASHBOARD — Vista general]
+
+```mermaid
+flowchart LR
+    A[Iniciar sesión] --> B[Pantalla principal]
+    B --> C[{Módulo 1}]
+    B --> D[{Módulo 2}]
+```
+
+## Índice de capturas de este capítulo
+
+| ID | Descripción | Estado |
+|----|-------------|--------|
+| UI_LOGIN | Pantalla de inicio de sesión | Pendiente |
+| UI_DASHBOARD | Vista general | Pendiente |
+
+---
+[⬅️ Anterior](01-introduccion.md) · [Índice](index.md) · [Siguiente ➡️](03-{tema-1}.md)
+```
+
+---
+
+## Thematic chapter file
+
+One file per thematic chapter (`03-{tema}.md`, `04-{tema}.md`, …). Groups one or more related features.
+
+```markdown
+---
+project: {project_name}
+chapter: {Nombre del capítulo}
+generated_date: {YYYY-MM-DD}
+last_updated: {YYYY-MM-DD}
+audience: Usuario final no técnico
+features: [{F1}, {F4}]
+sources:
+  - {source-path-1}
+  - {source-path-2}
+---
+
+[⬅️ Índice](index.md)
+
+# {Nombre del Capítulo}
+
+{1-2 frases: qué cubre este capítulo y cuándo lo necesitas.}
+
+## {Funcionalidad 1}
+
+### ¿Qué es?
+{Un párrafo. Descripción simple.}
+
+### ¿Para qué sirve?
+{El beneficio práctico para el usuario.}
+
+### ¿Cómo se usa?
+1. {Acción clara por paso.}
+2. ⚠️ {Advertencia en línea justo antes del paso riesgoso, si aplica.}
+3. {...}
+
+📸 [Screenshot: {FEATURE_ID}_{PASO} — Descripción]
+
+{Si el flujo tiene decisiones o ramas, incluye un diagrama con labels en español:}
+
+```mermaid
+flowchart TD
+    Inicio --> Paso1[{Acción 1}]
+    Paso1 --> Decision{{"¿Condición?"}}
+    Decision -->|Sí| Paso2[{Acción 2}]
+    Decision -->|No| Fin
+    Paso2 --> Fin
+```
+
+## {Funcionalidad 2}
+{misma estructura}
+
+## Índice de capturas de este capítulo
+
+| ID | Descripción | Estado |
+|----|-------------|--------|
+| {ID} | {Descripción} | Pendiente |
+
+---
+[⬅️ Anterior]({archivo-anterior}.md) · [Índice](index.md) · [Siguiente ➡️]({archivo-siguiente}.md)
+```
+
+---
+
+## Shared tail files
+
+### `NN-solucion-de-problemas.md`
+
+Merged from ALL features, deduplicated, grouped by symptom the user experiences (not by feature).
+
+```markdown
+[⬅️ Índice](index.md)
+
+# Solución de Problemas
+
+## {Problema en palabras del usuario}
+
+**Qué ves:** {síntoma}
+**Qué hacer:**
+1. {paso}
+2. {paso}
+
+## Mensajes comunes
+
+| Mensaje que aparece | Qué significa | Qué hacer |
+|---|---|---|
+| {mensaje} | {significado simple} | {acción} |
+```
+
+### `NN-preguntas-frecuentes.md`
+
+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.
+
+### `NN-glosario.md`
+
+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.
+
+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

@@ -0,0 +1,54 @@
+# Writing Style — sa-user-guide-builder
+
+The reader is comfortable with a smartphone but has no software background. Everything below exists to protect that reader.
+
+## Voice and language
+
+- Spanish, active voice, direct instructions: "Haz clic en…", "Escribe…", "Selecciona…".
+- Short sentences. If a sentence needs a comma to explain a technical concept, rewrite it.
+- One clear action per numbered step.
+- If a concept gives the end user no practical value, drop it.
+- ⚠️ warnings go inline, immediately **before** the step that can cause the problem — a warning after the mistake is decoration.
+- Explain a term the first time it appears (or link to the glossary); after that, just use it.
+
+## What to keep, transform, and omit from the sources
+
+**Keep (rewritten in plain language):** feature purpose, step-by-step flows, key concepts, troubleshooting, FAQ, and the practical implication of every warning.
+
+**Transform:**
+
+| Source element | Treatment in the guide |
+|---|---|
+| `deep linking` / unique URL per record | "Cada registro tiene su propia dirección web que puedes guardar o compartir" |
+| Component names (`ContactManager`, `EmptyState`, `ErrorPanel`, …) | Remove the name; describe what the user sees |
+| `NIT/RUC` | Keep it — explain once: "número de identificación tributaria (NIT/RUC)" |
+| `Toast` notification | "mensaje de confirmación que aparece brevemente en pantalla" |
+| Retry button on error | "si aparece un error, haz clic en Reintentar" |
+| Two-column panel | "La pantalla se divide en dos partes: a la izquierda la lista, a la derecha el detalle" |
+| Inline validation | "mensajes de error junto al campo que necesita corrección" |
+| GWT scenarios (Given/When/Then) | Rewrite as numbered user steps — never show the GWT wording |
+
+**Omit from the body (traceability lives in frontmatter `sources:` and the manifest):**
+- `[Source: FX Story Y.Z]` tags
+- Implementation details, API names, architecture references
+- `*Generado: ...*` footers from source docs
+
+## Mermaid diagrams
+
+- Include a diagram only when the flow has decisions, branches, or 4+ steps — a linear 2-step action doesn't need one.
+- All node labels in Spanish, phrased as user actions or screens ("Iniciar sesión", "¿Guardar cambios?"), never component or endpoint names.
+- Keep diagrams small: if a flow needs more than ~10 nodes, split the section instead.
+
+## Screenshot placeholders
+
+- Format: `📸 [Screenshot: ID — Descripción en español]`
+- 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).
+- Place one at each visually meaningful step — the screen the user must recognize before acting.
+- 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.
+
+## Coherence across files (the point of consolidation)
+
+- Access, login and navigation are explained once in `02-primeros-pasos.md`; chapters link there.
+- Shared concepts are defined once (introduction or glossary) and referenced with relative links.
+- FAQ, troubleshooting and glossary are single merged files — before adding an entry during maintenance, check it isn't already there under different wording.
+- 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

@@ -1,6 +0,0 @@
----
-name: sa-create-user-guide
-description: 'Genera guías de usuario comprehensivas en español e inglés desde épicas y PRDs, con diagramas Mermaid y trazabilidad completa'
----
-
-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

@@ -1,240 +0,0 @@
----
-name: sa-delivery-guides
-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.
----
-
-# Delivery Agent Guides — Consolidador
-
-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.
-
-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.
-
-**El MCP es la única fuente de contenido. No se escanea el sistema de archivos local.**
-
----
-
-## Herramientas del MCP disponibles (úsalas tal cual)
-
-El servidor `mcp-siesa-docs` expone **solo tres** herramientas. **No existe `get_document`** — no la llames.
-
-- `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).
-- `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.**
-- `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>" }`).
-
-> ⚠️ 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.
-
----
-
-## Flujo
-
-### Paso 1: Descubrir proyectos con guías de usuario (automático)
-
-Apenas se invoca la skill, sin preguntar primero:
-
-1. **Saluda con un mensaje de bienvenida** antes de cualquier llamada técnica. Una sola frase cálida y no técnica, p. ej.:
-   > 👋 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.
-
-   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.
-2. `list_collections()` para confirmar que **`siesa-docs`** está disponible.
-3. `list_projects()` y filtra los que tengan **`has_user_guide: true`**.
-4. Presenta los proyectos usando la herramienta **`AskUserQuestion`** (menú con selección por flechas, el usuario no escribe su opción):
-   - `header`: "Proyecto"
-   - `question`: "¿Para cuál proyecto quieres generar la guía consolidada de usuario final?"
-   - `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}").
-   - `multiSelect`: false
-   - **Nunca** muestres el número de fragmentos ni `document_count` — es un dato técnico que no le interesa al usuario.
-5. Toma la respuesta del menú como el proyecto seleccionado.
-
-Si ninguno califica, dilo claramente ("No encontré proyectos con guías de usuario indexadas en el MCP") y detente (no presentes el menú).
-
----
-
-### Paso 2: Mapear las guías por feature del proyecto
-
-Objetivo: saber qué features/áreas cubre el proyecto, recuperando los chunks de sus guías de usuario.
-
-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:
-   - `"guía de usuario funcionalidades del sistema"`
-   - `"cómo se usa pasos flujos de trabajo"`
-   - `"preguntas frecuentes y solución de problemas"`
-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.
-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.
-
-Si el barrido devuelve muy pocos chunks, repite con consultas más específicas por nombre de feature detectado.
-
----
-
-### Paso 3: Diseñar la estructura del manual (capítulos)
-
-Aplica una arquitectura de información orientada a la **necesidad del usuario** (Diátaxis simplificado), no un archivo por feature suelto:
-
-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".
-2. Define el conjunto de archivos a crear. Estructura recomendada (ajústala al tamaño real del proyecto):
-   - `index.md` — portada + tabla de contenidos enlazada
-   - `01-introduccion.md` — qué es el sistema y para qué sirve
-   - `02-primeros-pasos.md` — acceso, primer ingreso, navegación general
-   - `03-{area-1}.md`, `04-{area-2}.md`, … — un archivo por capítulo temático
-   - `NN-solucion-de-problemas.md`
-   - `NN-preguntas-frecuentes.md`
-   - `NN-glosario.md`
-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.
-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).
-
-> ❌ **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.
-
----
-
-### Paso 4: Generar los archivos del manual
-
-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).
-
-**Contenido a conservar y reescribir en lenguaje sencillo:**
-- Nombre y propósito de cada funcionalidad
-- Flujos paso a paso
-- Conceptos clave y definiciones (simplificadas)
-- Solución de problemas y FAQ
-- Advertencias (⚠️) — reformula sin detalle técnico; conserva la implicación práctica
-
-**Contenido a transformar:**
-- Diagramas Mermaid → reescríbelos como una o dos frases que describan el flujo. **Nunca emitas sintaxis Mermaid.**
-
-**Contenido a omitir:**
-- Placeholders `📸 [Screenshot: ...]`
-- Referencias de trazabilidad `[Source: FX Story Y.Z]`
-- Tablas de índice de capturas
-- Nombres de componentes de implementación (ContactManager, EmptyState, ErrorPanel, etc.) — describe el comportamiento
-- Pies `*Generado: ...`
-
-**Coherencia entre archivos (clave de la consolidación):**
-- 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.
-- El acceso/login/navegación va **una vez** en `02-primeros-pasos.md`, no en cada capítulo.
-- FAQ y Solución de Problemas se **fusionan** de todas las features en sus archivos únicos, sin repetir preguntas.
-- Cada archivo enlaza al anterior/siguiente y de vuelta al `index.md` con enlaces relativos Markdown.
-
-**Plantilla de un archivo de capítulo:**
-```markdown
----
-project: {proyecto}
-chapter: {nombre del capítulo}
-generated_date: {YYYY-MM-DD}
-audience: Usuario final no técnico
-sources:
-  - {mcp-path-1}
-  - {mcp-path-2}
----
-
-[⬅️ Índice](index.md)
-
-# {Nombre del Capítulo}
-
-## {Funcionalidad 1}
-
-### ¿Qué es?
-Un párrafo. Descripción simple.
-
-### ¿Para qué sirve?
-El beneficio práctico para el usuario.
-
-### ¿Cómo se usa?
-Pasos numerados. Una acción clara por paso.
-Incluye advertencias en línea (⚠️ ...) justo antes del paso que puede causar un problema.
-
-## {Funcionalidad 2}
-(misma estructura)
-
----
-[⬅️ Anterior]({archivo-anterior}.md) · [Índice](index.md) · [Siguiente ➡️]({archivo-siguiente}.md)
-```
-
-**Plantilla de `index.md`:**
-```markdown
----
-project: {proyecto}
-generated_date: {YYYY-MM-DD}
-audience: Usuario final no técnico
-type: indice-consolidado
-sources:
-  - {mcp-path-1}
-  - {mcp-path-2}
----
-
-# Guía de Usuario de {Proyecto}
-
-Manual de usuario final. Esta guía reúne, de forma coherente, toda la documentación de uso del sistema.
-
-## ¿Qué es {Proyecto}?
-2-3 frases. Qué hace y para quién es. Sin términos técnicos.
-
-## Contenido
-
-1. [Introducción](01-introduccion.md)
-2. [Primeros Pasos](02-primeros-pasos.md)
-3. [{Capítulo temático 1}](03-{area-1}.md)
-4. [{Capítulo temático 2}](04-{area-2}.md)
-...
-N. [Solución de Problemas](NN-solucion-de-problemas.md)
-N. [Preguntas Frecuentes](NN-preguntas-frecuentes.md)
-N. [Glosario](NN-glosario.md)
-```
-
-**Guías de redacción:**
-- Lector cómodo con un smartphone pero sin formación en software.
-- Voz activa, instrucciones directas: "Haz clic en...", "Escribe...", "Selecciona..."
-- Frases cortas. Si una frase necesita una coma para explicar un concepto técnico, reescríbela.
-- Si un concepto no aporta valor práctico al usuario final, elimínalo.
-
----
-
-### Paso 5: Guardar y confirmar
-
-Guarda todo en la carpeta del proyecto:
-```
-_bmad-output/documentation-artifacts/delivery-guides/{proyecto}/
-├── index.md
-├── 01-introduccion.md
-├── 02-primeros-pasos.md
-├── 03-{area-1}.md
-├── ...
-├── NN-solucion-de-problemas.md
-├── NN-preguntas-frecuentes.md
-└── NN-glosario.md
-```
-
-Crea la carpeta si no existe.
-
-Luego confirma:
-```
-Guía consolidada guardada en: _bmad-output/documentation-artifacts/delivery-guides/{proyecto}/
-
-Archivos generados:
-  - index.md
-  - 01-introduccion.md
-  - 02-primeros-pasos.md
-  - {capítulos...}
-  - NN-glosario.md
-
-Capítulos / features incluidos:
-  - {capítulo 1}: {features que agrupa}
-  - {capítulo 2}: {features que agrupa}
-
-Fuentes del MCP:
-  - {mcp-path-1}
-  - {mcp-path-2}
-```
-
----
-
-## Referencia de Transformación
-
-| Elemento técnico | Tratamiento en la guía |
-|---|---|
-| `deep linking` / URL única por registro | "Cada registro tiene su propia dirección web que puedes guardar o compartir" |
-| `ContactManager`, `EmptyState`, `ErrorPanel` | Quita el nombre; describe lo que el usuario ve |
-| `NIT/RUC` | Consérvalo — explícalo una vez: "número de identificación tributaria (NIT/RUC)" |
-| Notificación `Toast` | "mensaje de confirmación que aparece brevemente en pantalla" |
-| Botón Reintentar ante error | "si aparece un error, haz clic en Reintentar" |
-| Panel de dos columnas | "La pantalla se divide en dos partes: a la izquierda la lista, a la derecha el detalle" |
-| Validación inline | "mensajes de error junto al campo que necesita corrección" |
-| Bloque de código Mermaid | Una o dos frases que describan el flujo |
-| `[Source: FX Story Y.Z]` | Omitir |
-| `📸 [Screenshot: ...]` | Omitir |