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).

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.