--- name: design-define description: "Crear o actualizar documentación técnica (modelos de datos, grupos de APIs/endpoints, flujos/procesos, diagramas de clases/C4) en docs/architecture/, organizada por capability, como referencia de implementación de US-XXX, TK-XXX y WI-XXX; y generar y revisar con el usuario los wireframes de pantalla (WF-XXX: .md + SVG en escala de grises) que viven en wireframes/ del SRS, US o WI que los origina. Activar cuando el usuario pida documentar o especificar un modelo, entidad, DTO, contrato de API, endpoint, flujo, proceso técnico o diagrama; cuando pida un wireframe, mockup o boceto de una pantalla; cuando pida «más detalle» sobre un elemento técnico sin especificación citado en una US, TK o WI; o cuando otro skill (requirement-refine, work-define, work-plan) delegue la especificación técnica o los wireframes. También con «/design-define», «documento técnico», «technical doc», «especificación técnica», «diseño técnico» o «wireframe», aunque no se nombre la capability." license: MIT --- # Skill: Documentación técnica por capability Guía para **crear o actualizar** la documentación técnica en `docs/architecture/`. Cada **capability** (una capacidad del sistema: facturación, autenticación, catálogo…) tiene su **carpeta** `[capability]/` con un `README.md` que actúa como **índice** —propósito, tablas de elementos y observaciones— y las subcarpetas `models/`, `apis/`, `flows/` y `diagrams/` con un archivo por **modelo de datos**, por **grupo de APIs/endpoints**, por **flujo/proceso** y por **diagrama** (clases, contexto, contenedores, componentes…), enlazados desde el README. Todos los elementos llevan id identificable (`MD-XXX`, `API-XXX`, `FL-XXX`, `DG-XXX`) que las US, TK y WI enlazan como referencia de implementación. Este skill es además el **único productor de wireframes de pantalla (`WF-XXX`)** del catálogo: un documento `wireframes/WF-XXX-{slug}.md` más su SVG hermano, mockup de baja/media fidelidad en escala de grises que se valida con el usuario por lote. A diferencia de los elementos de capability, un `WF-XXX` **no vive en `docs/architecture/`**: es un recurso del artefacto que lo origina (SRS, US o WI) y se escribe en la carpeta `wireframes/` de ese artefacto; `requirement-refine` y `work-define` lo piden a este skill mediante subagente y solo registran en su artefacto las rutas y el estado devueltos (ver [Flujo: Wireframes](references/flow.md#flujo-wireframes-wf-xxx)). > **Repositorio solo de pruebas (`implementation.scope: tests`): este skill NO diseña.** No se producen wireframes `WF-XXX`, ni diseño de alta fidelidad, ni modelos, diagramas, flujos o `API-XXX` del **sistema bajo prueba**: ese sistema se diseña e implementa en otro repositorio y aquí no se infiere nada sobre él. Si una prueba visual, E2E o de API necesita conocer una pantalla, un flujo o un contrato, se **solicita al usuario** el material existente (wireframes, diseños, Figma, especificación de API, acceso al sistema desplegado vía MCP) y se **documenta tal cual lo entrega** en `docs/architecture/` como material de referencia, marcando su origen («aportado por el usuario el , no diseñado aquí») y sin completar huecos. Si el usuario no dispone del material, se registra la carencia en Observaciones del artefacto que lo pedía y se continúa; nunca se dibuja ni se propone una alternativa. Lo único que este skill puede describir por cuenta propia es la **arquitectura del propio repositorio de pruebas** (estructura de specs, page objects, configuración). Contrato en [`${PLUGIN_ROOT}/references/implementation.md`](../../references/implementation.md#modo-pruebas-implementationscope-tests--contrato-para-el-catálogo). Un `API-XXX` **no es un endpoint suelto: es un grupo de endpoints de una misma entidad o funcionalidad** — todo el CRUD de proyectos y sus endpoints relacionados en `apis/API-001-proyectos.md`; `login`, `logout`, `refresh` y `forgot-password` en `apis/API-002-autenticacion.md`. Dentro del archivo, cada operación es una sección con su ancla de método+ruta. > **Alcance:** este skill produce **especificación técnica**, no documentación funcional ni código. El valor de negocio y los criterios de aceptación viven en la US (`work-define`); el plan de implementación vive en las TK/WI (`work-plan`); las decisiones de arquitectura viven en ADRs (`docs/adr/`, nunca creados desde aquí). Un documento técnico describe **qué forma tienen** los modelos, contratos y flujos — no por qué se eligió una tecnología ni cómo se codifica. Los wireframes son la única salida de este skill en lenguaje de experiencia (qué ve y hace el usuario), y por eso se revisan con el usuario en ese lenguaje; el impacto de sus observaciones en `FR-XXX`/`AC-XXX` lo aplica el skill dueño del artefacto, nunca este. Las plantillas canónicas están en `assets/`: `capability-readme-template.md` (el README índice de la capability), `model-template.md` (cada archivo de `models/`), `api-template.md` (cada archivo de `apis/`), `flow-template.md` (cada archivo de `flows/`), `diagram-template.md` (cada archivo de `diagrams/`) y `wireframe-template.md` (cada `WF-XXX-{slug}.md` de la carpeta `wireframes/` del artefacto de origen) — léelas antes de escribir. Los estándares de cada tipo de elemento están en `references/element-standards.md`. ## Subagente **Si el proyecto define el subagente `docs-specialist`, ejecutar este skill bajo ese subagente.** Si no existe en el proyecto: - **Invocación directa por el usuario:** ejecutar el flujo normalmente, sin subagente. - **Invocación desde otro skill** (`requirement-refine`, `work-define`, `work-plan`): ejecutar este skill bajo un **subagente genérico** (el de propósito general que exponga el cliente). La delegación siempre ocurre en un subagente — con `docs-specialist` si existe, genérico si no — para aislar el contexto del skill llamador y que la respuesta final sea solo las referencias devueltas. Este skill es frecuentemente **invocado por otros skills mediante un subagente** (`requirement-refine` y `work-define` para generar y revisar los wireframes de un SRS o una US con UI; `work-define` al detectar que una US define flujos, modelos o APIs; `work-plan` cuando una TK/WI menciona elementos técnicos sin especificación). En ese modo, ver [Modo delegado](#modos-de-invocación). --- ## Mapa de referencias Carga el archivo correspondiente cuando vayas a ejecutar la tarea; el detalle íntegro vive en `references/`. | Necesitas… | Archivo | | ---------- | ------- | | Flujo paso a paso de **crear** y **actualizar**, grilling de preguntas, validación antes de crear, modo delegado, checklist, ejemplos, anti-patrones y handoffs | [`references/flow.md`](references/flow.md) | | **Flujo de wireframes** (`WF-XXX`): generación por lote de todas las pantallas, presentación, una sola pregunta de aprobación, vueltas de revisión, historial, y lo que se devuelve al skill llamador | [`references/flow.md`](references/flow.md#flujo-wireframes-wf-xxx) | | Estándares de definición de **modelos de datos** (`MD-XXX`), **grupos de APIs/endpoints** (`API-XXX`: criterio de agrupación, ancla de operación), **flujos/procesos** (`FL-XXX`), **diagramas** (`DG-XXX`: clases, contexto, contenedores, componentes) y **wireframes** (`WF-XXX`: ubicación, fidelidad, `viewBox`, estados, revisión): tablas, diagramas Mermaid, ejemplos | [`references/element-standards.md`](references/element-standards.md) | | Estructura de la carpeta de capability (README índice, modelos, APIs, flujos, diagramas) | `assets/capability-readme-template.md` · `assets/model-template.md` · `assets/api-template.md` · `assets/flow-template.md` · `assets/diagram-template.md` | | Estructura del documento de un wireframe de pantalla (`WF-XXX-{slug}.md`, con su SVG hermano enlazado) | [`assets/wireframe-template.md`](assets/wireframe-template.md) | ### Referencias compartidas del plugin Reglas transversales del catálogo; viven en la raíz del plugin, no en este skill. - [`${PLUGIN_ROOT}/references/language.md`](../../references/language.md): **Idioma** — resolución obligatoria del idioma de artefactos, documentos y mensajes. *Lectura obligatoria antes de ejecutar el skill.* - [`${PLUGIN_ROOT}/references/linking.md`](../../references/linking.md): **Enlaces** — toda referencia a un archivo del proyecto se escribe como enlace que lo abre. *Lectura obligatoria antes de ejecutar el skill.* - [`${PLUGIN_ROOT}/references/artifacts.md`](../../references/artifacts.md): **Artefactos** — rutas del harness, identificadores, archivado. *Al resolver una ruta o calcular un ID.* --- ## Rutas de las referencias compartidas `${PLUGIN_ROOT}` es la **raíz del plugin instalado** (la carpeta que contiene `skills/`, `agents/` y `references/`), y toda referencia compartida de este skill se escribe como `${PLUGIN_ROOT}/references/.md`. Para resolverla: la raíz es la **carpeta desde la que se cargó este archivo**, dos niveles arriba (`/skills//SKILL.md`) — el cliente anuncia esa ubicación al invocar el skill (p. ej. «Base directory for this skill: …»). Si esa ubicación no está disponible, localizar la instalación buscando el manifiesto del plugin: `PLUGIN_ROOT="$(dirname "$(grep -rl '\"name\": *\"sdd-devkit\"' "$HOME/.claude/plugins" --include=plugin.json 2>/dev/null | head -1)")"`. En ambos casos, **verificar antes de usarla** que `$PLUGIN_ROOT/references/language.md` existe. El destino de cada enlace markdown (`../../references/…`) existe solo para navegar el repositorio en GitHub o en un editor: **no** resolverlo desde el directorio de trabajo. **Nunca buscar `references/` en el proyecto**: un `/references/language.md` que no existe no es un archivo que falte, es una ruta mal resuelta — corregir la raíz y volver a leer, sin preguntar al usuario ni saltarse la lectura. ## Resolución de idioma Antes de ejecutar este skill, DEBES leer [`${PLUGIN_ROOT}/references/language.md`](../../references/language.md). Las reglas de `language.md` son obligatorias y tienen prioridad para determinar el idioma de todos los artefactos, documentos y mensajes generados por este skill. No continúes hasta haber leído y aplicado `language.md`. **Excepción deliberada:** los nombres de campos, rutas y payloads **no** siguen el idioma resuelto — siguen la convención del código existente (ver [`references/element-standards.md`](references/element-standards.md)). **Enlaces a archivos del proyecto:** DEBES leer y aplicar [`${PLUGIN_ROOT}/references/linking.md`](../../references/linking.md) — todo archivo o carpeta existente del proyecto que este skill mencione en un artefacto, documento o mensaje (identificadores como `US-XXX` o `WF-XXX`, rutas, índices) se escribe como enlace Markdown que lo abre. --- ## Ubicación de archivos Layout completo del harness e identificadores: [`${PLUGIN_ROOT}/references/artifacts.md`](../../references/artifacts.md). Lo propio de este skill: | Artefacto | Ruta | | --------- | ---- | | Carpeta de capability (**salida**) | `docs/architecture/[capability]/` | | Índice de la capability (propósito, tablas índice, observaciones) | `docs/architecture/[capability]/README.md` | | Modelos de datos (un archivo por modelo) | `docs/architecture/[capability]/models/MD-XXX-[slug].md` | | APIs / endpoints (un archivo por **grupo**: entidad o funcionalidad) | `docs/architecture/[capability]/apis/API-XXX-[slug].md` | | Flujos / procesos (un archivo por flujo) | `docs/architecture/[capability]/flows/FL-XXX-[slug].md` | | Diagramas (un archivo por diagrama) | `docs/architecture/[capability]/diagrams/DG-XXX-[slug].md` | | Archivos de apoyo (imágenes, esquemas exportados) | `docs/architecture/[capability]/assets/` | | Wireframes de pantalla (**salida**, solo en el flujo de wireframes) | `wireframes/WF-XXX-[slug].md` + `WF-XXX-[slug].svg` **dentro de la carpeta del artefacto de origen** (`SRS-XXX-…/`, `US-XXX-…/` o `WI-XXX-…/`, en ``) — son un recurso de ese artefacto, no de la capability: este skill los **crea y revisa** ahí con `assets/wireframe-template.md`, nunca en `docs/architecture/`, y nunca los indexa en el README de una capability; la fila de índice en el artefacto de origen (sección 11 del SRS, Referencias de la US/WI) la escribe el skill llamador con las rutas devueltas. Al documentar una capability, los lee como insumo de UI | | Glosario (opcional) | `docs/glossary.md` | ### Convenciones - **Una carpeta por capability.** Si la carpeta de la capability ya existe, se **actualiza** (se añaden o modifican elementos); nunca crear una segunda carpeta para la misma capability. - Nombre de la carpeta: capability en minúsculas, kebab-case, sin artículos ni palabras vacías. Ejemplos: `facturacion/`, `gestion-recetas/`, `autenticacion/`. - Cada elemento lleva id secuencial **por tipo**, único en el ámbito de la capability: modelos `MD-001, MD-002, …`; APIs `API-001, API-002, …`; flujos `FL-001, FL-002, …`; diagramas `DG-001, DG-002, …` — todos con **3 dígitos**, como los identificadores de artefactos del catálogo. No renumerar elementos existentes: los ids son estables porque otras historias y tareas ya pueden enlazarlos. - **Modelos, grupos de APIs, flujos y diagramas viven cada uno en su propio archivo**, en `models/`, `apis/`, `flows/` y `diagrams/`, nombrado con el estándar **`MD-XXX-{slug}` / `API-XXX-{slug}` / `FL-XXX-{slug}` / `DG-XXX-{slug}`** — `models/MD-001-factura.md`, `apis/API-001-facturas.md`, `flows/FL-001-emision-factura.md`, `diagrams/DG-002-contexto.md` — donde `{slug}` es el nombre del elemento en kebab-case, **fijado al crearlo**: renombrar el elemento después no renombra el archivo (el id sigue siendo el contrato de enlace; mismo criterio que las carpetas `US-XXX-[nombre-corto]`). Su referencia es la ruta del archivo, sin ancla: `docs/architecture/facturacion/apis/API-001-facturas.md`. El nombre humano vive en el `# {{ID}}: Nombre` del propio archivo y en las **tablas índice** del README («Modelos de datos», «APIs / Endpoints», «Flujos / Procesos» y «Diagramas»), que enlazan cada archivo — un elemento sin fila en su índice es un elemento huérfano. **El README no define elementos: es el índice.** - **Un `API-XXX` agrupa endpoints por entidad o funcionalidad**, no por operación: el CRUD completo de un recurso más sus endpoints relacionados va en un solo archivo (`apis/API-001-proyectos.md`), igual que `login`/`logout`/`refresh`/`forgot-password` van juntos en `apis/API-002-autenticacion.md`. Un endpoint pertenece a **un solo** grupo. Dentro del archivo, cada operación es un encabezado `###` con el formato `### \`MÉTODO /ruta\` — Nombre` precedido de su **ancla explícita** derivada de **método + ruta, sin el prefijo de versión**: se descartan los segmentos iniciales `api` y `vN` de la ruta, y el resto se pasa a minúsculas con todo carácter no alfanumérico convertido a guion (sin guiones repetidos ni al inicio/fin). `POST /api/v1/projects` → ``; `GET /api/v1/projects/{id}` → ``. El ancla no lleva versión **a propósito**: subir de `v1` a `v2` no debe invalidar los enlaces entrantes. Para citar un endpoint concreto se añade esa ancla a la ruta del archivo: `docs/architecture/proyectos/apis/API-001-proyectos.md#post-projects`. Nunca un ancla derivada del título de la operación: depende del renderizador y se rompe al renombrarla. Ver [Por qué el ancla no se deriva del título](references/element-standards.md#por-qué-el-ancla-no-se-deriva-del-título). - **Los wireframes no son parte de la capability, pero sí los produce este skill.** Un `WF-XXX` es un recurso del artefacto de implementación que lo origina (`wireframes/` dentro de la carpeta del SRS, la US o el WI); `requirement-refine` y `work-define` **nunca lo escriben**: delegan a este skill vía subagente y registran lo devuelto. `docs/architecture/` lo escribe **solo** `design-define`, sin excepciones, y no contiene wireframes ni índice de ellos. Id secuencial de 3 dígitos **dentro de la carpeta `wireframes/` del artefacto** (continuar la secuencia existente, sin renumerar), slug kebab-case fijado al crear, referencia por ruta de archivo sin ancla. Al documentar una capability, este skill los lee como insumo (pantallas ya validadas anticipan `FL-XXX`/`API-XXX`) y puede enlazarlos en Notas. Estándar completo: [Wireframes](references/element-standards.md#wireframes-wf-xxx). - El `README.md` lleva **fecha de creación** y **última actualización** de la capability. Las lagunas abiertas se registran en **Observaciones** del README, citando el elemento afectado esté donde esté. --- ## Modos de invocación | Modo | Quién invoca | Entrada típica | Salida esperada | | ---- | ------------ | -------------- | --------------- | | **Directo** | El usuario | «Documenta el modelo de factura», «especifica la API de pagos», «dame más detalle del flujo de aprobación de la TK-004» | Carpeta de capability creada/actualizada + resumen al usuario + oferta de enlazarla desde la US/TK/WI relacionada | | **Delegado** | `work-define` o `work-plan` vía subagente | Contexto de la US/TK/WI + los elementos técnicos a especificar | Carpeta creada/actualizada y, **como respuesta final del subagente, la lista de referencias** — la ruta del archivo de cada elemento en `models/`/`apis/`/`flows/`/`diagrams/`, más el ancla de operación (`#`) cuando se cita un endpoint concreto — para que el skill llamador las agregue a la sección Referencias del artefacto | | **Delegado — wireframes** | `requirement-refine` (SRS) o `work-define` (US) vía subagente; también el usuario en directo («haz el wireframe de la pantalla de login de la US-012») | Carpeta del artefacto de origen, tipo de solución y responsividad ya resueltos por el llamador, lista de pantallas (o los `FR-XXX`/`AC-XXX` para inferirlas), idioma | Archivos `wireframes/WF-XXX-{slug}.md` + `.svg` creados o actualizados en esa carpeta, **revisados con el usuario por lote dentro del subagente** hasta aprobación o pendiente explícito, y como respuesta final la lista de `WF-XXX` con ruta, estado de revisión y las observaciones que implican un requisito nuevo o modificado, para que el llamador las indexe y aplique a sus `FR-XXX`/`AC-XXX` — ver [Flujo: Wireframes](references/flow.md#flujo-wireframes-wf-xxx) | En modo delegado, el grilling de preguntas se dirige igualmente al usuario (el subagente hereda la herramienta de preguntas estructuradas); si el entorno no permite preguntar, documentar las lagunas en Observaciones y reportarlas en la respuesta final en lugar de inventar. **En modo directo**, si el entorno tampoco permite preguntar (p. ej. sesión desatendida/programada sin nadie que responda en el momento), aplicar el mismo criterio: no inventar, documentar cada laguna en Observaciones citando el elemento afectado, y destacarlas de forma prominente al principio del resumen final — a diferencia del modo delegado, aquí no hay un skill llamador que las recoja, así que es el propio resumen al usuario el único lugar donde quedan visibles. --- ## Cómo preguntar al usuario (grilling) Mecanismo, ritmo y fallback compartidos: [`${PLUGIN_ROOT}/references/asking.md`](../../references/asking.md). Cada vez que este skill o sus referencias digan *preguntar*, *pedir*, *confirmar*, *validar* o *sugerir* algo al usuario, asume ese mecanismo; no se repite allí. **Recopilación inicial (antes de redactar):** si hay más de tres lagunas, encadenar tandas hasta agotarlas o hasta que el usuario indique que lo restante quede como Observación. **No repreguntar** lo que ya está respondido en la US/TK/WI de origen o en el documento técnico existente. El detalle de **qué preguntar por tipo de elemento** (campos sin tipo, códigos de error sin definir, ramas de flujo ambiguas…) está en [`references/flow.md`](references/flow.md#grilling-por-tipo-de-elemento). --- ## Información requerida antes de redactar **No inventar nada** — si un dato no es explícito ni inferible del repo, preguntar al usuario (o reportarlo como laguna, en cualquier modo, cuando el entorno no permite preguntar — ver [Modos de invocación](#modos-de-invocación)). | Dato | Cómo obtenerlo | Si no está disponible | | ---- | -------------- | --------------------- | | **Capability** a la que pertenece el elemento | Indicada por el usuario/skill llamador, o inferible de la US/TK/WI y de los documentos existentes en `architecture/` | Preguntar; proponer opciones a partir de los documentos existentes antes de crear una capability nueva | | **Tipo(s) de elemento** (modelo, grupo de APIs, flujo, diagrama) | Del pedido o del contenido de la US/TK/WI | Preguntar | | **Grupo al que pertenece cada endpoint** (entidad o funcionalidad) | Del recurso que manipula el endpoint y de los grupos ya existentes en `apis/` | Proponer el grupo existente que lo cubra; si ninguno aplica, proponer el grupo nuevo y su nombre antes de crearlo | | **Contenido de cada elemento** (campos, contratos, pasos) | Del input recibido, del código existente del repo, o de la US/TK/WI de origen | Grilling de preguntas; lo irresoluble queda en Observaciones | | **Artefacto(s) que lo consumirán** (US/TK/WI) | Del contexto o del skill llamador | Opcional en modo directo; si existe, ofrecer enlazar la referencia al terminar | | **Solo wireframes — artefacto de origen** (carpeta del SRS/US/WI donde vivirá `wireframes/`) | Del skill llamador, o del artefacto que el usuario nombra | Preguntar; un wireframe sin artefacto de origen no tiene dónde vivir — nunca ubicarlo en `docs/architecture/` | | **Solo wireframes — tipo de solución y responsividad** (condicionan navegación y `viewBox`) | Del skill llamador (sección 11 del SRS, contexto de la US) | Inferir del artefacto; preguntar solo si queda ambiguo | | **Solo wireframes — pantallas a dibujar** | Del skill llamador, o inferidas de los `FR-XXX`/`AC-XXX` de categoría *Interacción de usuario* / *Salidas del sistema* | Preguntar qué pantallas hacen falta; resolver la lista completa antes de generar nada | --- ## Flujo (resumen) El procedimiento completo está en [`references/flow.md`](references/flow.md). Síntesis: - **Crear/actualizar:** resolver capability → leer la carpeta existente si la hay (README y archivos de `models/`, `apis/`, `flows/` y `diagrams/`) → detectar lagunas y hacer el grilling → redactar con las plantillas de `assets/` y los estándares de `references/element-standards.md`: cada modelo, grupo de APIs, flujo y diagrama en su archivo, enlazado desde los índices del README; los endpoints nuevos se añaden al grupo existente que los cubra antes de abrir uno nuevo → asignar ids estables → actualizar la fecha de última actualización → glosario si aplica. - **Wireframes:** resolver artefacto de origen, tipo de solución y pantallas → leer los `WF-*` ya existentes en su `wireframes/` (actualizar, no duplicar) → generar **todos** los `.md` + `.svg` de una vez con `assets/wireframe-template.md` → presentar el lote y preguntar **una sola vez** si hay cambios → aplicar cada cambio (SVG + Historial de cambios) y repetir hasta aprobar o dejar pendiente → devolver rutas, estados y observaciones con impacto en requisitos. Detalle en [Flujo: Wireframes](references/flow.md#flujo-wireframes-wf-xxx). - **Enlazar:** en modo delegado, devolver las referencias (ruta del archivo para MD/API/FL/DG, más `#` cuando se cita un endpoint concreto) al skill llamador; en modo directo, ofrecer agregar la referencia a la sección Referencias de la US/TK/WI relacionada. - **Cierre:** si quedaron lagunas en Observaciones, ofrecerle al usuario las preguntas que las cerrarían (misma mecánica de grilling). --- ## Mensaje al usuario Solo resultados y lo que el usuario debe saber o decidir. No incluir razonamiento interno ni narración del trabajo en curso («leí la US», «creé el archivo»). Si hay pendientes, listarlos agrupados por elemento (`MD-XXX`, `API-XXX`, `FL-XXX`, `DG-XXX`, `WF-XXX`), indicando la operación afectada cuando el pendiente sea de un endpoint concreto. En modo delegado, la respuesta final del subagente es **datos para el skill llamador** (rutas de archivo y, si aplica, anclas de operación; para wireframes, ruta + estado de revisión + observaciones con impacto en requisitos), no prosa para el humano. La excepción es la **presentación del lote de wireframes** durante la revisión: esa sí va dirigida al usuario (nombre y enlace de cada pantalla, imagen embebida si el entorno la renderiza), porque es él quien aprueba.