@tacuchi/agent-workflow-cli 11.0.1 → 12.2.0

package/skills/w/roles/testing/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: testing
+description: >
+  Estrategia y ejecución de pruebas: selecciona niveles (unit / integration / e2e),
+  resuelve comandos por stack detectado, guía la convención de nombres y estructura de tests.
+  Pregunta al humano antes de ejecutar; nunca lanza el test runner sin confirmación explícita.
+  Compuesta por plan-exec-loop y quick-loop durante la fase de validación de cambios.
+---
+
+# testing — Test strategy and execution capability
+
+## Role
+
+`testing` — implementación built-in por defecto. Rebindeable a otra skill (de tercero o `off`) en `.workflow/skills.toml`.
+
+## Purpose
+
+Dar a los loops la capacidad de razonar sobre tests: qué nivel aplicar, con qué comando, con qué convención. **No ejecuta tests de forma autónoma** — primero pregunta al humano si quiere que el loop los corra, o si los correrá manualmente, o si no hacen falta en esta sesión.
+
+## Composed by
+
+| Loop | Cuándo la compone |
+|---|---|
+| `plan-exec-loop` | durante validation de cada task ejecutada |
+| `quick-loop` | cuando el cambio quick requiere verificación |
+
+## Knowledge
+
+### Execution rule
+
+Por defecto, **no ejecutar pruebas automáticamente**. Antes de correr cualquier test runner:
+
+```
+AskUserQuestion:
+  "¿Correr los tests?"
+  [a] Sí, el loop los ejecuta
+  [b] Los corro yo manualmente
+  [c] No hace falta en esta sesión
+```
+
+Solo saltear la pregunta si el workspace declara `Validation mode: auto` en `.workflow/config.toml`.
+
+### Test levels
+
+Tres niveles universales (adaptados al stack detectado):
+
+| Nivel | Alcance | Cuándo usarlo |
+|---|---|---|
+| **a) Unit** | Lógica aislada (servicios, utils, mappers) | Fix puntual, lógica sin dependencias externas |
+| **b) Integration** | Unit + capa de API/controladores | Endpoint nuevo o modificado |
+| **c) Full** | Integration + contexto completo + e2e | Feature completa, flujo crítico, integración entre capas |
+
+### Stack resolution
+
+El stack se detecta por archivos de manifest presentes en el workspace. Precedencia: si el bloque `WORKSPACE → Stack` declara override de build/wrapper, usarlo.
+
+#### Spring Boot (Maven)
+
+| Nivel | Framework | Comando |
+|---|---|---|
+| a) Unit | JUnit 5 + Mockito | `./mvnw test -Dtest=ClaseTest` |
+| b) Integration | + MockMvc | `./mvnw test` |
+| c) Full | + @SpringBootTest | `./mvnw verify` |
+
+> Windows: `mvnw.cmd` en lugar de `./mvnw`.
+
+#### Spring Boot (Gradle)
+
+| Nivel | Comando |
+|---|---|
+| a) Unit | `./gradlew test --tests ClaseTest` |
+| b) Integration | `./gradlew test` |
+| c) Full | `./gradlew integrationTest` (o `check`) |
+
+#### Angular
+
+| Nivel | Framework | Comando |
+|---|---|---|
+| a) Unit | Jasmine + Karma (o Jest) | `ng test --watch=false` |
+| b) Integration | + TestBed + ComponentFixture | `ng test --watch=false` |
+| c) Full | + Cypress/Playwright si configurado | `npm run e2e` |
+
+#### Node / TypeScript genérico
+
+| Nivel | Comando |
+|---|---|
+| a) Unit | `npm test` (script `test` en `package.json`) |
+| b) Integration | `npm test` con suites de integración |
+| c) Full | `npm run test:e2e` o según config |
+
+#### Resolución automática
+
+1. `mvnw` / `mvnw.cmd` → Maven wrapper.
+2. `gradlew` → Gradle wrapper.
+3. `angular.json` → `ng test`.
+4. `package.json` con script `test` → `npm test`.
+5. Si hay override en `WORKSPACE → Stack` → usarlo.
+
+### Naming conventions
+
+**Java:** clase `[Objetivo]Test.java`, método `[metodo]_[escenario]_[resultado]`. Estructura Arrange-Act-Assert.
+
+```java
+@Test
+void enviar_conEmailValido_retornaExito() {
+    // Arrange
+    var request = new NotificacionRequest("user@example.com", "Asunto", "template", Map.of());
+    when(emailProvider.send(any())).thenReturn(true);
+    // Act
+    var resultado = service.enviar(request);
+    // Assert
+    assertThat(resultado).isTrue();
+}
+```
+
+**Angular / TypeScript:** archivo `[nombre].spec.ts`, bloques `describe` / `it`. Usar `TestBed` para componentes.
+
+```typescript
+describe('AuthService', () => {
+  it('should return token on login', () => {
+    // ...
+  });
+});
+```
+
+### Level selection prompt (to show the human)
+
+Adaptar al stack resuelto. Ejemplo para Spring Boot:
+
+```
+¿Qué nivel de pruebas aplicamos?
+  a) Unitarios       — JUnit 5 + Mockito (rápido, aislado)
+  b) Integración     — + MockMvc controllers
+  c) Completo        — + @SpringBootTest (contexto Spring completo)
+```
+
+El humano puede cambiar de nivel en cualquier momento o decidir no ejecutar desde el loop.
+
+### Execution and logging
+
+1. Confirmar que el humano quiere ejecución desde el loop (ver "Execution rule").
+2. Ejecutar el comando resuelto según stack y nivel.
+3. Registrar resultado en `TEST_LOG.md` **solo si** el humano pidió registro formal o la ejecución fue desde el loop.
+4. Si el humano ya validó manualmente, no repetir; anotar una línea breve si aporta trazabilidad.
+5. Si hay fallos y el humano quiere continuar: corregir y re-ejecutar.
+
+### TestBuilder pattern (Java)
+
+Para construir fixtures reutilizables sin acoplar los tests al constructor de producción:
+
+```java
+public class NotificacionTestBuilder {
+    private String destinatario = "test@example.com";
+    private String estado = "PENDIENTE";
+
+    public static NotificacionTestBuilder builder() { return new NotificacionTestBuilder(); }
+
+    public NotificacionTestBuilder destinatario(String val) { this.destinatario = val; return this; }
+    public NotificacionTestBuilder estado(String val) { this.estado = val; return this; }
+
+    public Notificacion build() {
+        var e = new Notificacion();
+        e.setDestinatario(destinatario);
+        e.setEstado(estado);
+        return e;
+    }
+}
+```
+
+## Output
+
+No produce artefactos de forma autónoma. Cuando el humano confirma ejecución:
+- Corre el comando resuelto y reporta el resultado inline.
+- Escribe `TEST_LOG.md` en la sesión activa solo si fue pedido explícitamente.
+
+No gradua a `docs/` (invariant #1).
+
+## Source
+
+Reciclado de `agent-workflow/standards/testing-strategy/` del bundle viejo (v0.1.0). Se conserva: los tres niveles (a/b/c), la regla de confirmación antes de ejecutar, la resolución de stack por manifest, los naming conventions, la tabla de comandos por framework. Se descarta: la referencia al bloque `AW-PROJECT → Stack` (reemplazado por `WORKSPACE → Stack`), el `TEST_LOG.md` obligatorio, el sandbox-readonly-rules legacy, referencias a `plan mode` del sistema anterior.

package/skills/w/roles/tools/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: tools
+description: >
+  Capacidad de autoría de herramientas y utilidades que el plan crea: scripts, CLIs, helpers,
+  configuraciones reutilizables. Produce el código de la herramienta y su documentación en
+  docs/tools/. Compuesta por plan-exec-loop cuando una task crea una utilidad nueva (no un
+  cambio de producto). No aplica a código de producto — solo a tooling auxiliar.
+---
+
+# tools — Tool authoring capability
+
+## Role
+
+`tools` — implementación built-in por defecto. Rebindeable a otra skill (de tercero o `off`) en `.workflow/skills.toml`.
+
+## Purpose
+
+Dar al `plan-exec-loop` la capacidad de crear herramientas y utilidades auxiliares con una estructura consistente: el código de la tool + su documentación en `docs/tools/`. Cubre scripts de automatización, CLIs auxiliares, helpers de CI/CD, configuraciones reutilizables, y cualquier artefacto de tooling que el plan genere como producto de una task.
+
+**Distinciones clave:**
+
+| Tipo | Rol | ¿Quién lo maneja? |
+|---|---|---|
+| Código de producto (services, controllers, components) | cambio en el repo fuente | `plan-exec-loop` + `coding-standards` |
+| Tool / utilidad auxiliar creada por el plan | herramienta de soporte | esta skill (`tools`) |
+| Script SQL de migración | dato persistente | `sql` + `export-scripts` |
+
+## Composed by
+
+| Loop | Cuándo la compone |
+|---|---|
+| `plan-exec-loop` | cuando una task del plan crea una herramienta nueva (helper, script CLI, configuración reutilizable) |
+
+## Knowledge
+
+### Tool vs. product code
+
+Una **tool** es cualquier artefacto que el plan crea para soportar el trabajo, no para el usuario final del producto:
+
+- Scripts de seed/fixtures para desarrollo local.
+- CLIs auxiliares (`validate-schema.js`, `sync-env.sh`).
+- Helpers de CI/CD (scripts de deploy, linters de configuración).
+- Configuraciones reutilizables (templates de entorno, fixtures de test).
+- Generadores o scaffolders para tareas repetitivas.
+
+Si el artefacto es lógica de negocio del producto → no es una tool, es código de producto.
+
+### Tool anatomy
+
+Cada tool tiene dos partes:
+
+1. **El código** — en el repo fuente apropiado (en su carpeta natural: `scripts/`, `tools/`, `bin/`, etc.).
+2. **La doc** — en `docs/tools/NNN-<slug>.md` del workspace (invariant #2: PLAN escribe `docs/tools`).
+
+### docs/tools/NNN-<slug>.md schema
+
+```markdown
+# <Nombre de la tool>
+
+> **Tipo**: <script | cli | helper | config-template | generator>
+> **Repo**: <alias de la fuente donde vive el código>
+> **Path**: <path relativo al repo>
+> **Creada en**: <sesion-slug>
+
+## Purpose
+
+[1-2 oraciones: qué hace y cuándo usarla.]
+
+## Usage
+
+```<lenguaje o bash>
+<ejemplo de invocación>
+```
+
+## Parameters
+
+| Param | Tipo | Requerido | Default | Descripcion |
+|---|---|---|---|---|
+| `--foo` | string | sí | — | ... |
+
+## Output
+
+[Qué produce: archivos, stdout, efectos secundarios.]
+
+## Dependencies
+
+- <prerequisito 1: binario, env var, servicio>
+- <prerequisito 2>
+
+## Examples
+
+```bash
+# Caso de uso principal
+./scripts/validate-schema.sh --env staging
+
+# Caso edge
+./scripts/validate-schema.sh --env staging --dry-run
+```
+
+## Notes
+
+[Advertencias, limitaciones, cuándo NO usar.]
+```
+
+### Numbering
+
+`docs/tools/` usa numeración secuencial `NNN` (001, 002, ...). Consultar el número siguiente con el filesystem antes de escribir; no asumir el siguiente en base a lo que el loop ya sabe.
+
+### Git-safe authoring (invariant #5)
+
+- Verificar la rama esperada antes de escribir código.
+- Proponer el commit; nunca hacer `push`/`--amend`/`--no-verify` autónomamente.
+- Si la tool modifica scripts ya existentes: leer el archivo completo primero.
+
+### DB scripts rule (invariant #4)
+
+Si la tool genera o manipula SQL:
+- Nunca generar DML/DDL que se ejecute inline — el SQL va a `SCRIPTS.sql` y se entrega vía `export-scripts`.
+- Una tool puede generar un archivo `.sql`; no puede ejecutarlo contra la BD.
+
+### Code quality baseline
+
+Al autorar el código de la tool, aplicar lo que la capacidad `coding-standards` del workspace establezca. Si `coding-standards` está `off` o no está configurada, usar los estándares del lenguaje detectado:
+- **Shell**: shellcheck-compatible, variables entre comillas, `set -euo pipefail`.
+- **Node/TS**: tipado explícito, sin `any` salvo justificación, error handling explícito.
+- **Python**: type hints, docstring en funciones públicas, manejo de excepciones específico.
+- **Java**: Javadoc mínimo en clases públicas, excepciones tipadas.
+
+### Self-contained tools
+
+Preferir tools que declaren explícitamente sus dependencias (en doc + en el propio script). Una tool que falla silenciosamente porque le falta un binario es peor que una que no existe.
+
+```bash
+# Pattern: check dependencies al inicio
+command -v jq >/dev/null 2>&1 || { echo "jq requerido: brew install jq"; exit 1; }
+```
+
+## Output
+
+Por cada tool creada:
+- **Código**: en el repo fuente, en la carpeta que corresponda (`scripts/`, `tools/`, `bin/`).
+- **Doc**: en `docs/tools/NNN-<slug>.md` del workspace.
+
+Writes `docs/tools/` (invariant #2: PLAN es el dueño de esta carpeta). No gradua a ninguna otra carpeta de `docs/`.
+
+## Source
+
+Autoria original (no hay skill equivalente en el bundle viejo). Basado en la descripción del rol en `workflow-skills/README.md` y en el invariant #2 del diseño (`docs/tools/` es del flujo PLAN). Las convenciones de estructura de doc (`## Purpose`, `## Usage`, `## Parameters`, `## Output`, `## Examples`) siguen el patrón de calidad del bundle.

package/skills/w/roles/ui-spec/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: ui-spec
+description: >-
+  UI spec authoring — built-in default for the `ui-design` capability. Given a UI
+  requirement, author a structured, framework-agnostic screen specification (the
+  universal `Screen` model in JSON) plus its readable Markdown render. Knows the
+  `Screen` schema, the kind/region vocabulary, the authoring rules, design-system /
+  theme / variant handling, and the exact Markdown render format. Use when a loop is
+  refining a spec that involves screens, forms, dashboards, modals or any UI surface
+  — primarily `spec-refine-loop`. Recycled from the `ui-spec-generator` service.
+---
+
+# ui-spec — UI spec authoring
+
+## Role
+
+`ui-design` — this is its **built-in default implementation**. Rebindable in `.workflow/skills.toml` to a third-party skill (installed via skills.sh) or `off`. Resolution: built-in default → `~/.workflow/skills.toml` (global) → `.workflow/skills.toml` (workspace).
+
+## Purpose
+
+Dado un requerimiento de UI, autorar una **especificación de pantalla estructurada** — un modelo universal, agnóstico de framework — más su render Markdown legible. **Reemplaza** al servicio single-shot `ui-spec-generator`: ahora la IA la autora **nativamente**, guiada por esta skill. No hay endpoint que llamar; el saber del servicio vive aquí.
+
+## Composed by
+
+La carga el **`spec-refine-loop`** (ver `../../loops/spec-refine-loop.md`) cuando el requerimiento involucra UI. El loop aporta lo que el servicio viejo no tenía:
+
+- **Pregunta al humano** (design-system, tema, ambigüedades de pantalla) vía `AskUserQuestion`.
+- **Itera** gap-driven hasta converger.
+- Ofrece **variantes** y **cura** el resultado.
+
+Cualquier loop podría componerla; el caso primario es SPEC. El `Screen` y su Markdown aterrizan como una sección dentro del documento spec (`docs/specs/NNN-spec.md`) — nunca como artefacto suelto (invariante 3: el spec es un documento).
+
+## Knowledge
+
+### Schema (modelo `Screen` — universal, recursivo)
+
+```
+Screen {
+  name: string             # nombre de la pantalla
+  purpose: string          # "tipo" semántico: auth, dashboard, form, list, detail, error, ...
+  platform: string         # web (default), mobile, ...
+  description?: string
+  regions?:   Region[]     # pantallas complejas
+  components?: Component[]  # pantallas simples
+}                          # usar regions O components, no ambos
+Region    { type: string, components: Component[] }
+Component { kind: string, role?: string, label?: string, children?: Component[] }  # recursive
+```
+
+- `type` (region) ∈ `header · main · footer · sidebar · filters · summary`
+- `kind` (component) por categoría:
+  - **Contenedores**: `card · panel · modal`
+  - **Datos**: `table · list · grid`
+  - **Visualización**: `chart · metric · badge · image`
+  - **Entrada**: `textInput · select · checkbox · datePicker · toggle`
+  - **Acciones**: `button · link · actionGroup`
+  - **Navegación**: `navBar · tabs · breadcrumb`
+  - **Feedback**: `alert · progress`
+
+JSON serializado en **camelCase**, **claves null omitidas** (no emitir `"description": null`).
+
+### Rules
+
+1. **Conciso** — solo lo esencial. Nada de relleno ni componentes especulativos.
+2. Pantalla simple (login, recuperar contraseña, error) → `components` directo, **sin** `regions`.
+3. Pantalla compleja (dashboard, mantenimiento CRUD) → `regions` para organizar.
+4. `role` es **opcional** — solo si aporta claridad (`role:"logo"`, `role:"primary"`).
+5. Límites: **≤100 componentes**, **≤5 niveles** de anidación.
+6. Un solo `Screen` por sección; si el requerimiento son varias pantallas, una sección por pantalla.
+
+### Design options (las pregunta el loop al humano)
+
+Estas opciones **guían contenido/labels**; el modelo `Screen` es **agnóstico** de design-system y NO las lleva como campos. Se **anotan en el spec** (encabezado de la sección), no en el JSON:
+
+- **Design system**: `material3 · bootstrap5 · tailwind3 · antDesign · chakraUI · custom`.
+- **Tema**: `light · dark · auto`.
+- **Idioma**: `es · en · …` (afecta los `label`).
+- **Densidad** (opcional): `compact · comfortable · spacious`.
+- **maxWidth** (opcional): pixeles, 320–3840 (anotación de layout).
+
+### Variants
+
+Cuando el requerimiento admite más de un layout razonable (ej. tabla vs. grid de cards; tabs vs. acordeón), ofrecer **2-3 variantes** como `Screen` alternativos y pedir al humano que elija. Una sola variante se cura y queda; las descartadas no se persisten.
+
+### Disambiguation
+
+Antes de autorar, resolver ambigüedades con `AskUserQuestion` (lo dispara el loop):
+
+- Pantalla simple o compleja (¿necesita `regions`?).
+- Qué acciones primarias/secundarias existen.
+- Qué datos muestra (tabla, métricas, ambos).
+- Si hay estados (loading, empty, error) que el spec deba enumerar.
+
+Si el humano no responde, asumir el caso más simple coherente con la descripción y anotar el supuesto.
+
+### Examples (few-shot)
+
+```json
+// Simple (sin regions)
+{"name":"Recuperar Contraseña","purpose":"auth","platform":"web","components":[{"kind":"image","role":"logo"},{"kind":"textInput","label":"Correo electrónico"},{"kind":"button","label":"Enviar enlace"},{"kind":"link","label":"Volver al login"}]}
+
+// Complejo (con regions)
+{"name":"Dashboard","purpose":"dashboard","platform":"web","regions":[{"type":"summary","components":[{"kind":"metric","label":"Total"},{"kind":"metric","label":"Pendientes"}]},{"type":"main","components":[{"kind":"table","label":"Registros"}]}]}
+```
+
+## Output — sección `## UI spec` dentro del spec (`docs/specs/NNN-spec.md`)
+
+La escribe el loop (no esta skill por sí sola). Encabezar la sección con las opciones de diseño elegidas (design system, tema, idioma) en una línea. Luego dos representaciones:
+
+1. **`Screen` (JSON)** — camelCase, claves null omitidas, en bloque ```json.
+2. **Markdown** — render legible (reglas exactas, recicladas del `MarkdownFormatter`):
+   - `# {name}`
+   - `**Tipo**: {purpose} | **Plataforma**: {platform}`
+   - `description` como párrafo aparte (solo si existe).
+   - Con `regions`: un `## {Type capitalizado}` por región (capitalizar la primera letra del `type`).
+   - Sin `regions`: un `## Componentes`.
+   - Cada componente: `- **{label || role || kind}**`, seguido de ` ({kind})` **solo si** había `label` o `role`.
+   - `children` indentados **2 espacios por nivel**.
+
+Ejemplo de render para el dashboard de arriba:
+
+```markdown
+# Dashboard
+**Tipo**: dashboard | **Plataforma**: web
+
+## Summary
+- **Total** (metric)
+- **Pendientes** (metric)
+
+## Main
+- **Registros** (table)
+```
+
+## Source
+
+Reciclada de `ui-spec-generator` (Spring Boot/Kotlin). Se **conservan**: el prompt de sistema (vocabulario, kinds, reglas), el esquema `Screen`/`Region`/`Component`, los pocos-shot, el enum de design systems, los constraints (theme/density/maxWidth) y las reglas exactas del `MarkdownFormatter`. Se **descarta**: el transporte HTTP, OpenRouter/Gemini y el modo single-shot — los reemplaza la iteración del `spec-refine-loop`. El endpoint del servicio deja de usarse. También absorbe los principios UX de la vieja skill `standards/frontend-design/` cuando el spec describe mantenimientos CRUD (formularios, listados, modales, navegación, feedback).

package/skills/w/roles/writing/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: writing
+description: >-
+  Clear technical writing capability — built-in default for the `writing` role. Rules
+  for any prose the AI produces in agent-workflow context: spec/plan/session artifacts,
+  commit messages, PR descriptions, export deliverables (manuals/reports). Short
+  sentences, lists over prose, one idea per line, "what + why" on one line, no jargon,
+  no filler. Use across all loops and in export-manuals / export-reports.
+---
+
+# writing — Clear technical writing
+
+## Role
+
+`writing` — built-in default. Rebindable in `.workflow/skills.toml` (third-party skill or `off`). The most broadly composed role.
+
+## Purpose
+
+Reglas de estilo y formato para **toda la prosa** que la IA produce en contexto agent-workflow. Read-only por diseño: carga reglas; el `.md` lo materializa el consumidor (loop o export).
+
+## Composed by
+
+- **Todos los loops** — al escribir specs, planes, artefactos de sesión, mensajes de commit, descripciones de PR.
+- **`export-manuals`** — al redactar manuales técnicos (`docs/manuals`).
+- **`export-reports`** — al redactar informes ejecutivos (`docs/reports`).
+
+(También aplica a respuestas en chat sobre temas agent-workflow.)
+
+## Knowledge
+
+### Las 6 reglas
+
+1. **Frases cortas**: máximo ~15 palabras. Si pasa de 20, partir en dos.
+2. **Listas sobre prosa**: 3+ ideas paralelas van en bullets. Prosa solo para narrar.
+3. **Una idea por línea**: si el bullet usa "y" o ";" para meter una segunda idea, separar.
+4. **"Qué + por qué" en una línea**: formato `<qué>: <por qué corto>`. Sin párrafo aparte para el "por qué".
+5. **Sin jerga ni abreviaturas raras**: palabras comunes. Términos técnicos (MCP, C4) OK; abreviaturas inventadas (ej. "TLDR del CTX") no.
+6. **Sin relleno**: borrar "es importante notar que…", "cabe destacar…", "como se mencionó…", "en conclusión…". La idea va directo.
+
+### Palabras a evitar / preferir
+
+| Evitar | Preferir |
+|---|---|
+| "es importante notar que" / "cabe destacar" | (borrar, empezar con la idea) |
+| "en otras palabras" / "asimismo" | (borrar) / "también" |
+| "se procede a" / "llevar a cabo" | verbo directo / "hacer" |
+| "implementar la funcionalidad de X" | "implementar X" |
+| "realizar la validación de" | "validar" |
+| "a los efectos de" / "en el marco de" | "para" / "en" |
+| "no obstante" / "previamente mencionado" | "pero" / "antes" |
+| "TLDR", "FYI", "WIP" | escribir la palabra completa |
+
+### Ejemplo antes / después
+
+Antes:
+> Es importante notar que cada llamada implica un round-trip al servidor MCP además del consumo de tokens correspondiente al JSON de respuesta.
+
+Después (-50%):
+> Cada llamada MCP cuesta un round-trip y los tokens del JSON.
+
+Decisión densa, antes:
+> Se decidió, luego de analizar las alternativas, implementar la validación de roles solo en el frontend, dado que el backend no requiere la lógica y evita duplicar la regla.
+
+Después:
+> **Decisión**: validar permisos solo en el frontend.
+> **Por qué**: el backend no necesita la lógica; evita duplicar la regla.
+
+### Cuándo SÍ se permite prosa larga
+
+- Resúmenes ejecutivos donde la decisión necesita 4-6 oraciones para sostenerse.
+- Cadena causal de un incidente (causa raíz puede requerir un párrafo).
+- Tradeoffs de UX que necesitan explicación.
+
+Aún ahí: oraciones simples encadenadas, no oraciones largas.
+
+### Aplicación a los documentos del modelo nuevo
+
+- **spec** (`docs/specs`): brief y criterios de aceptación claros; la sección `## UI spec` la formatea el rol `ui-design`.
+- **plan** (`docs/plans`): resumen + fases + tasks con dependencias; tasks sin código inline (el código va en evidencia y se referencia).
+- **decisiones**: `**Decisión**:` + `**Por qué**:`, 3-6 líneas; si es obvia, no se registra.
+- **commit messages / PR**: mismas reglas (frases cortas, sin jerga, sin relleno). Formato canónico del mensaje en el rol `git`.
+- **export manuals/reports**: audiencia operadores/gerencia; bullets sobre prosa, sin relleno corporativo.
+
+## Output
+
+Ninguno propio. La skill aporta reglas; el `.md` lo escribe el consumidor (loop o export). Cuando escribe a `docs/`, lo hace solo el export que la compone (invariante 1) y solo en su carpeta (invariante 2).
+
+## Source
+
+Reciclada de `standards/redaccion-simple/` (las 6 reglas, tabla evitar/preferir, ejemplos, cuándo permitir prosa larga). Se descarta el catálogo de estructuras por artefacto del modelo viejo (OBJETIVO/DECISIONES/etc.); los documentos del modelo nuevo son spec/plan + artefactos de sesión, y su estructura la definen los loops y exports.