# Astro Improvements

Skill to audit an Astro application, detect anti-patterns across four dimensions, and produce a prioritized report with concrete before/after refactor recipes.

## When to Use

- Before a production release to catch regressions
- When performance budget alerts fire (LCP, CLS, bundle size)
- During onboarding to an unfamiliar Astro codebase
- After migrating from SSG to SSR (or vice versa)
- Suspicion of over-hydration or unnecessary client JavaScript
- Routine accessibility or SEO audit

## Dimensions

| Dimension | Weight | Focus |
|-----------|--------|-------|
| ⚡ **Performance & Islands** | 30% | `client:*` directives, hydration cost, `<Image>`, prefetch, bundle size |
| 🏗️ **Architecture & Structure** | 25% | Layouts, content collections, routing, SSR vs SSG, `astro.config.mjs` |
| 🔍 **SEO, Accessibility & Meta** | 25% | Semantic HTML, ARIA, sitemap, robots, Open Graph, `lang`, headings |
| 🛠️ **DX, TypeScript & Quality** | 20% | `tsconfig`, env types, `Props` interfaces, linting, `astro check` in CI |

## Process

### Step 1: Inventory

Read in this order:
- `astro.config.mjs` — output mode (SSG/SSR/hybrid), integrations, adapters
- `package.json` — Astro version, framework integrations, bundle tools
- `src/` tree — layouts, pages, components, content, middleware
- `public/` — static assets that bypass Astro's asset pipeline

Flag:
```
✅ output mode is explicit and intentional
✅ only needed integrations are listed
⚠️ mixed .astro and framework components (React/Vue) without clear boundary
❌ no astro.config.mjs found → cannot proceed reliably
```

### Step 2: Map findings to dimensions

For each file or pattern found, assign it to one of the four dimensions and note the relevant path (`src/components/Card.astro:12`).

### Step 3: Score severity

| Severity | Criteria |
|----------|----------|
| 🔴 **Critical** | Blocks SEO indexing, breaks a11y for assistive tech, or sends 100+ KB unnecessary JS to every visitor |
| 🟡 **Major** | Degrades Core Web Vitals, creates confusing architecture, or causes DX friction in every feature |
| 🟢 **Minor** | Polish issue — measurable improvement but no immediate impact |

### Step 4: Propose refactors

For every 🔴 Critical and 🟡 Major finding, provide a before/after snippet. For 🟢 Minor findings a one-line fix is enough.

### Step 5: Emit report

Use the [Report Template](#report-template) at the end of this skill.

---

## Catalog of Improvements

### ⚡ Performance & Islands

#### `client:load` used for static content — 🔴 Critical

Every `client:load` sends a full framework bundle to the browser before the page is interactive. Reserve it for components that actually need browser APIs on load.

```astro
<!-- ❌ Before — sends React bundle even though Card is pure HTML -->
<Card client:load title="Hello" />

<!-- ✅ After — no directive: rendered to static HTML at build time -->
<Card title="Hello" />

<!-- ✅ After — interactive only when scrolled into view -->
<Counter client:visible initialCount={0} />
```

**Fix:** Audit every `client:*` directive. Use `client:visible` for below-the-fold interactivity, `client:idle` for low-priority widgets, and no directive for fully static components.

---

#### Raw `<img>` instead of `<Image>` — 🟡 Major

Astro's built-in `<Image>` component generates responsive `srcset`, converts to WebP/AVIF, and adds width/height to prevent layout shift. Raw `<img>` tags skip all of this.

```astro
<!-- ❌ Before -->
<img src="/hero.jpg" alt="Hero" />

<!-- ✅ After -->
---
import { Image } from 'astro:assets';
import heroImg from '../assets/hero.jpg';
---
<Image src={heroImg} alt="Hero" width={1200} height={600} />
```

**Fix:** Replace `<img src="...">` with `<Image>` for all local and remote images. Set `image.remotePatterns` in `astro.config.mjs` for external sources.

---

#### No prefetch strategy — 🟢 Minor

Astro supports automatic link prefetching with a single config line. Without it, navigations feel slower than necessary on multi-page sites.

```js
// ❌ Before — astro.config.mjs, no prefetch config
export default defineConfig({ ... });

// ✅ After — prefetch on hover, opt-out per link with data-astro-prefetch="false"
export default defineConfig({
  prefetch: { prefetchAll: false, defaultStrategy: 'hover' }
});
```

**Fix:** Add `prefetch` config to `astro.config.mjs`. Use `prefetchAll: true` only for small sites with few pages.

---

### 🏗️ Architecture & Structure

#### Front matter logic instead of Content Collections — 🔴 Critical

Embedding data arrays or fetch logic directly in `.astro` page front matter bypasses type safety and makes content unqueryable.

```astro
<!-- ❌ Before — data hardcoded in page front matter -->
---
const posts = [
  { title: 'Post 1', date: '2024-01-01', slug: 'post-1' },
  { title: 'Post 2', date: '2024-02-01', slug: 'post-2' },
];
---

<!-- ✅ After — define a collection with schema -->
```

```ts
// src/content/config.ts
import { defineCollection, z } from 'astro:content';

export const collections = {
  blog: defineCollection({
    schema: z.object({ title: z.string(), date: z.coerce.date() }),
  }),
};
```

```astro
<!-- src/pages/blog/index.astro -->
---
import { getCollection } from 'astro:content';
const posts = await getCollection('blog');
---
```

**Fix:** Move repeated data into `src/content/{collection}/` with a Zod schema in `src/content/config.ts`. Use `getCollection()` to query with full TypeScript inference.

---

#### Duplicate layout wrappers — 🟡 Major

Copy-pasted `<html>`, `<head>`, and `<body>` boilerplate across pages makes global changes (CSP headers, fonts, analytics) error-prone.

```astro
<!-- ❌ Before — same <head> repeated in every page -->
---
// src/pages/index.astro AND src/pages/about.astro
---
<html lang="en">
  <head><title>...</title><link rel="stylesheet" .../></head>
  <body>...</body>
</html>

<!-- ✅ After — one Layout component -->
---
import Layout from '../layouts/Layout.astro';
---
<Layout title="Home">
  <main>...</main>
</Layout>
```

**Fix:** Extract a `src/layouts/Layout.astro` that owns `<html>`, `<head>`, and global styles. Pass `title` and `description` as props.

---

#### Unused integrations in `astro.config.mjs` — 🟢 Minor

Every registered integration runs at build time. Leftover integrations from experiments increase build time and can introduce unexpected transformations.

```js
// ❌ Before — @astrojs/react listed but no .jsx/.tsx files exist
import react from '@astrojs/react';
export default defineConfig({ integrations: [react()] });

// ✅ After — only integrations actually in use
export default defineConfig({ integrations: [sitemap()] });
```

**Fix:** Cross-check `integrations` with `src/` — if no component files use a framework, remove its integration and package.

---

### 🔍 SEO, Accessibility & Meta

#### Missing `lang` attribute on `<html>` — 🔴 Critical

Screen readers and search engines need `lang` to parse content correctly. Its absence is a WCAG 2.1 Level A failure.

```astro
<!-- ❌ Before -->
<html>

<!-- ✅ After -->
<html lang="en">
```

**Fix:** Add `lang` to the root `<html>` in every layout. Accept it as a prop (`lang = 'en'`) for multilingual sites.

---

#### Missing Open Graph and meta description — 🟡 Major

Pages without `og:title`, `og:description`, and `description` meta appear as bare URLs when shared on social platforms and rank lower in search results.

```astro
<!-- ❌ Before — Layout.astro head has only a <title> -->
<head>
  <title>{title}</title>
</head>

<!-- ✅ After -->
<head>
  <title>{title}</title>
  <meta name="description" content={description} />
  <meta property="og:title" content={title} />
  <meta property="og:description" content={description} />
  <meta property="og:type" content="website" />
  <meta property="og:image" content={new URL(ogImage, Astro.url)} />
</head>
```

**Fix:** Add a `<SEO>` component or extend the Layout props to accept `description` and `ogImage`. Make `description` required via TypeScript.

---

#### Skipped heading levels — 🟡 Major

Jumping from `<h1>` to `<h3>` breaks the document outline used by screen readers and degrades SEO heading structure.

```astro
<!-- ❌ Before -->
<h1>Blog</h1>
<h3>Latest Posts</h3>  <!-- h2 is missing -->

<!-- ✅ After -->
<h1>Blog</h1>
<h2>Latest Posts</h2>
<h3>{post.title}</h3>
```

**Fix:** Enforce one `<h1>` per page and sequential levels. Use browser DevTools › Accessibility pane or axe to audit the heading tree.

---

### 🛠️ DX, TypeScript & Quality

#### `strict: false` in `tsconfig.json` — 🔴 Critical

Disabling strict mode masks `null`/`undefined` errors, implicit `any` types, and unchecked function parameters — all common sources of runtime bugs in Astro components.

```jsonc
// ❌ Before
{ "extends": "astro/tsconfigs/base", "compilerOptions": { "strict": false } }

// ✅ After — use the strictest preset Astro ships
{ "extends": "astro/tsconfigs/strictest" }
```

**Fix:** Replace with `astro/tsconfigs/strictest` (or at minimum `astro/tsconfigs/strict`). Fix resulting type errors before enabling — do not suppress with `// @ts-ignore`.

---

#### `import.meta.env` without type declarations — 🟡 Major

Accessing custom env variables without an `env.d.ts` declaration means TypeScript treats them as `any`, silencing typos in variable names.

```ts
// ❌ Before — no env.d.ts, IDE has no autocomplete
const key = import.meta.env.PUBLIC_API_KEY; // type: any

// ✅ After — src/env.d.ts
/// <reference types="astro/client" />
interface ImportMetaEnv {
  readonly PUBLIC_API_KEY: string;
  readonly SECRET_DB_URL: string;
}
interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

**Fix:** Create `src/env.d.ts` with typed declarations for every env variable. Add a check to CI that fails if `.env.example` variables are missing from `env.d.ts`.

---

#### Components without `Props` interface — 🟢 Minor

Untyped component props prevent IDE autocompletion and let callers pass wrong values silently.

```astro
<!-- ❌ Before — no prop types -->
---
const { title, count } = Astro.props;
---

<!-- ✅ After -->
---
interface Props {
  title: string;
  count?: number;
}
const { title, count = 0 } = Astro.props;
---
```

**Fix:** Add an `interface Props` block to every `.astro` component that accepts props. Use `astro check` (see below) to surface violations.

---

## Report Template

````markdown
# Astro Improvements — {project name}

## 📊 Overall Score: {X}/100

| Dimension | Score | Status |
|-----------|-------|--------|
| ⚡ Performance & Islands | {X}/30 | {✅ ⚠️ ❌} |
| 🏗️ Architecture & Structure | {X}/25 | {✅ ⚠️ ❌} |
| 🔍 SEO, Accessibility & Meta | {X}/25 | {✅ ⚠️ ❌} |
| 🛠️ DX, TypeScript & Quality | {X}/20 | {✅ ⚠️ ❌} |

## Verdict

{🟢 SHIP | 🟡 SHIP WITH MINOR FIXES | 🔴 NEEDS WORK BEFORE SHIPPING}

## Findings

| # | Severity | Dimension | Location | Effort |
|---|----------|-----------|----------|--------|
| 1 | 🔴 Critical | Performance | `src/components/Hero.astro:8` | S |
| 2 | 🟡 Major | Architecture | `src/pages/blog/index.astro:3–18` | M |

## Detailed Findings

### Finding 1 — {title}
**File:** `src/...`  
**Why it matters:** ...  
**Before:**
```astro
...
```
**After:**
```astro
...
```

## Top 5 Action Plan

1. [ ] {Most impactful fix — link to finding}
2. [ ] ...
3. [ ] ...
4. [ ] ...
5. [ ] ...

## Checklist

- [ ] No `client:load` on purely static components
- [ ] All `<img>` tags replaced with `<Image>`
- [ ] `astro.config.mjs` integrations match actual usage
- [ ] Every layout has `lang` on `<html>`
- [ ] `og:title`, `og:description`, `description` present on all pages
- [ ] No skipped heading levels
- [ ] `tsconfig.json` extends `astro/tsconfigs/strictest`
- [ ] `src/env.d.ts` types all `import.meta.env` variables
- [ ] All components have a `Props` interface
- [ ] `astro check` runs in CI with zero errors
````

## Heuristics & Quick Wins

- If `client:load` is on a component with no event handlers or browser API calls → remove the directive entirely.
- If `astro.config.mjs` output is `'server'` but every page has no dynamic data → switch to `'static'` and remove the adapter.
- If `@astrojs/sitemap` is absent and the site is SSG → add it; search engines won't automatically discover all pages.
- If a page has two or more `<h1>` tags → refactor so only the page title uses `<h1>`.
- If `astro check` is not in the CI pipeline → add it before the build step; it catches type errors that TypeScript alone misses in `.astro` files.

# Mejoras en Astro

Skill para auditar una aplicación Astro, detectar antipatrones en cuatro dimensiones y producir un informe priorizado con recetas concretas de refactorización con ejemplos Antes/Después.

## Cuándo Usar

- Antes de un lanzamiento a producción para detectar regresiones
- Cuando salten alertas de presupuesto de rendimiento (LCP, CLS, tamaño de bundle)
- Al incorporarse a una codebase Astro desconocida
- Tras migrar de SSG a SSR (o viceversa)
- Sospecha de over-hydration o JavaScript innecesario en el cliente
- Auditoría rutinaria de accesibilidad o SEO

## Dimensiones

| Dimensión | Peso | Foco |
|-----------|------|------|
| ⚡ **Performance & Islands** | 30% | Directivas `client:*`, coste de hidratación, `<Image>`, prefetch, tamaño de bundle |
| 🏗️ **Architecture & Structure** | 25% | Layouts, content collections, routing, SSR vs SSG, `astro.config.mjs` |
| 🔍 **SEO, Accesibilidad y Meta** | 25% | HTML semántico, ARIA, sitemap, robots, Open Graph, atributo `lang`, headings |
| 🛠️ **DX, TypeScript y Calidad** | 20% | `tsconfig`, tipos de env, interfaces `Props`, linting, `astro check` en CI |

## Proceso

### Paso 1: Inventario

Leer en este orden:
- `astro.config.mjs` — modo de salida (SSG/SSR/hybrid), integraciones, adaptadores
- `package.json` — versión de Astro, integraciones de framework, herramientas de bundle
- Árbol de `src/` — layouts, páginas, componentes, content, middleware
- `public/` — assets estáticos que no pasan por el pipeline de Astro

Verificar:
```
✅ El modo de salida es explícito e intencionado
✅ Solo están listadas las integraciones necesarias
⚠️ Mezcla de .astro y componentes de framework (React/Vue) sin límite claro
❌ No se encuentra astro.config.mjs → no es posible continuar con fiabilidad
```

### Paso 2: Mapear hallazgos a dimensiones

Por cada archivo o patrón detectado, asignarlo a una de las cuatro dimensiones e indicar la ruta relevante (`src/components/Card.astro:12`).

### Paso 3: Puntuar severidad

| Severidad | Criterio |
|-----------|----------|
| 🔴 **Crítico** | Bloquea la indexación SEO, rompe la accesibilidad para tecnologías asistivas, o envía más de 100 KB de JS innecesario a cada visitante |
| 🟡 **Mayor** | Degrada Core Web Vitals, genera arquitectura confusa o causa fricción de DX en cada funcionalidad |
| 🟢 **Menor** | Problema de pulido — mejora medible pero sin impacto inmediato |

### Paso 4: Proponer refactorizaciones

Para cada hallazgo 🔴 Crítico y 🟡 Mayor, proporcionar un fragmento Antes/Después. Para los hallazgos 🟢 Menores basta una corrección de una línea.

### Paso 5: Emitir informe

Usar la [Plantilla de Informe](#plantilla-de-informe) al final de esta skill.

---

## Catálogo de Mejoras

### ⚡ Performance & Islands

#### `client:load` usado en contenido estático — 🔴 Crítico

Cada `client:load` envía el bundle completo del framework al navegador antes de que la página sea interactiva. Reservarlo para componentes que realmente necesiten APIs del navegador al cargar.

```astro
<!-- ❌ Antes — envía el bundle de React aunque Card sea HTML puro -->
<Card client:load title="Hola" />

<!-- ✅ Después — sin directiva: se renderiza a HTML estático en build time -->
<Card title="Hola" />

<!-- ✅ Después — interactivo solo cuando entra en el viewport -->
<Counter client:visible initialCount={0} />
```

**Corrección:** Auditar cada directiva `client:*`. Usar `client:visible` para interactividad bajo el pliegue, `client:idle` para widgets de baja prioridad, y ninguna directiva para componentes completamente estáticos.

---

#### `<img>` sin `<Image>` — 🟡 Mayor

El componente `<Image>` de Astro genera `srcset` responsive, convierte a WebP/AVIF y añade ancho/alto para evitar layout shift. Las etiquetas `<img>` normales omiten todo esto.

```astro
<!-- ❌ Antes -->
<img src="/hero.jpg" alt="Hero" />

<!-- ✅ Después -->
---
import { Image } from 'astro:assets';
import heroImg from '../assets/hero.jpg';
---
<Image src={heroImg} alt="Hero" width={1200} height={600} />
```

**Corrección:** Reemplazar `<img src="...">` por `<Image>` en todas las imágenes locales y remotas. Configurar `image.remotePatterns` en `astro.config.mjs` para fuentes externas.

---

#### Sin estrategia de prefetch — 🟢 Menor

Astro soporta prefetching automático de enlaces con una sola línea de configuración. Sin él, las navegaciones se sienten más lentas de lo necesario en sitios multipágina.

```js
// ❌ Antes — astro.config.mjs sin configuración de prefetch
export default defineConfig({ ... });

// ✅ Después — prefetch al pasar el cursor, opt-out por enlace con data-astro-prefetch="false"
export default defineConfig({
  prefetch: { prefetchAll: false, defaultStrategy: 'hover' }
});
```

**Corrección:** Añadir configuración de `prefetch` a `astro.config.mjs`. Usar `prefetchAll: true` solo en sitios pequeños con pocas páginas.

---

### 🏗️ Architecture & Structure

#### Lógica en el front matter en lugar de Content Collections — 🔴 Crítico

Incrustar arrays de datos o lógica de fetch directamente en el front matter de páginas `.astro` elimina la seguridad de tipos y hace el contenido no consultable.

```astro
<!-- ❌ Antes — datos hardcodeados en el front matter de la página -->
---
const posts = [
  { title: 'Post 1', date: '2024-01-01', slug: 'post-1' },
  { title: 'Post 2', date: '2024-02-01', slug: 'post-2' },
];
---

<!-- ✅ Después — definir una colección con schema -->
```

```ts
// src/content/config.ts
import { defineCollection, z } from 'astro:content';

export const collections = {
  blog: defineCollection({
    schema: z.object({ title: z.string(), date: z.coerce.date() }),
  }),
};
```

```astro
<!-- src/pages/blog/index.astro -->
---
import { getCollection } from 'astro:content';
const posts = await getCollection('blog');
---
```

**Corrección:** Mover los datos repetidos a `src/content/{coleccion}/` con un schema Zod en `src/content/config.ts`. Usar `getCollection()` para consultar con inferencia completa de TypeScript.

---

#### Layouts duplicados — 🟡 Mayor

El boilerplate de `<html>`, `<head>` y `<body>` copiado entre páginas hace que los cambios globales (cabeceras CSP, fuentes, analytics) sean propensos a errores.

```astro
<!-- ❌ Antes — el mismo <head> repetido en cada página -->
<html lang="es">
  <head><title>...</title><link rel="stylesheet" .../></head>
  <body>...</body>
</html>

<!-- ✅ Después — un único componente Layout -->
---
import Layout from '../layouts/Layout.astro';
---
<Layout title="Inicio">
  <main>...</main>
</Layout>
```

**Corrección:** Extraer un `src/layouts/Layout.astro` que sea propietario de `<html>`, `<head>` y los estilos globales. Pasar `title` y `description` como props.

---

#### Integraciones sin uso en `astro.config.mjs` — 🟢 Menor

Cada integración registrada se ejecuta en build time. Las integraciones sobrantes de experimentos aumentan el tiempo de build y pueden introducir transformaciones inesperadas.

```js
// ❌ Antes — @astrojs/react listado pero sin archivos .jsx/.tsx
import react from '@astrojs/react';
export default defineConfig({ integrations: [react()] });

// ✅ Después — solo las integraciones realmente en uso
export default defineConfig({ integrations: [sitemap()] });
```

**Corrección:** Cruzar las `integrations` con `src/` — si ningún archivo de componentes usa un framework, eliminar su integración y su paquete.

---

### 🔍 SEO, Accesibilidad y Meta

#### Falta el atributo `lang` en `<html>` — 🔴 Crítico

Los lectores de pantalla y los motores de búsqueda necesitan `lang` para interpretar el contenido correctamente. Su ausencia es un fallo WCAG 2.1 Nivel A.

```astro
<!-- ❌ Antes -->
<html>

<!-- ✅ Después -->
<html lang="es">
```

**Corrección:** Añadir `lang` al `<html>` raíz en cada layout. Aceptarlo como prop (`lang = 'es'`) en sitios multilingüe.

---

#### Falta Open Graph y meta description — 🟡 Mayor

Las páginas sin `og:title`, `og:description` y `description` aparecen como URLs desnudas cuando se comparten en redes sociales y posicionan peor en búsquedas.

```astro
<!-- ❌ Antes — Layout.astro head solo con <title> -->
<head>
  <title>{title}</title>
</head>

<!-- ✅ Después -->
<head>
  <title>{title}</title>
  <meta name="description" content={description} />
  <meta property="og:title" content={title} />
  <meta property="og:description" content={description} />
  <meta property="og:type" content="website" />
  <meta property="og:image" content={new URL(ogImage, Astro.url)} />
</head>
```

**Corrección:** Añadir un componente `<SEO>` o extender las props del Layout para aceptar `description` e `ogImage`. Hacer `description` obligatorio vía TypeScript.

---

#### Niveles de heading saltados — 🟡 Mayor

Saltar de `<h1>` a `<h3>` rompe el esquema del documento que usan los lectores de pantalla y degrada la estructura de headings para SEO.

```astro
<!-- ❌ Antes -->
<h1>Blog</h1>
<h3>Últimas entradas</h3>  <!-- falta h2 -->

<!-- ✅ Después -->
<h1>Blog</h1>
<h2>Últimas entradas</h2>
<h3>{post.title}</h3>
```

**Corrección:** Aplicar un solo `<h1>` por página y niveles secuenciales. Usar el panel de Accesibilidad de DevTools o axe para auditar el árbol de headings.

---

### 🛠️ DX, TypeScript y Calidad

#### `strict: false` en `tsconfig.json` — 🔴 Crítico

Deshabilitar el modo estricto oculta errores de `null`/`undefined`, tipos `any` implícitos y parámetros de función sin verificar — fuentes habituales de errores en runtime en componentes Astro.

```jsonc
// ❌ Antes
{ "extends": "astro/tsconfigs/base", "compilerOptions": { "strict": false } }

// ✅ Después — usar el preset más estricto que incluye Astro
{ "extends": "astro/tsconfigs/strictest" }
```

**Corrección:** Reemplazar por `astro/tsconfigs/strictest` (o como mínimo `astro/tsconfigs/strict`). Corregir los errores de tipo resultantes antes de activarlo — no suprimir con `// @ts-ignore`.

---

#### `import.meta.env` sin declaraciones de tipos — 🟡 Mayor

Acceder a variables de entorno personalizadas sin un `env.d.ts` hace que TypeScript las trate como `any`, ocultando errores tipográficos en los nombres de variable.

```ts
// ❌ Antes — sin env.d.ts, el IDE no tiene autocompletado
const key = import.meta.env.PUBLIC_API_KEY; // tipo: any

// ✅ Después — src/env.d.ts
/// <reference types="astro/client" />
interface ImportMetaEnv {
  readonly PUBLIC_API_KEY: string;
  readonly SECRET_DB_URL: string;
}
interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

**Corrección:** Crear `src/env.d.ts` con declaraciones tipadas para cada variable de entorno. Añadir una verificación en CI que falle si las variables de `.env.example` no están en `env.d.ts`.

---

#### Componentes sin interfaz `Props` — 🟢 Menor

Las props sin tipos impiden el autocompletado del IDE y permiten que los consumidores pasen valores incorrectos sin advertencia.

```astro
<!-- ❌ Antes — sin tipos de props -->
---
const { title, count } = Astro.props;
---

<!-- ✅ Después -->
---
interface Props {
  title: string;
  count?: number;
}
const { title, count = 0 } = Astro.props;
---
```

**Corrección:** Añadir un bloque `interface Props` a cada componente `.astro` que acepte props. Usar `astro check` (ver más abajo) para detectar violaciones.

---

## Plantilla de Informe

````markdown
# Mejoras en Astro — {nombre del proyecto}

## 📊 Puntuación Global: {X}/100

| Dimensión | Puntuación | Estado |
|-----------|-----------|--------|
| ⚡ Performance & Islands | {X}/30 | {✅ ⚠️ ❌} |
| 🏗️ Architecture & Structure | {X}/25 | {✅ ⚠️ ❌} |
| 🔍 SEO, Accesibilidad y Meta | {X}/25 | {✅ ⚠️ ❌} |
| 🛠️ DX, TypeScript y Calidad | {X}/20 | {✅ ⚠️ ❌} |

## Veredicto

{🟢 LISTO PARA PRODUCCIÓN | 🟡 LISTO CON CORRECCIONES MENORES | 🔴 REQUIERE TRABAJO ANTES DE PRODUCCIÓN}

## Hallazgos

| # | Severidad | Dimensión | Ubicación | Esfuerzo |
|---|-----------|-----------|-----------|---------|
| 1 | 🔴 Crítico | Performance | `src/components/Hero.astro:8` | S |
| 2 | 🟡 Mayor | Architecture | `src/pages/blog/index.astro:3–18` | M |

## Hallazgos Detallados

### Hallazgo 1 — {título}
**Archivo:** `src/...`  
**Por qué importa:** ...  
**Antes:**
```astro
...
```
**Después:**
```astro
...
```

## Plan de Acción — Top 5

1. [ ] {Corrección de mayor impacto — enlace al hallazgo}
2. [ ] ...
3. [ ] ...
4. [ ] ...
5. [ ] ...

## Checklist

- [ ] Sin `client:load` en componentes puramente estáticos
- [ ] Todas las etiquetas `<img>` reemplazadas por `<Image>`
- [ ] Las integraciones de `astro.config.mjs` coinciden con el uso real
- [ ] Cada layout tiene `lang` en `<html>`
- [ ] `og:title`, `og:description` y `description` presentes en todas las páginas
- [ ] Sin niveles de heading saltados
- [ ] `tsconfig.json` extiende `astro/tsconfigs/strictest`
- [ ] `src/env.d.ts` tipifica todas las variables de `import.meta.env`
- [ ] Todos los componentes tienen una interfaz `Props`
- [ ] `astro check` se ejecuta en CI sin errores
````

## Heurísticas y Quick Wins

- Si `client:load` está en un componente sin event handlers ni llamadas a APIs del navegador → eliminar la directiva por completo.
- Si el output de `astro.config.mjs` es `'server'` pero cada página carece de datos dinámicos → cambiar a `'static'` y eliminar el adaptador.
- Si `@astrojs/sitemap` no está presente y el sitio es SSG → añadirlo; los motores de búsqueda no descubrirán automáticamente todas las páginas.
- Si una página tiene dos o más etiquetas `<h1>` → refactorizar para que solo el título de página use `<h1>`.
- Si `astro check` no está en el pipeline de CI → añadirlo antes del paso de build; detecta errores de tipo que TypeScript solo no detecta en archivos `.astro`.

# Public API Design and Compatibility

## When to Use This Skill

Use this skill when:
- Designing public APIs for NuGet packages or libraries
- Making changes to existing public APIs
- Planning wire format changes for distributed systems
- Implementing versioning strategies
- Reviewing pull requests for breaking changes

---

## The Three Types of Compatibility

| Type | Definition | Scope |
|------|------------|-------|
| **API/Source** | Code compiles against newer version | Public method signatures, types |
| **Binary** | Compiled code runs against newer version | Assembly layout, method tokens |
| **Wire** | Serialized data readable by other versions | Network protocols, persistence formats |

Breaking any of these creates upgrade friction for users.

---

## Extend-Only Design

The foundation of stable APIs: **never remove or modify, only extend**.

### Three Pillars

1. **Previous functionality is immutable** - Once released, behavior and signatures are locked
2. **New functionality through new constructs** - Add overloads, new types, opt-in features
3. **Removal only after deprecation period** - Years, not releases

### Benefits

- Old code continues working in new versions
- New and old pathways coexist
- Upgrades are non-breaking by default
- Users upgrade on their schedule

**Resources:**
- [Extend-Only Design](https://aaronstannard.com/extend-only-design/)
- [OSS Compatibility Standards](https://aaronstannard.com/oss-compatibility-standards/)

---

## API Change Guidelines

### Safe Changes (Any Release)

```csharp
// SAFE: Add NEW overload methods that delegate to existing methods
// Existing method - do not modify its signature
public void Process(Order order) { ... }
// New overload - safe to add
public void Process(Order order, CancellationToken ct)
{
    // implementation that handles cancellation
}

// SAFE: Add NEW overloads for additional functionality
// Existing method - do not modify
public void Send(Message msg) { ... }
// New overload - safe to add
public void Send(Message msg, Priority priority)
{
    // implementation that handles priority
}

// ADD new types, interfaces, enums
public interface IOrderValidator { }
public enum OrderStatus { Pending, Complete, Cancelled }

// ADD new members to existing types
public class Order
{
    public DateTimeOffset? ShippedAt { get; init; }  // NEW
}
```

### Unsafe Changes (Never or Major Version Only)

```csharp
// REMOVE or RENAME public members
public void ProcessOrder(Order order);  // Was: Process()

// CHANGE parameter types or order
public void Process(int orderId);  // Was: Process(Order order)

// CHANGE return types
public Order? GetOrder(string id);  // Was: public Order GetOrder()

// CHANGE access modifiers
internal class OrderProcessor { }  // Was: public

// ADD optional parameters to EXISTING methods (binary incompatible!)
// The compiled IL method signature changes - callers compiled against
// the old signature will get MissingMethodException at runtime.
// Optional parameter defaults are baked into the CALLER's assembly at compile time.
public void Process(Order order, CancellationToken ct = default);  // Breaks binary compat!
public void Send(Message msg, Priority priority = Priority.Normal);  // Breaks binary compat!
// Correct approach: add a NEW overload method instead (see Safe Changes above)

// ADD required parameters without defaults
public void Process(Order order, ILogger logger);  // Breaks callers!
```

### Deprecation Pattern

```csharp
// Step 1: Mark as obsolete with version (any release)
[Obsolete("Obsolete since v1.5.0. Use ProcessAsync instead.")]
public void Process(Order order) { }

// Step 2: Add new recommended API (same release)
public Task ProcessAsync(Order order, CancellationToken ct = default);

// Step 3: Remove in next major version (v2.0+)
// Only after users have had time to migrate
```

---

## API Approval Testing

Prevent accidental breaking changes with automated API surface testing.

### Using ApiApprover + Verify

```bash
dotnet add package PublicApiGenerator
dotnet add package Verify.Xunit
```

```csharp
[Fact]
public Task ApprovePublicApi()
{
    var api = typeof(MyLibrary.PublicClass).Assembly.GeneratePublicApi();
    return Verify(api);
}
```

Creates `ApprovePublicApi.verified.txt`:

```csharp
namespace MyLibrary
{
    public class OrderProcessor
    {
        public OrderProcessor() { }
        public void Process(Order order) { }
        public Task ProcessAsync(Order order, CancellationToken ct = default) { }
    }
}
```

**Any API change fails the test** - reviewer must explicitly approve changes.

### PR Review Process

1. PR includes changes to `*.verified.txt` files
2. Reviewers see exact API surface changes in diff
3. Breaking changes are immediately visible
4. Conscious decision required to approve

---

## Wire Compatibility

For distributed systems, serialized data must be readable across versions.

### Requirements

| Direction | Requirement |
|-----------|-------------|
| **Backward** | Old writers → New readers (current version reads old data) |
| **Forward** | New writers → Old readers (old version reads new data) |

Both are required for zero-downtime rolling upgrades.

### Safely Evolving Wire Formats

**Phase 1: Add read-side support (opt-in)**

```csharp
// New message type - readers deployed first
public sealed record HeartbeatV2(
    Address From,
    long SequenceNr,
    long CreationTimeMs);  // NEW field

// Deserializer handles both old and new
public object Deserialize(byte[] data, string manifest) => manifest switch
{
    "Heartbeat" => DeserializeHeartbeatV1(data),   // Old format
    "HeartbeatV2" => DeserializeHeartbeatV2(data), // New format
    _ => throw new NotSupportedException()
};
```

**Phase 2: Enable write-side (opt-out, next minor version)**

```csharp
// Config to enable new format (off by default initially)
akka.cluster.use-heartbeat-v2 = on
```

**Phase 3: Make default (future version)**

After install base has absorbed read-side code.

### Schema-Based Serialization

Prefer schema-based formats over reflection-based:

| Format | Type | Wire Compatibility |
|--------|------|-------------------|
| **Protocol Buffers** | Schema-based | Excellent - explicit field numbers |
| **MessagePack** | Schema-based | Good - with contracts |
| **System.Text.Json** | Schema-based (with source gen) | Good - explicit properties |
| Newtonsoft.Json | Reflection-based | Poor - type names in payload |
| BinaryFormatter | Reflection-based | Terrible - never use |

See `dotnet/serialization` skill for details.

---

## Encapsulation Patterns

### Internal APIs

Mark non-public APIs explicitly:

```csharp
// Attribute for documentation
[InternalApi]
public class ActorSystemImpl { }

// Namespace convention
namespace MyLibrary.Internal
{
    public class InternalHelper { }  // Public for extensibility, not for users
}
```

Document clearly:

> Types in `.Internal` namespaces or marked with `[InternalApi]` may change between any releases without notice.

### Sealing Classes

```csharp
// DO: Seal classes not designed for inheritance
public sealed class OrderProcessor { }

// DON'T: Leave unsealed by accident
public class OrderProcessor { }  // Users might inherit, blocking changes
```

### Interface Segregation

```csharp
// DO: Small, focused interfaces
public interface IOrderReader
{
    Order? GetById(OrderId id);
}

public interface IOrderWriter
{
    Task SaveAsync(Order order);
}

// DON'T: Monolithic interfaces (can't add methods without breaking)
public interface IOrderRepository
{
    Order? GetById(OrderId id);
    Task SaveAsync(Order order);
    // Adding new methods breaks all implementations!
}
```

---

## Versioning Strategy

### Semantic Versioning (Practical)

| Version | Changes Allowed |
|---------|----------------|
| **Patch** (1.0.x) | Bug fixes, security patches |
| **Minor** (1.x.0) | New features, deprecations, obsolete removal |
| **Major** (x.0.0) | Breaking changes, old API removal |

### Key Principles

1. **No surprise breaks** - Even major versions should be announced and planned
2. **Extensions anytime** - New APIs can ship in any release
3. **Deprecate before remove** - `[Obsolete]` for at least one minor version
4. **Communicate timelines** - Users need to plan upgrades

### Chesterton's Fence

> Before removing or changing something, understand why it exists.

Assume every public API is used by someone. If you want to change it:
1. Socialize the proposal on GitHub
2. Document migration path
3. Provide deprecation period
4. Ship in planned release

---

## Pull Request Checklist

When reviewing PRs that touch public APIs:

- [ ] **No removed public members** (use `[Obsolete]` instead)
- [ ] **No changed signatures** (add overloads instead)
- [ ] **No new required parameters** (use defaults)
- [ ] **API approval test updated** (`.verified.txt` changes reviewed)
- [ ] **Wire format changes are opt-in** (read-side first)
- [ ] **Breaking changes documented** (release notes, migration guide)

---

## Anti-Patterns

### Breaking Changes Disguised as Fixes

```csharp
// "Bug fix" that breaks users
public async Task<Order> GetOrderAsync(OrderId id)  // Was sync!
{
    // "Fixed" to be async - but breaks all callers
}

// Correct: Add new method, deprecate old
[Obsolete("Use GetOrderAsync instead")]
public Order GetOrder(OrderId id) => GetOrderAsync(id).Result;

public async Task<Order> GetOrderAsync(OrderId id) { }
```

### Silent Behavior Changes

```csharp
// Changing defaults breaks users who relied on old behavior
public void Configure(bool enableCaching = true)  // Was: false!

// Correct: New parameter with new name
public void Configure(
    bool enableCaching = false,  // Original default preserved
    bool enableNewCaching = true)  // New behavior opt-in
```

### Polymorphic Serialization

```csharp
// AVOID: Type names in wire format
{ "$type": "MyApp.Order, MyApp", "Id": 123 }

// Renaming Order class = wire break!

// PREFER: Explicit discriminators
{ "type": "order", "id": 123 }
```

---

## Resources

- [Making Public API Changes](https://getakka.net/community/contributing/api-changes-compatibility.html)
- [Wire Format Changes](https://getakka.net/community/contributing/wire-compatibility.html)
- [Extend-Only Design](https://aaronstannard.com/extend-only-design/)
- [OSS Compatibility Standards](https://aaronstannard.com/oss-compatibility-standards/)
- [Semantic Versioning](https://semver.org/)
- [PublicApiGenerator](https://github.com/PublicApiGenerator/PublicApiGenerator)

# Diseño de API Pública y Compatibilidad

## Cuándo usar esta habilidad

Recurre a esta habilidad cuando:
- Entables la creación y diseño del API pública de paquetes NuGet abiertos y extensivos.
- Te prepares para mutar o modificar firmas y trazas en APIs ya publicadas.
- Desarrolles o modifiques los serializadores ('Wire Formats') de tu proyecto, que entablan comunicación vía Red (Distributed Systems).
- Establezcas cómo versionar evolutivamente y planificar los ciclos de vida y desuso (Deprecation).

## 3 Vertientes de la Compatibilidad en C# / .NET

| Variante | Descripción Técnica y Definición | Alcance Global |
|------|------------|-------|
| **API/Source** | Permite que código externo sea recompilado sin cambiar ni una coma si se sube de versión | Firmas públicas y nombres de tipos |
| **Binaria** | El código binario existente (ya compilado) NO estalla ('Crash') ni se lanza sin modificar librerías DLL al ejecutarse bajo el paraguas actualizado | Layout orgánico y metadata de los métodos internos vinculados en la invocación (Method Tokens). |
| **Wire (Serialización)** | La data en Bytes viaja bidireccionalmente y puede traducirse libremente por nuevas y previas versiones | Json, Protocol Buffers, Data en Red |

Cualquier grieta o ruptura sobre estas reglas detona fricciones insoportables para los clientes adoptivos.

---

## Patrón de "Extend-Only" (Exclusivo por Ampliación)

El cimiento inamovible de un API a prueba de bombas reza así: **jamás mutiles ni mutans, únicamente amplia.**

### Tres Bastiones Fundamentales

1. **La maquinaria previa es Sacra (Inmutable)** - Ya subió a producción; queda blindada eternamente.
2. **Trazos nuevos sobre lienzos paralelos** - Despliega sobrecargas puras (`overloads`) o adhiere clases extra limitadas sin tocar la heráldica y el árbol genealógico del modelo primitivo.
3. **Muerte anunciada, no silenciosa** - Los retiros a los infiernos (`Deprecation / Remove`) necesitan ciclos de advertencias de Años, no Semanas.

---

## Puntos Clínicos en la Edición

### Modificaciones Seguras e Irreprochables (Safe Changes)

```csharp
// SEGURO: Desplegar una sobrecarga extra que interpele sigilosamente a tu propio ente primitivo
public void Process(Order order) { ... }  // Método inmaculado

// Nueva sobrecarga - Vía libre
public void Process(Order order, CancellationToken ct) { ... }

// SEGURO: Aportar nuevos contratos o Enumeradores al namespace público sin interponerse en la funcionalidad pasada.
public interface IOrderValidator { }
```

### Alteraciones Defectuosas o Fatales (Jamás hagas esto sin subir Mayor Release)

```csharp
// ERROR: Borrar cosas de la vista
public void ProcessOrder(Order order);  // Era: Process()

// ERROR ALARMISTA: Anadir parámetros extras (incluso opcionales!) en métodos vigentes 
// Destroza por completo la compatibilidad Binaria. Aunque tu API compilará
// los clientes antiguos no resolverán el "signature token" compilado sufriendo MissingMethodException 
public void Process(Order order, CancellationToken ct = default); // ❌ ¡CAOS BINARIO!
```

**Si deseas dar modernidad a un método carente de `CancellationToken`, debes conservar la antigua firma envolviéndola internamente para hacerla llamar a tu nuevo método ampliado.**

### Metódica de Clausura y Patrón Deprecation

```csharp
// FASE 1: Marcas como veneno radiactivo suave a los usuarios con aviso.
[Obsolete("En desuso en v1.5.0. Da el salto urgente a ProcessAsync")]
public void Process(Order order) { }

// FASE 2: Proporcionas la cura.
public Task ProcessAsync(Order order, CancellationToken ct = default);

// FASE 3: Eliminas todo (Sólo al propulsar cambio MASIVO de Versionado "Mayor v2.0")
```

---

## Tolerancia Estructural y Wire

Incluso superadas las DLLs locales, la mensajería serializada (Rabbit, Kafka, o persistencia local BBDD en JSON) arrastrará tu dominio para siempre y lo interpelarán microservicios ancianos en producción o consumidores desfasados.

- **Preferir discriminadores explícitos**: Explotar los discriminadores sobre tipologías de herencia que dejen patente la familia ("Type=Cat" frente a acoplamientos cerrados "$type=Namespace.Gato").
- **Tácticas Schema-First**: Los contratos `Protobuf` o `JsonSourceGen` obligan a indexar deudas sin sorpresas de reflection que arruinen los deserializadores opuestos. 
- **Nunca elimines un campo "Wire"**: Si desestimas un campo en un sistema interno de comunicaciones, mantenlo como "Obsoleto o reservado", e ignóralo, pero asume que viajará como un fantasma durante mucho tiempo provocado por escritores de versiones arcaicas del lado del Cliente.

# .NET Architecture

## Trigger On

- choosing architecture for a new or evolving .NET system
- reviewing layer boundaries, domain boundaries, or service decomposition
- deciding whether clean architecture, vertical slices, CQRS, or microservices are justified

## Workflow

1. Start from business capability boundaries and change frequency, not from a preferred diagram style.
2. Use simple modular monolith patterns by default, and move to microservices only when team autonomy, scale, or deployment boundaries justify the added operational cost.
3. Apply DDD and CQRS where business rules are genuinely complex; avoid forcing aggregates and command pipelines into CRUD-heavy code with no payoff.
4. Keep dependencies flowing inward when using clean architecture, but avoid creating extra projects that add ceremony without ownership clarity.
5. Make integration boundaries explicit: contracts, storage ownership, messaging, consistency model, and observability expectations.
6. Use `dotnet-aspire` when local orchestration, service discovery, and developer observability are part of the architecture story.

## Deliver

- an architecture direction that matches system complexity
- clear project and dependency boundaries
- migration notes or tradeoffs when changing an existing structure

## Validate

- the proposed structure reduces rather than increases accidental complexity
- data ownership and integration paths are explicit
- the architecture is testable and operable, not just diagram-friendly

## References

- [references/patterns.md](references/patterns.md) - detailed implementations of Clean Architecture, Vertical Slices, DDD, CQRS, Modular Monolith, and Microservices with C# 12+ examples
- [references/anti-patterns.md](references/anti-patterns.md) - common architectural mistakes including over-abstraction, anemic domain models, premature microservices, and cargo cult patterns

# Arquitectura .NET

## Cuándo usar esta skill

- Al elegir la arquitectura de un sistema .NET nuevo o en evolución.
- Al revisar los límites de capas, fronteras del dominio o descomposición de servicios.
- Al decidir si el uso de clean architecture, vertical slices, CQRS o microservicios está justificado.

## Flujo de trabajo

1. **Empieza por los límites funcionales de negocio y la frecuencia de cambio**, no por tu diagrama arquitectónico preferido.
2. Utiliza patrones simples de **monolito modular** por defecto. Muévete hacia microservicios solo cuando la necesidad de equipos autónomos, el requerimiento de alta escalabilidad o la segmentación de despliegues justifiquen el coste operacional añadido.
3. Aplica **DDD y CQRS** únicamente allí donde las reglas de negocio sean genuinamente complejas; evita forzar _aggregates_ o _command pipelines_ en dominios de puro CRUD sin retorno de inversión.
4. Mantén las dependencias orientadas hacia el centro (inward) si aplicas **clean architecture**, pero evita crear proyectos adicionales que solo añaden burocracia técnica sin clarificar quién posee qué.
5. **Haz explícita la integración:** usa contratos, define la propiedad del almacenamiento, la mensajería, el modelo de consistencia empleado y las expectativas funcionales y de observabilidad.
6. Utiliza `dotnet-aspire` cuando la orquestación en local, el Service Discovery y la observabilidad del entorno de desarrollo formen parte de la estrategia arquitectónica.

## Entregables

- Una dirección arquitectónica alineada con la complejidad del sistema.
- Límites claros para los proyectos y sus dependencias.
- Notas sobre estrategias de migración o concesiones e inconvenientes al alterar estructuras preexistentes.

## Validación

- La base propuesta **mitiga, no exacerba, la complejidad accidental**.
- La propiedad de los datos y los flujos de integración están estrictamente definidos.
- La arquitectura facilita tanto su testeo como su operación real, evadiendo la trampa de un "diseño perfecto solo en papel".

## Referencias

- [references/patterns.md](references/patterns.md) - Implementaciones en detalle de Patrones Arquitectónicos (Clean Architecture, Vertical Slices, DDD, CQRS, Modular Monolith y Microservicios) apalancados sobre ejemplos en C# 12+.
- [references/anti-patterns.md](references/anti-patterns.md) - Errores estructurales comunes, enfatizando aspectos como la sobre-abstracción, dominios anémicos, microservicios prematuros y falacias del *cargo cult*.

# .NET Core — Revisión de Código de Pull Requests

Skill para analizar Pull Requests de proyectos .NET Core y generar informes de revisión de código detallados con puntuación y recomendaciones.

## Cuándo Usar

- Al recibir una PR para revisión
- Antes de fusionar a `main` o `develop`
- Para auditorías de calidad de código
- Como segundo par de ojos tras revisión humana

## Dimensiones de Evaluación

El análisis cubre 6 dimensiones, cada una con peso diferente:

| Dimensión | Peso | Qué Evalúa |
|-----------|------|-------------|
| 🏗️ **Arquitectura** | 25% | Separación de capas, DI, patrones |
| 🔒 **Seguridad** | 20% | Vulnerabilidades, secretos, validación de entrada |
| ⚡ **Rendimiento** | 15% | Consultas N+1, asignaciones, async/await |
| 📐 **Convenciones** | 15% | Nomenclatura, formato, estilo del equipo |
| 🧪 **Testing** | 15% | Cobertura, calidad de tests, casos límite |
| 📖 **Legibilidad** | 10% | Claridad, complejidad, documentación |

## Proceso de Revisión

### Paso 1: Analizar el Contexto de la PR

Leer:
- **Título y descripción** de la PR
- **Commits** incluidos (mensajes y tamaño)
- **Archivos modificados** (lista y estadísticas)
- **Incidencia o ticket** vinculado

Evaluar:
```
✅ La PR tiene un propósito único y claro
✅ Los commits son atómicos y descriptivos
✅ El tamaño es razonable (< 400 líneas idealmente)
⚠️ PR grande (> 400 líneas) → sugerir dividir
❌ PR sin descripción → solicitar contexto
```

### Paso 2: Revisión de Arquitectura (25%)

#### Verificaciones

```
□ ¿Respeta la separación de capas (Domain → Application → Infrastructure)?
□ ¿Las dependencias apuntan hacia adentro (Inversión de Dependencias)?
□ ¿Los nuevos servicios se registran en la inyección de dependencias correctamente?
□ ¿Se usan interfaces para abstracciones?
□ ¿Los DTOs son independientes de las entidades de dominio?
□ ¿Se aplican los patrones del proyecto (CQRS, Repository, etc.)?
```

#### Señales de Alerta

```csharp
// ❌ Controller con lógica de negocio
[HttpPost]
public async Task<IActionResult> Create(CreateUserDto dto)
{
    // Validación manual en el controller
    if (string.IsNullOrEmpty(dto.Email)) return BadRequest();
    
    // Acceso directo a DbContext desde el controller
    var user = new User { Email = dto.Email };
    _context.Users.Add(user);
    await _context.SaveChangesAsync();
    
    // Envío de email desde el controller
    await _emailService.Send(user.Email, "Bienvenido");
    
    return Ok(user);
}

// ✅ Debería delegarse a un handler/servicio
[HttpPost]
public async Task<IActionResult> Create(CreateUserCommand command)
{
    var result = await _mediator.Send(command);
    return result.IsSuccess ? Created(result.Value) : BadRequest(result.Error);
}
```

### Paso 3: Revisión de Seguridad (20%)

#### Lista de Verificación Crítica

```
□ No hay secretos/contraseñas escritos directamente en el código
□ Los inputs del usuario se validan (FluentValidation / Data Annotations)
□ Las queries usan parámetros (no string interpolation de SQL)
□ Los endpoints tienen [Authorize] apropiado
□ No se exponen trazas de error en producción
□ Se sanitiza output para prevenir XSS
□ Los archivos subidos se validan (tipo, tamaño)
□ CORS está configurado correctamente
```

#### Patrones Peligrosos

```csharp
// ❌ Inyección SQL
var query = $"SELECT * FROM Users WHERE Email = '{email}'";

// ❌ Secreto escrito directamente en el código
var apiKey = "sk-1234567890abcdef";

// ❌ Información sensible en logs
_logger.LogInformation("User login: {Email}, Password: {Password}", email, password);

// ❌ Deserialización insegura
JsonConvert.DeserializeObject<object>(untrustedInput, new JsonSerializerSettings
{
    TypeNameHandling = TypeNameHandling.All // ¡PELIGROSO!
});

// ❌ Endpoint sin autorización
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(Guid id) // ¿Dónde está [Authorize]?
```

### Paso 4: Revisión de Rendimiento (15%)

#### Problemas Comunes

```csharp
// ❌ Consulta N+1
var orders = await _context.Orders.ToListAsync();
foreach (var order in orders)
{
    order.Items = await _context.OrderItems
        .Where(i => i.OrderId == order.Id)
        .ToListAsync(); // ¡N queries adicionales!
}

// ✅ Carga anticipada
var orders = await _context.Orders
    .Include(o => o.Items)
    .ToListAsync();

// ❌ Async sin await (lanzar y olvidar)
public void ProcessOrder(Order order)
{
    _emailService.SendAsync(order.Email, "Confirmación"); // ¡No se espera!
}

// ❌ Asignación innecesaria en ruta crítica
public string GetDisplayName(User user)
{
    return $"{user.FirstName} {user.LastName}".Trim(); // Nuevo string cada vez
}

// ❌ ToList() prematuro
var count = _context.Users.ToList().Count(); // ¡Carga TODA la tabla!
// ✅
var count = await _context.Users.CountAsync();
```

### Paso 5: Revisión de Convenciones (15%)

```
□ PascalCase para clases, métodos, propiedades públicas
□ camelCase para variables locales y parámetros
□ _camelCase para campos privados
□ Sufijo Async en métodos asíncronos
□ Interfaces con prefijo I
□ Los Namespaces coinciden con la estructura de carpetas
□ Archivos nombrados como la clase que contienen
□ Regiones evitadas (señal de clase grande)
□ Sentencias Using ordenadas y sin duplicados
```

### Paso 6: Revisión de Testing (15%)

```
□ ¿Los cambios incluyen tests nuevos o actualizados?
□ ¿Los tests cubren camino feliz Y casos límite?
□ ¿Los tests son independientes (no dependen del orden)?
□ ¿Los mocks verifican interacciones correctas?
□ ¿Hay tests de integración para cambios de infraestructura?
□ ¿La cobertura del código nuevo es ≥ 80%?
```

#### Señales de Alerta en Tests

```csharp
// ❌ Test sin verificación
[Fact]
public async Task Create_ShouldWork()
{
    await _sut.CreateAsync(new CreateUserDto()); // ¿Y qué verificamos?
}

// ❌ Test que pasa siempre
[Fact]
public void Validate_ShouldValidate()
{
    Assert.True(true); // Siempre verde
}

// ❌ Test acoplado a implementación
[Fact]
public void Delete_ShouldCallRepositoryThenLoggerThenCacheThenEventBus()
{
    // Verifica el orden exacto de 4 interacciones internas
    // → Frágil, se rompe con cualquier refactor
}
```

### Paso 7: Revisión de Legibilidad (10%)

```
□ ¿El código es autoexplicativo sin comentarios?
□ ¿Los nombres revelan la intención?
□ ¿La complejidad ciclomática es ≤ 10?
□ ¿Los métodos hacen una sola cosa?
□ ¿Los comentarios explican "por qué", no "qué"?
```

## Formato del Informe

```markdown
# Revisión de Código — PR #{número}: {título}

## 📊 Puntuación General: {X}/100

| Dimensión | Puntuación | Estado |
|-----------|-----------|--------|
| 🏗️ Arquitectura | {X}/25 | {✅ ⚠️ ❌} |
| 🔒 Seguridad | {X}/20 | {✅ ⚠️ ❌} |
| ⚡ Rendimiento | {X}/15 | {✅ ⚠️ ❌} |
| 📐 Convenciones | {X}/15 | {✅ ⚠️ ❌} |
| 🧪 Testing | {X}/15 | {✅ ⚠️ ❌} |
| 📖 Legibilidad | {X}/10 | {✅ ⚠️ ❌} |

## Veredicto

{🟢 APROBAR | 🟡 APROBAR CON CAMBIOS MENORES | 🔴 SOLICITAR CAMBIOS}

### Cambios Requeridos (bloqueantes)
1. {descripción del problema + archivo:línea + solución sugerida}

### Sugerencias (no bloqueantes)
1. {descripción + por qué mejoraría el código}

### Puntos Positivos ✨
1. {algo bien hecho que vale la pena destacar}

## Detalle por Archivo

### `src/Application/Handlers/CreateUserHandler.cs`

**Línea 34**: ❌ La validación de email debería estar en el Validator, no en el Handler.
```csharp
// Actual
if (!IsValidEmail(command.Email)) throw new Exception("Invalid");

// Sugerido
// Mover a CreateUserValidator usando FluentValidation
public class CreateUserValidator : AbstractValidator<CreateUserCommand>
{
    public CreateUserValidator()
    {
        RuleFor(x => x.Email).NotEmpty().EmailAddress();
    }
}
```

**Línea 67**: ⚠️ Considerar usar `CancellationToken` en la llamada async.
```csharp
// Actual
await _repository.SaveAsync();
// Sugerido
await _repository.SaveAsync(cancellationToken);
```
```

## Escala de Puntuación

| Rango | Veredicto | Acción |
|-------|-----------|--------|
| 90-100 | 🟢 Excelente | Aprobar directamente |
| 70-89 | 🟡 Bueno | Aprobar con sugerencias menores |
| 50-69 | 🟠 Necesita mejoras | Solicitar cambios específicos |
| 0-49 | 🔴 Requiere reescritura | Discutir enfoque con el autor |

## Etiquetas de Severidad

- `❌ Bloqueante` — Debe corregirse antes de fusionar
- `⚠️ Importante` — Debería corregirse, pero no bloquea
- `💡 Sugerencia` — Mejora opcional
- `❓ Pregunta` — Necesita aclaración del autor
- `✨ Bien hecho` — Refuerzo positivo

# .NET Core — Revisión de Código de Pull Requests

Skill para analizar Pull Requests de proyectos .NET Core y generar informes de revisión de código detallados con puntuación y recomendaciones accionables.

## Cuándo Usar

- Al recibir una PR para revisión
- Antes de fusionar a `main` o `develop`
- Para auditorías de calidad de código
- Como segundo par de ojos tras una revisión humana

## Dimensiones de Evaluación

El análisis cubre 6 dimensiones, cada una con un peso diferente:

| Dimensión | Peso | Qué Evalúa |
|-----------|------|-------------|
| 🏗️ **Arquitectura** | 25% | Separación de capas, Inversión de Dependencias (DI), patrones |
| 🔒 **Seguridad** | 20% | Vulnerabilidades, secretos en código, validación de inputs |
| ⚡ **Rendimiento** | 15% | Problemas N+1, asignaciones de memoria, uso de async/await |
| 📐 **Convenciones** | 15% | Nomenclatura, formato, alineación con el estilo del equipo |
| 🧪 **Testing** | 15% | Cobertura de pruebas, calidad de los tests, casos límite |
| 📖 **Legibilidad** | 10% | Claridad, complejidad ciclomática, documentación |

## Proceso de Revisión

### Paso 1: Analizar el Contexto de la PR

Leer:
- **Título y descripción** de la PR
- **Commits** incluidos (mensajes y tamaño)
- **Archivos modificados** (estadísticas y lista)
- **Incidencia o ticket** vinculado (si lo hay)

Evaluar:
```
✅ La PR tiene un propósito único y claro
✅ Los commits son atómicos y descriptivos
✅ El tamaño es razonable (< 400 líneas idealmente)
⚠️ PR masiva (> 400 líneas) → Sugerir dividir
❌ PR sin descripción → Solicitar contexto
```

### Paso 2: Revisión de Arquitectura (25%)

#### Verificaciones
```
□ ¿Respeta la separación de capas (Domain → Application → Infrastructure)?
□ ¿Las dependencias fluyen hacia adentro (Regla de Dependencia)?
□ ¿Se registran correctamente los nuevos servicios en inyección de dependencias?
□ ¿Se usan interfaces para definir abstracciones clave?
□ ¿Están desacoplados los DTOs de las entidades de dominio?
□ ¿Se aplican los patrones estructurales del proyecto (CQRS, Repository, etc.)?
```

### Paso 3: Revisión de Seguridad (20%)

#### Lista de Verificación Crítica
```
□ No hay contraseñas o secretos hardcodeados
□ Se validan todas las entradas de usuario (FluentValidation / Data Annotations)
□ Se usa parametrización en queries a BBDD (protección SQLi)
□ Los endpoints tienen `[Authorize]` adecuadamente aplicado
□ No se exponen StackTraces ni de errores internos al cliente en Producción
□ Se sanitiza la salida (Output encoding contra XSS)
□ Manejo seguro en la subida de archivos (tipo, tamaño)
□ Configuración correcta de CORS
```

### Paso 4: Revisión de Rendimiento (15%)

#### Problemas Comunes a Vigilar
```
□ Consultas N+1 en Entity Framework (faltan métodos `.Include()`)
□ Uso asíncrono sin `await` (Launch and Forget) en contextos críticos
□ Asignación de memoria en bucles y rutas calientes (ej: excesivo `.ToList()`)
```

### Paso 5: Revisión de Convenciones (15%)

```
□ PascalCase para tipos y miembros públicos
□ camelCase para variables locales y firmas
□ _camelCase para campos privados de clase
□ Uso de sufijo `Async` en firmas Tasks o corutinas
□ Namespaces que coinciden fielmente con los directorios
```

### Paso 6: Revisión de Testing (15%)

```
□ ¿Hay tests nuevos que acompañan la lógica implementada?
□ ¿Se testean los "happy paths" y "edge cases"?
□ ¿Están correctamente isolados y libres de dependencias temporales/secuenciales?
□ ¿Se proveen buenos *Assertions* y comprobación del resultado esperado?
```

### Paso 7: Revisión de Legibilidad (10%)

```
□ Código descriptivo y auto-explicativo frente a redundancia de comentarios
□ Limitación de la complejidad ciclomática de los métodos
□ Principio de Única Responsabilidad visible por componente
```

## Formato de Entrega del Informe

Emplea Markdown para generar un informe estructurado como sigue (adaptado según conclusiones):

```markdown
# Revisión de Código — PR #{número}: {título}

## 📊 Puntuación General: {X}/100

| Dimensión | Puntuación | Estado |
|-----------|-----------|--------|
| 🏗️ Arquitectura | {X}/25 | {✅ ⚠️ ❌} |
... y el resto de la tabla

## Veredicto
{🟢 APROBAR | 🟡 APROBAR CON CAMBIOS MENORES | 🔴 SOLICITAR CAMBIOS}

### Cambios Requeridos (bloqueantes)
1. ...

### Sugerencias (no bloqueantes)
1. ...
```

# Modern C# Coding Standards

## When to Use This Skill

Use this skill when:
- Writing new C# code or refactoring existing code
- Designing public APIs for libraries or services
- Optimizing performance-critical code paths
- Implementing domain models with strong typing
- Building async/await-heavy applications
- Working with binary data, buffers, or high-throughput scenarios

## Reference Files

- [value-objects-and-patterns.md](value-objects-and-patterns.md): Full value object examples and pattern matching code
- [performance-and-api-design.md](performance-and-api-design.md): Span<T>/Memory<T> examples and API design principles
- [composition-and-error-handling.md](composition-and-error-handling.md): Composition over inheritance, Result type, testing patterns
- [anti-patterns-and-reflection.md](anti-patterns-and-reflection.md): Reflection avoidance and common anti-patterns

## Core Principles

1. **Immutability by Default** - Use `record` types and `init`-only properties
2. **Type Safety** - Leverage nullable reference types and value objects
3. **Modern Pattern Matching** - Use `switch` expressions and patterns extensively
4. **Async Everywhere** - Prefer async APIs with proper cancellation support
5. **Zero-Allocation Patterns** - Use `Span<T>` and `Memory<T>` for performance-critical code
6. **API Design** - Accept abstractions, return appropriately specific types
7. **Composition Over Inheritance** - Avoid abstract base classes, prefer composition
8. **Value Objects as Structs** - Use `readonly record struct` for value objects

---

## Language Patterns

### Records for Immutable Data (C# 9+)

Use `record` types for DTOs, messages, events, and domain entities.

```csharp
// Simple immutable DTO
public record CustomerDto(string Id, string Name, string Email);

// Record with validation in constructor
public record EmailAddress
{
    public string Value { get; init; }

    public EmailAddress(string value)
    {
        if (string.IsNullOrWhiteSpace(value) || !value.Contains('@'))
            throw new ArgumentException("Invalid email address", nameof(value));

        Value = value;
    }
}

// Records with collections - use IReadOnlyList
public record ShoppingCart(
    string CartId,
    string CustomerId,
    IReadOnlyList<CartItem> Items
)
{
    public decimal Total => Items.Sum(item => item.Price * item.Quantity);
}
```

**When to use `record class` vs `record struct`:**
- `record class` (default): Reference types, use for entities, aggregates, DTOs with multiple properties
- `record struct`: Value types, use for value objects (see next section)

### Value Objects as readonly record struct

Value objects should **always be `readonly record struct`** for performance and value semantics. Use explicit conversions, never implicit operators.

```csharp
public readonly record struct OrderId(string Value)
{
    public OrderId(string value) : this(
        !string.IsNullOrWhiteSpace(value)
            ? value
            : throw new ArgumentException("OrderId cannot be empty", nameof(value)))
    { }
    public override string ToString() => Value;
}

public readonly record struct Money(decimal Amount, string Currency);
public readonly record struct CustomerId(Guid Value)
{
    public static CustomerId New() => new(Guid.NewGuid());
}
```

See [value-objects-and-patterns.md](value-objects-and-patterns.md) for complete examples including multi-value objects, factory patterns, and the no-implicit-conversion rule.

### Pattern Matching (C# 8-12)

Use switch expressions, property patterns, relational patterns, and list patterns for cleaner code.

```csharp
public decimal CalculateDiscount(Order order) => order switch
{
    { Total: > 1000m } => order.Total * 0.15m,
    { Total: > 500m } => order.Total * 0.10m,
    { Total: > 100m } => order.Total * 0.05m,
    _ => 0m
};
```

See [value-objects-and-patterns.md](value-objects-and-patterns.md) for full pattern matching examples.

---

### Nullable Reference Types (C# 8+)

Enable nullable reference types in your project and handle nulls explicitly.

```csharp
// In .csproj
<PropertyGroup>
    <Nullable>enable</Nullable>
</PropertyGroup>

// Explicit nullability
public string? FindUserName(string userId)
{
    var user = _repository.Find(userId);
    return user?.Name;
}

// Pattern matching with null checks
public decimal GetDiscount(Customer? customer) => customer switch
{
    null => 0m,
    { IsVip: true } => 0.20m,
    { OrderCount: > 10 } => 0.10m,
    _ => 0.05m
};

// Guard clauses with ArgumentNullException.ThrowIfNull (C# 11+)
public void ProcessOrder(Order? order)
{
    ArgumentNullException.ThrowIfNull(order);
    // order is now non-nullable in this scope
    Console.WriteLine(order.Id);
}
```

---

## Composition Over Inheritance

**Avoid abstract base classes.** Use interfaces + composition. Use static helpers for shared logic. Use records with factory methods for variants.

See [composition-and-error-handling.md](composition-and-error-handling.md) for full examples.

---

## Performance Patterns

### Async/Await Best Practices

```csharp
// Async all the way - always accept CancellationToken
public async Task<Order> GetOrderAsync(string orderId, CancellationToken cancellationToken)
{
    var order = await _repository.GetAsync(orderId, cancellationToken);
    return order;
}

// ValueTask for frequently-called, often-synchronous methods
public ValueTask<Order?> GetCachedOrderAsync(string orderId, CancellationToken cancellationToken)
{
    if (_cache.TryGetValue(orderId, out var order))
        return ValueTask.FromResult<Order?>(order);
    return GetFromDatabaseAsync(orderId, cancellationToken);
}

// IAsyncEnumerable for streaming
public async IAsyncEnumerable<Order> StreamOrdersAsync(
    string customerId,
    [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
    await foreach (var order in _repository.StreamAllAsync(cancellationToken))
    {
        if (order.CustomerId == customerId)
            yield return order;
    }
}
```

**Key rules:**
- Always accept `CancellationToken` with `= default`
- Use `ConfigureAwait(false)` in library code
- Never block on async code (no `.Result` or `.Wait()`)
- Use linked CancellationTokenSource for timeouts

### Span<T> and Memory<T>

Use `Span<T>` for synchronous zero-allocation operations, `Memory<T>` for async, and `ArrayPool<T>` for large temporary buffers.

See [performance-and-api-design.md](performance-and-api-design.md) for complete Span/Memory examples and the API design section.

---

## Error Handling: Result Type

For expected errors, use `Result<T, TError>` instead of exceptions. Use exceptions only for unexpected/system errors.

See [composition-and-error-handling.md](composition-and-error-handling.md) for the full Result type implementation and usage examples.

---

## Avoid Reflection-Based Metaprogramming

**Banned:** AutoMapper, Mapster, ExpressMapper. Use explicit mapping extension methods instead. Use `UnsafeAccessorAttribute` (.NET 8+) when you genuinely need private member access.

See [anti-patterns-and-reflection.md](anti-patterns-and-reflection.md) for full guidance.

---

## Code Organization

```csharp
// File: Domain/Orders/Order.cs

namespace MyApp.Domain.Orders;

// 1. Primary domain type
public record Order(
    OrderId Id,
    CustomerId CustomerId,
    Money Total,
    OrderStatus Status,
    IReadOnlyList<OrderItem> Items
)
{
    public bool IsCompleted => Status is OrderStatus.Completed;

    public Result<Order, OrderError> AddItem(OrderItem item)
    {
        if (Status is not OrderStatus.Draft)
            return Result<Order, OrderError>.Failure(
                new OrderError("ORDER_NOT_DRAFT", "Can only add items to draft orders"));

        var newItems = Items.Append(item).ToList();
        var newTotal = new Money(
            Items.Sum(i => i.Total.Amount) + item.Total.Amount,
            Total.Currency);

        return Result<Order, OrderError>.Success(
            this with { Items = newItems, Total = newTotal });
    }
}

// 2. Enums for state
public enum OrderStatus { Draft, Submitted, Processing, Completed, Cancelled }

// 3. Related types
public record OrderItem(ProductId ProductId, Quantity Quantity, Money UnitPrice)
{
    public Money Total => new(UnitPrice.Amount * Quantity.Value, UnitPrice.Currency);
}

// 4. Value objects
public readonly record struct OrderId(Guid Value)
{
    public static OrderId New() => new(Guid.NewGuid());
}

// 5. Errors
public readonly record struct OrderError(string Code, string Message);
```

---

## Best Practices Summary

### DO's
- Use `record` for DTOs, messages, and domain entities
- Use `readonly record struct` for value objects
- Leverage pattern matching with `switch` expressions
- Enable and respect nullable reference types
- Use async/await for all I/O operations
- Accept `CancellationToken` in all async methods
- Use `Span<T>` and `Memory<T>` for high-performance scenarios
- Accept abstractions (`IEnumerable<T>`, `IReadOnlyList<T>`)
- Use `Result<T, TError>` for expected errors
- Pool buffers with `ArrayPool<T>` for large allocations
- Prefer composition over inheritance

### DON'Ts
- Don't use mutable classes when records work
- Don't use classes for value objects (use `readonly record struct`)
- Don't create deep inheritance hierarchies
- Don't ignore nullable reference type warnings
- Don't block on async code (`.Result`, `.Wait()`)
- Don't use `byte[]` when `Span<byte>` suffices
- Don't forget `CancellationToken` parameters
- Don't return mutable collections from APIs
- Don't throw exceptions for expected business errors
- Don't allocate large arrays repeatedly (use `ArrayPool`)

See [anti-patterns-and-reflection.md](anti-patterns-and-reflection.md) for detailed anti-pattern examples.

---

## Additional Resources

- **C# Language Specification**: https://learn.microsoft.com/en-us/dotnet/csharp/
- **Pattern Matching**: https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching
- **Span<T> and Memory<T>**: https://learn.microsoft.com/en-us/dotnet/standard/memory-and-spans/
- **Async Best Practices**: https://learn.microsoft.com/en-us/archive/msdn-magazine/2013/march/async-await-best-practices-in-asynchronous-programming
- **.NET Performance Tips**: https://learn.microsoft.com/en-us/dotnet/framework/performance/

# Modern C# Coding Standards

## Cuándo usar esta skill

Úsala cuando vayas a:
- Escribir código nuevo o refactorizar C# existente.
- Diseñar la API pública para bibliotecas o servicios.
- Optimizar rutas de ejecución críticas a nivel de rendimiento.
- Modelar lógicas del dominio fuertemente tipadas.
- Orquestar operaciones asíncronas masivas (async/await pesado).
- Lidiar con representaciones binarias en memoria, buffers o entornos de alta concurrencia.

## Principios Centrales

1. **Inmutabilidad por defecto** - Preferencia por los tipos `record` y las propiedades `init`.
2. **Type Safety** - Uso de tipos de referencia anulables (`Nullable Reference Types`) y objetos de valor (Value Objects).
3. **Pattern Matching Moderno** - Dominio de expresiones `switch` y patrones variados de C# emergentes.
4. **Async por doquier** - Preferencia absoluta por APIs asíncronas delegando su Cancellation Token oportunamente.
5. **Zero-Allocation** - Dominio de `Span<T>` y `Memory<T>` para secciones críticas donde minimizar interacciones con el Garbage Collector es vital.
6. **Diseño de APIs** - Acepta abstracciones genéricas (ej: `IEnumerable`) pero retorna tipos razonablemente explícitos o sellados.
7. **Composición sobre Herencia** - Evita clases abstractas base, favoreciendo delegación e interefaces.
8. **Objetos de Valor (Value Objects) estructurados** - Implementados preferiblemente con `readonly record struct`.

---

## Patrones de Lenguaje

### Records para Datos Inmutables (C# 9+)

Usados en Modelos DTO, Mensajes asíncronos y Entidades de Dominio.

```csharp
// DTO Inmutable simple
public record CustomerDto(string Id, string Name, string Email);

// Evitar la mutabilidad con Listas: Usa interfaces de sólo lectura
public record ShoppingCart(
    string CartId,
    IReadOnlyList<CartItem> Items
)
{
    public decimal Total => Items.Sum(item => item.Price * item.Quantity);
}
```

### Objetos de Valor en readonly record struct

Todo VO debería ser empaquetado usando `readonly record struct` para un rendimiento ideal y semántica de valores directos.

```csharp
public readonly record struct OrderId(string Value)
{
    public OrderId(string value) : this(
        !string.IsNullOrWhiteSpace(value)
            ? value
            : throw new ArgumentException("El OrderId no puede ir vacío.", nameof(value)))
    { }
    public override string ToString() => Value;
}
```

### Composición por encima de herencia

**Evita las super-clases heredadas**.
Usa métodos estáticos para lógicas compartidas y prioriza los patrones factoría sobre interfaces cuando generes variaciones de un mismo ente.

---

## Patrones de Rendimiento

### Buenas Prácticas Async/Await

```csharp
// Inyección hasta el fondo con los CancellationToken
public async Task<Order> GetOrderAsync(string orderId, CancellationToken cancellationToken = default)
{
    return await _repository.GetAsync(orderId, cancellationToken);
}

// Empleo de ValueTask para operaciones probabilísticamente sincrónicas y veloces (como usar métodos que dependen mucho de Cachés locales)
public ValueTask<Order?> GetCachedOrderAsync(string orderId, CancellationToken cancellationToken)
{
    if (_cache.TryGetValue(orderId, out var order))
        return ValueTask.FromResult<Order?>(order);
        
    return GetFromDatabaseAsync(orderId, cancellationToken);
}
```

**Reglas de Oro:**
- NUNCA uses métodos `.Wait()` y `.Result` de una operación Task de manera asíncrona (conllevará *deadlocks* en subprocesos sincronizados).

## Tipos Result en lugar de Excepciones

Usa un modelo o tipo base `Result<T, TError>` en detrimento de excepciones programáticas. Las `throw Exception` se resguardan ÚNICAMENTE para errores y cataclismos no esperados de red/sistema o validaciones técnicas ineludibles.

## Resumen de Mejores Prácticas

### HAZLO:
- Usa `record` para todos los DTOs y Mensajería.
- Usa `readonly record struct` en los objetos de valor.
- Exige `CancellationToken` siempre que haya un `Task` asíncrono.
- Utiliza `ArrayPool<T>` si necesitas buffers gigantes durante poco tiempo.

### NO LO HAGAS:
- Evadir las advertencias de compilador sobre anulables: son tu primera línea de defensa contra `NullReferenceException`.
- Escribir `byte[]` en cascada si un simple `Span<byte>` te permite ojear subcadenas sin recolocarlas de nuevo en pila o memoria.

# .NET Concurrency: Choosing the Right Tool

## When to Use This Skill

Use this skill when:
- Deciding how to handle concurrent operations in .NET
- Evaluating whether to use async/await, Channels, Akka.NET, or other abstractions
- Tempted to use locks, semaphores, or other synchronization primitives
- Need to process streams of data with backpressure, batching, or debouncing
- Managing state across multiple concurrent entities

## Reference Files

- [advanced-concurrency.md](advanced-concurrency.md): Akka.NET Streams, Reactive Extensions, Akka.NET Actors (entity-per-actor, state machines, cluster sharding), and async local function patterns

## The Philosophy

**Start simple, escalate only when needed.**

Most concurrency problems can be solved with `async/await`. Only reach for more sophisticated tools when you have a specific need that async/await can't address cleanly.

**Try to avoid shared mutable state.** The best way to handle concurrency is to design it away. Immutable data, message passing, and isolated state (like actors) eliminate entire categories of bugs.

**Locks should be the exception, not the rule.** When you can't avoid shared mutable state:
1. **First choice:** Redesign to avoid it (immutability, message passing, actor isolation)
2. **Second choice:** Use `System.Collections.Concurrent` (ConcurrentDictionary, etc.)
3. **Third choice:** Use `Channel<T>` to serialize access through message passing
4. **Last resort:** Use `lock` for simple, short-lived critical sections

---

## Decision Tree

```
What are you trying to do?
│
├─► Wait for I/O (HTTP, database, file)?
│   └─► Use async/await
│
├─► Process a collection in parallel (CPU-bound)?
│   └─► Use Parallel.ForEachAsync
│
├─► Producer/consumer pattern (work queue)?
│   └─► Use System.Threading.Channels
│
├─► UI event handling (debounce, throttle, combine)?
│   └─► Use Reactive Extensions (Rx)
│
├─► Server-side stream processing (backpressure, batching)?
│   └─► Use Akka.NET Streams
│
├─► State machines with complex transitions?
│   └─► Use Akka.NET Actors (Become pattern)
│
├─► Manage state for many independent entities?
│   └─► Use Akka.NET Actors (entity-per-actor)
│
├─► Coordinate multiple async operations?
│   └─► Use Task.WhenAll / Task.WhenAny
│
└─► None of the above fits?
    └─► Ask yourself: "Do I really need shared mutable state?"
        ├─► Yes → Consider redesigning to avoid it
        └─► Truly unavoidable → Use Channels or Actors to serialize access
```

---

## Level 1: async/await (Default Choice)

**Use for:** I/O-bound operations, non-blocking waits, most everyday concurrency.

```csharp
// Simple async I/O
public async Task<Order> GetOrderAsync(string orderId, CancellationToken ct)
{
    var order = await _database.GetAsync(orderId, ct);
    var customer = await _customerService.GetAsync(order.CustomerId, ct);
    return order with { Customer = customer };
}

// Parallel async operations (when independent)
public async Task<Dashboard> LoadDashboardAsync(string userId, CancellationToken ct)
{
    var ordersTask = _orderService.GetRecentOrdersAsync(userId, ct);
    var notificationsTask = _notificationService.GetUnreadAsync(userId, ct);
    var statsTask = _statsService.GetUserStatsAsync(userId, ct);

    await Task.WhenAll(ordersTask, notificationsTask, statsTask);

    return new Dashboard(
        Orders: await ordersTask,
        Notifications: await notificationsTask,
        Stats: await statsTask);
}
```

**Key principles:** Always accept `CancellationToken`. Use `ConfigureAwait(false)` in library code. Don't block on async code.

---

## Level 2: Parallel.ForEachAsync (CPU-Bound Parallelism)

**Use for:** Processing collections in parallel when work is CPU-bound or you need controlled concurrency.

```csharp
public async Task ProcessOrdersAsync(
    IEnumerable<Order> orders,
    CancellationToken ct)
{
    await Parallel.ForEachAsync(
        orders,
        new ParallelOptions
        {
            MaxDegreeOfParallelism = Environment.ProcessorCount,
            CancellationToken = ct
        },
        async (order, token) =>
        {
            await ProcessOrderAsync(order, token);
        });
}
```

**When NOT to use:** Pure I/O operations, when order matters, when you need backpressure.

---

## Level 3: System.Threading.Channels (Producer/Consumer)

**Use for:** Work queues, producer/consumer patterns, decoupling producers from consumers.

```csharp
public class OrderProcessor
{
    private readonly Channel<Order> _channel;

    public OrderProcessor()
    {
        _channel = Channel.CreateBounded<Order>(new BoundedChannelOptions(100)
        {
            FullMode = BoundedChannelFullMode.Wait
        });
    }

    // Producer
    public async Task EnqueueOrderAsync(Order order, CancellationToken ct)
    {
        await _channel.Writer.WriteAsync(order, ct);
    }

    // Consumer (run as background task)
    public async Task ProcessOrdersAsync(CancellationToken ct)
    {
        await foreach (var order in _channel.Reader.ReadAllAsync(ct))
        {
            await ProcessOrderAsync(order, ct);
        }
    }

    public void Complete() => _channel.Writer.Complete();
}
```

**Channels are good for:** Decoupling speed, buffering with backpressure, fan-out to workers, background queues.

**Channels are NOT good for:** Complex stream operations (batching, windowing), stateful per-entity processing, sophisticated supervision.

---

## Level 4+: Akka.NET Streams, Reactive Extensions, Actors

For advanced scenarios requiring stream processing, UI event composition, or stateful entity management, see [advanced-concurrency.md](advanced-concurrency.md).

**Akka.NET Streams** excel at server-side batching, throttling, and backpressure. **Reactive Extensions** are ideal for UI event composition. **Akka.NET Actors** handle entity-per-actor patterns, state machines with `Become()`, and distributed systems via Cluster Sharding.

---

## Anti-Patterns: What to Avoid

### Locks for Business Logic

```csharp
// BAD: Using locks to protect shared state
private readonly object _lock = new();
private Dictionary<string, Order> _orders = new();

public void UpdateOrder(string id, Action<Order> update)
{
    lock (_lock) { if (_orders.TryGetValue(id, out var order)) update(order); }
}

// GOOD: Use an actor or Channel to serialize access
```

### Manual Thread Management

```csharp
// BAD: Creating threads manually
var thread = new Thread(() => ProcessOrders());
thread.Start();

// GOOD: Use Task.Run or better abstractions
_ = Task.Run(() => ProcessOrdersAsync(cancellationToken));
```

### Blocking in Async Code

```csharp
// BAD: Blocking on async - deadlock risk!
var result = GetDataAsync().Result;

// GOOD: Async all the way
var result = await GetDataAsync();
```

### Shared Mutable State Without Protection

```csharp
// BAD: Multiple tasks mutating shared state
var results = new List<Result>();
await Parallel.ForEachAsync(items, async (item, ct) =>
{
    var result = await ProcessAsync(item, ct);
    results.Add(result); // Race condition!
});

// GOOD: Use ConcurrentBag
var results = new ConcurrentBag<Result>();
```

---

## Quick Reference: Which Tool When?

| Need | Tool | Example |
|------|------|---------|
| Wait for I/O | `async/await` | HTTP calls, database queries |
| Parallel CPU work | `Parallel.ForEachAsync` | Image processing, calculations |
| Work queue | `Channel<T>` | Background job processing |
| UI events with debounce/throttle | Reactive Extensions | Search-as-you-type, auto-save |
| Server-side batching/throttling | Akka.NET Streams | Event aggregation, rate limiting |
| State machines | Akka.NET Actors | Payment flows, order lifecycles |
| Entity state management | Akka.NET Actors | Order management, user sessions |
| Fire multiple async ops | `Task.WhenAll` | Loading dashboard data |
| Race multiple async ops | `Task.WhenAny` | Timeout with fallback |
| Periodic work | `PeriodicTimer` | Health checks, polling |

---

## The Escalation Path

```
async/await (start here)
    │
    ├─► Need parallelism? → Parallel.ForEachAsync
    │
    ├─► Need producer/consumer? → Channel<T>
    │
    ├─► Need UI event composition? → Reactive Extensions
    │
    ├─► Need server-side stream processing? → Akka.NET Streams
    │
    └─► Need state machines or entity management? → Akka.NET Actors
```

**Only escalate when you have a concrete need.** Don't reach for actors or streams "just in case".

# Concurrencia .NET: Eligiendo la herramienta adaptada

## Cuándo usar esta skill

Acude a este archivo cuando:
- Has de definir cómo atajar hilos de ejecución concurrentes en operaciones de .NET.
- Evaluando las directivas `async/await` clásicas contra `Channels`, u otros modelos en cascada.
- Tienes la tentación de lanzar primitivas de `lock` o semáforos a diestro y siniestro.
- Administras cuellos de botella controlados, agrupamiento por lotes (batching) o control de peticiones en desborde.

## La Filosofía .NET Contemporánea

**Comienza en lo simple, escala gradualmente y solo si hay pruebas físicas irrebatibles de hacerlo.**

El 95% de la concurrencia normal se solventa combinando con destreza `async/await`.

**Tus prioridades cuando de estado mutado concurrente se trata:**
1. **Prioridad Máxima**: Rediseña la estructura en aislamiento o delegación explícita (mensajería) para NO compartir estado.
2. **Prioridad Secundaria**: Usa variables o colecciones especializadas como `System.Collections.Concurrent` (Ejemplo: `ConcurrentDictionary`).
3. **Prioridad Terciaria**: Usa `Channel<T>` para canalizar peticiones sin trabar memoria simultáneamente.
4. **Resorte Primitivo (y Final)**: Utilización breve de primitivas limitadas con `lock`.

---

## Árbol de decisiones y atajos mentalese

```
¿Qué estamos intentando modelar o resolver?
│
├─► ¿Espera de lectura/escritura (BBDD, HTTP, FileSystem)?
│   └─► Usa async/await habitual
│
├─► ¿Acumular listas gigantescas y procesar las variables (Problemas con el CPu bound)?
│   └─► Parallel.ForEachAsync 
│
├─► ¿Modelo Productor / Consumidor?
│   └─► System.Threading.Channels
│
├─► ¿Acumulación temporal de eventos de interfaz y "debounce"?
│   └─► Extensiones y flujos Reactivos (Rx)
│
└─► ¿Unión o gestión de decenas de operaciones aisladas ya lanzadas?
    └─► Task.WhenAll / Task.WhenAny para aguardar su resolución conjunta o la primera completada
```

## Level 1: `async/await` tradicional

Es la capa fundacional. Para esperar a la red, acceso a disco, acceso relacional de BBDD. Asegúrate SIEMPRE de dotar y arrastrar el parámetro predefinido `CancellationToken ct` hasta el final. Nunca bloquees una tarea con un síncrono `.Result` sobre su cabecera Task.

## Level 2: `Parallel.ForEachAsync`
Apto para concurrencia dependiente estrechamente del procesador y recursos CPU donde las variables no interfieren entre sí.

## Level 3: `System.Threading.Channels` (Productor/Consumidor)

Utilizado masivamente para procesos y workers asíncronos que corren en Background sin acoplar dependencias a quienes los impulsan en el Request.
Provee utilidades sofisticadas para generar buffers en memoria local y definir reglas de desborde y Backpressure.

```csharp
_channel = Channel.CreateBounded<Order>(new BoundedChannelOptions(100)
{
    FullMode = BoundedChannelFullMode.Wait // Bloquea al productor sutilmente mientras hay un pico
});
```

## Antipatrones Frecuentes

### Peligro: Gestión humana de hilos

```csharp
// INCORRECTO: Hilos manuales que escapan al hilo principal de procesos
var thread = new Thread(() => ProcessOrders());
thread.Start();

// CORRECTO: Manejo del Pool de Procesos asíncronos con envoltorio de supervisión controlada
_ = Task.Run(() => ProcessOrdersAsync(cancellationToken));
```

### Tareas superpuestas sin Mutex

```csharp
// INCORRECTO: Colecciones estándar perdiendo datos si hay dos threads
var results = new List<Result>();
await Parallel.ForEachAsync(items, async (item, ct) =>
{
    var result = await ProcessAsync(item, ct);
    results.Add(result); // Condiciones de Carrera en List<> causarán corrupción
});

// CORRECTO: Usar entidades concebidas para esta tarea
var results = new ConcurrentBag<Result>();
```

# Database Performance Patterns

## When to Use This Skill

Use this skill when:
- Designing data access layers
- Optimizing slow database queries
- Choosing between EF Core and Dapper
- Avoiding common performance pitfalls

---

## Core Principles

1. **Separate read and write models** - Don't use the same types for both
2. **Think in batches** - Avoid N+1 queries
3. **Only retrieve what you need** - No SELECT *
4. **Apply row limits** - Always have a configurable Take/Limit
5. **Do joins in SQL** - Never in application code
6. **AsNoTracking for reads** - EF Core change tracking is expensive

---

## Read/Write Model Separation (CQRS Pattern)

**Read and write models are fundamentally different - they have different shapes, columns, and purposes.** Don't create a single "User" entity and reuse it everywhere.

- **Read models** are denormalized, optimized for query efficiency, and return multiple projection types (UserProfile, UserSummary, UserDetailForAdmin)
- **Write models** are normalized, validation-focused, and accept strongly-typed commands (CreateUserCommand, UpdateUserCommand)

### Architecture

```
src/
  MyApp.Data/
    Users/
      # Read side - multiple optimized projections
      IUserReadStore.cs
      PostgresUserReadStore.cs

      # Write side - command handlers
      IUserWriteStore.cs
      PostgresUserWriteStore.cs

      # Read DTOs - lightweight, denormalized
      UserProfile.cs
      UserSummary.cs

      # Write commands - validation-focused
      CreateUserCommand.cs
      UpdateUserCommand.cs
    Orders/
      IOrderReadStore.cs
      IOrderWriteStore.cs
      (similar structure...)
```

### Read Store Interface

```csharp
// Read models: Multiple specialized projections optimized for different use cases
public interface IUserReadStore
{
    // Returns detailed profile for single-user view
    Task<UserProfile?> GetByIdAsync(UserId id, CancellationToken ct = default);

    // Returns lightweight info for lookups
    Task<UserProfile?> GetByEmailAsync(EmailAddress email, CancellationToken ct = default);

    // Returns paginated summaries - only what the list view needs
    Task<IReadOnlyList<UserSummary>> GetAllAsync(int limit, UserId? cursor = null, CancellationToken ct = default);

    // Boolean query - no entity needed
    Task<bool> EmailExistsAsync(EmailAddress email, CancellationToken ct = default);
}
```

### Write Store Interface

```csharp
// Write model: Accepts strongly-typed commands, minimal return values
public interface IUserWriteStore
{
    // Returns only the created ID - caller doesn't need the full entity
    Task<UserId> CreateAsync(CreateUserCommand command, CancellationToken ct = default);

    // Update validates command, returns void (success or throws)
    Task UpdateAsync(UserId id, UpdateUserCommand command, CancellationToken ct = default);

    // Delete is simple and explicit
    Task DeleteAsync(UserId id, CancellationToken ct = default);
}
```

**Key structural differences illustrated:**
- Read store returns multiple different DTOs (UserProfile, UserSummary, bool flag)
- Write store returns minimal data (just UserId on create) or void
- Read queries are stateless projections - no tracking needed
- Write operations focus on command validation, not retrieving data afterwards
- Different databases/tables can back read vs write (eventual consistency pattern)

---

## Always Apply Row Limits

**Never return unbounded result sets.** Every read method should have a configurable limit.

### Pattern: Limit Parameter

```csharp
public interface IOrderReadStore
{
    // Limit is required, not optional
    Task<IReadOnlyList<OrderSummary>> GetByCustomerAsync(
        CustomerId customerId,
        int limit,
        OrderId? cursor = null,
        CancellationToken ct = default);
}

// Implementation
public async Task<IReadOnlyList<OrderSummary>> GetByCustomerAsync(
    CustomerId customerId,
    int limit,
    OrderId? cursor = null,
    CancellationToken ct = default)
{
    await using var connection = await _dataSource.OpenConnectionAsync(ct);

    const string sql = """
        SELECT id, customer_id, total, status, created_at
        FROM orders
        WHERE customer_id = @CustomerId
        AND (@Cursor IS NULL OR created_at < (SELECT created_at FROM orders WHERE id = @Cursor))
        ORDER BY created_at DESC
        LIMIT @Limit
        """;

    var rows = await connection.QueryAsync<OrderRow>(sql, new
    {
        CustomerId = customerId.Value,
        Cursor = cursor?.Value,
        Limit = limit
    });

    return rows.Select(r => r.ToOrderSummary()).ToList();
}
```

### EF Core with Pagination

```csharp
public async Task<PaginatedList<OrderSummary>> GetOrdersAsync(
    CustomerId customerId,
    Paginator paginator,
    CancellationToken ct = default)
{
    var query = _context.Orders
        .AsNoTracking()
        .Where(o => o.CustomerId == customerId.Value)
        .OrderByDescending(o => o.CreatedAt);

    var totalCount = await query.CountAsync(ct);

    var orders = await query
        .Skip((paginator.PageNumber - 1) * paginator.PageSize)
        .Take(paginator.PageSize)  // Always limit!
        .Select(o => new OrderSummary(
            new OrderId(o.Id),
            o.Total,
            o.Status,
            o.CreatedAt))
        .ToListAsync(ct);

    return new PaginatedList<OrderSummary>(
        orders,
        totalCount,
        paginator.PageSize,
        paginator.PageNumber);
}
```

---

## AsNoTracking for Read Queries

EF Core's change tracking is expensive. Disable it for read-only queries.

```csharp
// DO: Disable tracking for reads
var users = await _context.Users
    .AsNoTracking()
    .Where(u => u.IsActive)
    .ToListAsync();

// DON'T: Track entities you won't modify
var users = await _context.Users
    .Where(u => u.IsActive)
    .ToListAsync();  // Change tracking enabled - wasteful
```

### Configure Default Behavior

```csharp
// For read-heavy applications, consider this in DbContext
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder.UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking);
}
```

Then explicitly enable tracking when needed:

```csharp
var user = await _context.Users
    .AsTracking()  // Explicit - we intend to modify
    .FirstOrDefaultAsync(u => u.Id == userId);
```

---

## Avoid N+1 Queries

The N+1 problem: fetching a list, then querying for each item's related data.

### The Problem

```csharp
// BAD: N+1 queries
var orders = await _context.Orders.ToListAsync();

foreach (var order in orders)
{
    // Each iteration hits the database!
    var items = await _context.OrderItems
        .Where(i => i.OrderId == order.Id)
        .ToListAsync();
}
```

### Solution 1: Include (EF Core)

```csharp
// GOOD: Single query with join
var orders = await _context.Orders
    .AsNoTracking()
    .Include(o => o.Items)
    .ToListAsync();
```

### Solution 2: Batch Query (Dapper)

```csharp
// GOOD: Two queries, no N+1
const string sql = """
    SELECT id, customer_id, total FROM orders WHERE customer_id = @CustomerId;
    SELECT oi.* FROM order_items oi
    INNER JOIN orders o ON oi.order_id = o.id
    WHERE o.customer_id = @CustomerId;
    """;

using var multi = await connection.QueryMultipleAsync(sql, new { CustomerId = customerId });
var orders = (await multi.ReadAsync<OrderRow>()).ToList();
var items = (await multi.ReadAsync<OrderItemRow>()).ToList();

// Join in memory (acceptable - data already fetched)
foreach (var order in orders)
{
    order.Items = items.Where(i => i.OrderId == order.Id).ToList();
}
```

---

## Never Do Application-Side Joins

**Joins must happen in SQL, not in C#.**

```csharp
// BAD: Application join - two queries, memory waste
var customers = await _context.Customers.ToListAsync();
var orders = await _context.Orders.ToListAsync();

var result = customers.Select(c => new
{
    Customer = c,
    Orders = orders.Where(o => o.CustomerId == c.Id).ToList()  // O(n*m) in memory!
});

// GOOD: SQL join - single query
var result = await _context.Customers
    .AsNoTracking()
    .Include(c => c.Orders)
    .ToListAsync();

// GOOD: Explicit join (Dapper)
const string sql = """
    SELECT c.id, c.name, COUNT(o.id) as order_count
    FROM customers c
    LEFT JOIN orders o ON c.id = o.customer_id
    GROUP BY c.id, c.name
    """;
```

---

## Avoid Cartesian Explosions

Multiple `Include` calls can cause Cartesian products.

```csharp
// DANGEROUS: Can explode into millions of rows
var product = await _context.Products
    .Include(p => p.Reviews)      // 100 reviews
    .Include(p => p.Images)       // 20 images
    .Include(p => p.Categories)   // 5 categories
    .FirstOrDefaultAsync(p => p.Id == id);
// Result: 100 * 20 * 5 = 10,000 rows transferred!
```

### Solution: Split Queries

```csharp
// GOOD: Multiple queries, no Cartesian explosion
var product = await _context.Products
    .AsSplitQuery()
    .Include(p => p.Reviews)
    .Include(p => p.Images)
    .Include(p => p.Categories)
    .FirstOrDefaultAsync(p => p.Id == id);
// Result: 4 separate queries, ~125 rows total
```

### Solution: Explicit Projection

```csharp
// BEST: Only fetch what you need
var product = await _context.Products
    .AsNoTracking()
    .Where(p => p.Id == id)
    .Select(p => new ProductDetail(
        p.Id,
        p.Name,
        p.Description,
        p.Reviews.OrderByDescending(r => r.CreatedAt).Take(10).ToList(),
        p.Images.Take(5).ToList(),
        p.Categories.Select(c => c.Name).ToList()))
    .FirstOrDefaultAsync();
```

---

## Constrain Column Sizes

Define maximum lengths in your EF Core model to prevent oversized data.

```csharp
public class UserConfiguration : IEntityTypeConfiguration<User>
{
    public void Configure(EntityTypeBuilder<User> builder)
    {
        builder.Property(u => u.Email)
            .HasMaxLength(254)  // RFC 5321 limit
            .IsRequired();

        builder.Property(u => u.Name)
            .HasMaxLength(100)
            .IsRequired();

        builder.Property(u => u.Bio)
            .HasMaxLength(500);

        // For truly large content, use text type explicitly
        builder.Property(u => u.Notes)
            .HasColumnType("text");
    }
}
```

---

## Don't Build Generic Repositories

Generic repositories hide query complexity and make optimization difficult.

```csharp
// BAD: Generic repository
public interface IRepository<T>
{
    Task<T?> GetByIdAsync(int id);
    Task<IEnumerable<T>> GetAllAsync();  // No limit!
    Task<IEnumerable<T>> FindAsync(Expression<Func<T, bool>> predicate);  // Can't optimize
}

// GOOD: Purpose-built read stores
public interface IOrderReadStore
{
    Task<OrderDetail?> GetByIdAsync(OrderId id, CancellationToken ct = default);
    Task<IReadOnlyList<OrderSummary>> GetByCustomerAsync(CustomerId id, int limit, CancellationToken ct = default);
    Task<IReadOnlyList<OrderSummary>> GetPendingAsync(int limit, CancellationToken ct = default);
}
```

**Problems with generic repositories:**
- Can't optimize specific queries
- No way to enforce limits
- Hide N+1 problems
- Make it easy to fetch too much data
- Encourage lazy thinking about data access

---

## Dapper for Read-Heavy Workloads

For complex read queries, Dapper with explicit SQL is often cleaner and faster.

```csharp
public sealed class PostgresUserReadStore : IUserReadStore
{
    private readonly NpgsqlDataSource _dataSource;

    public PostgresUserReadStore(NpgsqlDataSource dataSource)
    {
        _dataSource = dataSource;
    }

    public async Task<UserProfile?> GetByIdAsync(UserId id, CancellationToken ct = default)
    {
        await using var connection = await _dataSource.OpenConnectionAsync(ct);

        const string sql = """
            SELECT id, email, name, bio, created_at
            FROM users
            WHERE id = @Id
            """;

        var row = await connection.QuerySingleOrDefaultAsync<UserRow>(
            sql, new { Id = id.Value });

        return row?.ToUserProfile();
    }

    // Internal row type for Dapper mapping
    private sealed class UserRow
    {
        public Guid id { get; set; }
        public string email { get; set; } = null!;
        public string name { get; set; } = null!;
        public string? bio { get; set; }
        public DateTime created_at { get; set; }

        public UserProfile ToUserProfile() => new(
            Id: new UserId(id),
            Email: new EmailAddress(email),
            Name: new PersonName(name),
            Bio: bio,
            CreatedAt: new DateTimeOffset(created_at, TimeSpan.Zero));
    }
}
```

---

## When to Use EF Core vs Dapper

| Scenario | Recommendation |
|----------|---------------|
| Simple CRUD | EF Core |
| Complex read queries | Dapper |
| Writes with validation | EF Core |
| Bulk operations | Dapper or raw SQL |
| Reporting/analytics | Dapper |
| Domain-heavy writes | EF Core |

You can use both in the same project - EF Core for writes, Dapper for reads.

---

## Quick Reference

| Anti-Pattern | Solution |
|--------------|----------|
| No row limit | Add `limit` parameter to every read method |
| SELECT * | Project only needed columns |
| N+1 queries | Use Include or batch queries |
| Application joins | Do joins in SQL |
| Cartesian explosion | Use AsSplitQuery or projection |
| Tracking read-only data | Use AsNoTracking |
| Generic repository | Purpose-built read/write stores |
| Unbounded strings | Configure MaxLength in model |

---

## Resources

- **EF Core Performance**: https://learn.microsoft.com/en-us/ef/core/performance/
- **Dapper**: https://github.com/DapperLib/Dapper
- **AsSplitQuery**: https://learn.microsoft.com/en-us/ef/core/querying/single-split-queries

# Patrones de Rendimiento en Bases de Datos
 
## Cuándo usar esta skill
 
Úsala cuando:
- Diseñas capas de acceso a datos de alto impacto.
- Tratas de optimizar "queries" o consultas lentas.
- Requieres elegir entre EF Core y Dapper para escenarios concretos.
- Quieres evitar los típicos obstáculos que tumban el rendimiento de una BBDD.
 
---
 
## Principios Base
 
1. **Separa los modelos de Lectura y Escritura** - Nunca utilices las mismas clases para leer y escribir.
2. **Pensamiento por lotes** - Elude el funesto problema de N+1 queries.
3. **Pide sólo lo que necesites** - Olvida los `SELECT *`.
4. **Acota el número de filas** - Siempre impón y acepta métodos de control (Limit / Take).
5. **Deja que SQL haga las proyecciones (Joins)** - Nunca las hagas en memoria C#.
6. **AsNoTracking para las lecturas** - El rastreo de EF Core cuesta ciclos e incrementa el GC.
 
---
 
## Separación de Lectura y Escritura (Patrón CQRS)
 
No reutilices la mítica entidad masiva `User` de manera transversal.
 
- **Modelos Listos (Lectura)** están desnormalizados, afinados a velocidad, y devuelven proyecciones específicas (`UserProfile`, `UserSummary`...).
- **Modelos Transaccionales (Escritura)** están normalizados, centrados en aplicar validación sólida y absorben comandos (`CreateUserCommand`).
 
### Arquitectura y Esquema
 
```
src/
  MyApp.Data/
    Users/
      # Área de Lecura - Proyecciones limpias
      IUserReadStore.cs
      PostgresUserReadStore.cs
 
      # Área de Escritura - Comandos asertivos
      IUserWriteStore.cs
      PostgresUserWriteStore.cs
```

### Reglas básicas

El entorno de Lectura devuelve múltiples variantes y DTOs distintos, actuando de forma **sin estado (Stateless)** y sin rastreo. En el otro lado, las implementaciones Write retornan `void` o sencillamente el ID tras validar la lógica de Command; el foco de este área no radica en "devolver los datos que acaban de guardarse".
 
---
 
## Acotar los resultados (Limit limits)
 
**No exportes listados colosales bajo ningún pretexto**. 
Impregna todas tus llamadas con el concepto del paginado nativo.
 
### Patrón Limit en EF Core:
 
```csharp
public async Task<PaginatedList<OrderSummary>> GetOrdersAsync(
    CustomerId customerId,
    Paginator paginator,
    CancellationToken ct = default)
{
    var query = _context.Orders
        .AsNoTracking()
        .Where(o => o.CustomerId == customerId.Value)
        .OrderByDescending(o => o.CreatedAt);
 
    var totalCount = await query.CountAsync(ct);
 
    var orders = await query
        .Skip((paginator.PageNumber - 1) * paginator.PageSize)
        .Take(paginator.PageSize)  // ¡SIEMPRE LIMITE O TAKE!
        .Select(o => new OrderSummary(new OrderId(o.Id), o.Total, o.Status, o.CreatedAt))
        .ToListAsync(ct);
 
    return new PaginatedList<OrderSummary>(orders, totalCount, paginator.PageSize, paginator.PageNumber);
}
```
 
---
 
## AsNoTracking
Actívalo por defecto. Retira la propiedad si persigues un estado de mutación inminente antes del `SaveChangesAsync()`.
 
```csharp
// CORRECTO - Apagar seguimiento
var users = await _context.Users.AsNoTracking().Where(u => u.IsActive).ToListAsync();
```

## Problema N+1 y Soluciones

El error N+1 arrastra penalizaciones exponenciales por lanzar una consulta a la BD por cada hijo en el bucle padre (es decir, en `n` saltos).

**Solución 1: Explotación del Include (EF Core)**
Aceptable para mallas pequeñas.
```csharp
var orders = await _context.Orders.AsNoTracking().Include(o => o.Items).ToListAsync();
```

**Solución 2: Batch Query con Dapper**
Formato ideal y óptimo para evitar productos cartesianos y reducir cargas si hay 10+ joins.
El código extrae primero Orders y luego los Items vinculándolos mediante C# una vez en memoria, usando 2 *viajes únicos* al motor SQL.

## Jamás cruces Joins en local!
Cede estas operaciones al relacional a no ser de que hayas ejecutado una operación batch como la de Dapper mencionada. C# sufre de desperdicio de O(n+m) al correlacionar en LINQ-To-Objects sobre tablas descargadas al RAM.

```csharp
// FATAL - Un desastre RAM
var result = customers.Select(c => new {
    Customer = c,
    Orders = orders.Where(o => o.CustomerId == c.Id).ToList() 
});
```

---

## Repositorios Genéricos: NO

Evita la trampa `IRepository<T>` a toda costa. Oculta la complejidad N+1, arruina optimizaciones específicas de SQL e impide aplicar Limit/Take orgánicos y eficientes. Crea Stores acotados (`IOrderReadStore` y análogos).

## Rendimientos Masivos (`ExecuteUpdateAsync`)
.NET 7 te permite evitar bajar a memoria las filas editadas:
```csharp
await _db.Orders
    .Where(o => o.ExpiresAt < DateTimeOffset.UtcNow)
    .ExecuteUpdateAsync(setters => setters.SetProperty(o => o.Status, OrderStatus.Expired));
```

# Entity Framework Core Patterns

## When to Use This Skill

Use this skill when:
- Setting up EF Core in a new project
- Optimizing query performance
- Managing database migrations
- Integrating EF Core with .NET Aspire
- Debugging change tracking issues
- Loading multiple navigation collections efficiently (query splitting)

## Core Principles

1. **NoTracking by Default** - Most queries are read-only; opt-in to tracking
2. **Never Edit Migrations Manually** - Always use CLI commands
3. **Dedicated Migration Service** - Separate migration execution from application startup
4. **ExecutionStrategy for Retries** - Handle transient database failures
5. **Explicit Updates** - When NoTracking, explicitly mark entities for update

---

## Pattern 1: NoTracking by Default

Configure your DbContext to disable change tracking by default. This improves performance for read-heavy workloads.

```csharp
public class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options)
    {
        // Disable change tracking by default for better performance on read-only queries
        // Use .AsTracking() explicitly for queries that need to track changes
        ChangeTracker.QueryTrackingBehavior = QueryTrackingBehavior.NoTracking;
    }

    public DbSet<Order> Orders => Set<Order>();
    public DbSet<Customer> Customers => Set<Customer>();
}
```

### When NoTracking is Active

**Read-only queries work normally:**
```csharp
// ✅ Fast read - no tracking overhead
var orders = await dbContext.Orders
    .Where(o => o.Status == OrderStatus.Pending)
    .ToListAsync();
```

**Writes require explicit handling:**
```csharp
// ❌ WRONG - Entity not tracked, SaveChanges does nothing
var order = await dbContext.Orders.FirstOrDefaultAsync(o => o.Id == orderId);
order.Status = OrderStatus.Shipped;
await dbContext.SaveChangesAsync(); // Nothing happens!

// ✅ CORRECT - Explicitly mark entity for update
var order = await dbContext.Orders.FirstOrDefaultAsync(o => o.Id == orderId);
order.Status = OrderStatus.Shipped;
dbContext.Orders.Update(order); // Marks entire entity as modified
await dbContext.SaveChangesAsync();

// ✅ ALSO CORRECT - Use AsTracking() for the query
var order = await dbContext.Orders
    .AsTracking()
    .FirstOrDefaultAsync(o => o.Id == orderId);
order.Status = OrderStatus.Shipped;
await dbContext.SaveChangesAsync(); // Works!
```

### When to Use Tracking

| Scenario | Use Tracking? | Why |
|----------|---------------|-----|
| Display data in UI | No | Read-only, no updates |
| API GET endpoints | No | Returning data, no mutations |
| Update single entity | Yes or explicit Update() | Need to save changes |
| Complex update with navigation | Yes | Tracking handles relationships |
| Batch operations | No + ExecuteUpdate | More efficient |

### Explicit Add/Update Pattern

```csharp
public class OrderService
{
    private readonly ApplicationDbContext _db;

    // CREATE - Always use Add (works regardless of tracking)
    public async Task<Order> CreateOrderAsync(Order order)
    {
        _db.Orders.Add(order);
        await _db.SaveChangesAsync();
        return order;
    }

    // UPDATE - Explicitly mark as modified
    public async Task UpdateOrderStatusAsync(Guid orderId, OrderStatus newStatus)
    {
        var order = await _db.Orders.FirstOrDefaultAsync(o => o.Id == orderId)
            ?? throw new NotFoundException($"Order {orderId} not found");

        order.Status = newStatus;
        order.UpdatedAt = DateTimeOffset.UtcNow;

        // Explicitly mark as modified since DbContext uses NoTracking by default
        _db.Orders.Update(order);
        await _db.SaveChangesAsync();
    }

    // DELETE - Attach and remove
    public async Task DeleteOrderAsync(Guid orderId)
    {
        var order = new Order { Id = orderId };
        _db.Orders.Remove(order);
        await _db.SaveChangesAsync();
    }
}
```

---

## Pattern 2: Never Edit Migrations Manually

**CRITICAL:** Always use EF Core CLI commands to manage migrations. Never:
- Manually edit migration files (except for custom SQL in `Up()`/`Down()`)
- Delete migration files directly
- Rename migration files
- Copy migrations between projects

### Creating Migrations

```bash
# Create a new migration
dotnet ef migrations add AddCustomerTable \
    --project src/MyApp.Infrastructure \
    --startup-project src/MyApp.Api

# With a specific DbContext (if you have multiple)
dotnet ef migrations add AddCustomerTable \
    --context ApplicationDbContext \
    --project src/MyApp.Infrastructure \
    --startup-project src/MyApp.Api
```

### Removing Migrations

```bash
# Remove the last migration (if not yet applied)
dotnet ef migrations remove \
    --project src/MyApp.Infrastructure \
    --startup-project src/MyApp.Api

# NEVER do this:
# rm Migrations/20240101_AddCustomerTable.cs  # ❌ BAD!
```

### Applying Migrations

```bash
# Apply all pending migrations
dotnet ef database update \
    --project src/MyApp.Infrastructure \
    --startup-project src/MyApp.Api

# Apply to a specific migration
dotnet ef database update AddCustomerTable \
    --project src/MyApp.Infrastructure \
    --startup-project src/MyApp.Api

# Rollback to a previous migration
dotnet ef database update PreviousMigrationName \
    --project src/MyApp.Infrastructure \
    --startup-project src/MyApp.Api
```

### Generating SQL Scripts

```bash
# Generate SQL script for all migrations
dotnet ef migrations script \
    --project src/MyApp.Infrastructure \
    --startup-project src/MyApp.Api \
    --output migrations.sql

# Generate idempotent script (safe to run multiple times)
dotnet ef migrations script \
    --idempotent \
    --project src/MyApp.Infrastructure \
    --startup-project src/MyApp.Api
```

---

## Pattern 3: Dedicated Migration Service with Aspire

Separate migration execution from your main application using a dedicated migration service. This ensures:
- Migrations complete before the app starts
- Clean separation of concerns
- Controlled seeding in test environments

### Project Structure

```
src/
├── MyApp.AppHost/           # Aspire orchestration
├── MyApp.Api/               # Main application
├── MyApp.Infrastructure/    # DbContext and migrations
└── MyApp.MigrationService/  # Dedicated migration runner
```

### MigrationService Program.cs

```csharp
using MyApp.Infrastructure.Data;
using MyApp.MigrationService;
using Microsoft.EntityFrameworkCore;

var builder = Host.CreateApplicationBuilder(args);

// Add Aspire service defaults
builder.AddServiceDefaults();

// Add PostgreSQL DbContext
var connectionString = builder.Configuration.GetConnectionString("appdb")
    ?? throw new InvalidOperationException("Connection string 'appdb' not found.");

builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseNpgsql(connectionString, npgsqlOptions =>
        npgsqlOptions.MigrationsAssembly("MyApp.Infrastructure")));

// Add the migration worker
builder.Services.AddHostedService<MigrationWorker>();

var host = builder.Build();
host.Run();
```

### MigrationWorker.cs

```csharp
public class MigrationWorker : BackgroundService
{
    private readonly IServiceProvider _serviceProvider;
    private readonly IHostApplicationLifetime _hostApplicationLifetime;
    private readonly ILogger<MigrationWorker> _logger;

    public MigrationWorker(
        IServiceProvider serviceProvider,
        IHostApplicationLifetime hostApplicationLifetime,
        ILogger<MigrationWorker> logger)
    {
        _serviceProvider = serviceProvider;
        _hostApplicationLifetime = hostApplicationLifetime;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("Migration service starting...");

        try
        {
            using var scope = _serviceProvider.CreateScope();
            var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();

            await RunMigrationsAsync(dbContext, stoppingToken);

            _logger.LogInformation("Migration service completed successfully.");
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Migration service failed: {Error}", ex.Message);
            throw;
        }
        finally
        {
            // Stop the application after migrations complete
            _hostApplicationLifetime.StopApplication();
        }
    }

    private async Task RunMigrationsAsync(ApplicationDbContext dbContext, CancellationToken ct)
    {
        // Use execution strategy for transient failure handling
        var strategy = dbContext.Database.CreateExecutionStrategy();

        await strategy.ExecuteAsync(async () =>
        {
            var pendingMigrations = await dbContext.Database.GetPendingMigrationsAsync(ct);

            if (pendingMigrations.Any())
            {
                _logger.LogInformation("Applying {Count} pending migrations...",
                    pendingMigrations.Count());

                await dbContext.Database.MigrateAsync(ct);

                _logger.LogInformation("Migrations applied successfully.");
            }
            else
            {
                _logger.LogInformation("No pending migrations. Database is up to date.");
            }
        });
    }
}
```

### AppHost Configuration

```csharp
var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var db = postgres.AddDatabase("appdb");

// Migrations run first, then exit
var migrations = builder.AddProject<Projects.MyApp_MigrationService>("migrations")
    .WaitFor(db)
    .WithReference(db);

// API waits for migrations to complete
var api = builder.AddProject<Projects.MyApp_Api>("api")
    .WaitForCompletion(migrations)  // Key: waits for migrations to finish
    .WithReference(db);
```

---

## Pattern 4: ExecutionStrategy for Transient Failures

Always use `CreateExecutionStrategy()` for operations that might fail transiently:

```csharp
public async Task UpdateWithRetryAsync(Guid id, Action<Order> update)
{
    var strategy = _dbContext.Database.CreateExecutionStrategy();

    await strategy.ExecuteAsync(async () =>
    {
        var order = await _dbContext.Orders
            .AsTracking()
            .FirstOrDefaultAsync(o => o.Id == id);

        if (order is null) return;

        update(order);
        await _dbContext.SaveChangesAsync();
    });
}
```

**Important:** You cannot use `CreateExecutionStrategy()` with user-initiated transactions. If you need transactions with retry:

```csharp
var strategy = _dbContext.Database.CreateExecutionStrategy();

await strategy.ExecuteAsync(async () =>
{
    // Transaction must be INSIDE the strategy callback
    await using var transaction = await _dbContext.Database.BeginTransactionAsync();

    try
    {
        // ... your operations ...
        await _dbContext.SaveChangesAsync();
        await transaction.CommitAsync();
    }
    catch
    {
        await transaction.RollbackAsync();
        throw;
    }
});
```

---

## Pattern 5: Bulk Operations with ExecuteUpdate/ExecuteDelete

For bulk operations, use EF Core 7+ `ExecuteUpdateAsync` and `ExecuteDeleteAsync` instead of loading entities:

```csharp
// ❌ SLOW - Loads all entities into memory
var expiredOrders = await _db.Orders
    .Where(o => o.ExpiresAt < DateTimeOffset.UtcNow)
    .ToListAsync();

foreach (var order in expiredOrders)
{
    order.Status = OrderStatus.Expired;
}
await _db.SaveChangesAsync();

// ✅ FAST - Single SQL UPDATE statement
await _db.Orders
    .Where(o => o.ExpiresAt < DateTimeOffset.UtcNow)
    .ExecuteUpdateAsync(setters => setters
        .SetProperty(o => o.Status, OrderStatus.Expired)
        .SetProperty(o => o.UpdatedAt, DateTimeOffset.UtcNow));

// ✅ FAST - Single SQL DELETE statement
await _db.Orders
    .Where(o => o.Status == OrderStatus.Cancelled && o.CreatedAt < cutoffDate)
    .ExecuteDeleteAsync();
```

---

## Common Pitfalls

### 1. Forgetting to Update When NoTracking

```csharp
// ❌ Silent failure - entity not tracked
var customer = await _db.Customers.FindAsync(id);
customer.Name = "New Name";
await _db.SaveChangesAsync(); // Does nothing!

// ✅ Explicit update
var customer = await _db.Customers.FindAsync(id);
customer.Name = "New Name";
_db.Customers.Update(customer);
await _db.SaveChangesAsync();
```

### 2. N+1 Query Problem

```csharp
// ❌ N+1 queries - one query per order
var customers = await _db.Customers.ToListAsync();
foreach (var customer in customers)
{
    var orders = customer.Orders; // Lazy load triggers query
}

// ✅ Eager loading - single query
var customers = await _db.Customers
    .Include(c => c.Orders)
    .ToListAsync();
```

### 3. Tracking Conflicts with Multiple DbContext Instances

```csharp
// ❌ Tracking conflict - entity tracked by different context
var order1 = await _db1.Orders.AsTracking().FindAsync(id);
var order2 = await _db2.Orders.AsTracking().FindAsync(id);
order2.Status = OrderStatus.Shipped;
await _db2.SaveChangesAsync(); // May throw or behave unexpectedly

// ✅ Use single context or detach first
_db1.Entry(order1).State = EntityState.Detached;
```

### 4. Not Using Async Consistently

```csharp
// ❌ Blocking call in async context
var orders = _db.Orders.ToList(); // Blocks thread

// ✅ Async all the way
var orders = await _db.Orders.ToListAsync();
```

### 5. Querying Inside Loops

```csharp
// ❌ Query per iteration
foreach (var orderId in orderIds)
{
    var order = await _db.Orders.FindAsync(orderId);
    // process order
}

// ✅ Single query
var orders = await _db.Orders
    .Where(o => orderIds.Contains(o.Id))
    .ToListAsync();
```

---

## DbContext Lifetime in DI

### ASP.NET Core (Scoped by Default)

```csharp
// Scoped = one instance per HTTP request
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseNpgsql(connectionString));
```

### Background Services (Create Scope)

```csharp
public class MyBackgroundService : BackgroundService
{
    private readonly IServiceProvider _serviceProvider;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // ✅ Create scope for each unit of work
        using var scope = _serviceProvider.CreateScope();
        var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();

        // ... use dbContext ...
    }
}
```

### Actors / Long-Lived Objects (Factory Pattern)

```csharp
public class OrderActor : ReceiveActor
{
    private readonly IDbContextFactory<ApplicationDbContext> _dbFactory;

    public OrderActor(IDbContextFactory<ApplicationDbContext> dbFactory)
    {
        _dbFactory = dbFactory;

        ReceiveAsync<GetOrder>(async msg =>
        {
            // Create fresh context for each operation
            await using var db = await _dbFactory.CreateDbContextAsync();
            var order = await db.Orders.FindAsync(msg.OrderId);
            Sender.Tell(order);
        });
    }
}

// Registration
builder.Services.AddDbContextFactory<ApplicationDbContext>(options =>
    options.UseNpgsql(connectionString));
```

---

## Pattern 6: Query Splitting to Prevent Cartesian Explosion

When you load multiple navigation collections via `Include()`, EF Core generates a single query that can cause cartesian explosion. If you have 10 orders with 10 items each, you get 100 rows instead of 10 + 10.

### Global Configuration (Recommended for Most Cases)

Enable query splitting globally in your DbContext configuration:

```csharp
services.AddDbContext<ApplicationDbContext>(options =>
    options.UseNpgsql(connectionString, npgsqlOptions =>
        {
            npgsqlOptions.UseQuerySplittingBehavior(QuerySplittingBehavior.SplitQuery);
        }));
```

### Per-Query Override

Use single query when you know it's more efficient:

```csharp
// Use single query when you know the structure is well-understood
var orders = await dbContext.Orders
    .Include(o => o.Items)
    .Include(o => o.Payments)
    .AsSingleQuery()  // Override global split behavior
    .ToListAsync();
```

### Trade-offs

| Behavior | Pros | Cons |
|-----------|-------|-------|
| SplitQuery | No cartesian explosion, better for large collections | Multiple round-trips, potential consistency issues |
| SingleQuery | Single round-trip, transactional consistency | Cartesian explosion with multiple collections |

**Recommendation**: Default to `SplitQuery` globally, override with `AsSingleQuery()` for specific queries where single-query is known to be better.

### When to Prefer SingleQuery

- Small, well-understood navigation graphs (2-3 levels)
- Queries where all related data is always needed
- Performance-critical paths where round-trip cost is lower than cartesian explosion

### When to Prefer SplitQuery

- Large or unpredictable navigation graphs
- Many-to-many relationships
- Queries loading collections that may not all be needed

---

## Testing with EF Core

### In-Memory Provider (Unit Tests Only)

```csharp
// Only for simple unit tests - doesn't match real database behavior
var options = new DbContextOptionsBuilder<ApplicationDbContext>()
    .UseInMemoryDatabase(databaseName: Guid.NewGuid().ToString())
    .Options;

using var context = new ApplicationDbContext(options);
```

### Real Database with TestContainers (Integration Tests)

See the `testcontainers-integration-tests` skill for proper database testing.

```csharp
// Use real PostgreSQL in container
var container = new PostgreSqlBuilder()
    .WithImage("postgres:16-alpine")
    .Build();

await container.StartAsync();

var options = new DbContextOptionsBuilder<ApplicationDbContext>()
    .UseNpgsql(container.GetConnectionString())
    .Options;
```

# Patrones Entity Framework Core

## Cuándo Usar Esta Skill

- Al configurar EF Core en un proyecto recién lanzado
- Para optimizar cuellos de botella y rendimiento de queries
- Mantener y administrar migraciones base
- Instalar y adaptar Aspire junto a EF
- Entender desajustes con el ChangeTracker o prevenir Cartesianos en colecciones anidadas

## Los Principios Fundacionales

1. **NoTracking por Default** - Asume lectura; obliga confirmación y tracking individual en las actualizaciones.
2. **Las migraciones no se tocan a mano** - Usa CLI siempre.
3. **Workers Exclusivos de Migración** - Separa este delicadísimo paso del encendido global del Core App.
4. **Sigue un ExecutionStrategy para Reintentos** - Las tripas transitorias de las BBDD nubosas fallan; protégete.

---

## Patrón 1: Ausencia de Tracking por Defecto

Afinará drásticamente la latencia de toda operación de lecturas. 

```csharp
public class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : base(options)
    {
        ChangeTracker.QueryTrackingBehavior = QueryTrackingBehavior.NoTracking;
    }
}
```

### Implicación Directa

Si tratas de modificar un registro invocado sin `.AsTracking()` no surtirá efecto. Deberás añadir el comando expreso `_db.Orders.Update(order);` para revincular el mapeo antes de `SaveChangesAsync()`.
¿La alternativa? Declarar un `.AsTracking()` dentro de la sentencia linq de invocación.

| Caso | ¿Tracker? | Motivo |
|----------|---------------|-----|
| Render en el UI / Front | No | Lectura superficial |
| Microservicio GET | No | Data estática / DTOs retornados |
| Comando PUT/PATCH/UPDATE | Sí | Requiere volcado de información |
| Operaciones BULK (borrado/edición masiva) | No | Más rápido si usas `.ExecuteUpdateAsync` |

---

## Patrón 2: Mantén la CLI a cargo de tus Archivos Core de SQL Históricos

NUNCA (a no ser de que necesites meter vistas, sprocs de T-SQL o RAW queries en los puentes `Up() / Down()`):
- Edites los nombres de las clases de migración
- Borres las migraciones .cs del proyecto
- Importes migraciones sin usar las utilidades `ef migrations`

**Genera Scripts idempotentes de Despliegue para CD/CI:**
```bash
dotnet ef migrations script --idempotent \
    --project src/MyApp.Infrastructure --startup-project src/MyApp.Api
```

---

## Patrón 3: Migrations-as-a-Service, el futuro del Aspire

Extrae las migraciones de `Program.cs`. Genera un Worker Service adyacente. Los `HostedServices` puros o `BackgroundWorker` asegurarán el Seed y los alter-tables bloqueando e inmovilizando la ApplicationApi hasta que el semáforo devuelva OK. Revisa e inspecciona detenidamente *MyApp.MigrationService* si operas en arquitecturas serias o distribuidas de Microservicios.

---

## Patrón 4: Transient Failures (Temblores de Red Transitorios) y Retries

Si usas Cloud, las BBDD se "desconecta" microsegundos. Tu resiliencia viene dada por el `CreateExecutionStrategy()`.

```csharp
var strategy = _dbContext.Database.CreateExecutionStrategy();

await strategy.ExecuteAsync(async () =>
{
    // TODA LAS OPERACIONES Y TRANSACCIONES DENTRO DEL LAMBDA DE EJECUCIÓN 
    await using var transaction = await _dbContext.Database.BeginTransactionAsync();
    try
    {
        await _dbContext.SaveChangesAsync();
        await transaction.CommitAsync();
    }
    catch
    {
        await transaction.RollbackAsync();
        throw;
    }
});
```

---

## Patrón 5: Operaciones Masivas (Vía Rápida) `ExecuteUpdateAsync`

`// EF Core 7+` permite alterar esquemas de BBDD sin transbordar esos gigabytes a variables de la RAM o usar Bucles:

```csharp
// BORRAR FILAS MASIVAMENTE SUPER RÁPIDO
await _db.Orders
    .Where(o => o.Status == OrderStatus.Cancelled && o.CreatedAt < cutoffDate)
    .ExecuteDeleteAsync();
```

---

## Patrón 6: Atajar las Explosiones Cartesianas (Query Splitting)

Las inclusiones en cadena `.Include(o => o.Padres).Include(o => o.Productos)` provocan explosión de filas debido al CROSS JOIN subyacente que devuelve SQL. Una fila de pedido, vinculada a 100 reseñas y 20 imágenes... multiplicará 1x100x20 = 2000 filas de bytes a tu red.

**Remedio**: Establece globalmente la bandera `QuerySplittingBehavior.SplitQuery`. EF core particionará esa solicitud monstruosa en pequeñas consultas individuales paralelizables o asíncronas independientes por rama jerárquica. Retoma el SingleQuery o Join total `AsSingleQuery()` para árboles enanos que garantices que no pasarán de 3 ramificaciones.

# Minimal APIs

## Trigger On

- building new HTTP APIs in ASP.NET Core
- creating lightweight microservices
- choosing between Minimal APIs and controllers
- organizing endpoints with route groups
- implementing validation and filters

## Documentation

- [Minimal APIs Overview](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis?view=aspnetcore-10.0)
- [Minimal API Tutorial](https://learn.microsoft.com/en-us/aspnet/core/tutorials/min-web-api?view=aspnetcore-10.0)
- [Filters in Minimal APIs](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/min-api-filters?view=aspnetcore-10.0)
- [OpenAPI Support](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview?view=aspnetcore-10.0)
- [Route Groups](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/route-handlers?view=aspnetcore-10.0#route-groups)

### References

- [patterns.md](references/patterns.md) - detailed route groups, filters, TypedResults patterns, parameter binding, error handling, and testing
- [anti-patterns.md](references/anti-patterns.md) - common Minimal API mistakes to avoid

## When to Use Minimal APIs vs Controllers

| Use Minimal APIs | Use Controllers |
|------------------|-----------------|
| New projects | Existing MVC/API projects |
| Microservices | Complex model binding |
| Simple CRUD APIs | OData, JsonPatch |
| Lightweight handlers | Heavy use of attributes |
| .NET 8+ projects | Need `[ApiController]` features |

## Workflow

1. **Define endpoints directly in Program.cs** (for small APIs)
2. **Use route groups** for related endpoints
3. **Move handlers to separate classes** as the API grows
4. **Apply filters** for cross-cutting concerns
5. **Use TypedResults** for type-safe responses
6. **Generate OpenAPI docs** with `.WithOpenApi()`

## Basic Patterns

### Simple Endpoints
```csharp
var app = builder.Build();

app.MapGet("/", () => "Hello World");

app.MapGet("/products/{id}", (int id) => Results.Ok(new { Id = id }));

app.MapPost("/products", (Product product) => Results.Created($"/products/{product.Id}", product));
```

### TypedResults (Strongly-Typed)
```csharp
app.MapGet("/products/{id}", Results<Ok<Product>, NotFound> (int id, AppDb db) =>
{
    var product = db.Products.Find(id);
    return product is not null
        ? TypedResults.Ok(product)
        : TypedResults.NotFound();
});
```

### Dependency Injection
```csharp
app.MapGet("/products", async (IProductService service) =>
{
    return await service.GetAllAsync();
});

// Or with [FromServices] for clarity
app.MapGet("/products", async ([FromServices] IProductService service) =>
    await service.GetAllAsync());
```

## Route Groups

### Basic Grouping
```csharp
var products = app.MapGroup("/api/products");

products.MapGet("/", GetAll);
products.MapGet("/{id}", GetById);
products.MapPost("/", Create);
products.MapPut("/{id}", Update);
products.MapDelete("/{id}", Delete);
```

### Groups with Shared Configuration
```csharp
var api = app.MapGroup("/api")
    .RequireAuthorization()
    .AddEndpointFilter<ValidationFilter>();

var products = api.MapGroup("/products")
    .WithTags("Products");

var orders = api.MapGroup("/orders")
    .WithTags("Orders")
    .RequireAuthorization("AdminOnly");
```

## Endpoint Filters

### Inline Filter
```csharp
app.MapGet("/products/{id}", (int id) => Results.Ok(id))
    .AddEndpointFilter(async (context, next) =>
    {
        var id = context.GetArgument<int>(0);
        if (id <= 0)
            return Results.BadRequest("Invalid ID");

        return await next(context);
    });
```

### Class-Based Filter
```csharp
public class ValidationFilter<T> : IEndpointFilter where T : class
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var argument = context.Arguments
            .OfType<T>()
            .FirstOrDefault();

        if (argument is null)
            return Results.BadRequest("Invalid request body");

        var validator = context.HttpContext.RequestServices
            .GetService<IValidator<T>>();

        if (validator is not null)
        {
            var result = await validator.ValidateAsync(argument);
            if (!result.IsValid)
                return Results.ValidationProblem(result.ToDictionary());
        }

        return await next(context);
    }
}

// Usage
products.MapPost("/", Create)
    .AddEndpointFilter<ValidationFilter<CreateProductRequest>>();
```

### Global Filters via Root Group
```csharp
// All endpoints inherit filters from root group
var root = app.MapGroup("")
    .AddEndpointFilter<LoggingFilter>()
    .AddEndpointFilter<ErrorHandlingFilter>();

root.MapGet("/health", () => Results.Ok());
root.MapGroup("/api/products").MapGet("/", GetProducts);
```

## Organizing Larger APIs

### Extension Method Pattern
```csharp
// ProductEndpoints.cs
public static class ProductEndpoints
{
    public static RouteGroupBuilder MapProductEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/products")
            .WithTags("Products");

        group.MapGet("/", GetAll);
        group.MapGet("/{id}", GetById);
        group.MapPost("/", Create);

        return group;
    }

    private static async Task<Ok<List<Product>>> GetAll(IProductService service)
        => TypedResults.Ok(await service.GetAllAsync());

    private static async Task<Results<Ok<Product>, NotFound>> GetById(
        int id, IProductService service)
    {
        var product = await service.GetByIdAsync(id);
        return product is not null
            ? TypedResults.Ok(product)
            : TypedResults.NotFound();
    }

    private static async Task<Created<Product>> Create(
        CreateProductRequest request, IProductService service)
    {
        var product = await service.CreateAsync(request);
        return TypedResults.Created($"/api/products/{product.Id}", product);
    }
}

// Program.cs
app.MapProductEndpoints();
app.MapOrderEndpoints();
```

## Request/Response DTOs

```csharp
// Separate from domain models
public record CreateProductRequest(string Name, decimal Price);
public record UpdateProductRequest(string Name, decimal Price);
public record ProductResponse(int Id, string Name, decimal Price);

// Don't expose domain entities directly
app.MapPost("/products", (CreateProductRequest request, IMapper mapper) =>
{
    var product = mapper.Map<Product>(request);
    // ...
    return TypedResults.Created($"/products/{product.Id}",
        mapper.Map<ProductResponse>(product));
});
```

## Anti-Patterns to Avoid

| Anti-Pattern | Why It's Bad | Better Approach |
|--------------|--------------|-----------------|
| Everything in Program.cs | Unmaintainable | Use extension methods |
| No route groups | Repetitive config | Group related endpoints |
| Manual validation | Error-prone | Use filters + FluentValidation |
| Exposing entities | Tight coupling | Use DTOs |
| No TypedResults | No compile-time checks | Use `TypedResults` |
| Ignoring OpenAPI | No documentation | Add `.WithOpenApi()` |

## OpenAPI Integration

```csharp
builder.Services.AddOpenApi();

app.MapOpenApi();  // Serves OpenAPI spec

app.MapGet("/products", GetProducts)
    .WithName("GetProducts")
    .WithSummary("Get all products")
    .WithDescription("Returns a list of all available products")
    .Produces<List<Product>>(StatusCodes.Status200OK)
    .ProducesProblem(StatusCodes.Status500InternalServerError);
```

## Deliver

- clean, organized Minimal API endpoints
- proper use of route groups and filters
- type-safe responses with TypedResults
- OpenAPI documentation
- validation with endpoint filters

## Validate

- endpoints return correct status codes
- validation filters catch invalid input
- OpenAPI spec is accurate
- route groups share common configuration
- handlers are testable (can mock dependencies)

# Minimal APIs (APIs Mínimas)

## Cuándo usar estas instrucciones

- Vas a crear APIs nuevas bajo el paraguas moderno de ASP.NET Core.
- Estás forjando microservicios ágiles sin burocracia de capas.
- Debes discernir cuándo apostar por controladores MVC convencionales vs la agilidad de los Endpoints (Minimal APIs).
- Has de estructurar tu mapeo vía extensiones ("Route Groups").
- Te centras en validaciones de entradas bajo el sistema de *"Filtros"*.

## Minimal APIs vs MVC (Controladores Base)

| Usa Minimal API | Usa MVC Completo |
|------------------|-----------------|
| Rutas y API recien planteada | En Mantenimiento sobre legado MVC |
| Microservicios funcionales y sencillos | Fuerte unión a Data Binding complejo / HTML |
| Abstracción CRUD pura | Requerimientos OData, JsonPatch intensivo |
| Handlers ligeros y factoría in-line | Preferencia corporativa por `[Attributes]` y herencia rígida |
| Paradigmas post .NET 8 | Ecosistema altamente arraigado a `[ApiController]` |

## Flujo de Producción y Diseño

1. **Diseñarás en extensiones, NO** aglomerando el `Program.cs`.
2. Emplea **Grupos (Route Groups)** para unificar subapartados jerárquicos y filtros masivos.
3. Extrae tus métodos *Run/Task* a entidades independientes a medida que engordan.
4. Inyecta **Filtros de validación automáticos** que escaneen toda petición central de un grupo.
5. Emplea forzosamente **`TypedResults`**. Nada de objetos abstractos devueltos al aire.

## Aplicaciones Habituales

### Retornos Seguros (Strongly-Typed)
Ayudas a OpenAPI a describir sin errar tu respuesta:
```csharp
app.MapGet("/products/{id}", Results<Ok<Product>, NotFound> (int id, AppDb db) =>
{
    var product = db.Products.Find(id);
    return product is not null ? TypedResults.Ok(product) : TypedResults.NotFound();
});
// [FromServices] puede agregarse por legibilidad a parámetros inyectados en cascada
```

### Agrupación y Mapeo en Cadena
No expongas tu `Program.cs`. Genera clases estáticas. Otorga cohesión compartida:
```csharp
var api = app.MapGroup("/api").RequireAuthorization().AddEndpointFilter<ValidationFilter>();

var products = api.MapGroup("/products").WithTags("Products");
var orders = api.MapGroup("/orders").WithTags("Orders").RequireAuthorization("AdminOnly");

// Llenado de hojas
products.MapGet("/", GetAll);
products.MapPut("/{id}", Update);
```

## Filtros ("Endpoint Filters")

Se postulan como la navaja suiza actual para cortar problemas de raíz antes de que tus métodos reciban peticiones infractoras:

```csharp
// Un filtro genérico de validación sobre FluentValidation atado globalmente
public class ValidationFilter<T> : IEndpointFilter where T : class
{
    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
    {
        var argument = context.Arguments.OfType<T>().FirstOrDefault();
        if (argument is null) return Results.BadRequest("Invalid request body");

        var validator = context.HttpContext.RequestServices.GetService<IValidator<T>>();
        if (validator is not null)
        {
            var result = await validator.ValidateAsync(argument);
            if (!result.IsValid) return Results.ValidationProblem(result.ToDictionary());
        }
        return await next(context);
    }
}

// Conexión
products.MapPost("/", Create)
    .AddEndpointFilter<ValidationFilter<CreateProductRequest>>();
```

## Prácticas DTO Puras

SÍ: Retorna Records paralelos llamados Response y Request.
NO: Arrojes una Entidad ORM (Domain Entities de Base de Datos crudos) al exterior.

## Patrones a Evitar ⛔

| Antipatrón | Coste/Por qué es nocivo | Remedio Directo |
|--------------|--------------|-----------------|
| Colapsar Program.cs con cientos de líneas | Inmantenible e inlegible | Métodos de extensión modulares |
| Escasez de Grupos | Verbosiad exhaustiva ("Repetir DRY") | Aduna lógicas comunes (`MapGroup`) |
| Validar en medio del método final | Fugas de control / Dificil de testear | Adosa validaciones al `Filter pipeline` |
| Devolver Entity DbContext ciego | Roturas por bucles (ReferenceLoop), Acoplamiento duro | Haz uso intensivo de los DTOs / Records |
| Olvidar `.WithOpenApi()` | Tu Swagger UI estará desierto | Auto-compón tus documentaciones |

# .NET Core — Refactorización Inteligente

Skill para analizar código C#/.NET Core, detectar problemas de diseño y aplicar refactorizaciones guiadas por principios SOLID y código limpio.

## Principios Guía

1. **Refactorizar sin cambiar comportamiento** — Los tests existentes deben seguir pasando.
2. **Pequeños pasos** — Cada refactorización es un commit atómico.
3. **Priorizar legibilidad** — Código que se lee como prosa > código "inteligente".
4. **YAGNI** — No añadas abstracciones que no necesitas hoy.

## Proceso de Análisis

### Paso 1: Detectar Malos Olores de Código

Revisa el código buscando estos indicadores:

| Indicador | Descripción | Severidad |
|-----------|-------------|-----------|
| **Método largo** | > 20 líneas de lógica | 🔴 Alta |
| **Clase grande** | > 300 líneas o > 5 responsabilidades | 🔴 Alta |
| **Parámetros excesivos** | > 4 parámetros en método | 🟡 Media |
| **Código duplicado** | Bloques repetidos en ≥ 2 lugares | 🔴 Alta |
| **Condicionales anidados** | > 2 niveles de if/else | 🟡 Media |
| **Nombres ambiguos** | Variables como `x`, `temp`, `data` | 🟡 Media |
| **Comentarios excesivos** | El código necesita explicación constante | 🟠 Media |
| **Envidia de funcionalidad** | Método usa más datos de otra clase | 🟡 Media |
| **Números mágicos** | Literales sin nombre semántico | 🟡 Media |
| **Código muerto** | Código inalcanzable o sin usar | 🟢 Baja |

### Paso 2: Clasificar por Principio SOLID Violado

```
[S] Responsabilidad Única    → Extraer clase/método
[O] Abierto/Cerrado          → Aplicar Strategy/Template Method
[L] Sustitución de Liskov    → Revisar herencia, preferir composición
[I] Segregación de Interfaces → Dividir interfaces grandes
[D] Inversión de Dependencias → Inyectar abstracciones
```

### Paso 3: Aplicar Refactorizaciones

## Catálogo de Refactorizaciones

### 1. Extraer Método
**Cuándo**: Bloque de código con comentario explicativo.

```csharp
// ❌ Antes
public void ProcessOrder(Order order)
{
    // Validar stock
    foreach (var item in order.Items)
    {
        var product = _repo.GetProduct(item.ProductId);
        if (product.Stock < item.Quantity)
            throw new InsufficientStockException(product.Name);
    }
    
    // Calcular total
    decimal total = 0;
    foreach (var item in order.Items)
    {
        total += item.Price * item.Quantity;
        if (item.HasDiscount)
            total -= item.DiscountAmount;
    }
    
    order.Total = total;
    _repo.Save(order);
}

// ✅ Después
public void ProcessOrder(Order order)
{
    ValidateStock(order);
    order.Total = CalculateTotal(order.Items);
    _repo.Save(order);
}

private void ValidateStock(Order order) { /* ... */ }
private decimal CalculateTotal(IEnumerable<OrderItem> items) { /* ... */ }
```

### 2. Reemplazar Condicional con Polimorfismo
**Cuándo**: Switch/if-else sobre un tipo para diferentes comportamientos.

```csharp
// ❌ Antes
public decimal CalculateShipping(Order order)
{
    switch (order.ShippingType)
    {
        case "standard": return order.Weight * 0.5m;
        case "express": return order.Weight * 1.5m + 10;
        case "overnight": return order.Weight * 3m + 25;
        default: throw new ArgumentException();
    }
}

// ✅ Después
public interface IShippingCalculator
{
    decimal Calculate(Order order);
}

public class StandardShipping : IShippingCalculator
{
    public decimal Calculate(Order order) => order.Weight * 0.5m;
}

// Registrar en inyección de dependencias:
services.AddKeyedScoped<IShippingCalculator, StandardShipping>("standard");
```

### 3. Introducir Objeto de Parámetros
**Cuándo**: Método con más de 3-4 parámetros relacionados.

```csharp
// ❌ Antes
public Report Generate(DateTime from, DateTime to, string department, 
                        bool includeInactive, string format)

// ✅ Después
public record ReportRequest(
    DateRange Period,
    string Department,
    bool IncludeInactive = false,
    string Format = "pdf"
);

public Report Generate(ReportRequest request)
```

### 4. Reemplazar Excepción con Resultado
**Cuándo**: Excepciones usadas como flujo de control.

```csharp
// ❌ Antes
public User GetUser(Guid id)
{
    var user = _repo.Find(id);
    if (user == null) throw new NotFoundException();
    return user;
}

// ✅ Después
public Result<User> GetUser(Guid id)
{
    var user = _repo.Find(id);
    return user is null
        ? Result<User>.Failure("Usuario no encontrado")
        : Result<User>.Success(user);
}
```

### 5. Extraer Servicio (Responsabilidad Única)
**Cuándo**: Clase con múltiples responsabilidades.

```csharp
// ❌ Antes — UserService hace de todo
public class UserService
{
    public User Create(CreateUserDto dto) { /* validar + crear + notificar */ }
    public void SendWelcomeEmail(User user) { /* ... */ }
    public byte[] GenerateAvatar(User user) { /* ... */ }
    public Report ExportUsers(ExportOptions opts) { /* ... */ }
}

// ✅ Después — Cada responsabilidad en su servicio
public class UserService { /* solo CRUD */ }
public class UserNotificationService { /* emails */ }
public class AvatarService { /* generación de imágenes */ }
public class UserExportService { /* reportes */ }
```

## Formato de Informe

Al finalizar el análisis, genera un informe con esta estructura:

```markdown
## Informe de Refactorización

### Resumen
- **Archivos analizados**: X
- **Malos olores detectados**: Y
- **Refactorizaciones aplicadas**: Z

### Hallazgos por Severidad
🔴 Críticos: N
🟡 Medios: N  
🟢 Bajos: N

### Detalle por Archivo
| Archivo | Smell | Refactorización | Estado |
|---------|-------|-----------------|--------|
| UserService.cs | Clase grande (450 líneas) | Extraer Servicio | ✅ Aplicada |
| OrderHandler.cs | Condicionales anidados (4 niveles) | Cláusulas de Guarda | ✅ Aplicada |

### Tests Verificados
- [ ] Tests existentes siguen pasando
- [ ] Nuevos tests añadidos para código extraído
```

## Lista de Verificación Post-Refactorización

- [ ] Todos los tests pasan (barra verde)
- [ ] No se agregó funcionalidad nueva (solo restructuración)
- [ ] Los nombres reflejan la intención del código
- [ ] No hay código duplicado
- [ ] Cada clase tiene una sola responsabilidad
- [ ] Las dependencias se inyectan, no se instancian
- [ ] Los métodos son ≤ 20 líneas
- [ ] La complejidad ciclomática es ≤ 10 por método

# .NET Core — Refactorización Inteligente de Deuda Técnica

Emplea esta habilidad para diseccionar piezas y entresijos de componentes (o arquitecturas concretas) y promover una reforma drástica en base a Clean Code, refactorizando a un estado legible, elástico y de calidad sin quebrar las regresiones lógicas subyacentes.

## Mandamientos Principales de la Acción

1. **La refactorización es un proceso Ciego al Comportamiento**: No alteres reglas ni cálculos; el Output idéntico debe persistir inmutable.
2. **Pequeños pasos incrementales**: Propagación atómica, aislando cada cirugía pequeña en sí.
3. **Escritura amigable con el Humano**: Redactar para compresión de lectura humana y fluida prevalece a tratar de ganar milisegundos de CPU usando operadores "crípticos".
4. **Acero YAGNI**: Sólo desarrolla y extrae lo que te permita escalar y solventar las molestias actuales. Evita interfaces genéricas prematuras pensando a cinco años vista.

## El Escáner de Olores Sintomáticos

Afronta el escrutinio de los archivos buscando estas lacras estructurales:

| Detonante Identificable | ¿Por qué y Magnitud? | Alarma |
|-----------|-------------|-----------|
| **Bloques Mastodónticos** | Funciones que engloban +20 lógicas operativas | 🔴 Critica |
| **Monstruos Dioses (Clases)** | > 300 franjas o usurpadoras de > 5 quehaceres desvinculados | 🔴 Crítica |
| **Batería de Atributos excesiva** | Métodos aglutinando firmas de 5 parámetros o más | 🟡 Intermedia |
| **Copy/Paste descarado** | Sentencias iterando igual en varios frentes | 🔴 Critica |
| **Anidaciones Interminables (Arrow Code)** | Profundidad de validaciones `if/if/if/for/if` de alto calibre | 🟡 Intermedia |
| **Bautizos ambiguos** | Operaciones sin contexto visual tipo `res`, `dt1`, `finalVal` | 🟡 Intermedia |
| **Comentarios intrusivos que suplantan a buenos métodos** | Si has de explicar QUÉ hace en 4 líneas para que se entienda, ese bloque es un método encubierto carente de nombre independiente | 🟠 Intermedia |
| **Envidia ajena extrema** | Una clase invirtiendo energía en llamar múltiples veces a otra en lugar de pedir que ella misma se componga y opere las matemáticas | 🟡 Intermedia |

## Arsenal Refactorizador según los Agravios Diagnosticados

### Táctica Básica 1: Extraer Método Auxiliar o Extensión (Responsabilidad Única)
Secciona los monstruos en fracciones de trabajo más menudas. 

### Táctica 2: Polimorfismo frente a Switch Gigantes
Suele emplearse el Patrón Estrategia (Strategy Pattern) o inyecciones condicionadas (Keyed Services dictados en .NET 8) para delegar las lógicas de `switch`.

### Táctica 3: Enclaustrar Multitud Parámetros en una Pildora C#9
Convierte 6 parámetros independientes en un bonito, moderno e inmutable `Objeto DTO / Request Record`:
```csharp
public record ReportRequest(DateRange Period, string Department, bool IncludeInactive = false, string Format = "pdf");
```

### Táctica 4: Tipar Resultados Explícitos para obviar Exceptions
Eliminar la propagación de validaciones o bucles por ramas falsas que se apoyen en pesadas instrucciones de Throw/Catch. Usa patrones base genéricos de clase envoltorio tipo `Result<T>`.

### Táctica 5: Extracción de Clases o Escisión de Servicios
Separa un `UserService` generador de avatares, correos y usuarios en las subunidades `AvatarService`, `NotificationSystem` y `UserMgmt`.

## Formato del Checklist Final y Verificación Post-Refactor

Al redactarle el documento de validación, somete tu operación a esta rigurosa rúbrica visual:

- [ ] Todos los Tests siguen indemnes y pasando impunemente.
- [ ] No me he colado y he metido características funcionales extrañas o nuevas (sólo he "limpiado").
- [ ] Ya no persisten clones de código duplicado ni "ruído".
- [ ] La "Complejidad Ciclomática" real ha bajado; los métodos de validaciones guardan formato de Return Preventiva prematura (Cláusulas guarda).
- [ ] He erradicado los "Numbers Mágicos" introducidos a fuego por variables de Contexto y const nombradas.

# Integration Testing with TestContainers

## When to Use This Skill

Use this skill when:
- Writing integration tests that need real infrastructure (databases, caches, message queues)
- Testing data access layers against actual databases
- Verifying message queue integrations
- Testing Redis caching behavior
- Avoiding mocks for infrastructure components
- Ensuring tests work against production-like environments
- Testing database migrations and schema changes

## Reference Files

- [database-patterns.md](database-patterns.md): SQL Server, PostgreSQL, and migration testing examples
- [infrastructure-patterns.md](infrastructure-patterns.md): Redis, RabbitMQ, multi-container networks, container reuse, and Respawn

## Core Principles

1. **Real Infrastructure Over Mocks** - Use actual databases/services in containers, not mocks
2. **Test Isolation** - Each test gets fresh containers or fresh data
3. **Automatic Cleanup** - TestContainers handles container lifecycle and cleanup
4. **Fast Startup** - Reuse containers across tests in the same class when appropriate
5. **CI/CD Compatible** - Works seamlessly in Docker-enabled CI environments
6. **Port Randomization** - Containers use random ports to avoid conflicts

## Why TestContainers Over Mocks?

### The Problem with Mocking Infrastructure

```csharp
// BAD: Mocking a database
public class OrderRepositoryTests
{
    private readonly Mock<IDbConnection> _mockDb = new();

    [Fact]
    public async Task GetOrder_ReturnsOrder()
    {
        // This doesn't test real SQL behavior, constraints, or performance
        _mockDb.Setup(db => db.QueryAsync<Order>(It.IsAny<string>()))
            .ReturnsAsync(new[] { new Order { Id = 1 } });

        var repo = new OrderRepository(_mockDb.Object);
        var order = await repo.GetOrderAsync(1);

        Assert.NotNull(order);
    }
}
```

Problems: doesn't test actual SQL queries, misses constraints/indexes, gives false confidence, doesn't catch SQL syntax errors.

### Better: TestContainers with Real Database

```csharp
// GOOD: Testing against a real database
public class OrderRepositoryTests : IAsyncLifetime
{
    private readonly TestcontainersContainer _dbContainer;
    private IDbConnection _connection;

    public OrderRepositoryTests()
    {
        _dbContainer = new TestcontainersBuilder<TestcontainersContainer>()
            .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
            .WithEnvironment("ACCEPT_EULA", "Y")
            .WithEnvironment("SA_PASSWORD", "Your_password123")
            .WithPortBinding(1433, true)
            .Build();
    }

    public async Task InitializeAsync()
    {
        await _dbContainer.StartAsync();
        var port = _dbContainer.GetMappedPublicPort(1433);
        var connectionString = $"Server=localhost,{port};Database=TestDb;User Id=sa;Password=Your_password123;TrustServerCertificate=true";
        _connection = new SqlConnection(connectionString);
        await _connection.OpenAsync();
        await RunMigrationsAsync(_connection);
    }

    public async Task DisposeAsync()
    {
        await _connection.DisposeAsync();
        await _dbContainer.DisposeAsync();
    }

    [Fact]
    public async Task GetOrder_WithRealDatabase_ReturnsOrder()
    {
        await _connection.ExecuteAsync(
            "INSERT INTO Orders (Id, CustomerId, Total) VALUES (1, 'CUST1', 100.00)");

        var repo = new OrderRepository(_connection);
        var order = await repo.GetOrderAsync(1);

        Assert.NotNull(order);
        Assert.Equal("CUST1", order.CustomerId);
        Assert.Equal(100.00m, order.Total);
    }
}
```

See [database-patterns.md](database-patterns.md) for complete SQL Server, PostgreSQL, and migration testing examples.

See [infrastructure-patterns.md](infrastructure-patterns.md) for Redis, RabbitMQ, multi-container networks, container reuse, and Respawn database reset patterns.

## Required NuGet Packages

```xml
<ItemGroup>
  <PackageReference Include="Testcontainers" Version="*" />
  <PackageReference Include="xunit" Version="*" />
  <PackageReference Include="xunit.runner.visualstudio" Version="*" />

  <!-- Database-specific packages -->
  <PackageReference Include="Microsoft.Data.SqlClient" Version="*" />
  <PackageReference Include="Npgsql" Version="*" /> <!-- For PostgreSQL -->
  <PackageReference Include="MySqlConnector" Version="*" /> <!-- For MySQL -->

  <!-- Other infrastructure -->
  <PackageReference Include="StackExchange.Redis" Version="*" /> <!-- For Redis -->
  <PackageReference Include="RabbitMQ.Client" Version="*" /> <!-- For RabbitMQ -->
</ItemGroup>
```

## Best Practices

1. **Always Use IAsyncLifetime** - Proper async setup and teardown
2. **Wait for Port Availability** - Use `WaitStrategy` to ensure containers are ready
3. **Use Random Ports** - Let TestContainers assign ports automatically
4. **Clean Data Between Tests** - Either use fresh containers or truncate tables
5. **Reuse Containers When Possible** - Faster than creating new ones for each test
6. **Test Real Queries** - Don't just test mocks; verify actual SQL behavior
7. **Verify Constraints** - Test foreign keys, unique constraints, indexes
8. **Test Transactions** - Verify rollback and commit behavior
9. **Use Realistic Data** - Test with production-like data volumes
10. **Handle Cleanup** - Always dispose containers in `DisposeAsync`

## Common Issues and Solutions

### Container Startup Timeout

```csharp
_container = new TestcontainersBuilder<TestcontainersContainer>()
    .WithImage("postgres:latest")
    .WithWaitStrategy(Wait.ForUnixContainer()
        .UntilPortIsAvailable(5432)
        .WithTimeout(TimeSpan.FromMinutes(2)))
    .Build();
```

### Port Already in Use

Always use random port mapping:
```csharp
.WithPortBinding(5432, true) // true = assign random public port
```

### Containers Not Cleaning Up

Ensure proper disposal:
```csharp
public async Task DisposeAsync()
{
    await _connection?.DisposeAsync();
    await _container?.DisposeAsync();
}
```

### Tests Fail in CI But Pass Locally

Ensure CI has Docker support:
```yaml
# GitHub Actions
runs-on: ubuntu-latest # Has Docker pre-installed
```

## CI/CD Integration

### GitHub Actions

```yaml
name: Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 9.0.x

    - name: Run Integration Tests
      run: |
        dotnet test tests/YourApp.IntegrationTests \
          --filter Category=Integration \
          --logger trx

    - name: Cleanup Containers
      if: always()
      run: docker container prune -f
```

## Performance Tips

1. **Reuse containers** - Share fixtures across tests in a collection
2. **Use Respawn** - Reset data without recreating containers
3. **Parallel execution** - TestContainers handles port conflicts automatically
4. **Use lightweight images** - Alpine versions are smaller and faster
5. **Cache images** - Docker will cache pulled images locally

# Integration Testing con TestContainers

## Cuándo usar esta skill

Deberás usar este material cuando:
- Crees tests de integración que toquen infraestructura vital (bases de datos transaccionales, cachés temporales, message brokers).
- Compruebes que tus repositorios interactúan limpiamente sobre un motor SQL vivo.
- Valides la recepción e inyección en colas de tipo RabbitMQ/Kafka.
- Quieras dejar atrás el frágil arte de *mockear* interfaces de infraestructura.
- Quieras prevenir errores de sintaxis o motor SQL garantizando el testeo en entornos Docker que imitan fehacientemente Producción (Shift-Left validation).

## Principios Críticos

1. **Infraestructura Real por encima de los Mocks**: Si la BBDD se invoca, lo hará contra un contenedor, nunca ante la abstracción de una interfaz de C#.
2. **Aislamiento Pulcro (Test Isolation)**: Todo arranque de entorno dota al test de una imagen virgen.
3. **Limpieza Automatizada y Autogestionada**: Olvida los scripts de desmontaje. Las apis de interop de *TestContainers* desmantelan las huellas locales.
4. **Resurrección y Reutilización**: Los Tests dentro de un `ClassFixture` pueden aprovechar la misma instancia arrancada.
5. **No hay Conflictos de Puertos**: TestContainers amarra la máquina Dockerizada a un puerto aleatorio de tu tarjeta local en cascada.

## El Gran Problema del Testing basado en Mocks

La burla (Mocking) frente a `IDbConnection` o `DbContext` produce complacencia, donde tus pruebas pasan en verde localmente, pero al entrar a producción el programa colapsa ante un fallo sutil de FK (Claves Foráneas) o una simple coma olvidada en un *String Interpolation*.

El ecosistema actual pide probar con el framework en frío y la BBDD a plena potencia, validando restricciones, transacciones puras y rendimientos genuinos.

## Receta Básica con Base de Datos

```csharp
public class OrderRepositoryTests : IAsyncLifetime // Requisito vital del ciclo de xUnit
{
    private readonly TestcontainersContainer _dbContainer;
    private IDbConnection _connection;

    public OrderRepositoryTests()
    {
        // Construimos la imagen al Vuelo
        _dbContainer = new TestcontainersBuilder<TestcontainersContainer>()
            .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
            .WithEnvironment("ACCEPT_EULA", "Y")
            .WithEnvironment("SA_PASSWORD", "Super_password123")
            .WithPortBinding(1433, true) // Activa el Port Randomization (true)
            .Build();
    }

    public async Task InitializeAsync()
    {
        await _dbContainer.StartAsync(); // Levantamos el contenedor
        var port = _dbContainer.GetMappedPublicPort(1433);
        var connectionString = $"Server=localhost,{port};Database=TestDb;User Id=sa;Password=Super_password123;TrustServerCertificate=true";
        _connection = new SqlConnection(connectionString);
        await _connection.OpenAsync();
        
        // Lanzamos un script generador de las tablas iniciales
        await RunMigrationsAsync(_connection);
    }
    
    // ... Tu Fact o Theory irá aquí operando sobre el _connection 

    public async Task DisposeAsync()
    {
        await _connection.DisposeAsync();
        await _dbContainer.DisposeAsync(); // Mantenemos el PC de los devs limpio.
    }
}
```

## Buenas Prácticas Avanzadas

1. **Reutiliza Contenedores entre Suites Combinadas** - Arrancar MSSQL puede demorar 15 segundos. Usa `ICollectionFixture<T>` en xUnit para arrancar el SQL de pruebas solo vez por ejecución y purgar luego los datos intermedios con librerías eficientes.
2. **Purgado Ultrarápido: Patrón Respawn** - Antes de cada método Fact, limpia la Base de datos generada empleando el NuGet *Respawn*. Respeta las Foreing Keys y restablece tu contenedor sin recrearlo, arañando minutos en tus Pipelines de CI/CD.
3. **No fijes los puertos locales .WithPortBinding(1433, 1433)** - Esto detonará inmediatamente conflictos entre los tests asíncronos y paralelos destruyendo tus procesos y builds de GitHub Actions. Siempre deriva su responsabilidad al motor y captura el puerto variable con `GetMappedPublicPort()`.

# .NET Core — Generación de Tests Unitarios

Skill para crear, organizar y mantener tests unitarios de alta calidad en proyectos .NET Core.

## Principios

1. **Patrón AAA** — Arrange, Act, Assert en cada test.
2. **Un assert lógico** por test (salvo validaciones de estado compuesto).
3. **Tests independientes** — nunca dependan del orden de ejecución.
4. **Nombres descriptivos** — `Método_Escenario_ResultadoEsperado`.

## Tecnologías Recomendadas

| Paquete | Propósito |
|---------|-----------|
| `xUnit` | Framework de testing |
| `NSubstitute` | Mocks y stubs |
| `FluentAssertions` | Assertions expresivas |
| `Coverlet` | Cobertura de código |
| `AutoFixture` | Generación de datos de prueba |

## Estructura de Proyecto

```
src/
├── MiApp.Domain/
├── MiApp.Application/
└── MiApp.Infrastructure/
tests/
├── MiApp.Domain.Tests/
├── MiApp.Application.Tests/
└── MiApp.Infrastructure.Tests/
```

### Convenciones de Carpetas dentro de Tests

```
MiApp.Application.Tests/
├── Services/
│   ├── UserServiceTests.cs
│   └── OrderServiceTests.cs
├── Handlers/
│   └── CreateOrderHandlerTests.cs
├── Validators/
│   └── CreateOrderValidatorTests.cs
└── Fixtures/
    └── DatabaseFixture.cs
```

## Proceso de Generación

### Paso 1: Analizar la Clase Objetivo

Antes de escribir tests, examina:
- Dependencias inyectadas (interfaces para mockear)
- Métodos públicos (superficie a testear)
- Flujos condicionales (ramas if/else, switch, guard clauses)
- Excepciones esperadas
- Valores de retorno

### Paso 2: Crear la Clase de Test

```csharp
using FluentAssertions;
using NSubstitute;
using Xunit;

namespace MiApp.Application.Tests.Services;

public class UserServiceTests
{
    private readonly IUserRepository _userRepository;
    private readonly ILogger<UserService> _logger;
    private readonly UserService _sut; // Sistema Bajo Prueba

    public UserServiceTests()
    {
        _userRepository = Substitute.For<IUserRepository>();
        _logger = Substitute.For<ILogger<UserService>>();
        _sut = new UserService(_userRepository, _logger);
    }
}
```

### Paso 3: Generar Tests por Categoría

#### Camino Feliz (Happy Path)
```csharp
[Fact]
public async Task GetById_ConIdExistente_RetornaUsuario()
{
    // Arrange
    var userId = Guid.NewGuid();
    var expectedUser = new User { Id = userId, Name = "Juan" };
    _userRepository.GetByIdAsync(userId).Returns(expectedUser);

    // Act
    var result = await _sut.GetByIdAsync(userId);

    // Assert
    result.Should().NotBeNull();
    result!.Name.Should().Be("Juan");
}
```

#### Errores y Casos Límite
```csharp
[Fact]
public async Task GetById_ConIdInexistente_RetornaNull()
{
    // Arrange
    _userRepository.GetByIdAsync(Arg.Any<Guid>()).Returns((User?)null);

    // Act
    var result = await _sut.GetByIdAsync(Guid.NewGuid());

    // Assert
    result.Should().BeNull();
}

[Fact]
public async Task Create_ConEmailDuplicado_LanzaBusinessException()
{
    // Arrange
    var request = new CreateUserRequest { Email = "ya@existe.com" };
    _userRepository.ExistsByEmailAsync(request.Email).Returns(true);

    // Act
    var act = () => _sut.CreateAsync(request);

    // Assert
    await act.Should().ThrowAsync<BusinessException>()
        .WithMessage("*email*duplicado*");
}
```

#### Tests Parametrizados
```csharp
[Theory]
[InlineData("")]
[InlineData(null)]
[InlineData("   ")]
public async Task Create_ConNombreInvalido_LanzaValidationException(string? nombre)
{
    // Arrange
    var request = new CreateUserRequest { Name = nombre };

    // Act
    var act = () => _sut.CreateAsync(request);

    // Assert
    await act.Should().ThrowAsync<ValidationException>();
}
```

#### Verificación de Interacciones
```csharp
[Fact]
public async Task Delete_ConIdValido_LlamaRepositoryYLogger()
{
    // Arrange
    var userId = Guid.NewGuid();
    _userRepository.GetByIdAsync(userId).Returns(new User { Id = userId });

    // Act
    await _sut.DeleteAsync(userId);

    // Assert
    await _userRepository.Received(1).DeleteAsync(userId);
    _logger.Received(1).LogInformation(Arg.Is<string>(s => s.Contains("eliminado")));
}
```

## Cobertura Mínima

| Capa | Objetivo |
|------|----------|
| Domain | ≥ 90% |
| Application | ≥ 80% |
| Infrastructure | ≥ 60% (sin I/O real) |

### Comando para Medir Cobertura

```bash
dotnet test --collect:"XPlat Code Coverage"
dotnet tool run reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coverage-report
```

## Lista de Verificación de Calidad

- [ ] Cada método público tiene al menos un test de camino feliz
- [ ] Cada excepción documentada tiene un test
- [ ] Los mocks verifican interacciones clave
- [ ] No hay `Thread.Sleep` ni dependencias de tiempo real
- [ ] Tests corren en < 5 segundos individuales
- [ ] No hay dependencias entre tests (orden arbitrario)
- [ ] Nombres siguen `Método_Escenario_ResultadoEsperado`

## Errores Comunes

| Error | Solución |
|-------|----------|
| Test depende de BD real | Usar mocks o testcontainers |
| Asserts múltiples sin relación | Dividir en tests separados |
| Configuración compartida mutable | Usar constructor de xUnit (nuevo por test) |
| Ignorar async/await | Siempre retornar Task en tests asíncronos |
| Fechas fijas en el código | Inyectar `IDateTimeProvider` |

## Integración con CI/CD

```yaml
# Ejemplo en GitHub Actions
- name: Run Tests
  run: dotnet test --configuration Release --logger "trx" --results-directory TestResults
  
- name: Publish Results
  uses: dorny/test-reporter@v1
  with:
    name: .NET Tests
    path: TestResults/*.trx
    reporter: dotnet-trx
```

# .NET Core — Generación de Tests Unitarios

Crea, alinea y documenta tests de altísima calidad sin comprometer los tiempos de ejecución y usando directrices que mitigan la temida fragilidad de Testeo.

## Principios Base del Dominio de Tests

1. **Patrón AAA Orgánico** — Arrange (preparación), Act (invocación), Assert (comprobación analítica). Fúndelos en cada Factura o Theory.
2. **El poder de un Assert lógico** — Tu test se diseña en pos de verificar una única aserción vital de negocio (salvo en proyecciones masivas).
3. **Ignora los Ordenes** — Tu suite ha de ser ejecutada al azar (Random parallelization). Un test que demanda completarse tras su predecesor es un test parasitario.
4. **Legibilidad al extremo** — La nomenclatura `NombreDeMetodoBajoPrueba_EscenarioProvocado_EfectoOConsecuenciaValidada`.

## Tu Arsenal Moderno .NET

Asume este ecosistema en tus dependencias de proyectos Test:
- **xUnit** para orquestación de la suite 
- **NSubstitute** para engañar abstracciones (frente a Moq, gracias a su sintaxis lambda más expresiva)
- **FluentAssertions** para redactar validaciones como lenguaje natural
- **AutoFixture** (opcional y recomendable) para dejar de llenar constructores polimórficos de Dummy Texts.

## El Molde Central (Estructurador)

```csharp
using FluentAssertions;
using NSubstitute;
using Xunit;

public class UserServiceTests
{
    private readonly IUserRepository _userRepository;
    private readonly ILogger<UserService> _logger;
    private readonly UserService _sut; // SUT = System Under Test

    public UserServiceTests()
    {
        _userRepository = Substitute.For<IUserRepository>();
        _logger = Substitute.For<ILogger<UserService>>();
        _sut = new UserService(_userRepository, _logger);
    }
}
```

## Modalidades por Categorías

### A) El Camino de las Rosas (Happy Path)
```csharp
[Fact]
public async Task GetById_ProvidedExistingId_ReturnsMatchingUser()
{
    // Arrange
    var userId = Guid.NewGuid();
    var expectedUser = new User { Id = userId, Name = "Juan" };
    _userRepository.GetByIdAsync(userId).Returns(expectedUser); // NSubstitute

    // Act
    var result = await _sut.GetByIdAsync(userId);

    // Assert (FluentAssertions)
    result.Should().NotBeNull();
    result!.Name.Should().Be("Juan");
}
```

### B) Escenarios Condensados (Parametrizados)
Ahorra código masivo si la firma y la ejecución es monótona:
```csharp
[Theory]
[InlineData("")]
[InlineData(null)]
[InlineData("   ")]
public async Task Create_WithCorruptNames_ThrowsValidationException(string? invalidName)
{
    var request = new CreateUserRequest { Name = invalidName };
    var act = () => _sut.CreateAsync(request);
    
    // Testamos la salida controlada al cataclismo evadiendo Assert.Throws clásico
    await act.Should().ThrowAsync<ValidationException>();
}
```

### C) Comportamiento Interno e Interacciones Puras
```csharp
[Fact]
public async Task Delete_UponSuccessfulExecution_TriggersLoggerAndDeleter()
{
    // Arrange & Act (Simplificados)
    await _sut.DeleteAsync(userId);

    // Assert Interaccional
    await _userRepository.Received(1).DeleteAsync(userId);
    _logger.Received(1).LogInformation(Arg.Is<string>(s => s.Contains("eliminado")));
}
```

## Evita los Anti-Patrones Fatales de Unity Testing

| Error Típico | Remedio Drástico |
|-------|----------|
| **Cebos Falsos (Thread.Sleep)** | Evade demoras manuales; inyecta interfaces de servicio `ITimeProvider` pre-mockeables. |
| **Asserts Múltiples de distintos espectros** | Truncamiento y fraccionamiento a Tests independientes. |
| **Uso de async void en Testing** | Un desastre que anula xUnit por el pozo ciego; devuelve `async Task` en el decorador. |
| **Instancias compartidas que se manchan** | Resetea en el Constructor de Instancia en lugar de depender de Setups monolíticos (xUnit insta a usar el `.ctor` como su Setup base individual y virgen). |

# .NET Core — Generador de Wiki

Skill para generar documentación wiki profesional y estructurada a partir de proyectos .NET Core.

## Capacidades

1. **Extracción automática** de comentarios de documentación XML
2. **Análisis de arquitectura** — capas, dependencias, patrones usados
3. **Generación de diagramas** — dependencias entre proyectos, flujos de datos
4. **Índice navegable** — tabla de contenidos jerárquica
5. **Referencia de API** — documentación de endpoints, DTOs y contratos

## Estructura de Wiki Generada

```
wiki/
├── Home.md                      # Página principal con visión general
├── getting-started.md           # Guía de inicio rápido
├── architecture/
│   ├── overview.md              # Diagrama y descripción de capas
│   ├── decisions.md             # Registros de Decisiones de Arquitectura (ADRs)
│   └── dependencies.md          # Mapa de dependencias entre proyectos
├── domain/
│   ├── entities.md              # Entidades del dominio
│   ├── value-objects.md         # Objetos de Valor
│   └── events.md                # Eventos de dominio
├── api/
│   ├── endpoints.md             # Lista de endpoints REST
│   ├── authentication.md        # Flujo de autenticación
│   └── error-codes.md           # Códigos de error y respuestas
├── database/
│   ├── schema.md                # Esquema de base de datos
│   └── migrations.md            # Historial de migraciones
└── development/
    ├── setup.md                 # Configuración del entorno
    ├── conventions.md           # Convenciones de código
    └── testing.md               # Guía de testing
```

## Proceso de Generación

### Paso 1: Escanear la Solución

```bash
# Obtener estructura del proyecto
dotnet sln list
```

Analizar:
- Proyectos en la solución y sus relaciones
- Paquetes NuGet usados (para inferir tecnologías)
- Archivos de configuración (`appsettings.json`, `Program.cs`)
- Migraciones de Entity Framework

### Paso 2: Extraer Documentación del Código

Buscar y extraer:

```csharp
/// <summary>
/// Servicio principal para gestión de usuarios.
/// </summary>
/// <remarks>
/// Implementa el patrón Repository + Unit of Work.
/// Las operaciones de escritura son transaccionales.
/// </remarks>
public class UserService : IUserService
```

### Paso 3: Generar Home.md

```markdown
# {NombreProyecto}

> {Descripción extraída del .csproj o README}

## Tecnologías Utilizadas

| Categoría | Tecnología |
|-----------|-----------|
| Framework | .NET 8 |
| ORM | Entity Framework Core 8 |
| Auth | JWT + Identity |
| Cache | Redis |
| Mensajería | MediatR |

## Arquitectura

{Diagrama Mermaid generado automáticamente}

## Proyectos

| Proyecto | Tipo | Descripción |
|----------|------|-------------|
| src/Domain | Biblioteca de Clases | Entidades, interfaces, eventos |
| src/Application | Biblioteca de Clases | Casos de uso, DTOs, validaciones |
| src/Infrastructure | Biblioteca de Clases | EF Core, servicios externos |
| src/API | Web API | Controllers, middleware, config |

## Enlaces Rápidos

- [Guía de Inicio](getting-started.md)
- [Arquitectura](architecture/overview.md)
- [Referencia de API](api/endpoints.md)
- [Base de Datos](database/schema.md)
```

### Paso 4: Generar Documentación de API

Para cada Controller, generar:

```markdown
## POST /api/users

Crea un nuevo usuario en el sistema.

### Request

```json
{
  "name": "string (requerido, 2-100 caracteres)",
  "email": "string (requerido, formato email)",
  "role": "string (admin | user | viewer)"
}
``` 

### Respuestas

| Código | Descripción | Body |
|--------|-------------|------|
| 201 | Usuario creado | `UserDto` |
| 400 | Validación fallida | `ProblemDetails` |
| 409 | Email duplicado | `ProblemDetails` |

### Ejemplo

```bash
curl -X POST https://api.example.com/api/users \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Juan", "email": "juan@example.com", "role": "user"}'
```
```

### Paso 5: Generar Registros de Decisiones de Arquitectura (ADRs)

```markdown
## ADR-001: Usar MediatR para CQRS

**Estado**: Aceptado  
**Fecha**: 2024-01-15

### Contexto
Necesitamos separar las operaciones de lectura y escritura para mejorar la escalabilidad.

### Decisión
Usar MediatR como mediador para implementar CQRS ligero sin event sourcing.

### Consecuencias
- ✅ Handlers desacoplados y testables
- ✅ Comportamientos de pipeline para preocupaciones transversales
- ⚠️ Indirección adicional puede dificultar la depuración
```

## Formato de Salida

### Para GitHub Wiki
- Archivos `.md` en directorio `wiki/`
- Enlaces relativos entre páginas
- Sidebar (`_Sidebar.md`) con navegación

### Para Confluence
- Formato Confluence Wiki markup
- Macros de código y tablas nativas
- Jerarquía de páginas padre-hijo

## Lista de Verificación de Documentación Completa

- [ ] Home con visión general del proyecto
- [ ] Diagrama de arquitectura actualizado
- [ ] Cada endpoint documentado con request/response
- [ ] Entidades del dominio con relaciones
- [ ] Guía de configuración para nuevos desarrolladores
- [ ] ADRs para decisiones técnicas importantes
- [ ] Convenciones de código documentadas
- [ ] Esquema de base de datos actualizado

## Mantenimiento

### Automatización con CI/CD

```yaml
# Regenerar wiki en cada merge a la rama principal
- name: Generate Wiki
  run: |
    dotnet tool run docfx build docs/docfx.json
    # O ejecutar el script de generación personalizado
```

### Señales de Wiki Obsoleta

- Endpoints documentados que ya no existen
- Diagramas que no reflejan los proyectos actuales
- Configuraciones que ya no aplican
- Versiones de paquetes desactualizadas

# .NET Core — Generador de Wiki (Documentación Extendida)

Esta sub-aplicación y habilidad permite la conversión ágil y unificada del esfuerzo de código nativo documentado (XML comments y resúmenes relacionales o endpoints ASP.NET) a artefactos legibles, profesionales y anclables en intranets u hojas centralizadas externas (Confluence / Github Wiki).

## Capacidades Intrínsecas

1. **Extracción y barrido masivo** hacia la lectura de la semantica `<summary>`, `<param>`, y otros modificadores nativos C#.
2. **Scanner Arquitectónico** que disecciona tu dependencia y detecta límites limpios o polución.
3. Generación sintáctica de Diagramas y Mermaid auto-replegados según relaciones entre proyectos dll/csproj.
4. Tabla de Contenidos fluida y anclable a los headers Markdown.
5. Referenciador veloz y robusto de las APIs; convirtiendo los tipos y clases expuestas (Records / Request / Result) a ejemplos crudos HTTP REST.

## La Configuración del Ecosistema Resultante

Emanará una jerarquía organizada a nivel directorio de la siguiente envoltura:
```text
wiki/
├── Home.md                      # Index General y Manifiesto de entrada
├── getting-started.md           # Primeros Pasos del programador
├── architecture/
│   ├── overview.md              # Contexto de Integración 
│   ├── decisions.md             # Architecture Decision Records (ADR, tus confesiones técnicas)
│   └── dependencies.md          # Radiografía visual de Módulos (Mermaid)
├── api/
│   ├── endpoints.md             # Listado transaccional y Web
├── database/
│   ├── schema.md                # Esquema Db contextual de Entidades relacionales  
```

## Ciclo y Pasos Constructivos

### 1. Extracción e Identificación Endémica
Acudimos al XML Summary original:
```csharp
/// <summary>
/// Motor principal para la expedición de recibos en tránsito fiscal.
/// </summary>
/// <remarks>
/// Recrea el Patrón de Compensación Transaccional si la factura externa falla (Timeout/503).
/// </remarks>
public class ReceiptExpeditionService : IExpeditionOrchestrator
```
Transformamos estas sentencias en epígrafes limpios.

### 2. Extrusión hacia REST Endpoints

Un WebApi simple se volcará documentadamente como:

```markdown
## POST /api/invoices

Da a luz un recibo impositivo.

### Request Payloads (Payloads de Solicitud)

```json
{
  "fiscalId": "string (mandatory, DNI format)",
  "grossTotal": "decimal (> 0)"
}
```

### Respuestas Frecuentes

| Código HTTP | Detalle Técnico | Body Retornado |
|--------|-------------|------|
| 201 | Creado correctmente | `InvoiceCreatedDto` |
| 400 | Requisitos incumplidos (Validacion Interceptada) | `ProblemDetails` estándar de .NET |
```

### 3. Registro de Decisiones de Arquitectura (La Falsa Memoria)
Promueve la transparencia en entornos colaborativos con **ADR Documentation**:
```markdown
## ADR-005: Elección de Redis para la Memcached Sub-sistema

**Estado**: Confirmado  
**Fecha de Ratificación**: 2024-05-30

### Contexto Limitante
La capa SQL ha sobrepasado los 400 DTU de cómputo en horas pico ante búsquedas sobre tipologías inalterables.

### Resumen Consensuado
Uso de Caching Distribuido, abrazando el nuget nativo IDistributedCache y empleando a Redis como Broker y BackStore.

### Secuelas a Vigilar
- ✅ Elivación abrumadora de cuellos de botella CPU sobre SQL originario.
- ⚠️ Nos condena contractualmente a orquestar invalidaciones pro-activas de los bloques para prevenir datos arcaicos o desconfiguraciones catastróficas.
```

## Consejos de Sostenibilidad y Mantenimiento

Integra estas utilidades en tu canal (Pipeline) CI/CD.
Aprovechando herramientas base como **DocFX** (mítico .NET Doc framework) automatizando a cada `Merge de PR en Main Branch` tu Github Pages o carpeta de Assets será rearmada desde cero garantizando que el abismo entre la Wiki del proyecto y lo codificado realmente en C# se mantenga insustancial y mínimo.
No documentes tu API a mano, déjalo emanar de tu flujo de trabajo de programación C#.

# Assess Completeness

Lightweight readiness assessment to verify all required work is complete before marking a task done, completing an iteration, or transitioning phases.

## Process

### 1. Determine Assessment Scope

Based on `$ARGUMENTS[scope]` (defaults to "task"):

| Scope | Focus | Typical Checks |
|-------|-------|----------------|
| task | Single task completion | Code, tests, docs, commit |
| iteration | Iteration completion | All tasks, metrics, goals met |
| phase | Phase transition | Phase criteria, artifacts |

### 2. Perform Scope-Specific Checks

**Task Scope:**
- No uncommitted changes (or changes are intentional): `git status --porcelain`
- Changed files match task scope
- Tests exist for new code and pass
- Test coverage is acceptable
- Code is self-documenting; design docs updated if applicable
- Task exists in roadmap with accurate status

**Iteration Scope** (all task checks plus):
- All iteration tasks complete; no incomplete high-priority tasks
- Blocked tasks documented
- Iteration goals met; planned vs actual comparison; velocity captured
- Project status and roadmap updated; risk list updated
- All tests pass; no critical bugs; code review complete

**Phase Scope** (all iteration checks plus):
- Phase exit criteria met:
  - Inception: Vision, stakeholders, initial risk list
  - Elaboration: Architecture baseline, 80% use cases detailed
  - Construction: Feature complete, test coverage adequate
  - Transition: Deployment ready, user documentation complete
- Required phase artifacts exist, reviewed, and version-controlled
- Stakeholder buy-in obtained; next phase planned; risks identified

### 3. Generate Readiness Report

Output a structured report with: scope, date, strict mode, overall PASS/FAIL status, checks performed with results, missing items, recommendations, and next steps.

### 4. Handle Strict Mode

If `$ARGUMENTS[strict] == "true"`: any missing item results in FAIL. Otherwise: provide warnings for missing items; may pass with recommendations.

## Output

Returns: assessment scope, overall pass/fail status, checks performed with results, missing items, recommendations, next steps.

## See Also

- [openup-complete-task](../complete-task/SKILL.md) - Complete task after passing assessment
- [openup-retrospective](../retrospective/SKILL.md) - Create retrospective after iteration
- [openup-phase-review](../phase-review/SKILL.md) - Formal phase review process

# Evaluar la integridad

Evaluación de preparación ligera para verificar que todo el trabajo requerido esté completo antes de marcar una tarea como realizada, completar una iteración o realizar fases de transición.

## Proceso

### 1. Determinar el alcance de la evaluación

Basado en `$ARGUMENTS[scope]` (por defecto "tarea"):

| Alcance | Enfoque | Cheques típicos |
|-------|-------|----------------|
| tarea | Finalización de una sola tarea | Código, pruebas, documentos, confirmación |
| iteración | Finalización de iteración | Todas las tareas, métricas y objetivos cumplidos |
| fase | Transición de fase | Criterios de fase, artefactos |

### 2. Realizar comprobaciones específicas del ámbito

**Alcance de la tarea:**
- No hay cambios no confirmados (o los cambios son intencionales): `git status --porcelain`
- Los archivos modificados coinciden con el alcance de la tarea.
- Existen pruebas para código nuevo y aprobación.
- La cobertura de la prueba es aceptable.
- El código es autodocumentado; documentos de diseño actualizados si corresponde
- La tarea existe en la hoja de ruta con un estado preciso.

**Alcance de la iteración** (todas las comprobaciones de tareas más):
- Todas las tareas de iteración completadas; sin tareas incompletas de alta prioridad
- Tareas bloqueadas documentadas.
- Se cumplieron los objetivos de iteración; comparación planificada versus real; velocidad capturada
- Estado del proyecto y hoja de ruta actualizados; lista de riesgos actualizada
- Pasan todas las pruebas; sin errores críticos; revisión del código completa

**Alcance de la fase** (todas las comprobaciones de iteración más):
- Criterios de salida de fase cumplidos:
  - Inicio: Visión, partes interesadas, lista de riesgos inicial
  - Elaboración: Línea base de arquitectura, 80% casos de uso detallados.
  - Construcción: Característica completa, cobertura de prueba adecuada
  - Transición: implementación lista, documentación de usuario completa
- Los artefactos de fase requeridos existen, se revisan y están controlados por versión.
- Se obtuvo la aceptación de las partes interesadas; próxima fase prevista; riesgos identificados

### 3. Generar informe de preparación

Genere un informe estructurado con: alcance, fecha, modo estricto, estado general de PASO/FALLO, verificaciones realizadas con resultados, elementos faltantes, recomendaciones y próximos pasos.

### 4. Manejar el modo estricto

Si `$ARGUMENTS[strict] == ​​"true"`: cualquier elemento faltante resulta en FAIL. De lo contrario: proporcione advertencias sobre elementos faltantes; puede pasar con recomendaciones.

## Producción

Devoluciones: alcance de la evaluación, estado general de aprobación/reprobación, verificaciones realizadas con resultados, elementos faltantes, recomendaciones, próximos pasos.

## Ver también

- [openup-complete-task](../complete-task/SKILL.md) - Completa la tarea después de aprobar la evaluación
- [openup-retrospective](../retrospective/SKILL.md) - Crear retrospectiva después de la iteración
- [openup-phase-review](../phase-review/SKILL.md) - Proceso de revisión de fase formal

# Complete Task

Finalize a completed task: commit remaining changes, update docs, create traceability logs, and create a PR.

## Success Criteria

After this skill completes, ALL of these must be true:

- [ ] All changes are committed (no uncommitted changes remain)
- [ ] Commit messages follow canonical format: `type(scope): description [T-XXX]`
- [ ] Roadmap is updated to mark task complete
- [ ] Project status is updated
- [ ] Traceability logs are created with commit SHAs
- [ ] PR is created (unless `create_pr` was explicitly `"false"`)

## Detailed Steps

### 1. Verify Task Completion

Before marking a task as complete, verify:
- All implementation work is done
- All tests pass
- Documentation is updated

### 2. Commit Remaining Changes

Most changes should already be committed as atomic commits during implementation (see `commit-procedure.md`). This step handles any leftover uncommitted work.

1. Run `git status --porcelain` to check for uncommitted changes
2. If changes exist:
   - Stage relevant files: `git add <files>`
   - Commit using canonical format: `type(scope): description [$ARGUMENTS[task_id]]`
   - Use `$ARGUMENTS[commit_message]` if provided
3. Verify: `git status --porcelain` returns empty

### 3. Update Roadmap

Update `docs/roadmap.md`:
- Mark task `$ARGUMENTS[task_id]` as `completed`
- Add completion date

### 4. Update Project Status

Update `docs/project-status.md`:
- Update "Active Work Items" table
- Update `last_updated` and `updated_by` fields

### 5. Create Traceability Logs

Create both markdown and JSONL logs:
- Markdown log: `docs/agent-logs/YYYY/MM/DD/<timestamp>-<agent>-<branch>.md`
- JSONL entry: Append to `docs/agent-logs/agent-runs.jsonl`
- Include commit SHAs in the logs

### 6. Create Pull Request

**PR is created by default.** Skip ONLY if `$ARGUMENTS[create_pr]` is explicitly `"false"`.

1. Push the branch:
   ```bash
   git push -u origin $(git rev-parse --abbrev-ref HEAD)
   ```

2. Verify unmerged commits exist:
   ```bash
   git log <trunk>..HEAD --oneline
   ```

3. Invoke `/openup-create-pr` skill with `task_id: $ARGUMENTS[task_id]`

4. Report result to user:
   - Success → provide PR URL
   - No unmerged commits → inform user PR is not needed
   - Failure → explain error and provide manual steps

## Output

Returns a summary of:
- Task completed
- Commit SHAs
- Files changed
- Log locations
- PR URL

## See Also

- [openup-create-pr](../create-pr/SKILL.md) - Create pull request separately
- [openup-log-run](../log-run/SKILL.md) - Traceability logging details
- [openup-start-iteration](../start-iteration/SKILL.md) - Begin next iteration

# Completar tarea

Finalice una tarea completada: confirme los cambios restantes, actualice documentos, cree registros de trazabilidad y cree un PR.

## Criterios de éxito

Una vez completada esta habilidad, TODO lo siguiente debe ser cierto:

- [] Todos los cambios están confirmados (no quedan cambios no confirmados)
- [] Los mensajes de confirmación siguen el formato canónico: `tipo(alcance): descripción [T-XXX]`
- [] La hoja de ruta se actualiza para marcar la tarea como completada
- [] Se actualiza el estado del proyecto.
- [] Los registros de trazabilidad se crean con SHA de confirmación
- [ ] Se crea PR (a menos que `create_pr` fuera explícitamente `"falso"`)

## Pasos detallados

### 1. Verificar la finalización de la tarea

Antes de marcar una tarea como completa, verifique:
- Todo el trabajo de implementación está realizado.
- Todas las pruebas pasan
- La documentación está actualizada.

### 2. Confirmar los cambios restantes

La mayoría de los cambios ya deberían confirmarse como confirmaciones atómicas durante la implementación (consulte `commit-procedure.md`). Este paso maneja cualquier trabajo sobrante no comprometido.

1. Ejecute `git status --porcelain` para verificar cambios no confirmados
2. Si existen cambios:
   - Preparar archivos relevantes: `git add <files>`
   - Confirmar usando formato canónico: `tipo(alcance): descripción [$ARGUMENTS[task_id]]`
   - Utilice `$ARGUMENTS[commit_message]` si se proporciona
3. Verifique: `git status --porcelain` regresa vacío

### 3. Actualizar la hoja de ruta

Actualizar `docs/roadmap.md`:
- Marcar la tarea `$ARGUMENTS[task_id]` como `completada`
- Agregar fecha de finalización

### 4. Actualizar el estado del proyecto

Actualice `docs/project-status.md`:
- Actualizar la tabla "Elementos de trabajo activos"
- Actualizar los campos `last_updated` y `updated_by`

### 5. Crear registros de trazabilidad

Cree registros de rebajas y JSONL:
- Registro de rebajas: `docs/agent-logs/AAAA/MM/DD/<marca de tiempo>-<agente>-<rama>.md`
- Entrada JSONL: agregar a `docs/agent-logs/agent-runs.jsonl`
- Incluir SHA de confirmación en los registros

### 6. Crear solicitud de extracción

**PR se crea de forma predeterminada.** Omita SÓLO si `$ARGUMENTS[create_pr]` es explícitamente `"falso"`.

1. Empuja la rama:
   ```golpecito
   git push -u origen $(git rev-parse --abbrev-ref HEAD)
   ```

2. Verifique que existan confirmaciones no fusionadas:
   ```golpecito
   git log <trunk>..HEAD --oneline
   ```

3. Invocar la habilidad `/openup-create-pr` con `task_id: $ARGUMENTS[task_id]`

4. Informar el resultado al usuario:
   - Éxito → proporcionar URL de relaciones públicas
   - No hay confirmaciones no fusionadas → informar al usuario que no se necesita PR
   - Fallo → explicar el error y proporcionar pasos manuales

## Producción

Devuelve un resumen de:
- Tarea completada
- Confirmar SHA
- Archivos cambiados
- Ubicaciones de registro
- URL de relaciones públicas

## Ver también

- [openup-create-pr](../create-pr/SKILL.md) - Crear solicitud de extracción por separado
- [openup-log-run](../log-run/SKILL.md) - Detalles del registro de trazabilidad
- [openup-start-iteration](../start-iteration/SKILL.md) - Comienza la siguiente iteración

# Construction Phase

This skill guides you through the Construction phase of OpenUP - building the system incrementally.

## When to Use

Use this skill when:
- Elaboration is complete and architecture baseline is established
- Ready to build the system iteratively
- Implementing features incrementally
- Preparing for beta testing
- Checking if Construction phase is complete
- Getting guidance on next steps in Construction

## When NOT to Use

Do NOT use this skill when:
- Architecture is not yet stable (use `/openup-elaboration`)
- System is ready for deployment (use `/openup-transition`)
- Need to create specific artifacts (use artifact skills)
- Looking for iteration planning (use `/openup-create-iteration-plan`)

## Success Criteria

After using this skill, verify:
- [ ] Phase status is clearly understood (initiated, in-progress, or complete)
- [ ] Implementation progress is tracked
- [ ] Test coverage is adequate
- [ ] Next iteration tasks are identified
- [ ] Beta readiness is assessed

## Construction Overview

**Goal**: Build the system iteratively until it's ready for deployment
**Duration**: Typically 8-16 weeks (multiple iterations)
**Key Milestone**: Operational Capability

## Phase Objectives

1. Implement all remaining features
2. Iteratively test and refine the system
3. Prepare for beta testing
4. Complete user documentation
5. Achieve acceptable quality levels

## Completion Criteria

- [ ] Product is stable enough for beta testing
- [ ] Alpha test results documented
- [ ] Critical issues resolved
- [ ] User documentation is adequate
- [ ] Stakeholder agreement to deploy to beta users

## Process

### 1. Read Project Status

Read `docs/project-status.md` to:
- Confirm phase is `construction`
- Check iteration goals
- Review active work items

### 2. Based on Activity

**`initiate`**: Start Construction phase
- Update `docs/project-status.md` to set `phase: construction`
- Review `docs/architecture-notebook.md` for implementation guidance
- Update `docs/roadmap.md` with construction tasks
- Create iteration plans for upcoming iterations

**`check-status`**: Review progress
- Check all completion criteria above
- List what's done and what remains
- Identify blockers

**`next-steps`**: Get recommendations
- Suggest next tasks based on current state
- Prioritize by value and dependencies

## Key Work Products

- **Implementation** - Source code
- **Unit Tests** - Developer-written tests
- **Design** (`docs/design/*.md`) - Detailed design documents
- **Test Cases** (`docs/test-cases/*.md`) - Test documentation
- **User Documentation** - User guides and manuals

## Recommended Team

For Construction phase work, create a team with:
- **developer** - Lead implementation
- **tester** - Continuous testing and validation
- Add **architect** for technical guidance
- Add **analyst** for requirements clarification

## Iteration Focus

Each construction iteration should:
1. Select features from the roadmap
2. Implement with tests
3. Review and validate
4. Update documentation
5. Prepare for next iteration

## References

- Construction Phase: `docs-eng-process/openup-knowledge-base/practice-management/risk_value_lifecycle/guidances/concepts/phase-construction.md`
- Developer Role: `docs-eng-process/openup-knowledge-base/core/role/roles/developer-11.md`
- Tester Role: `docs-eng-process/openup-knowledge-base/core/role/roles/tester-5.md`

## See Also

- [openup-complete-task](../../openup-workflow/complete-task/SKILL.md) - Mark tasks complete
- [openup-create-test-plan](../../openup-artifacts/create-test-plan/SKILL.md) - Generate test cases
- [openup-elaboration](../elaboration/SKILL.md) - Previous phase
- [openup-transition](../transition/SKILL.md) - Next phase after Construction

# Fase de Construcción

Esta habilidad lo guía a través de la fase de construcción de OpenUP: construir el sistema de manera incremental.

## Cuándo utilizar

Utilice esta habilidad cuando:
- Se completa la elaboración y se establece la línea base de la arquitectura.
- Listo para construir el sistema de forma iterativa.
- Implementación de funciones de forma incremental.
- Preparación para las pruebas beta.
- Comprobar si la fase de construcción está completa.
- Obtener orientación sobre los próximos pasos en la construcción.

## Cuándo NO usarlo

NO uses esta habilidad cuando:
- La arquitectura aún no es estable (use `/openup-elaboration`)
- El sistema está listo para la implementación (use `/openup-transition`)
- Necesidad de crear artefactos específicos (usar habilidades de artefactos)
- Buscando planificación de iteración (use `/openup-create-iteration-plan`)

## Criterios de éxito

Después de usar esta habilidad, verifique:
- [ ] El estado de la fase se comprende claramente (iniciada, en curso o completa)
- [] Se realiza un seguimiento del progreso de la implementación.
- [ ] La cobertura de la prueba es adecuada
- [] Se identifican las tareas de la siguiente iteración.
- [ ] Se evalúa la preparación Beta

## Descripción general de la construcción

**Objetivo**: construir el sistema de forma iterativa hasta que esté listo para su implementación.
**Duración**: normalmente de 8 a 16 semanas (múltiples iteraciones)
**Hito clave**: Capacidad operativa

## Objetivos de la fase

1. Implementar todas las funciones restantes
2. Probar y perfeccionar el sistema de forma iterativa
3. Prepárese para las pruebas beta
4. Documentación de usuario completa
5. Alcanzar niveles de calidad aceptables

## Criterios de finalización

- [] El producto es lo suficientemente estable para realizar pruebas beta.
- [] Resultados de la prueba alfa documentados
- [] Problemas críticos resueltos
- [ ] La documentación del usuario es adecuada
- [] Acuerdo de las partes interesadas para implementar a los usuarios beta

## Proceso

### 1. Leer el estado del proyecto

Lea `docs/project-status.md` para:
- Confirmar que la fase es "construcción".
- Verificar los objetivos de iteración.
- Revisar elementos de trabajo activos.

### 2. Basado en la actividad

**`iniciar`**: Iniciar fase de construcción
- Actualice `docs/project-status.md` para configurar `fase: construcción`
- Revise `docs/architecture-notebook.md` para obtener orientación sobre la implementación.
- Actualización `docs/roadmap.md` con tareas de construcción
- Crear planes de iteración para las próximas iteraciones.

**`check-status`**: Revisar el progreso
- Verifique todos los criterios de finalización anteriores
- Enumerar lo que se hizo y lo que queda
- Identificar bloqueadores

**`próximos pasos`**: obtener recomendaciones
- Sugerir próximas tareas según el estado actual
- Priorizar por valor y dependencias.

## Productos de trabajo clave

- **Implementación** - Código fuente
- **Pruebas unitarias** - Pruebas escritas por desarrolladores
- **Diseño** (`docs/design/*.md`) - Documentos de diseño detallados
- **Casos de prueba** (`docs/test-cases/*.md`) - Documentación de prueba
- **Documentación de usuario** - Guías y manuales de usuario

## Equipo recomendado

Para el trabajo de la fase de Construcción, cree un equipo con:
- **desarrollador** - Implementación líder
- **tester** - Pruebas y validación continuas
- Agregue **arquitecto** para obtener orientación técnica.
- Agregue **analista** para aclarar los requisitos.

## Enfoque de iteración

Cada iteración de construcción debe:
1. Seleccione funciones de la hoja de ruta
2. Implementar con pruebas
3. Revisar y validar
4. Actualizar la documentación
5. Prepárese para la próxima iteración

## Referencias

- Fase de construcción: `docs-eng-process/openup-knowledge-base/practice-management/risk_value_lifecycle/guidances/concepts/phase-construction.md`
- Rol de desarrollador: `docs-eng-process/openup-knowledge-base/core/role/roles/developer-11.md`
- Rol del probador: `docs-eng-process/openup-knowledge-base/core/role/roles/tester-5.md`

## Ver también

- [openup-complete-task](../../openup-workflow/complete-task/SKILL.md) - Marcar tareas completadas
- [openup-create-test-plan](../../openup-artifacts/create-test-plan/SKILL.md) - Generar casos de prueba
- [openup-elaboration](../elaboration/SKILL.md) - Fase previa
- [openup-transition](../transition/SKILL.md) - Siguiente fase después de la construcción

# Crear Cuaderno de Arquitectura

Esta skill genera o actualiza un cuaderno de arquitectura a partir de la plantilla OpenUP.

## Cuándo Usar

Usa esta skill cuando:
- Comiences la fase de Elaboración y necesites documentar la arquitectura
- Tomes decisiones arquitectónicas significativas
- Necesites documentar el diseño y las restricciones del sistema
- Establezcas la línea base de arquitectura
- Revises o actualices la arquitectura existente

## Cuándo NO Usar

NO uses esta skill cuando:
- Estés en la fase de Inicio antes de definir la arquitectura (usa `/openup-create-vision`)
- Necesites diseño detallado de componentes (usa documentos de diseño)
- Busques detalles de implementación (usa documentación del código)
- El cuaderno de arquitectura existe y solo necesita cambios menores (edítalo directamente)

## Criterios de Éxito

Tras usar esta skill, verifica:
- [ ] El cuaderno de arquitectura existe en `docs/architecture-notebook.md`
- [ ] El nombre y contexto del sistema están definidos
- [ ] Las decisiones arquitectónicas clave están documentadas
- [ ] Las restricciones arquitectónicas están listadas
- [ ] Los atributos de calidad están especificados

## Proceso

### 1. Comprobar Arquitectura Existente

Comprobar si `docs/architecture-notebook.md` existe:
- Si existe, actualizarlo
- Si no existe, crear desde la plantilla

### 2. Leer Contexto del Proyecto

Leer `docs/project-status.md` y `docs/vision.md` para comprender:
- Requisitos del sistema
- Restricciones
- Preocupaciones de los interesados

### 3. Copiar Plantilla (si es nuevo)

Si se crea nuevo, copiar `docs-eng-process/templates/architecture-notebook.md` a `docs/architecture-notebook.md`

### 4. Completar el Cuaderno de Arquitectura

Actualizar con:
- **Nombre del sistema**: `$ARGUMENTS[system_name]`
- **Preocupaciones arquitectónicas**: De `$ARGUMENTS[architectural_concerns]` o derivadas de los requisitos
- **Visión general de la arquitectura**: Arquitectura del sistema a alto nivel
- **Decisiones arquitectónicas clave**: Justificación de las decisiones principales
- **Restricciones**: Restricciones técnicas y de negocio
- **Atributos de calidad**: Requisitos de rendimiento, seguridad y escalabilidad
- **Descomposición en subsistemas**: Componentes principales del sistema

### 5. Validar Completitud

Asegurar que el cuaderno de arquitectura incluya:
- Visión general y contexto del sistema
- Decisiones arquitectónicas clave con justificación
- Restricciones arquitectónicas
- Requisitos de atributos de calidad
- Descomposición en subsistemas/componentes

## Salida

Devuelve:
- Ruta al cuaderno de arquitectura
- Lista de secciones completadas
- Decisiones arquitectónicas documentadas

## Errores Comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que `docs-eng-process/templates/architecture-notebook.md` existe |
| Contexto insuficiente | Visión/requisitos no definidos | Crear primero el documento de visión |
| Sobrescribir existente | El cuaderno de arquitectura ya existe | Actualizar el archivo existente en lugar de crear uno nuevo |

## Referencias

- Plantilla de Cuaderno de Arquitectura: `docs-eng-process/templates/architecture-notebook.md`
- Producto de Trabajo de Arquitectura: `docs-eng-process/openup-knowledge-base/practice-technical/evolutionary_arch/base/workproducts/architecture-notebook-6.md`
- Rol de Arquitecto: `docs-eng-process/openup-knowledge-base/core/role/roles/architect-6.md`

## Ver También

- [openup-elaboration](../../openup-phases/elaboration/SKILL.md) - Guía de la fase de Elaboración
- [openup-create-vision](../create-vision/SKILL.md) - Definir visión antes de la arquitectura
- [openup-create-risk-list](../create-risk-list/SKILL.md) - Documentar riesgos técnicos

# Crear Cuaderno de Arquitectura

Esta habilidad genera o actualiza un cuaderno de arquitectura a partir de la plantilla OpenUP.

## Cuándo usar

Usa esta habilidad cuando:
- Comienza la fase de Elaboración y necesitas documentar la arquitectura.
- Tomes decisiones arquitectónicas significativas
- Necesites documentar el diseño y las restricciones del sistema.
- Establezcas la línea base de arquitectura.
- Revisa o actualiza la arquitectura existente.

## Cuándo NO Usar

NO usa esta habilidad cuando:
- Estés en la fase de Inicio antes de definir la arquitectura (usa `/openup-create-vision`)
- Necesites diseño detallado de componentes (usa documentos de diseño)
- Busques detalles de implementación (usa documentación del código)
- El cuaderno de arquitectura existe y solo necesita cambios menores (edítalo directamente)

## Criterios de Éxito

Tras usar esta habilidad, verifica:
- [ ] El cuaderno de arquitectura existe en `docs/architecture-notebook.md`
- [ ] El nombre y contexto del sistema están definidos
- [ ] Las decisiones arquitectónicas clave están documentadas
- [ ] Las restricciones arquitectónicas están listadas
- [ ] Los atributos de calidad están especificados

##Proceso

### 1. Comprobar Arquitectura Existente

Comprobar si existe `docs/architecture-notebook.md`:
- Si existe, actualízalo
- Si no existe, crear desde la plantilla

### 2. Leer Contexto del Proyecto

Lea `docs/project-status.md` y `docs/vision.md` para comprender:
- Requisitos del sistema
- Restricciones
- Preocupaciones de los interesados

### 3. Copiar plantilla (si es nuevo)

Si se crea nuevo, copie `docs-eng-process/templates/architecture-notebook.md` a `docs/architecture-notebook.md`

### 4. Completar el Cuaderno de Arquitectura

Actualizar con:
- **Nombre del sistema**: `$ARGUMENTS[nombre_sistema]`
- **Preocupaciones arquitectónicas**: De `$ARGUMENTS[architectural_concerns]` o derivadas de los requisitos
- **Visión general de la arquitectura**: Arquitectura del sistema a alto nivel
- **Decisiones arquitectónicas clave**: Justificación de las decisiones principales
- **Restricciones**: Restricciones técnicas y de negocio
- **Atributos de calidad**: Requisitos de rendimiento, seguridad y escalabilidad
- **Descomposición en subsistemas**: Componentes principales del sistema

### 5. Validar Completitud

Asegurar que el cuaderno de arquitectura incluya:
- Visión general y contexto del sistema.
- Decisiones arquitectónicas clave con justificación
- Restricciones arquitectónicas
- Requisitos de atributos de calidad
- Descomposición en subsistemas/componentes

##Salida

Devuelve:
- Ruta al cuaderno de arquitectura.
- Lista de secciones completadas
- Decisiones arquitectónicas documentadas

## Errores Comunes

| Error | causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que existe `docs-eng-process/templates/architecture-notebook.md` |
| Contexto insuficiente | Visión/requisitos no definidos | Crear primero el documento de visión |
| Sobrescribir existente | El cuaderno de arquitectura ya existe | Actualizar el archivo existente en lugar de crear uno nuevo |

## Referencias

- Plantilla de Cuaderno de Arquitectura: `docs-eng-process/templates/architecture-notebook.md`
- Producto de Trabajo de Arquitectura: `docs-eng-process/openup-knowledge-base/practice-technical/evolutionary_arch/base/workproducts/architecture-notebook-6.md`
- Rol de Arquitecto: `docs-eng-process/openup-knowledge-base/core/role/roles/architect-6.md`

## Ver También

- [openup-elaboration](../../openup-phases/elaboration/SKILL.md) - Guía de la fase de Elaboración
- [openup-create-vision](../create-vision/SKILL.md) - Definir visión antes de la arquitectura
- [openup-create-risk-list](../create-risk-list/SKILL.md) - Documentar riesgos técnicos

# Crear Documentación

Genera documentación legible para humanos a partir de casos de uso, código y artefactos.

## Proceso

### 1. Determinar Tipo de Documentación

Según `$ARGUMENTS[doc_type]`:

| doc_type | Plantilla | Propósito |
|----------|-----------|-----------|
| guia-usuario | user-guide-template.md | Documentación para el usuario final |
| referencia-api | api-reference-template.md | Documentación de la API |
| solucion-problemas | (generada) | Problemas comunes y soluciones |
| tutorial | (generada) | Aprendizaje paso a paso |

### 2. Recopilar Material Fuente

Leer las fuentes relevantes para la funcionalidad: casos de uso (`docs/use-cases/`), casos de prueba (`docs/test-cases/`), documentos de diseño (`docs/design/`) y código fuente (`src/`). Adaptar las fuentes según el tipo de documentación.

### 3. Generar Documentación

Consultar los archivos específicos por tipo para el proceso detallado de generación:
- [user-guide.md](./user-guide.md)
- [api-reference.md](./api-reference.md)
- [troubleshooting.md](./troubleshooting.md)
- [tutorial.md](./tutorial.md)

### 4. Validar y Revisar

- Verificar que todos los ejemplos son correctos
- Probar los ejemplos de código si aplica
- Comprobar las referencias cruzadas
- Asegurar la claridad para el público objetivo

### 5. Crear Archivo de Documentación

- Ruta por defecto: `docs/user-guides/<funcionalidad>-<tipo_doc>.md`
- Ruta personalizada: Usar `$ARGUMENTS[output_path]` si se proporciona
- Enlazar documentación relacionada

## Ejemplo de Uso

```
/openup-create-documentation doc_type: guia-usuario feature: autenticacion-usuarios
/openup-create-documentation doc_type: referencia-api feature: api-pagos output_path: docs/api/
```

## Errores Comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Caso de uso no encontrado | La funcionalidad carece de casos de uso | Crear primero los casos de uso |
| Código no encontrado | La funcionalidad no está implementada | Verificar el nombre y estado de la funcionalidad |
| Plantilla no disponible | La plantilla no está disponible | Usar estructura genérica |

## Referencias

- Plantilla de Guía de Usuario: `docs-eng-process/templates/user-guide-template.md`
- Plantilla de Referencia de API: `docs-eng-process/templates/api-reference-template.md`

## Ver También

- [openup-create-use-case](../create-use-case/SKILL.md) - Crear primero los casos de uso
- [openup-detail-use-case](../detail-use-case/SKILL.md) - Detallar casos de uso para mejor documentación

# Crear Documentación

Genera documentación legible para humanos a partir de casos de uso, código y artefactos.

##Proceso

### 1. Determinar tipo de documentación

Según `$ARGUMENTS[doc_type]`:

| tipo_doc | Plantilla | Propósito |
|----------|-----------|-----------|
| guia-usuario | plantilla-guía-usuario.md | Documentación para el usuario final |
| referencia-api | plantilla-referencia-api.md | Documentación de la API |
| solucion-problemas | (generada) | Problemas comunes y soluciones |
| tutorial | (generada) | Aprendizaje paso a paso |

### 2. Material Recopilar Fuente

Lea las fuentes relevantes para la funcionalidad: casos de uso (`docs/use-cases/`), casos de prueba (`docs/test-cases/`), documentos de diseño (`docs/design/`) y código fuente (`src/`). Adaptar las fuentes según el tipo de documentación.

### 3. Generar Documentación

Consultar los archivos específicos por tipo para el proceso detallado de generación:
- [guía-usuario.md](./guía-usuario.md)
- [api-referencia.md](./api-referencia.md)
- [solución de problemas.md](./solución de problemas.md)
- [tutorial.md](./tutorial.md)

### 4. Validar y Revisar

- Verificar que todos los ejemplos son correctos
- Probar los ejemplos de código si aplica
- Comprobar las referencias cruzadas
- Asegurar la claridad para el público objetivo.

### 5. Crear Archivo de Documentación

- Ruta por defecto: `docs/user-guides/<funcionalidad>-<tipo_doc>.md`
- Ruta personalizada: Usar `$ARGUMENTS[output_path]` si se proporciona
- Enlazar documentación relacionada

## Ejemplo de uso

```
/openup-create-documentation doc_type: guia-usuario feature: autenticacion-usuarios
/openup-create-documentation doc_type: referencia-api feature: api-pagos output_path: docs/api/
```

## Errores Comunes

| Error | causa | Solución |
|-------|-------|----------|
| Caso de uso no encontrado | La funcionalidad carece de casos de uso | Crear primero los casos de uso |
| Código no encontrado | La funcionalidad no está implementada | Verificar el nombre y estado de la funcionalidad |
| Plantilla no disponible | La plantilla no está disponible | Usar estructura genérica |

## Referencias

- Plantilla de Guía de Usuario: `docs-eng-process/templates/user-guide-template.md`
- Plantilla de Referencia de API: `docs-eng-process/templates/api-reference-template.md`

## Ver También

- [openup-create-use-case](../create-use-case/SKILL.md) - Crear primero los casos de uso
- [openup-detail-use-case](../detail-use-case/SKILL.md) - Detallar casos de uso para mejor documentación

# Crear Plan de Iteración

Esta skill genera un plan de iteración a partir de la plantilla OpenUP.

## Cuándo Usar

Usa esta skill cuando:
- Comiences una nueva iteración y necesites planificar el trabajo
- Estés en la fase de Construcción planificando iteraciones
- Necesites seleccionar tareas de la hoja de ruta para la iteración
- Asignes tareas a miembros del equipo
- Definas criterios de éxito de la iteración

## Cuándo NO Usar

NO uses esta skill cuando:
- Quieras iniciar la iteración (usa `/openup-start-iteration`)
- Necesites crear la hoja de ruta (usa la gestión de proyecto)
- El plan de iteración existe y solo necesita cambios menores (edítalo directamente)
- Estés en la fase de Inicio (usa las actividades de fase en su lugar)

## Criterios de Éxito

Tras usar esta skill, verifica:
- [ ] El archivo del plan de iteración existe
- [ ] El objetivo de la iteración está claramente definido
- [ ] Las tareas están seleccionadas de la hoja de ruta
- [ ] Las asignaciones de tareas están hechas
- [ ] Los criterios de éxito están especificados

## Proceso

### 1. Leer Estado del Proyecto

Leer `docs/project-status.md` para obtener:
- Fase actual
- Iteración actual
- Objetivos de la iteración

### 2. Leer Hoja de Ruta

Leer `docs/roadmap.md` para identificar:
- Tareas pendientes apropiadas para esta iteración
- Prioridades y dependencias de las tareas

### 3. Determinar Número de Iteración

Usar `$ARGUMENTS[iteration_number]` o auto-incrementar desde la iteración actual.

### 4. Copiar Plantilla

Copiar `docs-eng-process/templates/iteration-plan.md` a `docs/phases/<fase>/iteration-<n>-plan.md`

### 5. Completar el Plan de Iteración

Actualizar con:
- **Número de iteración** y fechas
- **Objetivo de la iteración**: Derivado de la hoja de ruta y los objetivos de fase
- **Tareas seleccionadas**: De la hoja de ruta, priorizadas para esta iteración
- **Asignaciones de tareas**: Qué roles se encargarán de cada tarea
- **Criterios de éxito**: Cómo saber si la iteración tuvo éxito
- **Evaluación de riesgos**: Riesgos específicos de la iteración

### 6. Validar Completitud

Asegurar que el plan de iteración incluya:
- Objetivo de iteración claro
- Lista de tareas a completar
- Asignaciones de tareas
- Criterios de éxito
- Cronograma de la iteración

## Salida

Devuelve:
- Ruta al plan de iteración
- Lista de tareas planificadas
- Composición de equipo recomendada

## Errores Comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que `docs-eng-process/templates/iteration-plan.md` existe |
| Sin tareas disponibles | La hoja de ruta está vacía o todas las tareas completadas | Revisar la hoja de ruta y añadir tareas pendientes |
| Número de iteración inválido | Conflictos o huecos en el número de iteración | Verificar la iteración actual desde el estado del proyecto |

## Referencias

- Plantilla de Plan de Iteración: `docs-eng-process/templates/iteration-plan.md`
- Rol de Jefe de Proyecto: `docs-eng-process/openup-knowledge-base/core/role/roles/project-manager-4.md`

## Ver También

- [openup-start-iteration](../../openup-workflow/start-iteration/SKILL.md) - Iniciar nueva iteración
- [openup-complete-task](../../openup-workflow/complete-task/SKILL.md) - Marcar tareas de iteración como completadas
- [openup-construction](../../openup-phases/construction/SKILL.md) - Planificación de iteraciones de Construcción

# Crear Plan de Iteración

Esta habilidad genera un plan de iteración a partir de la plantilla OpenUP.

## Cuándo usar

Usa esta habilidad cuando:
- Comienza una nueva iteración y necesitas planificar el trabajo.
- Estés en la fase de Construcción planificando iteraciones
- Necesites seleccionar tareas de la hoja de ruta para la iteración
- Asigna tareas a miembros del equipo.
- Definir criterios de éxito de la iteración.

## Cuándo NO Usar

NO usa esta habilidad cuando:
- Quieras iniciar la iteración (usa `/openup-start-iteration`)
- Necesites crear la hoja de ruta (usa la gestión de proyecto)
- El plan de iteración existe y solo necesita cambios menores (edítalo directamente)
- Estés en la fase de Inicio (usa las actividades de fase en su lugar)

## Criterios de Éxito

Tras usar esta habilidad, verifica:
- [ ] El archivo del plan de iteración existe
- [ ] El objetivo de la iteración está claramente definido
- [ ] Las tareas están seleccionadas de la hoja de ruta
- [ ] Las asignaciones de tareas están hechas
- [ ] Los criterios de éxito están especificados

##Proceso

### 1. Leer Estado del Proyecto

Lea `docs/project-status.md` para obtener:
- Fase real
- Iteración real
- Objetivos de la iteración

### 2. Leer Hoja de Ruta

Leer `docs/roadmap.md` para identificar:
- Tareas pendientes apropiadas para esta iteración
- Prioridades y dependencias de las tareas

### 3. Determinar Número de Iteración

Usar `$ARGUMENTS[iteration_number]` para autoincrementar desde la iteración actual.

### 4. Copiar plantilla

Copiar `docs-eng-process/templates/iteration-plan.md` a `docs/phases/<fase>/iteration-<n>-plan.md`

### 5. Completar el Plan de Iteración

Actualizar con:
- **Número de iteración** y fechas
- **Objetivo de la iteración**: Derivado de la hoja de ruta y los objetivos de fase
- **Tareas seleccionadas**: De la hoja de ruta, priorizadas para esta iteración
- **Asignaciones de tareas**: Qué roles se encargarán de cada tarea
- **Criterios de éxito**: Cómo saber si la iteración tuvo éxito
- **Evaluación de riesgos**: Riesgos específicos de la iteración

### 6. Validar Completitud

Asegurar que el plan de iteración incluya:
- Objetivo de iteración claro
- Lista de tareas a completar
- Asignaciones de tareas
- Criterios de éxito
- Cronograma de la iteración

##Salida

Devuelve:
- Ruta al plan de iteración
- Lista de tareas planificadas
- Composición del equipo recomendada

## Errores Comunes

| Error | causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que existe `docs-eng-process/templates/iteration-plan.md` |
| Sin tareas disponibles | La hoja de ruta está vacía o todas las tareas completadas | Revisar la hoja de ruta y agregar tareas pendientes |
| Número de iteración inválido | Conflictos o huecos en el número de iteración | Verificar la iteración actual desde el estado del proyecto |

## Referencias

- Plantilla de Plan de Iteración: `docs-eng-process/templates/iteration-plan.md`
- Rol de Jefe de Proyecto: `docs-eng-process/openup-knowledge-base/core/role/roles/project-manager-4.md`

## Ver También

- [openup-start-iteration](../../openup-workflow/start-iteration/SKILL.md) - Iniciar nueva iteración
- [openup-complete-task](../../openup-workflow/complete-task/SKILL.md) - Marcar tareas de iteración como completadas
- [openup-construction](../../openup-phases/construction/SKILL.md) - Planificación de iteraciones de Construcción

# Crear Pull Request

Crea una PR con una descripción estructurada vinculada al contexto de la tarea en la hoja de ruta.

## Proceso

### 1. Detectar Estado Actual

1. Usar `$ARGUMENTS[branch]` o `git rev-parse --abbrev-ref HEAD`.
2. Comprobar commits sin fusionar: `git log <tronco>..HEAD --oneline`. Salir si no hay ninguno.
3. Detectar plataforma: `command -v gh` (GitHub) o `command -v glab` (GitLab).
4. Verificar remoto: `git remote get-url origin`.

### 2. Preparar Commits

1. **Protección de tronco**: Si estás en el tronco (main/master/detectado), crear y cambiar a una rama de funcionalidad (`git checkout -b feature/...` o `fix/...`).
2. **Comprobar cambios sin confirmar**: `git status --porcelain`. Si está limpio, saltar al paso 3.
3. **Organizar commits atómicos**: Agrupar cambios en unidades lógicas. Confirmar en orden de dependencia (deps/config → tipos/interfaces → lógica central → funcionalidades dependientes). Seguir el formato de `docs-eng-process/conventions.md`.
4. **Aplicar estrategia de tests**: Empaquetar tests con los commits de funcionalidad. Para correcciones de errores, confirmar primero el test que falla, luego la corrección.
5. **Lint antes de confirmar**: Ejecutar linter/formateador antes de cada commit. Omitir si no hay ninguno configurado.
6. Reglas completas: `commit-procedure.md` en `complete-task/`.

### 3. Extraer Contexto de la Tarea

1. Obtener task_id de `$ARGUMENTS[task_id]` o extraer del nombre de la rama (regex `([Tt]-?\d+)`).
2. Leer `docs/roadmap.md`, buscar la sección de la tarea, extraer descripción/prioridad/estado.
3. Generar título: `[<task_id>] <descripción>` o usar `$ARGUMENTS[title]`.

### 4. Detectar Rama Tronco

Usar `$ARGUMENTS[base]` si se proporciona; de lo contrario, seguir la detección de tronco en `docs-eng-process/agent-workflow.md` (Procedimiento de Ramas). Registrar el tronco detectado en el log de ejecución.

### 5. Generar Descripción de la PR

Usar la plantilla de `docs-eng-process/templates/pr-description.md` y completar:
- Resumen, Contexto de Tarea (id, descripción, prioridad), Cambios Realizados (git diff/log)
- Pruebas Realizadas, Lista de Verificación de Revisión, Incidencias Relacionadas, Cambios Incompatibles, Notas

### 6. Subir Rama y Crear PR

```bash
git push -u origin <rama>
# GitHub:
gh pr create --base <base> --title "<título>" --body "<descripción>" --label "tarea:<task_id>"
# GitLab:
glab mr create --base <base> --title "<título>" --description "<descripción>" --label "tarea:<task_id>"
```

### 7. Actualizar Documentación (Opcional)

- `docs/roadmap.md`: Añadir URL de la PR a la entrada de la tarea
- `docs/project-status.md`: Anotar la PR en Elementos de Trabajo Activos

## Errores Comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Sin commits pendientes | La rama está al día con el tronco | Informar al usuario de que no se necesita PR |
| Remoto no configurado | El remoto de Git no está configurado | `git remote add origin <url>` |
| CLI no instalado | gh/glab no disponible | `brew install gh` o `brew install glab` |
| task_id no encontrado | El nombre de la rama no tiene ID de tarea | Continuar sin contexto de tarea o proporcionar manualmente |
| Hoja de ruta no encontrada | docs/roadmap.md no existe | Continuar sin contexto de tarea, informar al usuario |
| PR ya existe | La rama ya tiene una PR abierta | Informar al usuario de la URL de la PR existente |
| En rama tronco | Trabajando directamente en main/master | Crear automáticamente una rama de funcionalidad antes de confirmar |

## Referencias

- Procedimiento de Ramas: `docs-eng-process/agent-workflow.md`
- Plantilla de Descripción de PR: `docs-eng-process/templates/pr-description.md`
- Hoja de Ruta: `docs/roadmap.md`

## Ver También

- [openup-complete-task](../complete-task/SKILL.md) - Completar tarea y crear PR
- [openup-start-iteration](../start-iteration/SKILL.md) - Iniciar iteración con creación de rama

# Crear solicitud de extracción

Crea una PR con una estructura descrita vinculada al contexto de la tarea en la hoja de ruta.

##Proceso

### 1. Detectar Estado Actual

1. Usar `$ARGUMENTS[branch]` o `git rev-parse --abbrev-ref HEAD`.
2. Comprobar confirma sin fusionar: `git log <tronco>..HEAD --oneline`. Salir si no hay ninguno.
3. Detectar plataforma: `command -v gh` (GitHub) o `command -v glab` (GitLab).
4. Verificar remoto: `git remoto get-url origin`.

### 2. Preparar compromisos

1. **Protección de tronco**: Si estás en el tronco (main/master/detectado), crea y cambia a una rama de funcionalidad (`git checkout -b feature/...` o `fix/...`).
2. **Comprobar cambios sin confirmar**: `git status --porcelain`. Si está limpio, salte al paso 3.
3. **Organizar commits atómicos**: Agrupar cambios en unidades lógicas. Confirmar en orden de dependencia (deps/config → tipos/interfaces → lógica central → funcionalidades dependientes). Siga el formato de `docs-eng-process/conventions.md`.
4. **Aplicar estrategia de pruebas**: Empaquetar pruebas con los commits de funcionalidad. Para correcciones de errores, confirme primero la prueba que falló, luego la corrección.
5. **Lint antes de confirmar**: Ejecutar linter/formateador antes de cada commit. Omitir si no hay ninguno configurado.
6. Reglas completas: `commit-procedure.md` en `complete-task/`.

### 3. Extraer Contexto de la Tarea

1. Obtener task_id de `$ARGUMENTS[task_id]` o extraer el nombre de la rama (regex `([Tt]-?\d+)`).
2. Leer `docs/roadmap.md`, buscar la sección de la tarea, extraer descripción/prioridad/estado.
3. Generar título: `[<task_id>] <descripción>` o usar `$ARGUMENTS[title]`.

### 4. Detectar Rama Tronco

Usar `$ARGUMENTS[base]` si se proporciona; de lo contrario, seguir la detección de tronco en `docs-eng-process/agent-workflow.md` (Procedimiento de Ramas). Registrar el tronco detectado en el registro de ejecución.

### 5. Generar Descripción de la PR

Usar la plantilla de `docs-eng-process/templates/pr-description.md` y completar:
- Resumen, Contexto de Tarea (id, descripción, prioridad), Cambios Realizados (git diff/log)
- Pruebas Realizadas, Lista de Verificación de Revisión, Incidencias Relacionadas, Cambios Incompatibles, Notas

### 6. Subir Rama y Crear PR

```bash
git push -u origin <rama>
# GitHub:
gh pr create --base <base> --title "<título>" --body "<descripción>" --label "tarea:<task_id>"
# GitLab:
glab mr create --base <base> --title "<título>" --description "<descripción>" --label "tarea:<task_id>"
```

### 7. Actualizar Documentación (Opcional)

- `docs/roadmap.md`: Añadir URL del PR a la entrada de la tarea
- `docs/project-status.md`: Anotar la PR en Elementos de Trabajo Activos

## Errores Comunes

| Error | causa | Solución |
|-------|-------|----------|
| Sin comete pendientes | La rama está al día con el tronco | Informar al usuario de que no se necesita PR |
| Remoto no configurado | El control remoto de Git no está configurado | `git remoto agregar origen <url>` |
| CLI no instalado | gh/glab no disponible | `brew install gh` o `brew install glab` |
| task_id no encontrado | El nombre de la rama no tiene ID de tarea | Continuar sin contexto de tarea o proporcionar manualmente |
| Hoja de ruta no encontrada | docs/roadmap.md no existe | Continuar sin contexto de tarea, informar al usuario |
| PR ya existe | La rama ya tiene una PR abierta | Informar al usuario de la URL de la PR existente |
| En rama tronco | Trabajando directamente en main/master | Crear automáticamente una rama de funcionalidad antes de confirmar |

## Referencias

- Procedimiento de Ramas: `docs-eng-process/agent-workflow.md`
- Plantilla de Descripción de PR: `docs-eng-process/templates/pr-description.md`
- Hoja de Ruta: `docs/roadmap.md`

## Ver También

- [openup-complete-task](../complete-task/SKILL.md) - Completar tarea y crear PR
- [openup-start-iteration](../start-iteration/SKILL.md) - Iniciar iteración con creación de rama

# Crear Lista de Riesgos

Esta skill crea o actualiza un documento de lista de riesgos a partir de la plantilla OpenUP.

## Cuándo Usar

Usa esta skill cuando:
- Comiences un nuevo proyecto y necesites identificar riesgos
- Estés en la fase de Inicio documentando riesgos principales
- Surjan nuevos riesgos durante el proyecto
- Necesites actualizar la probabilidad o impacto de un riesgo
- Planifiques estrategias de mitigación de riesgos

## Cuándo NO Usar

NO uses esta skill cuando:
- La lista de riesgos existe y solo necesita cambios menores (edítala directamente)
- Busques seguimiento de incidencias (usa el gestor de incidencias)
- Los riesgos se hayan materializado y sean ahora incidencias (gestiónalos como incidencias)
- Necesites un análisis de riesgos detallado (usa el proceso de gestión de riesgos)

## Criterios de Éxito

Tras usar esta skill, verifica:
- [ ] La lista de riesgos existe en `docs/risk-list.md`
- [ ] Los riesgos están documentados con descripciones
- [ ] La probabilidad e impacto están evaluados
- [ ] Las estrategias de mitigación están definidas
- [ ] Los responsables de cada riesgo están asignados

## Proceso

### 1. Comprobar Lista de Riesgos Existente

Comprobar si `docs/risk-list.md` existe:
- Si existe, actualizarla
- Si no existe, crear desde la plantilla

### 2. Copiar Plantilla (si es nueva)

Si se crea nueva, copiar `docs-eng-process/templates/risk-list.md` a `docs/risk-list.md`

### 3. Leer Contexto del Proyecto

Leer `docs/project-status.md` y `docs/vision.md` para identificar riesgos potenciales.

### 4. Completar la Lista de Riesgos

Actualizar con:
- **Nombre del proyecto** y contexto
- **Riesgos**: De `$ARGUMENTS[risks]` o identificados del contexto del proyecto
  Para cada riesgo, documentar:
  - Descripción del riesgo
  - Probabilidad (alta/media/baja)
  - Impacto (alto/medio/bajo)
  - Estrategia de mitigación
  - Responsable

### 5. Validar Completitud

Asegurar que la lista de riesgos incluya:
- Descripciones claras de riesgos
- Evaluaciones de probabilidad e impacto
- Estrategias de mitigación
- Responsables de cada riesgo

## Salida

Devuelve:
- Ruta a la lista de riesgos
- Número de riesgos documentados
- Resumen de riesgos de alta prioridad

## Errores Comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que `docs-eng-process/templates/risk-list.md` existe |
| Sin riesgos identificados | Contexto del proyecto insuficiente | Revisar la visión y los requisitos en busca de riesgos potenciales |
| Mitigación ausente | Riesgos documentados sin mitigación | Añadir estrategia de mitigación para cada riesgo |

## Referencias

- Plantilla de Lista de Riesgos: `docs-eng-process/templates/risk-list.md`
- Gestión de Riesgos: `docs-eng-process/openup-knowledge-base/practice-management/risk_val_lifecycle/`
- Rol de Jefe de Proyecto: `docs-eng-process/openup-knowledge-base/core/role/roles/project-manager-4.md`

## Ver También

- [openup-inception](../../openup-phases/inception/SKILL.md) - Identificación de riesgos en la fase de Inicio
- [openup-create-vision](../create-vision/SKILL.md) - La visión revela riesgos potenciales
- [openup-create-architecture-notebook](../create-architecture-notebook/SKILL.md) - Evaluación de riesgos técnicos

# Crear Lista de Riesgos

Esta habilidad crea o actualiza un documento de lista de riesgos a partir de la plantilla OpenUP.

## Cuándo usar

Usa esta habilidad cuando:
- Comienza un nuevo proyecto y necesitas identificar riesgos.
- Estés en la fase de Inicio documentando riesgos principales
- Surjan nuevos riesgos durante el proyecto
- Necesites actualizar la probabilidad o impacto de un riesgo
- Planifique estrategias de mitigación de riesgos.

## Cuándo NO Usar

NO usa esta habilidad cuando:
- La lista de riesgos existe y solo necesita cambios menores (edítala directamente)
- Busques seguimiento de incidencias (usa el gestor de incidencias)
- Los riesgos se hayan materializado y sean ahora incidencias (gestiónalos como incidencias)
- Necesites un análisis de riesgos detallado (usa el proceso de gestión de riesgos)

## Criterios de Éxito

Tras usar esta habilidad, verifica:
- [ ] La lista de riesgos existe en `docs/risk-list.md`
- [ ] Los riesgos están documentados con descripciones
- [ ] La probabilidad e impacto están evaluadas
- [ ] Las estrategias de mitigación están definidas
- [ ] Los responsables de cada riesgo están asignados

##Proceso

### 1. Comprobar Lista de Riesgos Existentes

Comprobar si existe `docs/risk-list.md`:
- Si existe, actualízala
- Si no existe, crear desde la plantilla

### 2. Copiar plantilla (si es nueva)

Si se crea nueva, copie `docs-eng-process/templates/risk-list.md` a `docs/risk-list.md`

### 3. Leer Contexto del Proyecto

Lea `docs/project-status.md` y `docs/vision.md` para identificar riesgos potenciales.

### 4. Completar la Lista de Riesgos

Actualizar con:
- **Nombre del proyecto** y contexto
- **Riesgos**: De `$ARGUMENTS[riesgos]` o identificados del contexto del proyecto
  Para cada riesgo, documental:
  - Descripción del riesgo
  - Probabilidad (alta/media/baja)
  - Impacto (alto/medio/bajo)
  - Estrategia de mitigación
  - Responsable

### 5. Validar Completitud

Asegurar que la lista de riesgos incluya:
- Descripciones claras de riesgos
- Evaluaciones de probabilidad e impacto.
- Estrategias de mitigación
- Responsables de cada riesgo

##Salida

Devuelve:
- Ruta a la lista de riesgos
- Número de riesgos documentados
- Resumen de riesgos de alta prioridad

## Errores Comunes

| Error | causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que existe `docs-eng-process/templates/risk-list.md` |
| Sin riesgos identificados | Contexto del proyecto insuficiente | Revisar la visión y los requisitos en busca de riesgos potenciales |
| Mitigación ausente | Riesgos documentados sin mitigación | Añadir estrategia de mitigación para cada riesgo |

## Referencias

- Plantilla de Lista de Riesgos: `docs-eng-process/templates/risk-list.md`
- Gestión de Riesgos: `docs-eng-process/openup-knowledge-base/practice-management/risk_val_lifecycle/`
- Rol de Jefe de Proyecto: `docs-eng-process/openup-knowledge-base/core/role/roles/project-manager-4.md`

## Ver También

- [openup-inception](../../openup-phases/inception/SKILL.md) - Identificación de riesgos en la fase de Inicio
- [openup-create-vision](../create-vision/SKILL.md) - La visión revela riesgos potenciales
- [openup-create-architecture-notebook](../create-architecture-notebook/SKILL.md) - Evaluación de riesgos técnicos

# Crear Plan de Pruebas

Esta skill genera casos de prueba y documentación de testing a partir de las plantillas OpenUP.

## Cuándo Usar

Usa esta skill cuando:
- Necesites crear casos de prueba para funcionalidades o casos de uso
- Estés en la fase de Elaboración o Construcción planificando pruebas
- Comiences las pruebas de una nueva funcionalidad
- Necesites documentar procedimientos de prueba
- Crees scripts de prueba para automatización

## Cuándo NO Usar

NO uses esta skill cuando:
- Quieras ejecutar pruebas (usa el ejecutor de tests)
- Necesites depurar fallos en tests (usa herramientas de depuración)
- El plan de pruebas existe y solo necesita cambios menores (edítalo directamente)
- Busques informes de pruebas (usa los reportes de testing)

## Criterios de Éxito

Tras usar esta skill, verifica:
- [ ] Los casos de prueba existen en `docs/test-cases/`
- [ ] Los scripts de prueba existen en `docs/test-scripts/`
- [ ] La cobertura incluye camino feliz y casos límite
- [ ] Los resultados esperados están definidos
- [ ] Los procedimientos de prueba están documentados

## Proceso

### 1. Leer Requisitos

Leer la documentación relevante:
- `docs/use-cases/*.md` para casos de uso
- `docs/requirements/*.md` para requisitos
- Cualquier documento de diseño para el `$ARGUMENTS[scope]`

### 2. Crear Directorio de Pruebas

Asegurar que los directorios `docs/test-cases/` y `docs/test-scripts/` existen.

### 3. Copiar Plantillas

Copiar las plantillas según sea necesario:
- `docs-eng-process/templates/test-case.md` → `docs/test-cases/<nombre>-test-case.md`
- `docs-eng-process/templates/test-script.md` → `docs/test-scripts/<nombre>-test-script.md`

### 4. Completar los Casos de Prueba

Para cada caso de prueba, documentar:
- **ID del caso de prueba** y nombre
- **Descripción**: Qué se está probando
- **Precondiciones**: Estado antes de la prueba
- **Pasos de prueba**: Acciones paso a paso
- **Resultados esperados**: Qué debería ocurrir
- **Postcondiciones**: Estado después de la prueba
- **Prioridad**: Nivel de prioridad del test

### 5. Completar los Scripts de Prueba

Para cada script de prueba, documentar:
- **ID del script de prueba** y nombre
- **Propósito**: Qué valida el script
- **Configuración**: Cómo preparar la prueba
- **Procedimientos de prueba**: Pasos detallados de ejecución
- **Limpieza**: Cómo limpiar después de la prueba

### 6. Validar Cobertura

Asegurar que la cobertura de pruebas incluya:
- Escenarios de camino feliz
- Casos límite
- Condiciones de error
- Puntos de integración

## Salida

Devuelve:
- Rutas a los casos de prueba y scripts creados
- Resumen de cobertura de pruebas
- Huecos identificados

## Errores Comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que `docs-eng-process/templates/test-case.md` y `test-script.md` existen |
| Cobertura insuficiente | Solo tests de camino feliz | Añadir casos límite y condiciones de error |
| Resultados esperados ausentes | Pasos de prueba sin validación | Definir resultados esperados para cada paso |

## Referencias

- Plantilla de Caso de Prueba: `docs-eng-process/templates/test-case.md`
- Plantilla de Script de Prueba: `docs-eng-process/templates/test-script.md`
- Rol de Probador: `docs-eng-process/openup-knowledge-base/core/role/roles/tester-5.md`

## Ver También

- [openup-create-use-case](../create-use-case/SKILL.md) - Generar pruebas desde casos de uso
- [openup-construction](../../openup-phases/construction/SKILL.md) - Pruebas en la fase de Construcción
- [openup-phase-review](../../openup-workflow/phase-review/SKILL.md) - Revisar cobertura de pruebas

# Crear Plan de Pruebas

Esta habilidad genera casos de prueba y documentación de prueba a partir de las plantillas OpenUP.

## Cuándo usar

Usa esta habilidad cuando:
- Necesites crear casos de prueba para funcionalidades o casos de uso.
- Estés en la fase de Elaboración o Construcción planificando pruebas
- Comienza las pruebas de una nueva funcionalidad.
- Necesidades documentales procedimientos de prueba
- Crees scripts de prueba para automatización.

## Cuándo NO Usar

NO usa esta habilidad cuando:
- Quiere ejecutar pruebas (usa el ejecutor de pruebas)
- Necesites depurar fallos en pruebas (usa herramientas de depuración)
- El plan de pruebas existe y solo necesita cambios menores (edítalo directamente)
- Busques informes de pruebas (usa los informes de pruebas)

## Criterios de Éxito

Tras usar esta habilidad, verifica:
- [ ] Los casos de prueba existen en `docs/test-cases/`
- [ ] Los scripts de prueba existen en `docs/test-scripts/`
- [ ] La cobertura incluye camino feliz y límite de casos
- [ ] Los resultados esperados están definidos
- [ ] Los procedimientos de prueba están documentados

##Proceso

### 1. Leer requisitos

Leer la documentación relevante:
- `docs/use-cases/*.md` para casos de uso
- `docs/requirements/*.md` para requisitos
- Cualquier documento de diseño para el `$ARGUMENTS[scope]`

### 2. Crear Directorio de Pruebas

Asegúrese de que los directorios `docs/test-cases/` y `docs/test-scripts/` existan.

### 3. Copiar plantillas

Copiar las plantillas según sea necesario:
- `docs-eng-process/templates/test-case.md` → `docs/test-cases/<nombre>-test-case.md`
- `docs-eng-process/templates/test-script.md` → `docs/test-scripts/<nombre>-test-script.md`

### 4. Completar los Casos de Prueba

Para cada caso de prueba, documental:
- **ID del caso de prueba** y nombre
- **Descripción**: Qué se está probando
- **Precondiciones**: Estado antes de la prueba
- **Pasos de prueba**: Acciones paso a paso
- **Resultados esperados**: Qué debería ocurrir
- **Postcondiciones**: Estado después de la prueba
- **Prioridad**: Nivel de prioridad del test

### 5. Completar los scripts de prueba

Para cada guión de prueba, documental:
- **ID del script de prueba** y nombre
- **Propósito**: Qué valida el guión
- **Configuración**: Cómo preparar la prueba
- **Procedimientos de prueba**: Pasos detallados de ejecución
- **Limpieza**: Cómo limpiar después de la prueba

### 6. Validar Cobertura

Asegurar que la cobertura de pruebas incluya:
- Escenarios de camino feliz
- Casos límite
- Condiciones de error
- Puntos de integración

##Salida

Devuelve:
- Rutas a los casos de prueba y scripts creados.
- Resumen de cobertura de pruebas.
- Huecos identificados

## Errores Comunes

| Error | causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que `docs-eng-process/templates/test-case.md` y `test-script.md` existen |
| Cobertura insuficiente | Pruebas en solitario de camino feliz | Añadir casos límite y condiciones de error |
| Resultados esperados ausentes | Pasos de prueba sin validación | Definir resultados esperados para cada paso |

## Referencias

- Plantilla de Caso de Prueba: `docs-eng-process/templates/test-case.md`
- Plantilla de Script de Prueba: `docs-eng-process/templates/test-script.md`
- Rol de Probador: `docs-eng-process/openup-knowledge-base/core/role/roles/tester-5.md`

## Ver También

- [openup-create-use-case](../create-use-case/SKILL.md) - Generar pruebas desde casos de uso
- [openup-construction](../../openup-phases/construction/SKILL.md) - Pruebas en la fase de Construcción
- [openup-phase-review](../../openup-workflow/phase-review/SKILL.md) - Revisar cobertura de pruebas

# Crear Caso de Uso

Esta skill crea una especificación de caso de uso a partir de la plantilla OpenUP.

## Cuándo Usar

Usa esta skill cuando:
- Necesites documentar interacciones del usuario con el sistema
- Estés en la fase de Inicio o Elaboración definiendo requisitos
- Captures requisitos funcionales desde la perspectiva del usuario
- Necesites especificar precondiciones, flujos y postcondiciones
- Crees escenarios de prueba a partir de requisitos

## Cuándo NO Usar

NO uses esta skill cuando:
- Necesites requisitos no funcionales (usa el cuaderno de arquitectura)
- Busques especificaciones técnicas (usa documentos de diseño)
- Documentes comportamiento interno del sistema (usa diseño técnico)
- El caso de uso ya existe (actualiza el archivo existente)

## Criterios de Éxito

Tras usar esta skill, verifica:
- [ ] El archivo de caso de uso existe en `docs/use-cases/`
- [ ] El nombre del caso de uso y el actor principal están definidos
- [ ] El flujo básico está documentado
- [ ] Los flujos alternativos están identificados
- [ ] Las pre/postcondiciones están especificadas

## Proceso

### 1. Crear Directorio de Casos de Uso

Asegurar que el directorio `docs/use-cases/` existe.

### 2. Generar Nombre de Archivo

Crear el nombre de archivo a partir del nombre del caso de uso: `docs/use-cases/<nombre-caso-uso>.md`

### 3. Copiar Plantilla

Copiar `docs-eng-process/templates/use-case-specification.md` al nuevo archivo.

### 4. Completar el Caso de Uso

Actualizar la especificación del caso de uso con:
- **Nombre del caso de uso**: `$ARGUMENTS[use_case_name]`
- **Actor principal**: `$ARGUMENTS[primary_actor]`
- **Descripción**: `$ARGUMENTS[description]`
- **Precondiciones**: Qué debe ser cierto antes de comenzar
- **Flujo básico**: Interacción principal paso a paso
- **Flujos alternativos**: Caminos alternativos y casos límite
- **Postcondiciones**: Qué es cierto tras la finalización

### 5. Validar Completitud

Asegurar que el caso de uso incluya:
- Nombre y descripción claros
- Actores identificados
- Flujo básico de eventos
- Flujos alternativos clave
- Pre/postcondiciones

## Salida

Devuelve:
- Ruta al archivo de caso de uso creado
- ID del caso de uso (para seguimiento)
- Secciones completadas

## Errores Comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que `docs-eng-process/templates/use-case-specification.md` existe |
| Nombre de archivo inválido | El nombre del caso de uso tiene caracteres no válidos | Sanear el nombre de archivo, reemplazar espacios con guiones |
| Actores ausentes | Actores no identificados | Identificar actores primarios y secundarios desde la visión/requisitos |

## Referencias

- Plantilla de Caso de Uso: `docs-eng-process/templates/use-case-specification.md`
- Producto de Trabajo de Caso de Uso: `docs-eng-process/openup-knowledge-base/core/common/workproducts/use_case.md`

## Ver También

- [openup-create-vision](../create-vision/SKILL.md) - Definir primero la visión del proyecto
- [openup-detail-use-case](../detail-use-case/SKILL.md) - Transformar caso de uso de alto nivel en escenarios detallados
- [openup-create-test-plan](../create-test-plan/SKILL.md) - Generar pruebas desde los casos de uso
- [openup-elaboration](../../openup-phases/elaboration/SKILL.md) - Detalle de casos de uso en la fase de Elaboración

# Crear Caso de Uso

Esta habilidad crea una especificación de caso de uso a partir de la plantilla OpenUP.

## Cuándo usar

Usa esta habilidad cuando:
- Necesites documentar interacciones del usuario con el sistema
- Estés en la fase de Inicio o Elaboración definiendo requisitos
- Captura requisitos funcionales desde la perspectiva del usuario
- Necesites especifican precondiciones, flujos y postcondiciones
- Crees escenarios de prueba a partir de requisitos.

## Cuándo NO Usar

NO usa esta habilidad cuando:
- Necesites requisitos no funcionales (usa el cuaderno de arquitectura)
- Busques especificaciones técnicas (usa documentos de diseño)
- Documentes comportamiento interno del sistema (usa diseño técnico)
- El caso de uso ya existe (actualiza el archivo existente)

## Criterios de Éxito

Tras usar esta habilidad, verifica:
- [ ] El archivo de caso de uso existe en `docs/use-cases/`
- [ ] El nombre del caso de uso y el actor principal están definidos
- [ ] El flujo básico está documentado
- [ ] Los flujos alternativos están identificados
- [ ] Las pre/postcondiciones están especificadas

##Proceso

### 1. Crear Directorio de Casos de Uso

Asegúrese de que el directorio `docs/use-cases/` exista.

### 2. Generar Nombre de Archivo

Crear el nombre de archivo a partir del nombre del caso de uso: `docs/use-cases/<nombre-caso-uso>.md`

### 3. Copiar plantilla

Copiar `docs-eng-process/templates/use-case-specification.md` al nuevo archivo.

### 4. Completar el Caso de Uso

Actualizar la especificación del caso de uso con:
- **Nombre del caso de uso**: `$ARGUMENTS[use_case_name]`
- **Actor principal**: `$ARGUMENTS[actor_primario]`
- **Descripción**: `$ARGUMENTS[descripción]`
- **Precondiciones**: Qué debe ser cierto antes de comenzar
- **Flujo básico**: Interacción principal paso a paso
- **Flujos alternativos**: Caminos alternativos y casos límite
- **Postcondiciones**: Qué es cierto tras la finalización

### 5. Validar Completitud

Asegurar que el caso de uso incluye:
- Nombre y descripción claros
- Actores identificados
- Flujo básico de eventos
- Flujos de clave alternativa
- Pre/postcondiciones

##Salida

Devuelve:
- Ruta al archivo de caso de uso creado
- ID del caso de uso (para seguimiento)
- Secciones completadas

## Errores Comunes

| Error | causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que existe `docs-eng-process/templates/use-case-specification.md` |
| Nombre de archivo inválido | El nombre del caso de uso tiene caracteres no válidos | Sanear el nombre de archivo, reemplazar espacios con guiones |
| Actores ausentes | Actores no identificados | Identificar actores primarios y secundarios desde la visión/requisitos |

## Referencias

- Plantilla de Caso de Uso: `docs-eng-process/templates/use-case-specification.md`
- Producto de Trabajo de Caso de Uso: `docs-eng-process/openup-knowledge-base/core/common/workproducts/use_case.md`

## Ver También

- [openup-create-vision](../create-vision/SKILL.md) - Definir primero la visión del proyecto
- [openup-detail-use-case](../detail-use-case/SKILL.md) - Transformar caso de uso de alto nivel en escenarios detallados
- [openup-create-test-plan](../create-test-plan/SKILL.md) - Generar pruebas desde los casos de uso
- [openup-elaboration](../../openup-phases/elaboration/SKILL.md) - Detalle de casos de uso en la fase de Elaboración

# Crear Documento de Visión

Esta skill genera un documento de visión a partir de la plantilla OpenUP.

## Cuándo Usar

Usa esta skill cuando:
- Comiences un nuevo proyecto y necesites definir la visión
- Estés en la fase de Inicio y necesites documentar el alcance del proyecto
- Los interesados necesiten una comprensión clara de los objetivos del proyecto
- Necesites definir el planteamiento del problema y la solución propuesta
- Crees los artefactos iniciales del proyecto

## Cuándo NO Usar

NO uses esta skill cuando:
- El documento de visión ya existe (actualízalo directamente o usa un proceso de revisión)
- Necesites requisitos detallados (usa las skills de casos de uso en su lugar)
- Busques arquitectura técnica (usa `/openup-create-architecture-notebook`)
- Estés en fases posteriores (Elaboración+) cuando la visión debería estar estable

## Criterios de Éxito

Tras usar esta skill, verifica:
- [ ] El documento de visión existe en `docs/vision.md`
- [ ] El nombre del proyecto y el planteamiento del problema están completados
- [ ] Los interesados están identificados
- [ ] Las funcionalidades clave están listadas
- [ ] Los criterios de éxito están definidos

## Proceso

### 1. Leer Contexto del Proyecto

Leer `docs/project-status.md` para comprender:
- Fase actual
- Interesados
- Contexto del proyecto

### 2. Copiar Plantilla

Copiar `docs-eng-process/templates/vision.md` a `docs/vision.md`

### 3. Completar el Documento de Visión

Actualizar el documento de visión con:
- **Nombre del proyecto**: `$ARGUMENTS[project_name]`
- **Planteamiento del problema**: `$ARGUMENTS[problem_statement]`
- **Posicionamiento**: Qué hace única a esta solución
- **Interesados**: Interesados clave y sus necesidades
- **Funcionalidades clave**: Lista de funcionalidades a alto nivel
- **Restricciones**: Técnicas, de negocio u otras restricciones

### 4. Validar Completitud

Asegurar que el documento de visión incluya:
- Planteamiento del problema claro
- Visión general de la solución propuesta
- Descripciones de los interesados
- Funcionalidades y beneficios clave
- Criterios de éxito

## Salida

Devuelve:
- Ruta al documento de visión creado
- Lista de secciones completadas
- Secciones que requieren completarse manualmente

## Errores Comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que `docs-eng-process/templates/vision.md` existe |
| El archivo ya existe | El documento de visión ya fue creado | Actualizar el archivo existente o confirmar sobrescritura |
| Argumentos ausentes | Argumentos requeridos no proporcionados | Proporcionar project_name y problem_statement |

## Referencias

- Plantilla de Visión: `docs-eng-process/templates/vision.md`
- Producto de Trabajo de Visión: `docs-eng-process/openup-knowledge-base/core/common/workproducts/vision.md`
- Rol de Analista: `docs-eng-process/openup-knowledge-base/core/role/roles/analyst-6.md`

## Ver También

- [openup-inception](../../openup-phases/inception/SKILL.md) - Guía de la fase de Inicio
- [openup-create-use-case](../create-use-case/SKILL.md) - Crear casos de uso detallados
- [openup-create-risk-list](../create-risk-list/SKILL.md) - Documentar riesgos del proyecto

# Crear Documento de Visión

Esta habilidad genera un documento de visión a partir de la plantilla OpenUP.

## Cuándo usar

Usa esta habilidad cuando:
- Comienza un nuevo proyecto y necesitas definir la visión.
- Estés en la fase de Inicio y necesitas documentar el alcance del proyecto
- Los interesados necesitan una comprensión clara de los objetivos del proyecto.
- Necesites definir el planteamiento del problema y la solución propuesta.
- Crees los artefactos iniciales del proyecto.

## Cuándo NO Usar

NO usa esta habilidad cuando:
- El documento de visión ya existe (actualízalo directamente o usa un proceso de revisión)
- Necesites requisitos detallados (usa las skills de casos de uso en su lugar)
- Busques arquitectura técnica (usa `/openup-create-architecture-notebook`)
- Estés en fases posteriores (Elaboración+) cuando la visión debería estar estable

## Criterios de Éxito

Tras usar esta habilidad, verifica:
- [ ] El documento de visión existe en `docs/vision.md`
- [ ] El nombre del proyecto y el planteamiento del problema están completados
- [ ] Los interesados están identificados
- [ ] Las funcionalidades clave están listadas
- [ ] Los criterios de éxito están definidos

##Proceso

### 1. Leer Contexto del Proyecto

Leer `docs/project-status.md` para comprender:
- Fase real
- Interesados
- Contexto del proyecto

### 2. Copiar plantilla

Copiar `docs-eng-process/templates/vision.md` a `docs/vision.md`

### 3. Completar el Documento de Visión

Actualizar el documento de visión con:
- **Nombre del proyecto**: `$ARGUMENTS[nombre_proyecto]`
- **Plantamiento del problema**: `$ARGUMENTS[problem_statement]`
- **Posicionamiento**: Qué hace única a esta solución
- **Interesados**: Interesados clave y sus necesidades
- **Funcionalidades clave**: Lista de funcionalidades a alto nivel
- **Restricciones**: Técnicas, de negocio u otras restricciones

### 4. Validar Completitud

Asegurar que el documento visión de incluir:
- Planteamiento del problema claro
- Visión general de la solución propuesta.
- Descripciones de los interesados
- Clave de funcionalidades y beneficios.
- Criterios de éxito

##Salida

Devuelve:
- Ruta al documento de visión creado.
- Lista de secciones completadas
- Secciones que requieren completarse manualmente

## Errores Comunes

| Error | causa | Solución |
|-------|-------|----------|
| Plantilla no encontrada | Ruta de plantilla incorrecta | Verificar que existe `docs-eng-process/templates/vision.md` |
| El archivo ya existe | El documento de visión ya fue creado | Actualizar el archivo existente o confirmar sobreescritura |
| Argumentos ausentes | Argumentos requeridos no proporcionados | Proporcionar nombre_proyecto y declaración_problema |

## Referencias

- Plantilla de Visión: `docs-eng-process/templates/vision.md`
- Producto de Trabajo de Visión: `docs-eng-process/openup-knowledge-base/core/common/workproducts/vision.md`
- Rol de Analista: `docs-eng-process/openup-knowledge-base/core/role/roles/analyst-6.md`

## Ver También

- [openup-inception](../../openup-phases/inception/SKILL.md) - Guía de la fase de Inicio
- [openup-create-use-case](../create-use-case/SKILL.md) - Crear casos de uso detallados
- [openup-create-risk-list](../create-risk-list/SKILL.md) - Documentar riesgos del proyecto

# Deploy Team

This skill deploys an OpenUP agent team to work on the current iteration. It reads the iteration context and creates the appropriate team with proper role assignments.

## When to Use

Use this skill **after** `/openup-start-iteration` has completed:
- Iteration is initialized
- Branch is created
- Project status is updated
- Roadmap has the task

Then use this skill to deploy the team.

## When NOT to Use

Do NOT use this skill:
- Before `/openup-start-iteration` has been called
- Without knowing the iteration goal
- For non-OpenUP work

## Process

### 1. Read Current Iteration Context

Read `docs/project-status.md` to get:
- Current phase
- Current iteration number
- Current iteration goal
- Current task (if set)

### 2. Determine Team Composition

Based on the iteration goal and team_type:
- **feature**: analyst, architect, developer, tester
- **investigation**: architect, developer, tester
- **construction**: developer, tester (+ architect, analyst as needed)
- **elaboration**: architect, developer, tester (+ analyst as needed)
- **inception**: analyst, project-manager (+ architect as needed)
- **transition**: tester, project-manager, developer (+ analyst as needed)
- **planning**: project-manager, analyst (+ architect, developer as needed)
- **full**: all roles

Or use custom roles from `$ARGUMENTS[roles]`

### 3. Create the Team

Spawn teammates using the Task tool with appropriate subagent types.

### 4. Brief the Team

Send initial message to all teammates with:
- Iteration goal
- Current phase
- Task context
- Expected workflow
- Coordination instructions

### 5. Set Up Coordination

Ensure the team lead knows to:
- Monitor progress
- Assign tasks to appropriate roles
- Use `/openup-complete-task` when work is done

## Output

Returns:
- Team composition
- Team member assignments
- Current iteration context
- Expected workflow

## Example Usage

```
/openup-deploy-team team_type: feature
```

Or with specific roles:
```
/openup-deploy-team roles: analyst,developer,tester
```

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| No iteration found | docs/project-status.md doesn't exist or no active iteration | Run /openup-start-iteration first |
| Unknown team type | team_type parameter not recognized | Use one of: feature, investigation, construction, elaboration, inception, transition, planning, full |
| Cannot spawn team | Agent teams not enabled | Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 |

## See Also

- [openup-start-iteration](../openup-start-iteration/SKILL.md) - Initialize iteration first
- [openup-complete-task](../openup-complete-task/SKILL.md) - Complete work when done
- [Team configurations](../../teams/) - Team definition files

# Implementar equipo

Esta habilidad implementa un equipo de agentes de OpenUP para trabajar en la iteración actual. Lee el contexto de la iteración y crea el equipo apropiado con las asignaciones de roles adecuadas.

## Cuándo utilizar

Utilice esta habilidad **después** de que `/openup-start-iteration` se haya completado:
- Se inicializa la iteración.
- Se crea la sucursal
- Se actualiza el estado del proyecto.
- La hoja de ruta tiene la tarea.

Luego usa esta habilidad para desplegar el equipo.

## Cuándo NO usarlo

NO uses esta habilidad:
- Antes de que se haya llamado a `/openup-start-iteration`
- Sin conocer el objetivo de la iteración.
- Para trabajos que no sean OpenUP

## Proceso

### 1. Leer el contexto de iteración actual

Lea `docs/project-status.md` para obtener:
- Fase actual
- Número de iteración actual
- Objetivo de iteración actual
- Tarea actual (si está configurada)

### 2. Determinar la composición del equipo

Según el objetivo de la iteración y el tipo_equipo:
- **característica**: analista, arquitecto, desarrollador, probador
- **investigación**: arquitecto, desarrollador, probador
- **construcción**: desarrollador, probador (+ arquitecto, analista según sea necesario)
- **elaboración**: arquitecto, desarrollador, tester (+ analista según sea necesario)
- **inception**: analista, director de proyecto (+ arquitecto según sea necesario)
- **transición**: tester, director de proyecto, desarrollador (+ analista según sea necesario)
- **planificación**: director de proyecto, analista (+ arquitecto, desarrollador según sea necesario)
- **completo**: todos los roles

O utilice roles personalizados de `$ARGUMENTS[roles]`

### 3. Crea el equipo

Genere compañeros de equipo utilizando la herramienta Tarea con los tipos de subagente adecuados.

### 4. Informar al equipo

Enviar mensaje inicial a todos los compañeros de equipo con:
- Objetivo de iteración
- Fase actual
- Contexto de la tarea
- Flujo de trabajo esperado
- Instrucciones de coordinación

### 5. Configurar la coordinación

Asegúrese de que el líder del equipo sepa:
- Monitorear el progreso
- Asignar tareas a los roles apropiados.
- Utilice `/openup-complete-task` cuando haya terminado el trabajo.

## Producción

Devoluciones:
- Composición del equipo
- Asignaciones de miembros del equipo.
- Contexto de iteración actual
- Flujo de trabajo esperado

## Ejemplo de uso

```
/openup-deploy-team team_type: feature
```

O con roles específicos:
```
/roles del equipo openup-deploy: analista,desarrollador,probador
```

## Errores comunes

| Error | Causa | Solución |
|-------|-------|----------|
| No se encontró ninguna iteración | docs/project-status.md no existe o no hay iteración activa | Ejecute /openup-start-iteration primero |
| Tipo de equipo desconocido | parámetro team_type no reconocido | Utilice uno de: característica, investigación, construcción, elaboración, inicio, transición, planificación, completo |
| No se puede generar equipo | Equipos de agentes no habilitados | Establecer CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 |

## Ver también

- [openup-start-iteration](../openup-start-iteration/SKILL.md) - Inicialice la iteración primero
- [openup-complete-task](../openup-complete-task/SKILL.md) - Completa el trabajo cuando termines
- [Configuraciones de equipo](../../teams/) - Archivos de definición de equipo

# Detail Use Case

This skill transforms a high-level use case specification into detailed scenarios with Gherkin acceptance criteria and test cases.

## When to Use

Use this skill when:
- A high-level use case exists but lacks detailed scenarios
- Need to document happy paths, alternative flows, and error cases
- Ready to create Gherkin acceptance criteria for automation
- Preparing to generate test cases from use cases
- In Elaboration phase when detailing requirements

## When NOT to Use

Do NOT use this skill when:
- The use case doesn't exist (use `/openup-create-use-case` first)
- The use case is already fully detailed with scenarios
- Just need to create a new use case from scratch
- Working on non-functional requirements (use architecture notebook)

## Success Criteria

After using this skill, verify:
- [ ] Use case is updated with detailed scenarios
- [ ] Happy path, alternative paths, and error paths are documented
- [ ] Gherkin acceptance criteria are written for each scenario
- [ ] Test cases are generated (if generate_tests=true)
- [ ] All actors are identified (primary and secondary)
- [ ] Preconditions and postconditions are clear

## Process Summary

1. Read existing use case
2. Identify scenarios (happy path, alternatives, errors)
3. Document each scenario with step-by-step flows
4. Generate Gherkin acceptance criteria
5. Create test cases (if requested)
6. Update the use case file

## Detailed Steps

### 1. Read Existing Use Case

Read the use case file from `docs/use-cases/$ARGUMENTS[use_case_name].md`:
- Extract use case name, ID, and description
- Identify the primary actor
- Review existing basic flow
- Note any alternative flows already documented

### 2. Identify Scenarios

Break down the use case into distinct scenarios:

**Happy Path (Primary Scenario):**
- The main success scenario where everything goes as expected
- User follows the most common workflow

**Alternative Paths:**
- Different ways to accomplish the same goal
- Optional steps or branching logic
- User choices and variations

**Error Paths:**
- Invalid inputs or actions
- System failures
- Edge cases and boundary conditions

### 3. Document Scenarios

For each scenario, document:

| Element | Description |
|---------|-------------|
| Scenario Name | Clear, descriptive name |
| Description | What makes this scenario unique |
| Steps | Step-by-step interaction (Actor → System) |
| Preconditions | What must be true before this scenario |
| Postconditions | What is true after this scenario |

### 4. Generate Gherkin Acceptance Criteria

For each scenario, write Gherkin format criteria:

```gherkin
Given <precondition>
And <additional preconditions>
When <actor takes action>
And <additional actions>
Then <expected outcome>
And <additional outcomes>
```

**Example:**

```gherkin
Given the user is logged in
And the user has items in their cart
When the user clicks "Checkout"
Then the user is redirected to the payment page
And the order total is displayed
```

### 5. Create Test Cases (Optional)

If `$ARGUMENTS[generate_tests] == "true"`:

Create test case files for each scenario in `docs/test-cases/`:
- Filename format: `<use-case-name>-<scenario>-test.md`
- Use the test case template as a guide
- Include scenario steps, test data, and expected results

### 6. Update the Use Case File

Update the existing use case file with:
- Add detailed scenarios section
- Include Gherkin acceptance criteria
- Link to test case files
- Ensure all actors are documented
- Verify pre/postconditions are complete

## Output

Returns a summary of:
- Use case file updated
- Number of scenarios documented
- Test cases created (if applicable)
- Sections added to use case

## Example Usage

```
/openup-detail-use-case use_case_name: user-login generate_tests: true
```

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| Use case not found | File doesn't exist in docs/use-cases/ | Verify use case name or create use case first |
| No basic flow | Use case is incomplete | Complete basic flow before detailing |
| Duplicate scenarios | Same scenario documented multiple times | Consolidate similar scenarios |
| Missing actors | Actors not identified | Identify primary and secondary actors from context |

## References

- Use Case Template: `docs-eng-process/templates/use-case-specification.md`
- Use Case Scenarios Template: `docs-eng-process/templates/use-case-scenarios.md`
- Test Case Template: `docs-eng-process/templates/test-case.md`
- Gherkin Syntax: https://cucumber.io/docs/gherkin/reference/

## See Also

- [openup-create-use-case](../create-use-case/SKILL.md) - Create a new use case
- [openup-create-test-plan](../create-test-plan/SKILL.md) - Generate test plan from use cases
- [openup-elaboration](../../openup-phases/elaboration/SKILL.md) - Elaboration phase activities

# Caso de uso detallado

Esta habilidad transforma una especificación de caso de uso de alto nivel en escenarios detallados con criterios de aceptación de Gherkin y casos de prueba.

## Cuándo utilizar

Utilice esta habilidad cuando:
- Existe un caso de uso de alto nivel pero carece de escenarios detallados.
- Necesidad de documentar caminos felices, flujos alternativos y casos de error.
- Listo para crear criterios de aceptación de Gherkin para la automatización.
- Preparación para generar casos de prueba a partir de casos de uso.
- En fase de Elaboración al detallar requisitos

## Cuándo NO usarlo

NO uses esta habilidad cuando:
- El caso de uso no existe (use `/openup-create-use-case` primero)
- El caso de uso ya está completamente detallado con escenarios.
- Sólo necesitas crear un nuevo caso de uso desde cero.
- Trabajar en requisitos no funcionales (usar cuaderno de arquitectura)

## Criterios de éxito

Después de usar esta habilidad, verifique:
- [] El caso de uso se actualiza con escenarios detallados.
- [] La ruta feliz, las rutas alternativas y las rutas de error están documentadas
- [] Los criterios de aceptación de Gherkin están escritos para cada escenario.
- [] Se generan casos de prueba (si generate_tests=true)
- [ ] Todos los actores están identificados (primarios y secundarios)
- [ ] Las condiciones previas y posteriores son claras

## Resumen del proceso

1. Leer el caso de uso existente
2. Identificar escenarios (camino feliz, alternativas, errores)
3. Documente cada escenario con flujos paso a paso.
4. Generar criterios de aceptación de Gherkin
5. Cree casos de prueba (si se solicita)
6. Actualice el archivo de caso de uso.

## Pasos detallados

### 1. Leer el caso de uso existente

Lea el archivo de caso de uso de `docs/use-cases/$ARGUMENTS[use_case_name].md`:
- Extraer el nombre del caso de uso, el ID y la descripción.
- Identificar el actor principal.
- Revisar el flujo básico existente.
- Tenga en cuenta cualquier flujo alternativo ya documentado.

### 2. Identificar escenarios

Divida el caso de uso en distintos escenarios:

**Camino feliz (escenario principal):**
- El principal escenario de éxito donde todo sale como se esperaba.
- El usuario sigue el flujo de trabajo más común.

**Rutas alternativas:**
- Diferentes formas de lograr el mismo objetivo.
- Pasos opcionales o lógica de ramificación.
- Opciones y variaciones del usuario.

**Rutas de error:**
- Entradas o acciones no válidas
- Fallos del sistema
- Casos extremos y condiciones de contorno.

### 3. Escenarios de documentos

Para cada escenario, documente:

| Elemento | Descripción |
|---------|-------------|
| Nombre del escenario | Nombre claro y descriptivo |
| Descripción | Qué hace que este escenario sea único |
| Pasos | Interacción paso a paso (Actor → Sistema) |
| Condiciones previas | Lo que debe ser cierto ante este escenario |
| Poscondiciones | ¿Qué es cierto después de este escenario?

### 4. Generar criterios de aceptación de pepinillo

Para cada escenario, escriba los criterios de formato de Gherkin:

```gherkin
Given <precondition>
And <additional preconditions>
When <actor takes action>
And <additional actions>
Then <expected outcome>
And <additional outcomes>
```

**Ejemplo:**

```gherkin
Given the user is logged in
And the user has items in their cart
When the user clicks "Checkout"
Then the user is redirected to the payment page
And the order total is displayed
```

### 5. Crear casos de prueba (opcional)

Si `$ARGUMENTS[generate_tests] == "verdadero"`:

Cree archivos de casos de prueba para cada escenario en `docs/test-cases/`:
- Formato del nombre de archivo: `<nombre-caso-de-uso>-<escenario>-test.md`
- Utilice la plantilla de caso de prueba como guía.
- Incluir pasos del escenario, datos de prueba y resultados esperados.

### 6. Actualizar el archivo de caso de uso

Actualice el archivo de caso de uso existente con:
- Agregar sección de escenarios detallados
- Incluir criterios de aceptación de Gherkin.
- Enlace a archivos de casos de prueba
- Asegurar que todos los actores estén documentados.
- Verificar que las condiciones previas y posteriores estén completas

## Producción

Devuelve un resumen de:
- Archivo de caso de uso actualizado
- Número de escenarios documentados
- Casos de prueba creados (si corresponde)
- Secciones agregadas al caso de uso.

## Ejemplo de uso

```
/openup-detail-use-case use_case_name: user-login generate_tests: true
```

## Errores comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Caso de uso no encontrado | El archivo no existe en docs/use-cases/ | Verifique el nombre del caso de uso o cree un caso de uso primero |
| Sin flujo básico | El caso de uso está incompleto | Complete el flujo básico antes de detallar |
| Escenarios duplicados | Mismo escenario documentado varias veces | Consolidar escenarios similares |
| Actores desaparecidos | Actores no identificados | Identificar actores primarios y secundarios del contexto |

## Referencias

- Plantilla de caso de uso: `docs-eng-process/templates/use-case-specification.md`
- Plantilla de escenarios de casos de uso: `docs-eng-process/templates/use-case-scenarios.md`
- Plantilla de caso de prueba: `docs-eng-process/templates/test-case.md`
- Sintaxis del pepinillo: https://cucumber.io/docs/gherkin/reference/

## Ver también

- [openup-create-use-case](../create-use-case/SKILL.md) - Crea un nuevo caso de uso
- [openup-create-test-plan](../create-test-plan/SKILL.md) - Generar plan de prueba a partir de casos de uso
- [openup-elaboration](../../openup-phases/elaboration/SKILL.md) - Actividades de la fase de elaboración

# Elaboration Phase

This skill guides you through the Elaboration phase of OpenUP - establishing the architecture baseline.

## When to Use

Use this skill when:
- Inception is complete and need to establish architecture baseline
- Need to design and validate system architecture
- Resolving high-risk technical elements
- Implementing architectural prototypes
- Checking if Elaboration phase is complete
- Getting guidance on next steps in Elaboration

## When NOT to Use

Do NOT use this skill when:
- Still defining project vision and scope (use `/openup-inception`)
- Architecture is stable and ready for incremental build (move to Construction)
- Need to create specific artifacts (use artifact skills)
- Looking for iteration planning (use `/openup-create-iteration-plan`)

## Success Criteria

After using this skill, verify:
- [ ] Phase status is clearly understood (initiated, in-progress, or complete)
- [ ] Architecture notebook is created or updated
- [ ] Technical risks are identified and mitigated
- [ ] Critical use cases are detailed
- [ ] Next steps are clearly defined

## Elaboration Overview

**Goal**: Design and implement the architecture, resolve high-risk elements
**Duration**: Typically 4-8 weeks
**Key Milestone**: Lifecycle Architecture

## Phase Objectives

1. Design and validate the architecture
2. Detail the critical use cases
3. Implement and test the architectural baseline
4. Refine the project plan with accurate estimates
5. Mitigate high-priority risks

## Completion Criteria

- [ ] Architecture notebook completed
- [ ] Critical use cases detailed (80%)
- [ ] Technical risks identified and mitigated
- [ ] Prototype(s) validated key architectural decisions
- [ ] Project plan refined with accurate estimates
- [ ] Stakeholder agreement on architecture

## Process

### 1. Read Project Status

Read `docs/project-status.md` to:
- Confirm phase is `elaboration`
- Check iteration goals
- Review active work items

### 2. Based on Activity

**`initiate`**: Start Elaboration phase
- Update `docs/project-status.md` to set `phase: elaboration`
- Create `docs/architecture-notebook.md` from template
- Review and refine `docs/risk-list.md` for technical risks
- Update `docs/roadmap.md` with elaboration tasks

**`check-status`**: Review progress
- Check all completion criteria above
- List what's done and what remains
- Identify blockers

**`next-steps`**: Get recommendations
- Suggest next tasks based on current state
- Prioritize by technical risk and dependencies

## Key Work Products

- **Architecture Notebook** (`docs/architecture-notebook.md`) - Architecture documentation
- **Design** (`docs/design/*.md`) - Detailed design documents
- **Use Cases** (`docs/use-cases/*.md`) - Detailed use cases
- **Developer Tests** - Test implementations
- **Updated Project Plan** (`docs/project-plan.md`)

## Recommended Team

For Elaboration phase work, create a team with:
- **architect** - Lead architecture design
- **developer** - Implement architectural baseline
- **tester** - Validate architecture through testing
- Add **analyst** for detailed requirements

## References

- Elaboration Phase: `docs-eng-process/openup-knowledge-base/practice-management/risk_value_lifecycle/guidances/concepts/phase-elaboration.md`
- Architect Role: `docs-eng-process/openup-knowledge-base/core/role/roles/architect-6.md`
- Architecture Notebook Template: `docs-eng-process/templates/architecture-notebook.md`

## See Also

- [openup-create-architecture-notebook](../../openup-artifacts/create-architecture-notebook/SKILL.md) - Generate architecture documentation
- [openup-shared-vision](../../openup-artifacts/shared-vision/SKILL.md) - Create shared technical vision
- [openup-create-use-case](../../openup-artifacts/create-use-case/SKILL.md) - Create detailed use cases
- [openup-detail-use-case](../../openup-artifacts/detail-use-case/SKILL.md) - Detail use cases with scenarios
- [openup-inception](../inception/SKILL.md) - Previous phase
- [openup-construction](../construction/SKILL.md) - Next phase after Elaboration

# Fase de Elaboración

Esta habilidad lo guía a través de la fase de elaboración de OpenUP: establecer la línea base de la arquitectura.

## Cuándo utilizar

Utilice esta habilidad cuando:
- El inicio está completo y es necesario establecer una base de arquitectura
- Necesidad de diseñar y validar la arquitectura del sistema.
- Resolver elementos técnicos de alto riesgo.
- Implementación de prototipos arquitectónicos.
- Comprobar si la fase de elaboración está completa.
- Obtener orientación sobre los próximos pasos en la elaboración.

## Cuándo NO usarlo

NO uses esta habilidad cuando:
- Aún definiendo la visión y el alcance del proyecto (use `/openup-inception`)
- La arquitectura es estable y está lista para una construcción incremental (pasar a Construcción)
- Necesidad de crear artefactos específicos (usar habilidades de artefactos)
- Buscando planificación de iteración (use `/openup-create-iteration-plan`)

## Criterios de éxito

Después de usar esta habilidad, verifique:
- [ ] El estado de la fase se comprende claramente (iniciada, en curso o completa)
- [] Se crea o actualiza el cuaderno de arquitectura.
- [ ] Los riesgos técnicos son identificados y mitigados
- [] Se detallan los casos de uso críticos.
- [ ] Los próximos pasos están claramente definidos

## Descripción general de la elaboración

**Objetivo**: Diseñar e implementar la arquitectura, resolver elementos de alto riesgo.
**Duración**: normalmente de 4 a 8 semanas
**Hito clave**: Arquitectura del ciclo de vida

## Objetivos de la fase

1. Diseñar y validar la arquitectura.
2. Detallar los casos de uso críticos
3. Implementar y probar la línea base arquitectónica.
4. Refinar el plan del proyecto con estimaciones precisas.
5. Mitigar los riesgos de alta prioridad

## Criterios de finalización

- [] Cuaderno de arquitectura completado
- [ ] Casos de uso críticos detallados (80%)
- [ ] Riesgos técnicos identificados y mitigados
- [ ] Prototipo(s) decisiones arquitectónicas clave validadas
- [ ] Plan de proyecto refinado con estimaciones precisas
- [ ] Acuerdo de partes interesadas sobre arquitectura

## Proceso

### 1. Leer el estado del proyecto

Lea `docs/project-status.md` para:
- Confirmar que la fase es `elaboración`
- Verificar los objetivos de iteración.
- Revisar elementos de trabajo activos.

### 2. Basado en la actividad

**`iniciar`**: Iniciar fase de elaboración
- Actualizar `docs/project-status.md` para configurar `fase: elaboración`
- Crear `docs/architecture-notebook.md` a partir de la plantilla
- Revisar y perfeccionar `docs/risk-list.md` para riesgos técnicos
- Actualización `docs/roadmap.md` con tareas de elaboración

**`check-status`**: Revisar el progreso
- Verifique todos los criterios de finalización anteriores
- Enumerar lo que se hizo y lo que queda
- Identificar bloqueadores

**`próximos pasos`**: obtener recomendaciones
- Sugerir próximas tareas según el estado actual
- Priorizar por riesgo técnico y dependencias.

## Productos de trabajo clave

- **Cuaderno de Arquitectura** (`docs/architecture-notebook.md`) - Documentación de arquitectura
- **Diseño** (`docs/design/*.md`) - Documentos de diseño detallados
- **Casos de uso** (`docs/use-cases/*.md`) - Casos de uso detallados
- **Pruebas de desarrollador** - Implementaciones de prueba
- **Plan de proyecto actualizado** (`docs/project-plan.md`)

## Equipo recomendado

Para el trabajo de la fase de Elaboración, cree un equipo con:
- **arquitecto** - Diseño arquitectónico líder
- **desarrollador** - Implementar línea base arquitectónica
- **tester** - Validar la arquitectura mediante pruebas
- Agregue **analista** para requisitos detallados

## Referencias

- Fase de elaboración: `docs-eng-process/openup-knowledge-base/practice-management/risk_value_lifecycle/guidances/concepts/phase-elaboration.md`
- Rol de arquitecto: `docs-eng-process/openup-knowledge-base/core/role/roles/architect-6.md`
- Plantilla de cuaderno de arquitectura: `docs-eng-process/templates/architecture-notebook.md`

## Ver también

- [openup-create-architecture-notebook](../../openup-artifacts/create-architecture-notebook/SKILL.md) - Generar documentación de arquitectura
- [openup-shared-vision](../../openup-artifacts/shared-vision/SKILL.md) - Crear una visión técnica compartida
- [openup-create-use-case](../../openup-artifacts/create-use-case/SKILL.md) - Crear casos de uso detallados
- [openup-detail-use-case](../../openup-artifacts/detail-use-case/SKILL.md) - Detallar casos de uso con escenarios
- [openup-inception](../inception/SKILL.md) - Fase anterior
- [openup-construction](../construction/SKILL.md) - Siguiente fase después de la Elaboración

# openup-export-skills-pdf

Genera un PDF con la documentación completa de todas las skills del repositorio.

## Cuándo usar esta skill

- El usuario pide "documentar las skills", "exportar skills a PDF" o "generar catálogo de skills"
- Se necesita un documento imprimible o compartible del catálogo de skills
- Se quiere revisar visualmente el estado de todas las skills

## Dependencias

Instala antes de ejecutar:

```bash
pip install markdown xhtml2pdf
```

## Ejecución

### Uso básico

```bash
python .agents/skills/openup-export-skills-pdf/scripts/export_skills_pdf.py
```

Genera `docs/skills-documentation.pdf` escaneando `.agents/skills/`.

### Opciones

```bash
python scripts/export_skills_pdf.py \
  --skills-dir <ruta_al_directorio_de_skills> \
  --output <ruta_de_salida.pdf> \
  --title "Catálogo de Skills" \
  --extra-dir <directorio_adicional>
```

| Argumento | Por defecto | Descripción |
|-----------|-------------|-------------|
| `--skills-dir` | `.agents/skills` | Directorio principal de skills |
| `--output` | `docs/skills-documentation.pdf` | Ruta del PDF generado |
| `--title` | `Catálogo de Agent Skills` | Título del documento |
| `--extra-dir` | *(ninguno)* | Directorio adicional de skills a incluir |

### Ejemplo con ambos directorios de skills

```bash
python .agents/skills/openup-export-skills-pdf/scripts/export_skills_pdf.py \
  --skills-dir .agents/skills \
  --extra-dir .github/skills \
  --output docs/skills-documentation.pdf
```

## Contenido del PDF generado

1. **Portada** — Título, fecha de generación y número total de skills
2. **Tabla de contenidos** — Listado con nombre y descripción breve de cada skill
3. **Secciones por skill** — Para cada skill:
   - Nombre y descripción
   - Metadatos del frontmatter (compatibility, license, version, etc.)
   - Cuerpo completo del SKILL.md renderizado
4. **Pie de página** — Número de página y nombre del documento

## Gestión de errores

| Error | Acción |
|-------|--------|
| `ModuleNotFoundError: markdown` | Ejecutar `pip install markdown xhtml2pdf` |
| `ModuleNotFoundError: xhtml2pdf` | Ejecutar `pip install xhtml2pdf` |
| Skill sin `SKILL.md` | Se omite el directorio con aviso en consola |
| Frontmatter YAML inválido | Se incluye la skill con metadatos vacíos y aviso |
| Directorio no existe | Error claro con la ruta incorrecta |

## Verificación del resultado

Después de ejecutar, confirma:
- El archivo PDF existe en la ruta de salida
- Tiene portada con fecha actual
- El índice lista todas las skills encontradas
- Cada sección muestra el nombre, descripción y contenido completo

## Script de referencia

Ver `scripts/export_skills_pdf.py` para la implementación completa.

# openup-exportar-habilidades-pdf

Genera un PDF con la documentación completa de todas las skills del repositorio.

## Cuándo usar esta habilidad

- El usuario pide "documentar las skills", "exportar skills a PDF" o "generar catálogo de skills"
- Se necesita un documento imprimible o compartible del catálogo de habilidades.
- Se quiere revisar visualmente el estado de todas las habilidades.

## Dependencias

Instale antes de ejecutar:

```bash
pip install markdown xhtml2pdf
```

## Ejecución

### Uso básico

```bash
python .agents/skills/openup-export-skills-pdf/scripts/export_skills_pdf.py
```

Genera `docs/skills-documentation.pdf` escaneando `.agents/skills/`.

### Opciones

```bash
python scripts/export_skills_pdf.py \
  --skills-dir <ruta_al_directorio_de_skills> \
  --output <ruta_de_salida.pdf> \
  --title "Catálogo de Skills" \
  --extra-dir <directorio_adicional>
```

| Argumento | Por defecto | Descripción |
|-----------|-------------|-------------|
| `--skills-dir` | `.agentes/habilidades` | Directorio principal de habilidades |
| `--salida` | `docs/documentación-de-habilidades.pdf` | Ruta del PDF generado |
| `--título` | `Catálogo de Habilidades de Agente` | Título del documento |
| `--extra-dir` | *(ninguno)* | Directorio adicional de habilidades a incluir |

### Ejemplo con ambos directorios de skills

```bash
python .agents/skills/openup-export-skills-pdf/scripts/export_skills_pdf.py \
  --skills-dir .agents/skills \
  --extra-dir .github/skills \
  --output docs/skills-documentation.pdf
```

## Contenido del PDF generado

1. **Portada** — Título, fecha de generación y número total de habilidades
2. **Tabla de contenidos** — Listado con nombre y descripción breve de cada habilidad
3. **Secciones por habilidad** — Para cada habilidad:
   - Nombre y descripción
   - Metadatos del frontmatter (compatibilidad, licencia, versión, etc.)
   - Cuerpo completo del SKILL.md renderizado
4. **Pie de página** — Número de página y nombre del documento

## Gestión de errores

| Error | Acción |
|-------|--------|
| `ModuleNotFoundError: rebaja` | Ejecutar `pip install markdown xhtml2pdf` |
| `MóduloNotFoundError: xhtml2pdf` | Ejecutar `pip install xhtml2pdf` |
| Pecado de habilidad `SKILL.md` | Se omite el directorio con aviso en consola |
| Frontmatter YAML inválido | Se incluye la habilidad con metadatos vacíos y aviso |
| Directorio no existe | Error claro con la ruta incorrecta |

## Verificación del resultado

Después de ejecutar, confirme:
- El archivo PDF existe en la ruta de salida
- Tiene portada con fecha actual
- El índice lista de todas las habilidades encontradas.
- Cada sección muestra el nombre, descripción y contenido completo.

## Guión de referencia

Ver `scripts/export_skills_pdf.py` para la implementación completa.

# Inception Phase

This skill guides you through the Inception phase of OpenUP - defining scope, vision, and feasibility.

## When to Use

Use this skill when:
- Starting a new project and need to define scope and vision
- Need to identify key stakeholders and risks
- Preparing to move from idea to validated business case
- Checking if Inception phase is complete
- Getting guidance on next steps in Inception

## When NOT to Use

Do NOT use this skill when:
- Currently in Elaboration, Construction, or Transition phase (use appropriate phase skill)
- Need to create specific artifacts like vision documents or use cases (use artifact skills)
- Already have clear vision and architecture baseline (move to Elaboration)
- Looking for iteration planning (use `/openup-create-iteration-plan`)

## Success Criteria

After using this skill, verify:
- [ ] Phase status is clearly understood (initiated, in-progress, or complete)
- [ ] Key artifacts are identified or created (vision, risk list, roadmap)
- [ ] Next steps are clearly defined
- [ ] Stakeholders and risks are documented

## Inception Overview

**Goal**: Understand what to build and identify key risks
**Duration**: Typically 2-4 weeks
**Key Milestone**: Lifecycle Objectives

## Phase Objectives

1. Define the project's vision
2. Understand the problem to be solved
3. Identify key stakeholders
4. Define initial scope
5. Identify major risks
6. Demonstrate viability with a business case

## Completion Criteria

- [ ] Vision document approved by stakeholders
- [ ] Key use cases identified (20-30% detailed)
- [ ] Major risks documented with mitigation strategies
- [ ] Initial project plan with cost/schedule estimates
- [ ] Business case demonstrates viability
- [ ] Stakeholder agreement to proceed

## Process

### 1. Read Project Status

Read `docs/project-status.md` to:
- Confirm phase is `inception`
- Check iteration goals
- Review active work items

### 2. Based on Activity

**`initiate`**: Start Inception phase
- Update `docs/project-status.md` to set `phase: inception`
- Create initial `docs/vision.md` from template
- Create initial `docs/risk-list.md` from template
- Create `docs/roadmap.md` with initial backlog

**`check-status`**: Review progress
- Check all completion criteria above
- List what's done and what remains
- Identify blockers

**`next-steps`**: Get recommendations
- Suggest next tasks based on current state
- Prioritize by dependencies and value

## Key Work Products

- **Vision** (`docs/vision.md`) - Project vision and scope
- **Use Cases** (`docs/use-cases/*.md`) - Key use cases
- **Risk List** (`docs/risk-list.md`) - Identified risks
- **Project Plan** (`docs/project-plan.md`) - Initial plan
- **Glossary** (`docs/glossary.md`) - Project terminology

## Recommended Team

For Inception phase work, create a team with:
- **analyst** - Lead requirements and vision
- **project-manager** - Plan and coordinate
- Add **architect** for technical feasibility assessment

## References

- Inception Phase: `docs-eng-process/openup-knowledge-base/practice-management/risk_value_lifecycle/guidances/concepts/phase-inception.md`
- Analyst Role: `docs-eng-process/openup-knowledge-base/core/role/roles/analyst-6.md`
- Vision Template: `docs-eng-process/templates/vision.md`

## See Also

- [openup-create-vision](../../openup-artifacts/create-vision/SKILL.md) - Generate vision document
- [openup-shared-vision](../../openup-artifacts/shared-vision/SKILL.md) - Create shared technical vision
- [openup-create-risk-list](../../openup-artifacts/create-risk-list/SKILL.md) - Create risk assessment
- [openup-elaboration](../elaboration/SKILL.md) - Next phase after Inception
- [openup-start-iteration](../../openup-workflow/start-iteration/SKILL.md) - Begin iteration planning

# Fase de inicio

Esta habilidad lo guía a través de la fase inicial de OpenUP: define el alcance, la visión y la viabilidad.

## Cuándo utilizar

Utilice esta habilidad cuando:
- Inicio de un nuevo proyecto y necesidad de definir alcance y visión.
- Necesidad de identificar las partes interesadas clave y los riesgos.
- Preparación para pasar de la idea al caso de negocio validado.
- Comprobar si la fase de inicio está completa
- Obtener orientación sobre los próximos pasos en Inception

## Cuándo NO usarlo

NO uses esta habilidad cuando:
- Actualmente en fase de Elaboración, Construcción o Transición (use la habilidad de fase adecuada)
- Necesidad de crear artefactos específicos como documentos de visión o casos de uso (usar habilidades de artefactos)
- Ya tengo una visión clara y una base de arquitectura (pasar a Elaboración)
- Buscando planificación de iteración (use `/openup-create-iteration-plan`)

## Criterios de éxito

Después de usar esta habilidad, verifique:
- [ ] El estado de la fase se comprende claramente (iniciada, en curso o completa)
- [ ] Se identifican o crean artefactos clave (visión, lista de riesgos, hoja de ruta)
- [ ] Los próximos pasos están claramente definidos
- [ ] Las partes interesadas y los riesgos están documentados.

## Descripción general del inicio

**Objetivo**: comprender qué construir e identificar los riesgos clave
**Duración**: normalmente de 2 a 4 semanas
**Hito clave**: Objetivos del ciclo de vida

## Objetivos de la fase

1. Definir la visión del proyecto.
2. Comprender el problema a resolver
3. Identificar las partes interesadas clave
4. Definir el alcance inicial
5. Identificar los principales riesgos
6. Demostrar viabilidad con un caso de negocio

## Criterios de finalización

- [ ] Documento de visión aprobado por las partes interesadas
- [ ] Casos de uso clave identificados (20-30% detallados)
- [ ] Riesgos importantes documentados con estrategias de mitigación
- [ ] Plan inicial del proyecto con estimaciones de costos/cronograma
- [ ] Caso de negocio demuestra viabilidad
- [ ] Acuerdo de las partes interesadas para proceder

## Proceso

### 1. Leer el estado del proyecto

Lea `docs/project-status.md` para:
- Confirmar que la fase es "inicio".
- Verificar los objetivos de iteración.
- Revisar elementos de trabajo activos.

### 2. Basado en la actividad

**`iniciar`**: Iniciar la fase inicial
- Actualice `docs/project-status.md` para configurar `fase: inicio`
- Crear `docs/vision.md` inicial a partir de la plantilla
- Crear `docs/risk-list.md` inicial a partir de la plantilla
- Crear `docs/roadmap.md` con el trabajo pendiente inicial

**`check-status`**: Revisar el progreso
- Verifique todos los criterios de finalización anteriores
- Enumerar lo que se hizo y lo que queda
- Identificar bloqueadores

**`próximos pasos`**: obtener recomendaciones
- Sugerir próximas tareas según el estado actual
- Priorizar por dependencias y valor.

## Productos de trabajo clave

- **Visión** (`docs/vision.md`) - Visión y alcance del proyecto
- **Casos de uso** (`docs/use-cases/*.md`) - Casos de uso clave
- **Lista de riesgos** (`docs/risk-list.md`) - Riesgos identificados
- **Plan de proyecto** (`docs/project-plan.md`) - Plan inicial
- **Glosario** (`docs/glossary.md`) - Terminología del proyecto

## Equipo recomendado

Para el trabajo de la fase inicial, cree un equipo con:
- **analista** - Requisitos y visión del líder
- **director-de-proyecto** - Planificar y coordinar
- Agregar **arquitecto** para evaluación de viabilidad técnica

## Referencias

- Fase inicial: `docs-eng-process/openup-knowledge-base/practice-management/risk_value_lifecycle/guidances/concepts/phase-inception.md`
- Rol de analista: `docs-eng-process/openup-knowledge-base/core/role/roles/analyst-6.md`
- Plantilla de visión: `docs-eng-process/templates/vision.md`

## Ver también

- [openup-create-vision](../../openup-artifacts/create-vision/SKILL.md) - Generar documento de visión
- [openup-shared-vision](../../openup-artifacts/shared-vision/SKILL.md) - Crear una visión técnica compartida
- [openup-create-risk-list](../../openup-artifacts/create-risk-list/SKILL.md) - Crear evaluación de riesgos
- [openup-elaboration](../elaboration/SKILL.md) - Siguiente fase después del inicio
- [openup-start-iteration](../../openup-workflow/start-iteration/SKILL.md) - Comenzar la planificación de la iteración

# OpenUP Init - Interactive Project Setup

This skill provides a **one-command initialization** for OpenUP projects, replacing the complex multi-step setup process with an interactive conversational flow.

## When to Use

Use this skill when:
- Starting a new OpenUP project
- Setting up OpenUP in an existing repository
- Need quick project initialization without manual steps

## When NOT to Use

Do NOT use this skill when:
- Project is already initialized (use phase skills instead)
- Need to customize individual components (manual setup recommended)

## Success Criteria

After using this skill, verify:
- [ ] Project structure is created
- [ ] Initial documents are generated
- [ ] Agent teams are configured (if enabled)
- [ ] Git is initialized (if needed)

## Process

### 1. Gather Project Information

If not provided via arguments, interactively prompt for:

**Project Name**: What would you like to call this project?

**Project Type**: What type of project is this?
- `web` - Web application (frontend/backend)
- `api` - REST/GraphQL API service
- `library` - Reusable code library/package
- `mobile` - Mobile application
- `cli` - Command-line tool
- `other` - Specify

**Initial Phase**: Which phase should we start in?
- `inception` - Define scope and vision (default for new projects)
- `elaboration` - Architecture planning (for projects with vision)
- `construction` - Active development
- `transition` - Deployment preparation

### 2. Create Project Structure

Create the following directories:
```
docs/
├── input-requests/      # Stakeholder input documents
├── use-cases/           # Use case specifications
└── agent-logs/          # Agent activity logs
```

### 3. Generate Initial Documents

#### Project Status (`docs/project-status.md`)
```markdown
# Project Status

**Project**: [PROJECT_NAME]
**Phase**: [INITIAL_PHASE]
**Iteration**: 0
**Iteration Goal**: Project initialization
**Status**: initialized
**Current Task**: None
**Started**: [DATE]
**Last Updated**: [DATE]
**Updated By**: openup-init
```

#### Roadmap (`docs/roadmap.md`)
```markdown
# Project Roadmap

## T-001: Initialize OpenUP Project Structure
**Status**: completed
**Priority**: high
**Description**: Initial project setup and documentation structure

## T-002: [Next Task Placeholder]
**Status**: pending
**Priority**: medium
**Description**: [To be defined]
```

### 4. Configure Agent Teams (if not skipped)

**Check if agent teams are enabled:**
```bash
# Check environment variable
if [ -z "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" ]; then
  echo "Agent teams not enabled. Enable with:"
  echo "export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1"
fi
```

**Create initial team configuration:**
- Set default team type based on project type and phase
- Create `.claude/settings.json` with recommended hooks

### 5. Initialize Git (if needed)

Check if git is initialized:
```bash
if ! git rev-parse --git-dir > /dev/null 2>&1; then
  git init
  # Create initial commit
fi
```

### 6. Create Initial Branch (Optional)

If starting with inception phase:
- Detect trunk branch
- Create branch: `inception/initialize-project`
- Update project status

## Output

Returns a summary of:
- Project name and type
- Initial phase
- Created files and directories
- Next steps

## Smart Defaults

The skill uses intelligent defaults based on project type:

| Project Type | Default Phase | Recommended Team | Initial Tasks |
|--------------|---------------|------------------|---------------|
| web | inception | analyst + architect | Requirements, Architecture |
| api | elaboration | architect + developer | API design, Implementation |
| library | construction | developer + tester | Implementation, Testing |
| mobile | inception | analyst + architect | Requirements, UX Design |
| cli | construction | developer | Implementation |

## Quick Start Templates

### Web Application
```bash
/openup-init project_name: "MyWebApp" project_type: web
```

### API Service
```bash
/openup-init project_name: "MyAPI" project_type: api
```

### Code Library
```bash
/openup-init project_name: "MyLib" project_type: library
```

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| Directory not empty | Project already initialized | Use existing structure or specify new location |
| Git not found | Git not installed | Install git or use --no-git flag |
| Permission denied | Cannot create directories | Check directory permissions |

## Next Steps

After initialization:

1. **For Inception Phase**: Use `/openup-inception activity: initiate`
2. **Create Vision**: Use `/openup-create-vision`
3. **Start First Iteration**: Use `/openup-start-iteration`
4. **Spawn Team**: Create appropriate agent team for your phase

## See Also

- [openup-inception](../openup-phases/inception/SKILL.md) - Inception phase guidance
- [openup-create-vision](../openup-artifacts/create-vision/SKILL.md) - Vision document creation
- [Agent Teams Setup](../../docs-eng-process/agent-teams-setup.md) - Team configuration guide

## Examples

### Minimal Setup
```
/openup-init
# Prompts for all information interactively
```

### Full Setup with Teams
```
/openup-init project_name: "ECommerce" project_type: web
# Creates web app structure with team configuration
```

### Existing Project
```
/openup-init project_name: "ExistingAPI" project_type: api skip_teams: true
# Adds OpenUP to existing project without team setup
```

# OpenUP Init - Configuración interactiva del proyecto

Esta habilidad proporciona una **inicialización con un solo comando** para proyectos OpenUP, reemplazando el complejo proceso de configuración de varios pasos con un flujo de conversación interactivo.

## Cuándo utilizar

Utilice esta habilidad cuando:
- Iniciar un nuevo proyecto OpenUP
- Configurar OpenUP en un repositorio existente
- Necesita una inicialización rápida del proyecto sin pasos manuales

## Cuándo NO usarlo

NO uses esta habilidad cuando:
- El proyecto ya está inicializado (en su lugar, utilice habilidades de fase)
- Necesidad de personalizar componentes individuales (se recomienda configuración manual)

## Criterios de éxito

Después de usar esta habilidad, verifique:
- [] Se crea la estructura del proyecto.
- [ ] Se generan los documentos iniciales
- [] Los equipos de agentes están configurados (si están habilitados)
- [] Git se inicializa (si es necesario)

## Proceso

### 1. Reúna información del proyecto

Si no se proporciona mediante argumentos, solicite interactivamente:

**Nombre del proyecto**: ¿Cómo le gustaría llamar a este proyecto?

**Tipo de proyecto**: ¿Qué tipo de proyecto es este?
- `web` - Aplicación web (frontend/backend)
- `api` - Servicio API REST/GraphQL
- `biblioteca` - Biblioteca/paquete de código reutilizable
- `móvil` - Aplicación móvil
- `cli` - Herramienta de línea de comandos
- `otro` - Especificar

**Fase Inicial**: ¿En qué fase debemos empezar?
- `inception`: define el alcance y la visión (predeterminado para nuevos proyectos)
- `elaboración` - Planificación de arquitectura (para proyectos con visión)
- `construcción` - Desarrollo activo
- `transición` - Preparación para el despliegue

### 2. Crear estructura de proyecto

Cree los siguientes directorios:
```
documentos/
├── solicitudes de entrada/# Documentos de entrada de las partes interesadas
├── casos de uso/ # especificaciones de casos de uso
└── agent-logs/ # Registros de actividad del agente
```

### 3. Generar Documentos Iniciales

#### Estado del proyecto (`docs/project-status.md`)
```rebaja
# Estado del proyecto

**Proyecto**: [PROJECT_NAME]
**Fase**: [INITIAL_PHASE]
**Iteración**: 0
**Objetivo de iteración**: inicialización del proyecto
**Estado**: inicializado
**Tarea actual**: Ninguna
**Iniciado**: [FECHA]
**Última actualización**: [FECHA]
**Actualizado por**: openup-init
```

#### Hoja de ruta (`docs/roadmap.md`)
```rebaja
# Hoja de ruta del proyecto

## T-001: Inicializar la estructura del proyecto OpenUP
**Estado**: completado
**Prioridad**: alta
**Descripción**: Configuración inicial del proyecto y estructura de documentación.

## T-002: [Marcador de posición de siguiente tarea]
**Estado**: pendiente
**Prioridad**: media
**Descripción**: [Por definir]
```

### 4. Configurar equipos de agentes (si no se omite)

**Compruebe si los equipos de agentes están habilitados:**
```golpecito
# Verificar variable de entorno
si [ -z "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" ]; entonces
  echo "Equipos de agentes no habilitados. Habilítelo con:"
  echo "exportar CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1"
fi
```

**Crear configuración inicial del equipo:**
- Establecer el tipo de equipo predeterminado según el tipo y la fase del proyecto
- Crear `.claude/settings.json` con los ganchos recomendados

### 5. Inicialice Git (si es necesario)

Compruebe si git está inicializado:
```golpecito
si! git rev-parse --git-dir > /dev/null 2>&1; entonces
  inicio de git
  # Crear compromiso inicial
fi
```

### 6. Crear rama inicial (opcional)

Si comienza con la fase inicial:
- Detectar rama del tronco
- Crear rama: `inception/initialize-project`
- Actualizar el estado del proyecto.

## Producción

Devuelve un resumen de:
- Nombre y tipo de proyecto.
- Fase inicial
- Archivos y directorios creados.
- Próximos pasos

## Valores predeterminados inteligentes

La habilidad utiliza valores predeterminados inteligentes según el tipo de proyecto:

| Tipo de proyecto | Fase predeterminada | Equipo recomendado | Tareas iniciales |
|--------------|---------------|------------------|---------------|
| web | inicio | analista + arquitecto | Requisitos, Arquitectura |
| API | elaboración | arquitecto + promotor | Diseño API, Implementación |
| biblioteca | construcción | desarrollador + probador | Implementación, Pruebas |
| móvil | inicio | analista + arquitecto | Requisitos, Diseño UX |
| cli | construcción | desarrollador | Implementación |

## Plantillas de inicio rápido

### Aplicación web
```golpecito
/openup-init nombre_proyecto: "MyWebApp" tipo_proyecto: web
```

### Servicio API
```golpecito
/openup-init nombre_proyecto: "MiAPI" tipo_proyecto: api
```

### Biblioteca de códigos
```golpecito
/openup-init nombre_proyecto: "MyLib" tipo_proyecto: biblioteca
```

## Errores comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Directorio no vacío | Proyecto ya inicializado | Utilice la estructura existente o especifique una nueva ubicación |
| Git no encontrado | Git no instalado | Instale git o use la bandera --no-git |
| Permiso denegado | No se pueden crear directorios | Verificar permisos de directorio |

## Próximos pasos

Después de la inicialización:

1. **Para la fase inicial**: use `/openup-inception actividad: iniciar`
2. **Crear visión**: utilice `/openup-create-vision`
3. **Iniciar la primera iteración**: utilice `/openup-start-iteration`
4. **Equipo de generación**: crea el equipo de agentes apropiado para tu fase

## Ver también

- [openup-inception](../openup-phases/inception/SKILL.md) - Guía de la fase inicial
- [openup-create-vision](../openup-artifacts/create-vision/SKILL.md) - Creación de documentos de visión
- [Configuración de equipos de agentes](../../docs-eng-process/agent-teams-setup.md) - Guía de configuración de equipos

## Ejemplos

### Configuración mínima
```
/inicio-apertura
# Solicita toda la información de forma interactiva
```

### Configuración completa con Teams
```
/openup-init nombre_proyecto: "Comercio electrónico" tipo_proyecto: web
# Crea una estructura de aplicación web con configuración de equipo.
```

### Proyecto existente
```
/openup-init nombre_proyecto: "API existente" tipo_proyecto: api skip_teams: verdadero
# Agrega OpenUP al proyecto existente sin configuración del equipo
```

# Log Run

Create traceability logs for the current agent run. **Call only AFTER all changes are committed** (logs require actual commit SHAs).

## Prerequisites

- `git status --porcelain` returns empty (all changes committed)
- Commit SHAs are available for reference

## Process

### 1. Generate Run ID

If `$ARGUMENTS[run_id]` is not provided, generate: `YYYY-MM-DDTHH:MM:SSZ-agent-branch`

### 2. Collect Run Metadata

- Branch: `git branch --show-current`
- Trunk: detect via `origin/HEAD`, fallback `main`/`master`
- Start/end timestamps
- Phase from `docs/project-status.md`
- Commits: `git log --oneline <since>...HEAD`

### 3. Create Markdown Log

Create `docs/agent-logs/YYYY/MM/DD/<timestamp>-<agent>-<branch>.md` with:
- Run metadata (branch, trunk, timestamps)
- Roles assumed and switches
- Tasks performed (one per primary-role task boundary)
- Commit SHAs created during run
- Consulting-role usage
- Key decisions/assumptions + doc links
- Initial instructions/prompt (verbatim)

### 4. Append JSONL Entry

Append to `docs/agent-logs/agent-runs.jsonl`:

```json
{"run_id":"<id>","agent":"claude","branch":"<branch>","trunk":"<trunk>","start":"<ts>","end":"<ts>","phase":"<phase>","iteration_goals":["..."],"prompt_hash":"sha256:...","md_log_path":"<path>","tasks":[{"role":"<role>","objective":"<obj>","start":"<ts>","end":"<ts>","commits":["<sha>"],"docs_updated":["<path>"],"consulting_roles":["<role>"]}],"decisions":["<path>"],"notes":"<summary>"}
```

### 5. Verify

- Markdown log exists and is readable
- JSONL entry is valid JSON
- Commit SHAs referenced actually exist
- All required fields are populated

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| Uncommitted changes | Files not committed | `git add -A && git commit` first |
| Invalid JSONL | JSON format error | Verify syntax before appending |
| Missing commits | No commits for run | Verify run is complete |
| Directory not found | docs/agent-logs/ missing | Create directory structure first |

## References

- Traceability Logging SOP: `docs-eng-process/agent-workflow.md`

## See Also

- [openup-complete-task](../complete-task/SKILL.md) - Calls this skill automatically
- [openup-start-iteration](../start-iteration/SKILL.md) - Logs iteration start

# Ejecución de registro

Cree registros de trazabilidad para la ejecución actual del agente. **Llame solo DESPUÉS de que se hayan confirmado todos los cambios** (los registros requieren SHA de confirmación real).

## Requisitos previos

- `git status --porcelain` regresa vacío (todos los cambios confirmados)
- Los SHA de confirmación están disponibles como referencia

## Proceso

### 1. Generar ID de ejecución

Si no se proporciona `$ARGUMENTS[run_id]`, genere: `AAAA-MM-DDTHH:MM:SSZ-agent-branch`

### 2. Recopilar metadatos de ejecución

- Rama: `git rama --show-current`
- Tronco: detectar a través de `origin/HEAD`, respaldo `main`/`master`
- Marcas de tiempo de inicio/finalización
- Fase de `docs/project-status.md`
- Confirma: `git log --oneline <since>...HEAD`

### 3. Crear registro de rebajas

Cree `docs/agent-logs/YYYY/MM/DD/<timestamp>-<agent>-<branch>.md` con:
- Ejecutar metadatos (rama, troncal, marcas de tiempo)
- Roles asumidos y cambios.
- Tareas realizadas (una por límite de tarea de rol principal)
- Confirmar SHA creados durante la ejecución
- Uso del rol de consultoría
- Decisiones/supuestos clave + enlaces a documentos
- Instrucciones/indicaciones iniciales (textualmente)

### 4. Agregar entrada JSONL

Agregue a `docs/agent-logs/agent-runs.jsonl`:

```json
{"run_id":"<id>","agent":"claude","branch":"<branch>","trunk":"<trunk>","start":"<ts>","end":"<ts>","phase":"<phase>","iteration_goals":["..."],"prompt_hash":"sha256:...","md_log_path":"<path>","tasks":[{"role":"<role>","objective":"<obj>","start":"<ts>","end":"<ts>","commits":["<sha>"],"docs_updated":["<path>"],"consulting_roles":["<role>"]}],"decisions":["<path>"],"notes":"<summary>"}
```

### 5. Verificar

- El registro de rebajas existe y es legible.
- La entrada JSONL es JSON válida.
- Confirmar que los SHA a los que se hace referencia realmente existen
- Todos los campos obligatorios están completos.

## Errores comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Cambios no confirmados | Archivos no confirmados | `git add -A && git commit` primero |
| JSONL no válido | Error de formato JSON | Verifique la sintaxis antes de agregar |
| Confirmaciones faltantes | No hay confirmaciones para ejecutar | Verificar que la ejecución esté completa |
| Directorio no encontrado | docs/agent-logs/faltan | Primero cree la estructura del directorio |

## Referencias

- SOP de registro de trazabilidad: `docs-eng-process/agent-workflow.md`

## Ver también

- [openup-complete-task](../complete-task/SKILL.md) - Llama esta habilidad automáticamente
- [openup-start-iteration](../start-iteration/SKILL.md) - Registra el inicio de la iteración

# Phase Review

This skill checks phase completion criteria and prepares documentation for a phase review meeting.

## When to Use

Use this skill when:
- Nearing end of a phase and need to check completion
- Preparing for phase review meeting with stakeholders
- Assessing readiness to move to next phase
- Generating phase summary documentation
- Need to demonstrate phase accomplishments

## When NOT to Use

Do NOT use this skill when:
- Just starting a phase (use phase skill instead)
- Need to complete iteration tasks (use `/openup-complete-task`)
- Looking for iteration planning (use `/openup-create-iteration-plan`)
- Phase is clearly not complete (continue work first)

## Success Criteria

After using this skill, verify:
- [ ] All phase completion criteria are checked
- [ ] Missing items are clearly identified
- [ ] Phase review summary is generated
- [ ] Recommendations for next phase are provided
- [ ] User knows what decisions are needed

## Process

### 1. Read Current Project Status

Read `docs/project-status.md` to determine:
- Current phase (or use `$ARGUMENTS[phase]` if provided)
- Iteration status
- Phase completion criteria checklist

### 2. Check Phase Completion Criteria

For the current phase, verify all completion criteria are met:

**Inception - Lifecycle Objectives Milestone**:
- [ ] Vision document approved by stakeholders
- [ ] Key use cases identified (20-30% detailed)
- [ ] Major risks documented with mitigation strategies
- [ ] Initial project plan with cost/schedule estimates
- [ ] Business case demonstrates viability
- [ ] Stakeholder agreement to proceed

**Elaboration - Lifecycle Architecture Milestone**:
- [ ] Architecture notebook completed
- [ ] Critical use cases detailed (80%)
- [ ] Technical risks identified and mitigated
- [ ] Prototype(s) validated key architectural decisions
- [ ] Project plan refined with accurate estimates
- [ ] Stakeholder agreement on architecture

**Construction - Operational Capability Milestone**:
- [ ] Product is stable enough for beta testing
- [ ] Alpha test results documented
- [ ] Critical issues resolved
- [ ] User documentation is adequate
- [ ] Stakeholder agreement to deploy to beta users

**Transition - Product Release Milestone**:
- [ ] Product is ready for release
- [ ] All acceptance tests pass
- [ ] Deployment documentation complete
- [ ] Support materials ready
- [ ] Stakeholder sign-off obtained

### 3. Generate Phase Review Summary

Create a phase review summary including:
- Phase accomplishments
- Work products completed
- Risks and issues
- Lessons learned
- Recommendations for next phase

### 4. Create Review Presentation

Generate a review presentation outline:
- Executive summary
- Phase objectives vs. results
- Demonstrations (if applicable)
- Open issues and decisions needed

### 5. Notify User

Inform the user that:
- Phase review materials are ready
- Any completion criteria that are not yet met
- Decisions needed from stakeholders

## Output

Returns:
- Phase completion criteria checklist status
- List of completed work products
- Review summary
- Recommendations

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| Project status not found | docs/project-status.md doesn't exist | Initialize project with phase skill first |
| Phase not recognized | Invalid phase name provided | Use valid phase: inception, elaboration, construction, transition |
| Criteria not met | Phase incomplete | Continue work or document exceptions |

## References

- Phase Milestones: `docs-eng-process/openup-knowledge-base/practice-management/risk_value_lifecycle/guidances/concepts/phase-milestones.md`
- Agent Workflow: `docs-eng-process/agent-workflow.md`

## See Also

- [openup-inception](../../openup-phases/inception/SKILL.md) - Inception phase details
- [openup-elaboration](../../openup-phases/elaboration/SKILL.md) - Elaboration phase details
- [openup-construction](../../openup-phases/construction/SKILL.md) - Construction phase details
- [openup-transition](../../openup-phases/transition/SKILL.md) - Transition phase details

# Revisión de fase

Esta habilidad verifica los criterios de finalización de la fase y prepara la documentación para una reunión de revisión de la fase.

## Cuándo utilizar

Utilice esta habilidad cuando:
- Se acerca el final de una fase y es necesario comprobar su finalización.
- Preparación de la reunión de revisión de fase con las partes interesadas.
- Evaluar la preparación para pasar a la siguiente fase.
- Generación de documentación resumen de fase.
- Necesidad de demostrar los logros de la fase.

## Cuándo NO usarlo

NO uses esta habilidad cuando:
- Recién comenzando una fase (usa la habilidad de fase en su lugar)
- Necesidad de completar tareas de iteración (use `/openup-complete-task`)
- Buscando planificación de iteración (use `/openup-create-iteration-plan`)
- La fase claramente no está completa (continuar trabajando primero)

## Criterios de éxito

Después de usar esta habilidad, verifique:
- [ ] Se verifican todos los criterios de finalización de fase.
- [ ] Los elementos faltantes están claramente identificados
- [ ] Se genera el resumen de revisión de fase
- [] Se proporcionan recomendaciones para la siguiente fase.
- [] El usuario sabe qué decisiones son necesarias

## Proceso

### 1. Leer el estado actual del proyecto

Lea `docs/project-status.md` para determinar:
- Fase actual (o use `$ARGUMENTS[phase]` si se proporciona)
- Estado de iteración
- Lista de verificación de criterios de finalización de fase

### 2. Verificar los criterios de finalización de la fase

Para la fase actual, verifique que se cumplan todos los criterios de finalización:

**Inicio: Hito de los objetivos del ciclo de vida**:
- [ ] Documento de visión aprobado por las partes interesadas
- [ ] Casos de uso clave identificados (20-30% detallados)
- [ ] Riesgos importantes documentados con estrategias de mitigación
- [ ] Plan inicial del proyecto con estimaciones de costos/cronograma
- [ ] Caso de negocio demuestra viabilidad
- [ ] Acuerdo de las partes interesadas para proceder

**Elaboración - Hito de la Arquitectura del Ciclo de Vida**:
- [] Cuaderno de arquitectura completado
- [ ] Casos de uso críticos detallados (80%)
- [ ] Riesgos técnicos identificados y mitigados
- [ ] Prototipo(s) decisiones arquitectónicas clave validadas
- [ ] Plan de proyecto refinado con estimaciones precisas
- [ ] Acuerdo de partes interesadas sobre arquitectura

**Construcción - Hito de capacidad operativa**:
- [] El producto es lo suficientemente estable para realizar pruebas beta.
- [] Resultados de la prueba alfa documentados
- [] Problemas críticos resueltos
- [ ] La documentación del usuario es adecuada
- [] Acuerdo de las partes interesadas para implementar a los usuarios beta

**Transición: hito del lanzamiento del producto**:
- [ ] El producto está listo para su lanzamiento.
- [] Todas las pruebas de aceptación pasan
- [] Documentación de implementación completa
- [ ] Materiales de apoyo listos
- [ ] Se obtuvo la aprobación de las partes interesadas

### 3. Generar resumen de revisión de fase

Cree un resumen de revisión de fase que incluya:
- Logros de fase
- Productos de trabajo completados.
- Riesgos y problemas
- Lecciones aprendidas
- Recomendaciones para la siguiente fase.

### 4. Crear presentación de revisión

Genere un esquema de presentación de revisión:
- Resumen ejecutivo
- Objetivos de fase vs. resultados
- Demostraciones (si corresponde)
- Cuestiones abiertas y decisiones necesarias.

### 5. Notificar al usuario

Informar al usuario que:
- Los materiales de revisión de la fase están listos.
- Cualquier criterio de finalización que aún no se haya cumplido.
- Decisiones necesarias de las partes interesadas

## Producción

Devoluciones:
- Estado de la lista de verificación de criterios de finalización de fase
- Lista de productos de trabajo completados.
- Resumen de revisión
- Recomendaciones

## Errores comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Estado del proyecto no encontrado | docs/project-status.md no existe | Inicialice el proyecto con la habilidad de fase primero |
| Fase no reconocida | Nombre de fase no válido proporcionado | Uso fase válida: inicio, elaboración, construcción, transición |
| Criterios no cumplidos | Fase incompleta | Continuar con excepciones de trabajo o documentos |

## Referencias

- Hitos de fase: `docs-eng-process/openup-knowledge-base/practice-management/risk_value_lifecycle/guidances/concepts/phase-milestones.md`
- Flujo de trabajo del agente: `docs-eng-process/agent-workflow.md`

## Ver también

- [openup-inception](../../openup-phases/inception/SKILL.md) - Detalles de la fase inicial
- [openup-elaboration](../../openup-phases/elaboration/SKILL.md) - Detalles de la fase de elaboración
- [openup-construction](../../openup-phases/construction/SKILL.md) - Detalles de la fase de construcción
- [openup-transition](../../openup-phases/transition/SKILL.md) - Detalles de la fase de transición

# Plan Feature

This skill automates the full "plan a feature" workflow: explore the codebase, generate a detailed iteration plan, add a roadmap entry, and optionally create a PR — all from a single feature idea.

## When to Use

Use this skill when:
- You have a new feature idea and need a detailed implementation plan
- You want to add a feature to the roadmap with a plan document
- You need to explore the codebase to understand what a feature will touch before coding
- Planning an iteration task from a high-level description

## When NOT to Use

Do NOT use this skill when:
- The feature already has an iteration plan (edit it directly)
- You need to start implementing (use `/openup-start-iteration`)
- The task is a quick fix or bug fix (use `/openup-quick-task`)
- You only need to update the roadmap without a plan (edit `docs/roadmap.md` directly)

## Success Criteria

After using this skill, verify:
- [ ] Iteration plan file exists at `docs/iteration-plans/{task_id}-{slug}.md`
- [ ] Plan includes Current State with actual code excerpts from the codebase
- [ ] Plan includes Proposed Design with concrete code examples
- [ ] Plan includes Acceptance Criteria, Dependencies, and Key Files
- [ ] Roadmap entry exists in `docs/roadmap.md` with correct format
- [ ] PR is created (if `create_pr` is true)

## Process Summary

1. Read project context (status, roadmap, architecture)
2. Auto-detect task ID from roadmap
3. Explore codebase for relevant code
4. Generate iteration plan document
5. Update roadmap with new entry
6. Optionally validate with analyst + architect team
7. Optionally create branch, commit, push, and PR
8. Present summary

## Detailed Steps

### 1. Read Project Context

Read these files to understand the current state of the project:
- `docs/project-status.md` — current phase, iteration, completed tasks
- `docs/roadmap.md` — existing tasks, priorities, dependencies, format
- `docs/architecture-notebook.md` — architectural decisions and constraints

Record:
- Current phase (e.g., `construction`)
- Current iteration number
- Naming conventions for task IDs in the current phase

### 2. Auto-Detect Task ID

If `$ARGUMENTS[task_id]` is provided, use it directly.

Otherwise, auto-detect by scanning `docs/roadmap.md`:
1. Identify the current phase prefix from `docs/project-status.md` (e.g., `C` for Construction, `E` for Elaboration, `T` for Inception)
2. Find all task IDs matching the pattern `{prefix}{iteration}-{sequence}` (e.g., `C3-001`, `C3-002`, `C3-003`)
3. Extract the highest sequence number in the current iteration
4. Increment by 1 to get the next ID (e.g., if highest is `C3-003`, next is `C3-004`)
5. If no tasks exist for the current iteration, start at `001`

**Important**: Also scan the "Future / Backlog Features" section for any `T-0XX` IDs to avoid collisions.

### 3. Explore Codebase

This is a critical step. The iteration plan must reference real files and code, not abstract descriptions.

Based on the feature topic (`$ARGUMENTS[topic]`), explore:
1. **Models** — Grep/Glob for relevant ActiveRecord models, their associations, validations, and scopes
2. **Controllers** — Find controllers that handle related functionality
3. **Services** — Look for service objects in `app/services/` related to the feature
4. **Views** — Find relevant views and partials
5. **Routes** — Check `config/routes.rb` for related route definitions
6. **Schema** — Read `db/schema.rb` for relevant table definitions
7. **Locales** — Check `config/locales/en.yml` and `config/locales/es.yml` for existing i18n keys in the area
8. **Tests** — Find existing test files for the affected code
9. **Config** — Check `config/app_settings.yml` or other config files if relevant

Extract actual code snippets (with file paths and line numbers) for the "Current State" section of the plan.

### 4. Generate Iteration Plan

Write the iteration plan to `docs/iteration-plans/{task_id_lower}-{slug}.md` where:
- `{task_id_lower}` is the lowercase task ID (e.g., `c3-004`)
- `{slug}` is a short kebab-case slug derived from the feature topic (e.g., `pdf-export`)

Use this structure (matching the project's established format):

```markdown
# {Task ID}: {Title}

**Phase**: {phase}
**Status**: pending
**Goal**: {one-line goal}
**Priority**: {priority}

---

## Context

{Why this feature is needed. Background and motivation.}

---

## Current State

{For each relevant area, show the actual current code with file paths and line numbers.
Include model definitions, controller actions, service methods, view excerpts, routes, schema.}

### {Area 1} (`path/to/file.rb`)

```ruby
# Current implementation
```

### {Area 2} (`path/to/file.rb`)

```ruby
# Current implementation
```

---

## Proposed Design

{For each change, show the proposed code with clear before/after or new code.
Group by logical units of work (e.g., Migration, Model, Service, Controller, Views, i18n).}

### {Change 1}: {Description}

**File**: `path/to/file.rb`

```ruby
# Proposed implementation
```

### {Change 2}: {Description}

**New file**: `path/to/new_file.rb`

```ruby
# Proposed implementation
```

---

## i18n

New keys for `config/locales/en.yml`:

```yaml
en:
  # new keys
```

New keys for `config/locales/es.yml`:

```yaml
es:
  # new keys
```

---

## Acceptance Criteria

- [ ] {Criterion 1}
- [ ] {Criterion 2}
- [ ] ...

---

## Testing Strategy

- {Test category 1}: {what to test}
- {Test category 2}: {what to test}

---

## Dependencies

- {Task ID} ({description} — {status})

---

## Key Files

| File | Change |
|------|--------|
| `path/to/file` | {Description of change} |

---

## Out of Scope

- {Item 1}
- {Item 2}

---

## Open Questions

1. {Question 1}
2. {Question 2}
```

### 5. Update Roadmap

Insert a new entry in `docs/roadmap.md` under the correct phase section.

Match the existing format exactly:

```markdown
---

## {Task ID}: {Title}
**Status**: pending
**Priority**: {priority}
**Description**: {1-3 sentence description of the feature}
- {Key deliverable 1}
- {Key deliverable 2}
- ...

**Dependencies**: {comma-separated task IDs}

**See**: `docs/iteration-plans/{filename}.md`
```

**Placement rules**:
- Insert under the correct phase heading (e.g., "## Construction Phase")
- Place after the last entry in that phase section (before the next phase heading or "---" separator)
- Pending tasks should appear after completed tasks in the same phase

### 6. Validate with Team (Optional)

Only if `$ARGUMENTS[validate]` is `"true"`:

1. **Create a team** using TeamCreate with name `plan-review-{task_id}`
2. **Create review tasks**:
   - Task for analyst: "Review requirements completeness for {task_id}"
   - Task for architect: "Review technical feasibility for {task_id}"
3. **Spawn teammates**:
   - Analyst (subagent_type: `general-purpose`, team_name, instructions from `.claude/teammates/analyst.md`):
     - Read the generated iteration plan
     - Review for: requirements completeness, missing acceptance criteria, unclear scope, stakeholder impact
     - Send findings back via message
   - Architect (subagent_type: `general-purpose`, team_name, instructions from `.claude/teammates/architect.md`):
     - Read the generated iteration plan and `docs/architecture-notebook.md`
     - Review for: technical feasibility, architectural alignment, performance concerns, security implications, dependency risks
     - Send findings back via message
4. **Wait for both reviews** to complete
5. **Incorporate feedback** — update the iteration plan with any valid suggestions
6. **Shut down team** — send shutdown requests to both teammates, then delete team

### 7. Create Branch and PR (Optional)

Only if `$ARGUMENTS[create_pr]` is not `"false"` (default is true):

1. **Create branch**: `docs/{task_id_lower}-{slug}` (uses `docs/` prefix since this is documentation-only)
   ```bash
   git checkout -b docs/{task_id_lower}-{slug}
   ```

2. **Stage and commit**:
   ```bash
   git add docs/iteration-plans/{filename}.md docs/roadmap.md
   git commit -m "docs: add iteration plan and roadmap entry for {task_id}"
   ```

3. **Push branch**:
   ```bash
   git push -u origin docs/{task_id_lower}-{slug}
   ```

4. **Create PR**:
   ```bash
   gh pr create \
     --title "docs: {Task ID} — {Title}" \
     --body "$(cat <<'EOF'
   ## Summary

   - Add iteration plan for {Task ID}: {Title}
   - Add roadmap entry under {Phase} phase

   ## Files

   - `docs/iteration-plans/{filename}.md` — detailed implementation plan
   - `docs/roadmap.md` — new roadmap entry

   ## Review Notes

   This is a planning PR (documentation only). Review the iteration plan for:
   - Completeness of proposed design
   - Accuracy of current state analysis
   - Feasibility of acceptance criteria

   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   EOF
   )"
   ```

### 8. Present Summary

Output a summary to the user:

```
## Feature Plan Created

- **Task ID**: {task_id}
- **Title**: {title}
- **Priority**: {priority}
- **Iteration Plan**: `docs/iteration-plans/{filename}.md`
- **Roadmap**: Updated `docs/roadmap.md`
- **Branch**: `docs/{task_id_lower}-{slug}` (if created)
- **PR**: {PR URL} (if created)
- **Validated**: {yes/no}

### Next Steps
- Review the iteration plan
- When ready to implement: `/openup-start-iteration task_id: {task_id}`
```

## Output

Returns a summary of:
- Task ID (auto-detected or provided)
- Iteration plan file path
- Roadmap entry location
- Branch name (if created)
- PR URL (if created)
- Validation results (if validated)

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| Task ID collision | Auto-detected ID already exists | Provide explicit `task_id` argument |
| Roadmap parse error | Unexpected roadmap format | Verify `docs/roadmap.md` follows standard format |
| No relevant code found | Feature is entirely new | Plan will have minimal "Current State" — focus on "Proposed Design" |
| Team spawn failed | Agent teams not enabled | Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` for validation |
| PR creation failed | No remote or gh not installed | Use `create_pr: false` and create PR manually |

## References

- Iteration Plans: `docs/iteration-plans/`
- Roadmap: `docs/roadmap.md`
- Project Status: `docs/project-status.md`
- Architecture Notebook: `docs/architecture-notebook.md`

## See Also

- [openup-start-iteration](../openup-start-iteration/SKILL.md) — Begin implementing a planned task
- [openup-create-iteration-plan](../openup-create-iteration-plan/SKILL.md) — Generic iteration planning (phase-level)
- [openup-complete-task](../openup-complete-task/SKILL.md) — Mark task complete after implementation
- [openup-create-pr](../openup-create-pr/SKILL.md) — Create PR with roadmap context

# Característica del plan

Esta habilidad automatiza todo el flujo de trabajo de "planificar una característica": explora la base de código, genera un plan de iteración detallado, agrega una entrada de hoja de ruta y, opcionalmente, crea un PR, todo a partir de una única idea de característica.

## Cuándo utilizar

Utilice esta habilidad cuando:
- Tiene una idea para una nueva característica y necesita un plan de implementación detallado.
- Quiere agregar una característica a la hoja de ruta con un documento de plan.
- Debes explorar el código base para comprender qué tocará una característica antes de codificar.
- Planificación de una tarea de iteración a partir de una descripción de alto nivel.

## Cuándo NO usarlo

NO uses esta habilidad cuando:
- La función ya tiene un plan de iteración (edítelo directamente)
- Necesitas comenzar a implementar (usa `/openup-start-iteration`)
- La tarea es una solución rápida o una corrección de errores (use `/openup-quick-task`)
- Solo necesita actualizar la hoja de ruta sin un plan (edite `docs/roadmap.md` directamente)

## Criterios de éxito

Después de usar esta habilidad, verifique:
- [] El archivo del plan de iteración existe en `docs/iteration-plans/{task_id}-{slug}.md`
- [] El plan incluye el estado actual con extractos de código reales del código base
- [] El plan incluye el diseño propuesto con ejemplos de código concretos
- [ ] El plan incluye criterios de aceptación, dependencias y archivos clave
- [] La entrada de la hoja de ruta existe en `docs/roadmap.md` con el formato correcto
- [] Se crea PR (si `create_pr` es verdadero)

## Resumen del proceso

1. Leer el contexto del proyecto (estado, hoja de ruta, arquitectura)
2. Detectar automáticamente el ID de la tarea en la hoja de ruta
3. Explore la base de código para obtener código relevante
4. Generar documento de plan de iteración.
5. Actualizar la hoja de ruta con una nueva entrada.
6. Opcionalmente validar con el equipo de analista + arquitecto.
7. Opcionalmente, cree sucursales, confirmaciones, envíos y relaciones públicas.
8. Resumen actual

## Pasos detallados

### 1. Leer el contexto del proyecto

Lea estos archivos para comprender el estado actual del proyecto:
- `docs/project-status.md` — fase actual, iteración, tareas completadas
- `docs/roadmap.md` — tareas existentes, prioridades, dependencias, formato
- `docs/architecture-notebook.md` — decisiones y limitaciones arquitectónicas

Registro:
- Fase actual (por ejemplo, "construcción")
- Número de iteración actual
- Convenciones de nomenclatura para ID de tareas en la fase actual

### 2. ID de tarea de detección automática

Si se proporciona `$ARGUMENTS[task_id]`, úselo directamente.

De lo contrario, realice la detección automática escaneando `docs/roadmap.md`:
1. Identifique el prefijo de fase actual en `docs/project-status.md` (por ejemplo, `C` para Construcción, `E` para Elaboración, `T` para Inicio)
2. Encuentre todos los ID de tareas que coincidan con el patrón `{prefijo}{iteración}-{secuencia}` (por ejemplo, `C3-001`, `C3-002`, `C3-003`)
3. Extraiga el número de secuencia más alto en la iteración actual.
4. Incremente en 1 para obtener el siguiente ID (por ejemplo, si el más alto es "C3-003", el siguiente es "C3-004")
5. Si no existen tareas para la iteración actual, comience en `001`

**Importante**: Escanee también la sección "Funciones futuras/acumuladas" en busca de ID `T-0XX` para evitar colisiones.

### 3. Explorar la base de código

Este es un paso crítico. El plan de iteración debe hacer referencia a archivos y códigos reales, no a descripciones abstractas.

Según el tema de la función ("$ARGUMENTS[topic]`), explore:
1. **Modelos**: Grep/Glob para modelos ActiveRecord relevantes, sus asociaciones, validaciones y alcances.
2. **Controladores**: busque controladores que manejen funciones relacionadas
3. **Servicios**: busque objetos de servicio en `app/services/` relacionados con la característica
4. **Vistas**: busque vistas y parciales relevantes
5. **Rutas**: consulte `config/routes.rb` para ver definiciones de rutas relacionadas
6. **Esquema** — Lea `db/schema.rb` para ver las definiciones de tablas relevantes
7. **Configuraciones regionales**: verifique `config/locales/en.yml` y `config/locales/es.yml` para ver las claves i18n existentes en el área
8. **Pruebas**: busque archivos de prueba existentes para el código afectado
9. **Config** — Verifique `config/app_settings.yml` u otros archivos de configuración si son relevantes

Extraiga fragmentos de código reales (con rutas de archivo y números de línea) para la sección "Estado actual" del plan.

### 4. Generar plan de iteración

Escriba el plan de iteración en `docs/iteration-plans/{task_id_lower}-{slug}.md` donde:
- `{task_id_lower}` es el ID de la tarea en minúscula (por ejemplo, `c3-004`)
- `{slug}` es un slug corto de kebab derivado del tema principal (por ejemplo, `pdf-export`)

Utilice esta estructura (que coincida con el formato establecido del proyecto):

```markdown
# {Task ID}: {Title}

**Fase**: {fase}
**Estado**: pendiente
**Objetivo**: {objetivo de una línea}
**Prioridad**: {prioridad}

---

## Contexto

{Por qué se necesita esta función. Antecedentes y motivación.}

---

## Estado actual

{Para cada área relevante, muestre el código actual real con rutas de archivo y números de línea.
Incluya definiciones de modelos, acciones del controlador, métodos de servicio, extractos de vista, rutas y esquemas.}

### {Área 1} (`ruta/al/archivo.rb`)

```ruby
# Current implementation
```

### {Área 2} (`ruta/al/archivo.rb`)

```ruby
# Current implementation
```

---

## Diseño propuesto

{Para cada cambio, muestre el código propuesto con un antes/después claro o un código nuevo.
Agrupar por unidades lógicas de trabajo (por ejemplo, Migración, Modelo, Servicio, Controlador, Vistas, i18n).}

### {Cambio 1}: {Descripción}

**Archivo**: `ruta/al/archivo.rb`

```ruby
# Proposed implementation
```

### {Cambio 2}: {Descripción}

**Nuevo archivo**: `ruta/al/nuevo_archivo.rb`

```ruby
# Proposed implementation
```

---

## i18n

Nuevas claves para `config/locales/en.yml`:

```yaml
en:
  # new keys
```

Nuevas claves para `config/locales/es.yml`:

```yaml
es:
  # new keys
```

---

## Criterios de aceptación

- [ ] {Criterio 1}
- [ ] {Criterio 2}
-[ ]...

---

## Estrategia de prueba

- {Categoría de prueba 1}: {qué probar}
- {Categoría de prueba 2}: {qué probar}

---

## Dependencias

- {ID de tarea} ({descripción} — {estado})

---

## Archivos clave

| Archivo | Cambiar |
|------|--------|
| `ruta/al/archivo` | {Descripción del cambio} |

---

## Fuera de alcance

- {Artículo 1}
- {Artículo 2}

---

## Preguntas abiertas

1. {Pregunta 1}
2. {Pregunta 2}
```

### 5. Actualizar la hoja de ruta

Inserte una nueva entrada en `docs/roadmap.md` en la sección de fase correcta.

Coincide exactamente con el formato existente:

```markdown
---

## {ID de tarea}: {Título}
**Estado**: pendiente
**Prioridad**: {prioridad}
**Descripción**: {descripción de 1 a 3 oraciones de la función}
- {Entregable clave 1}
- {Entregable clave 2}
-...

**Dependencias**: {ID de tarea separados por comas}

**Ver**: `docs/iteration-plans/{filename}.md`
```

**Reglas de colocación**:
- Insertar debajo del título de fase correcto (por ejemplo, "## Fase de construcción")
- Colocar después de la última entrada en esa sección de fase (antes del encabezado de la siguiente fase o del separador "---")
- Las tareas pendientes deberían aparecer después de las tareas completadas en la misma fase.

### 6. Validar con el equipo (opcional)

Sólo si `$ARGUMENTS[validar]` es `"verdadero"`:

1. **Cree un equipo** usando TeamCreate con el nombre `plan-review-{task_id}`
2. **Crear tareas de revisión**:
   - Tarea para analista: "Revisar la integridad de los requisitos para {task_id}"
   - Tarea para arquitecto: "Revisar la viabilidad técnica de {task_id}"
3. **Regenerar compañeros de equipo**:
   - Analista (tipo_subagente: `propósito general`, nombre_equipo, instrucciones de `.claude/teammates/analyst.md`):
     - Leer el plan de iteración generado.
     - Revisión de: requisitos completos, criterios de aceptación faltantes, alcance poco claro, impacto en las partes interesadas
     - Enviar los resultados por mensaje
   - Arquitecto (tipo_subagente: `propósito general`, nombre_equipo, instrucciones de `.claude/teammates/architect.md`):
     - Leer el plan de iteración generado y `docs/architecture-notebook.md`
     - Revisión de: viabilidad técnica, alineación arquitectónica, problemas de rendimiento, implicaciones de seguridad, riesgos de dependencia
     - Enviar los resultados por mensaje
4. **Espere a que se completen ambas revisiones**
5. **Incorporar comentarios**: actualice el plan de iteración con sugerencias válidas.
6. **Cerrar equipo**: envía solicitudes de cierre a ambos compañeros de equipo y luego elimina el equipo.

### 7. Crear sucursal y PR (opcional)

Sólo si `$ARGUMENTS[create_pr]` no es `"falso"` (el valor predeterminado es verdadero):

1. **Crear rama**: `docs/{task_id_lower}-{slug}` (usa el prefijo `docs/` ya que es solo documentación)
   ```golpecito
   git checkout -b docs/{task_id_lower}-{slug}
   ```

2. **Preparación y compromiso**:
   ```golpecito
   git add docs/iteration-plans/{nombre de archivo}.md docs/roadmap.md
   git commit -m "docs: agregar plan de iteración y entrada de hoja de ruta para {task_id}"
   ```

3. **Empujar rama**:
   ```golpecito
   git push -u documentos de origen/{task_id_lower}-{slug}
   ```

4. **Crear relaciones públicas**:
   ```golpecito
   gh pr crear \
     --title "docs: {ID de tarea} — {Título}" \
     --cuerpo "$(gato <<'EOF'
   ## Resumen

- Agregar plan de iteración para {ID de tarea}: {Título}
   - Agregar entrada de hoja de ruta en la fase {Fase}

## Archivos

- `docs/iteration-plans/{filename}.md` — plan de implementación detallado
   - `docs/roadmap.md` — nueva entrada de hoja de ruta

## Notas de revisión

Este es un PR de planificación (solo documentación). Revise el plan de iteración para:
   - Integridad del diseño propuesto.
   - Precisión del análisis del estado actual.
   - Viabilidad de los criterios de aceptación.

🤖 Generado con [Código Claude](https://claude.com/claude-code)
   EOF
   )"
   ```

### 8. Resumen actual

Envíe un resumen al usuario:

```
## Feature Plan Created

- **ID de tarea**: {task_id}
- **Título**: {título}
- **Prioridad**: {prioridad}
- **Plan de iteración**: `docs/iteration-plans/{filename}.md`
- **Hoja de ruta**: `docs/roadmap.md` actualizado
- **Sucursal**: `docs/{task_id_lower}-{slug}` (si se creó)
- **PR**: {URL PR} (si se crea)
- **Validado**: {sí/no}

### Próximos pasos
- Revisar el plan de iteración.
- Cuando esté listo para implementar: `/openup-start-iteration task_id: {task_id}`
```

## Producción

Devuelve un resumen de:
- ID de tarea (detectada automáticamente o proporcionada)
- Ruta del archivo del plan de iteración
- Ubicación de entrada de la hoja de ruta
- Nombre de la sucursal (si se creó)
- URL de relaciones públicas (si se creó)
- Resultados de la validación (si están validados)

## Errores comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Colisión de ID de tarea | La identificación detectada automáticamente ya existe | Proporcione el argumento `task_id` explícito |
| Error de análisis de la hoja de ruta | Formato de hoja de ruta inesperado | Verifique que `docs/roadmap.md` siga el formato estándar |
| No se encontró ningún código relevante | La característica es completamente nueva | El plan tendrá un "estado actual" mínimo; se centrará en el "diseño propuesto" |
| Falló la generación del equipo | Equipos de agentes no habilitados | Establezca `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` para validación |
| La creación de relaciones públicas falló | No hay control remoto o gh no instalado | Utilice `create_pr: false` y cree PR manualmente |

## Referencias

- Planes de iteración: `docs/iteration-plans/`
- Hoja de ruta: `docs/roadmap.md`
- Estado del proyecto: `docs/project-status.md`
- Cuaderno de Arquitectura: `docs/architecture-notebook.md`

## Ver también

- [openup-start-iteration](../openup-start-iteration/SKILL.md) — Comience a implementar una tarea planificada
- [openup-create-iteration-plan](../openup-create-iteration-plan/SKILL.md) — Planificación de iteración genérica (nivel de fase)
- [openup-complete-task](../openup-complete-task/SKILL.md) — Marcar la tarea como completada después de la implementación
- [openup-create-pr](../openup-create-pr/SKILL.md) — Crea relaciones públicas con el contexto de la hoja de ruta

# Quick Task - Fast Iteration Mode

**Quick Task** is a lightweight workflow for small changes and rapid iteration. It combines multiple steps into a single command while maintaining essential OpenUP practices.

## When to Use

Use Quick Task for:
- Small bug fixes (< 50 lines changed)
- Documentation updates
- Configuration changes
- Quick experiments
- Hot fixes

**Target**: Complete tasks in 50% less time than standard workflow.

## When NOT to Use

Do NOT use for:
- New features (use standard workflow)
- Major refactoring (use `/openup-start-iteration`)
- Tasks requiring architecture review (use full team)
- Multi-hour development work

## Process

### 1. Quick Context Load

```bash
# Load minimal context only
python3 .claude/scripts/batch-context.py --minimal
```

### 2. Quick Branch (optional)

If not skipping branching:
```bash
# Detect trunk and create quick branch
BRANCH_NAME="quick/$(date +%Y%m%d-%H%M%S)-$(echo $task | tr ' ' '-' | head -c 20)"
git checkout -b $BRANCH_NAME
```

### 3. Execute Task

Implement the change:
- Read task description
- Make necessary changes
- Verify the fix works

### 4. Quick Commit (optional)

If not skipping commit:
```bash
git add .
git commit -m "quick: $task

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
```

### 5. Quick Log (optional)

If not skipping logging:
```bash
echo "$(date -Iseconds) | quick-task | $task" >> docs/agent-logs/quick-tasks.log
```

## Output

Returns:
- Task completed confirmation
- Files changed (count)
- Branch name (if created)
- Commit hash (if committed)

## Comparison: Standard vs Quick

| Step | Standard Workflow | Quick Task |
|------|-------------------|------------|
| Read project-status | Full document | Minimal only |
| Create branch | Task-based naming | Timestamp-based |
| SOP compliance | Full Start-of-Run | Skipped |
| Documentation | Full update | Minimal |
| Log entry | Full JSONL | Simple log line |
| **Typical time** | ~8 minutes | ~4 minutes |

## Examples

### Quick Bug Fix
```
/openup-quick-task task: "Fix typo in README.md"
```

### Documentation Update
```
/openup-quick-task task: "Update API docs for new endpoint"
```

### Skip Branching
```
/openup-quick-task task: "Add comment to utils.py" skip_branch: true
```

### Full Control
```
/openup-quick-task task: "Hot fix auth bug" skip_commit: false skip_logging: true
```

## Success Criteria

- [ ] Task completed
- [ ] Changes verified
- [ ] Branch created (if not skipped)
- [ ] Committed (if not skipped)
- [ ] Logged (if not skipped)

## Smart Features

**Auto-detect skip opportunities:**
- If already on feature branch → skip branching
- If no git changes → skip commit
- If single file change → minimal logging

**Auto-categorize task:**
- Bug fixes → `bugfix/` prefix
- Docs → `docs/` prefix
- Hot fixes → `hotfix/` prefix

## See Also

- [openup-start-iteration](../start-iteration/SKILL.md) - Full iteration workflow
- [openup-complete-task](../complete-task/SKILL.md) - Task completion with PR
- [openup-tdd-workflow](../tdd-workflow/SKILL.md) - TDD cycle

# Tarea rápida: modo de iteración rápida

**Quick Task** es un flujo de trabajo liviano para pequeños cambios e iteraciones rápidas. Combina varios pasos en un solo comando manteniendo las prácticas esenciales de OpenUP.

## Cuándo utilizar

Utilice tarea rápida para:
- Pequeñas correcciones de errores (<50 líneas cambiadas)
- Actualizaciones de documentación.
- Cambios de configuración
- Experimentos rápidos
- Correcciones urgentes

**Objetivo**: completar tareas en un 50% menos de tiempo que el flujo de trabajo estándar.

## Cuándo NO usarlo

NO lo use para:
- Nuevas funciones (use el flujo de trabajo estándar)
- Refactorización importante (use `/openup-start-iteration`)
- Tareas que requieren revisión de arquitectura (usar equipo completo)
- Trabajo de desarrollo de varias horas.

## Proceso

### 1. Carga rápida de contexto

```bash
# Load minimal context only
python3 .claude/scripts/batch-context.py --minimal
```

### 2. Rama rápida (opcional)

Si no omite la ramificación:
```golpecito
# Detectar tronco y crear rama rápida
BRANCH_NAME="quick/$(fecha +%Y%m%d-%H%M%S)-$(echo $tarea | tr ' ' '-' | head -c 20)"
git pago -b $BRANCH_NAME
```

### 3. Ejecutar tarea

Implementar el cambio:
- Leer la descripción de la tarea.
- Hacer los cambios necesarios
- Verificar que la solución funcione.

### 4. Confirmación rápida (opcional)

Si no se salta el compromiso:
```golpecito
git agregar.
git commit -m "rápido: $tarea

Coautor de: Claude Opus 4.6 <noreply@anthropic.com>"
```

### 5. Registro rápido (opcional)

Si no omite el registro:
```golpecito
echo "$(fecha -Isegundos) | tarea rápida | $tarea" >> docs/agent-logs/quick-tasks.log
```

## Producción

Devoluciones:
- Confirmación de tarea completada
- Archivos cambiados (recuento)
- Nombre de la sucursal (si se creó)
- Confirmar hash (si se confirma)

## Comparación: estándar versus rápido

| Paso | Flujo de trabajo estándar | Tarea rápida |
|------|-------------------|------------|
| Leer el estado del proyecto | Documento completo | Sólo mínimo |
| Crear sucursal | Denominación basada en tareas | Basado en marca de tiempo |
| Cumplimiento de los POE | Inicio de ejecución completo | Saltado |
| Documentación | Actualización completa | Mínimo |
| Entrada de registro | JSONL completo | Línea de registro simple |
| **Hora típica** | ~8 minutos | ~4 minutos |

## Ejemplos

### Corrección rápida de errores
```
/tarea openup-quick-task: "Corregir error tipográfico en README.md"
```

### Actualización de documentación
```
/tarea openup-quick-task: "Actualizar documentos API para un nuevo punto final"
```

### Saltar ramificación
```
/tarea openup-quick-task: "Agregar comentario a utils.py" skip_branch: verdadero
```

### Control total
```
/tarea openup-quick-task: "Error de autenticación de corrección urgente" skip_commit: false skip_logging: true
```

## Criterios de éxito

- [] Tarea completada
- [] Cambios verificados
- [] Rama creada (si no se omite)
- [] Comprometido (si no se omite)
- [] Registrado (si no se omite)

## Funciones inteligentes

**Detección automática de oportunidades de omisión:**
- Si ya está en la rama de funciones → omitir la rama
- Si no hay cambios en git → omitir confirmación
- Si se cambia un solo archivo → registro mínimo

**Tarea de categorización automática:**
- Corrección de errores → prefijo `bugfix/`
- Documentos → prefijo `docs/`
- Correcciones urgentes → prefijo `hotfix/`

## Ver también

- [openup-start-iteration](../start-iteration/SKILL.md) - Flujo de trabajo de iteración completo
- [openup-complete-task](../complete-task/SKILL.md) - Finalización de tareas con PR
- [openup-tdd-workflow](../tdd-workflow/SKILL.md) - Ciclo TDD

# Request Input

Create an input request document for asynchronous stakeholder communication.

## Process

### 1. Generate Filename

Format: `docs/input-requests/YYYY-MM-DD-<short-topic>.md` (derive topic from `$ARGUMENTS[title]`).

### 2. Fill Frontmatter

```yaml
---
title: "$ARGUMENTS[title]"
created: "<current-timestamp-ISO8601>"
created_by: "agent-name"
status: pending
run_id: "<current-run-id>"
related_task: "$ARGUMENTS[related_task]"  # optional
---
```

### 3. Write Context Section

Use `$ARGUMENTS[context]` to explain current task/phase, what information is needed, and why.

### 4. Add Questions

For each question in `$ARGUMENTS[questions]`, use the appropriate format:

**multiple-choice**: `### Q[N]: [Title]` with `**Type**: multiple-choice`, checkbox options (`- [ ] \`option\` - Description`), and `**Answer**:` placeholder.

**text**: `### Q[N]: [Title]` with `**Type**: text`, optional `**Example**:`, and `**Answer**:` placeholder.

**reference**: `### Q[N]: [Title]` with `**Type**: reference`, `**Accepts**: Path or URL`, and `**Answer**:` placeholder.

### 5. Include Instructions

Add instructions for respondent:
1. Fill in Answer section for each question
2. Update status from `pending` to `answered`
3. Save the file
4. Tell the agent to continue

### 6. Notify User

Inform user of document location and how to proceed.

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| Invalid questions format | JSON array malformed | Verify valid JSON array |
| Missing context | Context not provided | Provide context argument |
| Directory not found | docs/input-requests/ missing | Create directory first |

## References

- Asynchronous Input SOP: `docs-eng-process/agent-workflow.md`
- Input Request Template: `docs-eng-process/templates/input-request.md`

## See Also

- [openup-start-iteration](../start-iteration/SKILL.md) - Process answered requests when starting iteration
- [openup-complete-task](../complete-task/SKILL.md) - Check for answered input before completing

# Solicitar entrada

Cree un documento de solicitud de entrada para la comunicación asincrónica con las partes interesadas.

## Proceso

### 1. Generar nombre de archivo

Formato: `docs/input-requests/AAAA-MM-DD-<short-topic>.md` (tema derivado de `$ARGUMENTS[title]`).

### 2. Rellenar el frontmatter

```yaml
---
title: "$ARGUMENTS[title]"
created: "<current-timestamp-ISO8601>"
created_by: "agent-name"
status: pending
run_id: "<current-run-id>"
related_task: "$ARGUMENTS[related_task]"  # optional
---
```

### 3. Escribir sección de contexto

Utilice `$ARGUMENTS[context]` para explicar la tarea/fase actual, qué información se necesita y por qué.

### 4. Agregar preguntas

Para cada pregunta en `$ARGUMENTS[questions]`, utilice el formato apropiado:

**elección múltiple**: `### Q[N]: [Título]` con `**Tipo**: opción múltiple`, opciones de casilla de verificación (`- [ ] \`opción\` - Descripción`) y `**Respuesta**:` marcador de posición.

**text**: `### Q[N]: [Título]` con `**Tipo**: texto`, `**Ejemplo**:` opcional y marcador de posición `**Respuesta**:`.

**referencia**: `### Q[N]: [Título]` con `**Tipo**: referencia`, `**Acepta**: Ruta o URL` y `**Respuesta**:` marcador de posición.

### 5. Incluir instrucciones

Agregue instrucciones para el encuestado:
1. Complete la sección de Respuestas para cada pregunta.
2. Actualizar el estado de "pendiente" a "respondido"
3. Guarde el archivo
4. Dígale al agente que continúe

### 6. Notificar al usuario

Informar al usuario de la ubicación del documento y cómo proceder.

## Errores comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Formato de preguntas no válido | Matriz JSON mal formada | Verificar matriz JSON válida |
| Falta contexto | Contexto no proporcionado | Proporcionar argumento de contexto |
| Directorio no encontrado | documentos/solicitudes de entrada/faltantes | Crear directorio primero |

## Referencias

- SOP de entrada asincrónica: `docs-eng-process/agent-workflow.md`
- Plantilla de solicitud de entrada: `docs-eng-process/templates/input-request.md`

## Ver también

- [openup-start-iteration](../start-iteration/SKILL.md) - Procesar solicitudes respondidas al iniciar la iteración
- [openup-complete-task](../complete-task/SKILL.md) - Verifique las respuestas antes de completar

# Retrospective

Generate an iteration retrospective capturing what went well, what to improve, and action items.

## Process

### 1. Determine Iteration

If `$ARGUMENTS[iteration_number]` is provided, use it. Otherwise read `docs/project-status.md` for the current iteration number.

### 2. Read Project Context

Read `docs/project-status.md` for: iteration goal, dates, team members, overall status.

### 3. Analyze Completed Tasks

Read `docs/roadmap.md` to identify: tasks planned, completed, not completed, and added during iteration. Note complexity, challenges, and successes for each.

### 4. Gather Feedback

Review these sources for patterns and issues:
- `docs/agent-logs/` - Agent run logs
- `docs/risk-list.md` - Risks emerged or mitigated
- `docs/roadmap.md` - Velocity (completed vs planned), blocked items
- Git commit messages

### 5. Collect Metrics (if `$ARGUMENTS[include_metrics] == "true"`)

```bash
# Commits in iteration period
git log --oneline --since="$start_date" --until="$end_date" | wc -l

# Lines changed
git diff --stat trunk...HEAD

# Active contributors
git shortlog -sn --since="$start_date" --until="$end_date"
```

Task metrics: tasks planned, tasks completed, completion rate (completed / planned * 100%).

### 6. Create Retrospective Document

Create `docs/iteration-retrospectives/iteration-{n}-retrospective.md` with sections:
- **Iteration Overview**: number, date range, goal, participants
- **Summary**: overall assessment, key achievements, major challenges
- **What Went Well**: process, technical, collaboration successes
- **What to Improve**: process issues, technical challenges, gaps
- **Action Items**: specific action, owner, due date, priority for each improvement
- **Metrics** (if included): task completion stats, git stats
- **Next Iteration Considerations**: carry forward, changes, risks to monitor

### 7. Update Project Status

In `docs/project-status.md`: add link to retrospective, note ongoing action items, update iteration status.

## Output

Returns: retrospective document path, counts of what went well / what to improve / action items, overall iteration rating, key metrics (if included).

## See Also

- [openup-start-iteration](../start-iteration/SKILL.md) - Start next iteration
- [openup-complete-task](../complete-task/SKILL.md) - Complete iteration tasks
- [openup-assess-completeness](../assess-completeness/SKILL.md) - Assess iteration completeness before retrospective
- [openup-create-iteration-plan](../openup-artifacts/create-iteration-plan/SKILL.md) - Plan next iteration based on retrospective

# Retrospectiva

Genere una retrospectiva de iteraciones que capture lo que salió bien, qué mejorar y los elementos de acción.

## Proceso

### 1. Determinar la iteración

Si se proporciona `$ARGUMENTS[iteration_number]`, úselo. De lo contrario, lea `docs/project-status.md` para conocer el número de iteración actual.

### 2. Leer el contexto del proyecto

Lea `docs/project-status.md` para conocer: objetivo de la iteración, fechas, miembros del equipo y estado general.

### 3. Analizar tareas completadas

Lea `docs/roadmap.md` para identificar: tareas planificadas, completadas, no completadas y agregadas durante la iteración. Tenga en cuenta la complejidad, los desafíos y los éxitos de cada uno.

### 4. Recopile comentarios

Revise estas fuentes para detectar patrones y problemas:
- `docs/agent-logs/` - Registros de ejecución del agente
- `docs/risk-list.md` - Riesgos surgidos o mitigados
- `docs/roadmap.md` - Velocidad (completada vs planificada), elementos bloqueados
- Mensajes de confirmación de Git

### 5. Recopilar métricas (si `$ARGUMENTS[include_metrics] == "true"`)

```bash
# Commits in iteration period
git log --oneline --since="$start_date" --until="$end_date" | wc -l

# Líneas cambiadas
git diff --stat tronco...CABEZA

# Colaboradores activos
git shortlog -sn --since="$fecha_inicio" --until="$fecha_final"
```

Métricas de tareas: tareas planificadas, tareas completadas, tasa de finalización (completada/planificada * 100%).

### 6. Crear documento retrospectivo

Cree `docs/iteration-retrospectives/iteration-{n}-retrospective.md` con secciones:
- **Resumen de la iteración**: número, intervalo de fechas, objetivo, participantes
- **Resumen**: evaluación general, logros clave, principales desafíos
- **Lo que salió bien**: éxitos de proceso, técnicos y de colaboración
- **Qué mejorar**: problemas de proceso, desafíos técnicos, brechas
- **Elementos de acción**: acción específica, propietario, fecha de vencimiento, prioridad para cada mejora
- **Métricas** (si se incluyen): estadísticas de finalización de tareas, estadísticas de git
- **Consideraciones para la próxima iteración**: transferencia, cambios, riesgos a monitorear

### 7. Actualizar el estado del proyecto

En `docs/project-status.md`: agregue un enlace a la retrospectiva, observe los elementos de acción en curso, actualice el estado de la iteración.

## Producción

Devoluciones: ruta del documento retrospectivo, recuentos de lo que salió bien/qué mejorar/elementos de acción, calificación general de la iteración, métricas clave (si se incluyen).

## Ver también

- [openup-start-iteration](../start-iteration/SKILL.md) - Iniciar la siguiente iteración
- [openup-complete-task](../complete-task/SKILL.md) - Completar tareas de iteración
- [openup-assess-completeness](../assess-completeness/SKILL.md) - Evaluar la integridad de la iteración antes de la retrospectiva
- [openup-create-iteration-plan](../openup-artifacts/create-iteration-plan/SKILL.md) - Planifica la próxima iteración en función de la retrospectiva

# Visión Compartida

Esta skill crea un documento de visión técnica compartida que asegura la alineación entre los interesados y el equipo de desarrollo sobre objetivos técnicos, alcance y decisiones clave.

## Cuándo Usar

Usa esta skill cuando:
- El documento de visión existe pero necesita elaboración técnica
- Necesites definir el alcance DENTRO/FUERA claramente
- Comiences la fase de Elaboración y necesites alineación técnica
- Los miembros del equipo tengan diferente comprensión de la dirección técnica
- Necesites documentar decisiones técnicas clave y restricciones

## Cuándo NO Usar

NO uses esta skill cuando:
- No existe documento de visión (usa `/openup-create-vision` primero)
- Estés en las fases de Construcción tardía o Transición (ya debería existir)
- Solo necesites detalles de arquitectura (usa `/openup-create-architecture-notebook`)
- La visión ya está bien definida y comprendida

## Criterios de Éxito

Tras usar esta skill, verifica:
- [ ] Los objetivos técnicos están claramente documentados
- [ ] El alcance DENTRO/FUERA está bien definido
- [ ] Las suposiciones y restricciones técnicas están listadas
- [ ] Las decisiones técnicas clave tienen justificación
- [ ] Las preguntas abiertas están registradas para elaboración
- [ ] El documento está enlazado desde la visión principal

## Resumen del Proceso

1. Leer el documento de visión existente
2. Extraer el contexto y los objetivos técnicos
3. Definir el alcance DENTRO/FUERA
4. Documentar suposiciones y restricciones técnicas
5. Registrar decisiones técnicas clave
6. Identificar preguntas abiertas

## Pasos Detallados

### 1. Leer la Visión Existente

Leer `docs/vision.md` para comprender:
- Planteamiento del problema del proyecto
- Necesidades de los interesados
- Objetivos de negocio
- Estado actual del proyecto

### 2. Extraer Contexto Técnico

De la visión y el estado del proyecto, identificar:

**Objetivos Técnicos:**
- ¿Qué problemas técnicos necesitan resolverse?
- ¿Cuáles son los atributos de calidad clave (rendimiento, seguridad, escalabilidad)?
- ¿Qué criterios de éxito técnicos existen?

**Si se proporciona `$ARGUMENTS[technical_objectives]`:**
- Centrarse en esos objetivos específicos
- Añadir objetivos técnicos relacionados

**Ejemplos:**
- "Lograr tiempos de respuesta inferiores a un segundo"
- "Soportar 10.000 usuarios concurrentes"
- "Garantizar cifrado de datos en reposo y en tránsito"

### 3. Definir Alcance DENTRO/FUERA

Crear límites claros de lo que se incluye y lo que se excluye:

**DENTRO del Alcance:**
¿Qué funcionalidades y capacidades están definitivamente incluidas?
- Usar `$ARGUMENTS[scope_focus]` como punto de partida si se proporciona
- Listar funcionalidades, capacidades y tecnologías específicas
- Ser específico sobre lo que significa "dentro del alcance"

**FUERA del Alcance:**
¿Qué se excluye explícitamente para gestionar expectativas?
- Funcionalidades que explícitamente NO se van a construir
- Tecnologías que no se utilizarán
- Capacidades que están fuera del alcance de este proyecto

### 4. Documentar Suposiciones Técnicas

Registrar suposiciones sobre el entorno técnico:

| Suposición | Impacto | Validado Por |
|------------|---------|--------------|
| Ejemplo: PostgreSQL disponible | Bajo - afecta capa de datos | DBA |
| Ejemplo: Usuarios en navegadores modernos | Medio - afecta frontend | Investigación UX |

### 5. Documentar Restricciones Técnicas

Registrar restricciones conocidas que limitan las opciones:

| Restricción | Descripción | Mitigación |
|-------------|-------------|------------|
| Ejemplo: Presupuesto para servicios en la nube | Debe usar soluciones rentables | Arquitectura serverless |
| Ejemplo: Integración con sistema legado | Debe funcionar con APIs existentes | Patrón adaptador |

### 6. Registrar Decisiones Técnicas Clave

Documentar decisiones técnicas significativas con justificación:

**Ejemplos:**
- Elección del lenguaje de programación
- Estilo arquitectónico (microservicios vs monolito)
- Selección de base de datos
- Enfoque de despliegue

Para cada decisión:
- Qué se decidió
- Por qué (justificación)
- Alternativas consideradas
- Compromisos aceptados

### 7. Identificar Preguntas Abiertas

Listar preguntas que necesitan respuesta durante la elaboración:

| Pregunta | Impacto | Fase Objetivo |
|----------|---------|---------------|
| Ejemplo: ¿Cómo gestionar el modo sin conexión? | Alto - afecta la arquitectura | Elaboración |
| Ejemplo: ¿Límites de la API de terceros? | Medio - afecta el diseño | Elaboración |

### 8. Crear Documento de Visión Compartida

Crear `docs/shared-vision.md` usando la plantilla de visión compartida con:
- Tabla de objetivos técnicos
- Secciones de alcance DENTRO/FUERA
- Tablas de suposiciones y restricciones
- Decisiones técnicas clave
- Preguntas abiertas

### 9. Enlazar desde la Visión Principal

Añadir una referencia en `docs/vision.md`:
```markdown
## Visión Técnica

Consulta la [Visión Compartida](shared-vision.md) para objetivos técnicos detallados, alcance y decisiones.
```

## Salida

Devuelve un resumen de:
- Documento de visión compartida creado en `docs/shared-vision.md`
- Objetivos técnicos documentados
- Alcance DENTRO/FUERA definido
- Decisiones clave registradas
- Preguntas abiertas identificadas

## Ejemplo de Uso

```
/openup-shared-vision technical_objectives: "escalabilidad, seguridad" scope_focus: "autenticación de usuarios"
```

## Errores Comunes

| Error | Causa | Solución |
|-------|-------|----------|
| Visión no encontrada | docs/vision.md no existe | Crear primero la visión con /openup-create-vision |
| Demasiado vago | Objetivos no suficientemente específicos | Añadir criterios medibles |
| Falta alcance FUERA | Solo se definió el alcance DENTRO | Definir siempre ambos DENTRO y FUERA |
| Sin justificación | Decisiones sin fundamentación | Añadir el porqué y las alternativas consideradas |

## Referencias

- Plantilla de Visión Compartida: `docs-eng-process/templates/shared-vision.md`
- Plantilla de Visión: `docs-eng-process/templates/vision.md`
- Plantilla de Cuaderno de Arquitectura: `docs-eng-process/templates/architecture-notebook.md`

## Ver También

- [openup-create-vision](../create-vision/SKILL.md) - Crear primero la visión del proyecto
- [openup-create-architecture-notebook](../create-architecture-notebook/SKILL.md) - Crear documentación de arquitectura detallada
- [openup-elaboration](../../openup-phases/elaboration/SKILL.md) - Actividades de la fase de Elaboración

#Visión Compartida

Esta habilidad crea un documento de visión técnica compartida que asegura la alineación entre los interesados ​​y el equipo de desarrollo sobre objetivos técnicos, alcance y decisiones clave.

## Cuándo usar

Usa esta habilidad cuando:
- El documento de visión existe pero necesita elaboración técnica.
- Necesites definir el alcance DENTRO/FUERA claramente
- Comienza la fase de Elaboración y necesitas alineación técnica.
- Los miembros del equipo tienen diferente comprensión de la dirección técnica.
- Necesidades documentales decisiones técnicas clave y restricciones

## Cuándo NO Usar

NO usa esta habilidad cuando:
- No existe documento de visión (usa `/openup-create-vision` primero)
- Estés en las fases de Construcción tardía o Transición (ya debería existir)
- Solo necesitas detalles de arquitectura (usa `/openup-create-architecture-notebook`)
- La visión ya está bien definida y comprendida

## Criterios de Éxito

Tras usar esta habilidad, verifica:
- [ ] Los objetivos técnicos están claramente documentados
- [ ] El alcance DENTRO/FUERA está bien definido
- [ ] Las suposiciones y restricciones técnicas están listadas
- [ ] Las decisiones técnicas clave tienen justificación
- [ ] Las preguntas abiertas están registradas para elaboración
- [ ] El documento está enlazado desde la visión principal

## Resumen del Proceso

1. Leer el documento de visión existente
2. Extraer el contexto y los objetivos técnicos
3. Definir el alcance DENTRO/FUERA
4. Documental suposiciones y restricciones técnicas
5. Registrador decisiones técnicas clave
6. Identificar preguntas abiertas

## Pasos Detallados

### 1. Leer la Visión Existente

Leer `docs/vision.md` para comprender:
- Planteamiento del problema del proyecto.
- Necesidades de los interesados
- Objetivos de negocio
- Estado actual del proyecto

### 2. Contexto Técnico Extraer

De la visión y el estado del proyecto, identifique:

**Objetivos Técnicos:**
- ¿Qué problemas técnicos necesitan resolverse?
- ¿Cuáles son los atributos de calidad clave (rendimiento, seguridad, escalabilidad)?
- ¿Qué criterios de éxito técnico existen?

**Si se proporciona `$ARGUMENTS[technical_objectives]`:**
- Centrarse en esos objetivos específicos
- Añadir objetivos técnicos relacionados

**Ejemplos:**
- "Lograr tiempos de respuesta inferiores a un segundo"
- "Soportar 10.000 usuarios concurrentes"
- "Garantizar cifrado de datos en reposo y en tránsito"

### 3. Definir Alcance DENTRO/FUERA

Crear límites claros de lo que se incluye y lo que se excluye:

**DENTRO del Alcance:**
¿Qué funcionalidades y capacidades están definitivamente incluidas?
- Usar `$ARGUMENTS[scope_focus]` como punto de partida si se proporciona
- Listar funcionalidades, capacidades y tecnologías específicas
- Ser específico sobre lo que significa "dentro del alcance"

**FUERA del Alcance:**
¿Qué se excluye exclusivamente para gestionar las expectativas?
- Funcionalidades que específicamente NO se van a construir
- Tecnologías que no se utilizarán
- Capacidades que están fuera del alcance de este proyecto

### 4. Documental Suposiciones Técnicas

Suposiciones del registrador sobre el entorno técnico:

| Suposición | Impacto | Validado Por |
|------------|---------|--------------|
| Ejemplo: PostgreSQL disponible | Bajo - afecta capa de datos | Administrador de bases de datos |
| Ejemplo: Usuarios en navegadores modernos | Medio - afecta frontend | Investigación UX |

### 5. Documental Restricciones Técnicas

Registrar restricciones conocidas que limitan las opciones:

| Restricción | Descripción | Mitigación |
|-------------|-------------|------------|
| Ejemplo: Presupuesto para servicios en la nube | Debe usar soluciones rentables | Arquitectura sin servidor |
| Ejemplo: Integración con sistema legado | Debe funcionar con API existentes | Patrón adaptador |

### 6. Decisiones del Registrador Técnicas Clave

Documentar decisiones técnicas significativas con justificación:

**Ejemplos:**
- Elección del lenguaje de programación
- Estilo arquitectónico (microservicios vs monolito)
- Selección de base de datos
- Enfoque de despliegue

Para cada decisión:
- Qué se decidió
- Por qué (justificación)
- Alternativas consideradas
- Compromisos aceptados

### 7. Identificar Preguntas Abiertas

Listar preguntas que necesitan respuesta durante la elaboración:

| Pregunta | Impacto | Fase Objetivo |
|----------|---------|---------------|
| Ejemplo: ¿Cómo gestionar el modo sin conexión? | Alto - afecta la arquitectura | Elaboración |
| Ejemplo: ¿Límites de la API de terceros? | Medio - afecta el diseño | Elaboración |

### 8. Crear Documento de Visión Compartida

Crear `docs/shared-vision.md` usando la plantilla de visión compartida con:
- Tabla de objetivos técnicos
- Secciones de alcance DENTRO/FUERA
- Tablas de suposiciones y restricciones
- Decisiones técnicas clave
- Preguntas abiertas

### 9. Enlázar desde la Visión Principal

Añadir una referencia en `docs/vision.md`:
```rebaja
##Visión Técnica

Consulta la [Visión Compartida](shared-vision.md) para objetivos técnicos detallados, alcance y decisiones.
```

##Salida

Devuelve un resumen de:
- Documento de visión compartido creado en `docs/shared-vision.md`
- Objetivos técnicos documentados
- Alcance DENTRO/FUERA definido
- Decisiones claves registradas
- Preguntas abiertas identificadas

## Ejemplo de uso

```
/openup-shared-vision technical_objectives: "escalabilidad, seguridad" scope_focus: "autenticación de usuarios"
```

## Errores Comunes

| Error | causa | Solución |
|-------|-------|----------|
| Visión no encontrada | docs/vision.md no existe | Crear primero la visión con /openup-create-vision |
| Demasiado vago | Objetivos no suficientemente específicos | Añadir criterios medicinales |
| Falta alcance FUERA | Solo se definió el alcance DENTRO | Definir siempre ambos DENTRO y FUERA |
| Sin justificación | Decisiones sin fundamento | Añadir el porqué y las alternativas consideradas |

## Referencias

- Plantilla de Visión Compartida: `docs-eng-process/templates/shared-vision.md`
- Plantilla de Visión: `docs-eng-process/templates/vision.md`
- Plantilla de Cuaderno de Arquitectura: `docs-eng-process/templates/architecture-notebook.md`

## Ver También

- [openup-create-vision](../create-vision/SKILL.md) - Crear primero la visión del proyecto
- [openup-create-architecture-notebook](../create-architecture-notebook/SKILL.md) - Crear documentación de arquitectura detallada
- [openup-elaboration](../../openup-phases/elaboration/SKILL.md) - Actividades de la fase de Elaboración

# Start Iteration

Initialize a new OpenUP iteration: read project state, create a task branch, and begin work.

## Success Criteria

After this skill completes, ALL of these must be true:

- [ ] Project status is updated with new iteration
- [ ] **BLOCKING CHECK**: `git rev-parse --abbrev-ref HEAD` returns a non-trunk branch name (not `main`, `master`, or whatever trunk is). If it returns trunk, the skill has FAILED — do not proceed.
- [ ] Iteration goal is defined
- [ ] Answered input requests are processed
- [ ] Log entry is created

## Process

### 1. Read Project Status

Read `docs/project-status.md` to establish context:
- Current phase (inception | elaboration | construction | transition)
- Current iteration number
- Previous iteration status

### 2. Read Roadmap and Identify Task

Read `docs/roadmap.md` to:
- Find the task specified by `$ARGUMENTS[task_id]`
- Extract task details: title, description, task type (feature, bugfix, refactor, etc.)
- Determine priority and dependencies
- **If task_id not found**: Ask user to specify which task from the roadmap

### 3. Create Task Branch

**Execute these commands in order:**

```bash
# 1. Detect trunk
TRUNK=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
[ -z "$TRUNK" ] && TRUNK="main"
git rev-parse --verify "$TRUNK" 2>/dev/null || TRUNK="master"

# 2. Switch to trunk and pull latest
git checkout "$TRUNK"
git pull origin "$TRUNK" 2>/dev/null || true

# 3. Create branch (see branching.md for naming patterns)
git checkout -b {type}/{task_id}-{short-description}

# 4. VERIFY — this must NOT return trunk
git rev-parse --abbrev-ref HEAD
```

**If the branch already exists**, check its status:
- No unmerged commits → delete and recreate from trunk
- Has unmerged commits → create PR or merge first, then create new branch

### 4. Check for Answered Input Requests

Check `docs/input-requests/` for files with `status: answered`. Process any answered requests before continuing.

### 5. Initialize Iteration

Update `docs/project-status.md`:
- Increment `iteration` or use provided `$ARGUMENTS[iteration_number]`
- Set `iteration_goal` to provided `$ARGUMENTS[goal]` or derive from roadmap task
- Set `status` to `in-progress`
- Set `current_task` to the task_id
- Update `iteration_started` to today's date

### 6. Log Initialization

Create an entry in `docs/agent-logs/agent-runs.jsonl` documenting the iteration start with task context.

### 7. Deploy Team (Optional)

If `$ARGUMENTS[deploy_team]` is `true` or `$ARGUMENTS[team]` is specified:

1. Determine team composition based on `$ARGUMENTS[team]` or current phase:
   - **feature**: analyst, architect, developer, tester
   - **investigation**: architect, developer, tester
   - **construction**: developer, tester
   - **elaboration**: architect, developer, tester
   - **inception**: analyst, project-manager
   - **transition**: tester, project-manager, developer
   - **planning**: project-manager, analyst
   - **full**: all roles

2. Deploy the team using Task tool, brief each teammate with iteration context.

## Output

Returns a summary of:
- Current phase and iteration number
- Task being worked on (task_id, title)
- Iteration goal
- Active branch name (must be a non-trunk task branch)

## See Also

- [openup-complete-task](../complete-task/SKILL.md) - Complete iteration tasks
- [openup-create-iteration-plan](../../openup-artifacts/create-iteration-plan/SKILL.md) - Plan iteration before starting

# Iniciar iteración

Inicialice una nueva iteración de OpenUP: lea el estado del proyecto, cree una rama de tareas y comience a trabajar.

## Criterios de éxito

Una vez completada esta habilidad, TODO lo siguiente debe ser cierto:

- [] El estado del proyecto se actualiza con una nueva iteración.
- [] **COMPROBACIÓN DE BLOQUEO**: `git rev-parse --abbrev-ref HEAD` devuelve un nombre de rama que no es troncal (no `main`, `master` o cualquier tronco que sea). Si devuelve troncal, la habilidad FALLÓ; no continúe.
- [] El objetivo de iteración está definido.
- [ ] Las solicitudes de entrada respondidas se procesan
- [] Se crea la entrada de registro

## Proceso

### 1. Leer el estado del proyecto

Lea `docs/project-status.md` para establecer el contexto:
- Fase actual (inicio | elaboración | construcción | transición)
- Número de iteración actual
- Estado de iteración anterior

### 2. Leer la hoja de ruta e identificar la tarea

Lea `docs/roadmap.md` para:
- Encuentra la tarea especificada por `$ARGUMENTS[task_id]`
- Extraer detalles de la tarea: título, descripción, tipo de tarea (característica, corrección de errores, refactorización, etc.)
- Determinar prioridad y dependencias.
- **Si no se encuentra task_id**: solicite al usuario que especifique qué tarea de la hoja de ruta

### 3. Crear rama de tareas

**Ejecute estos comandos en orden:**

```bash
# 1. Detect trunk
TRUNK=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
[ -z "$TRUNK" ] && TRUNK="main"
git rev-parse --verify "$TRUNK" 2>/dev/null || TRUNK="master"

# 2. Cambie al maletero y obtenga la última versión
git pago "$TRUNK"
git pull origen "$TRUNK" 2>/dev/null || verdadero

# 3. Crear rama (consulte branching.md para conocer los patrones de nombres)
git checkout -b {tipo}/{task_id}-{breve descripción}

# 4. VERIFICAR: esto NO debe devolver el troncal
git rev-parse --abrev-ref CABEZA
```

**Si la sucursal ya existe**, consulta su estado:
- No hay confirmaciones no fusionadas → eliminar y volver a crear desde el tronco
- Tiene confirmaciones no fusionadas → cree PR o fusione primero, luego cree una nueva rama

### 4. Verifique las solicitudes de entrada respondidas

Verifique `docs/input-requests/` para ver si hay archivos con `estado: respondido`. Procese cualquier solicitud respondida antes de continuar.

### 5. Inicializar iteración

Actualice `docs/project-status.md`:
- Incrementar la `iteración` o usar `$ARGUMENTS[iteration_number]` proporcionado
- Establezca `iteration_goal` en `$ARGUMENTS[goal]` proporcionado o derive de la tarea de hoja de ruta
- Establecer "estado" en "en curso"
- Establecer `current_task` al task_id
- Actualizar `iteration_started` a la fecha de hoy

### 6. Inicialización del registro

Cree una entrada en `docs/agent-logs/agent-runs.jsonl` que documente el inicio de la iteración con el contexto de la tarea.

### 7. Implementar equipo (opcional)

Si `$ARGUMENTS[deploy_team]` es `true` o se especifica `$ARGUMENTS[team]`:

1. Determine la composición del equipo según `$ARGUMENTS[team]` o la fase actual:
   - **característica**: analista, arquitecto, desarrollador, probador
   - **investigación**: arquitecto, desarrollador, probador
   - **construcción**: desarrollador, probador
   - **elaboración**: arquitecto, desarrollador, tester
   - **inicio**: analista, director de proyectos
   - **transición**: tester, director de proyecto, desarrollador
   - **planificación**: director de proyecto, analista
   - **completo**: todos los roles

2. Implemente el equipo utilizando la herramienta Tarea, informe a cada compañero de equipo sobre el contexto de la iteración.

## Producción

Devuelve un resumen de:
- Fase actual y número de iteración.
- Tarea en la que se está trabajando (task_id, título)
- Objetivo de iteración
- Nombre de la rama activa (debe ser una rama de tarea no troncal)

## Ver también

- [openup-complete-task](../complete-task/SKILL.md) - Completar tareas de iteración
- [openup-create-iteration-plan](../../openup-artifacts/create-iteration-plan/SKILL.md) - Planificar la iteración antes de comenzar

# TDD Workflow

Guide the red-green-refactor cycle with a pragmatic approach. TDD is a tool, not a mandate -- use it when it helps.

## Process

### 1. Determine Phase

Based on `$ARGUMENTS[phase]`:

| Phase | Description |
|-------|-------------|
| red | Write test first (preferably before implementation) |
| green | Implement to make test pass (commit point) |
| refactor | Clean up code while tests pass (optional for small changes) |
| full | Run complete red-green-refactor cycle |

### 2. Run Phase-Specific Process

See phase-specific documentation:
- [RED Phase](./red-phase.md) - Write failing test
- [GREEN Phase](./green-phase.md) - Implement feature
- [REFACTOR Phase](./refactor-phase.md) - Improve code quality

### 3. Verify Before Proceeding

After each phase:
- RED: Write test first when practical (not mandatory for every case)
- GREEN: Verify test passes before committing (commit when green)
- REFACTOR: Verify tests still pass; refactor is optional for small changes

### 4. Create TDD Log

Document the TDD cycle in `docs/tdd-logs/<feature>-tdd.md`:
- Feature name, test cases written, implementation notes, refactoring performed, lessons learned

## Success Criteria

- [ ] Tests are written (preferably before implementation)
- [ ] Implementation makes tests pass
- [ ] Code is reasonably clean and functional
- [ ] Tests pass before commit

## Output

Returns a summary of:
- TDD phase completed
- Test file created/updated
- Implementation file created/updated
- Test results
- Refactoring notes

## See Also

- [openup-create-test-plan](../openup-artifacts/create-test-plan/SKILL.md) - Create comprehensive test plan
- [openup-complete-task](../complete-task/SKILL.md) - Complete task after TDD cycle
- [openup-detail-use-case](../openup-artifacts/detail-use-case/SKILL.md) - Detail use cases before writing tests

# Flujo de trabajo TDD

Guíe el ciclo de refactorización rojo-verde con un enfoque pragmático. TDD es una herramienta, no un mandato: utilícela cuando sea útil.

## Proceso

### 1. Determinar la fase

Basado en `$ARGUMENTS[fase]`:

| Fase | Descripción |
|-------|-------------|
| rojo | Escriba la prueba primero (preferiblemente antes de la implementación) |
| verde | Implementar para pasar la prueba (punto de confirmación) |
| refactorizar | Limpiar código mientras pasan las pruebas (opcional para cambios pequeños) |
| lleno | Ejecute el ciclo completo de refactor rojo-verde |

### 2. Ejecutar proceso específico de fase

Ver documentación específica de la fase:
- [Fase ROJA](./red-phase.md) - Prueba fallida de escritura
- [Fase VERDE](./green-phase.md) - Función de implementación
- [Fase REFACTOR](./refactor-phase.md) - Mejora la calidad del código

### 3. Verificar antes de continuar

Después de cada fase:
- ROJO: Escriba el examen primero cuando sea práctico (no es obligatorio en todos los casos)
- VERDE: Verifique que la prueba pase antes de confirmar (confirmar cuando esté verde)
- REFACTOR: Verifica que las pruebas aún pasen; refactor es opcional para pequeños cambios

### 4. Crear registro TDD

Documente el ciclo TDD en `docs/tdd-logs/<feature>-tdd.md`:
- Nombre de la característica, casos de prueba escritos, notas de implementación, refactorización realizada, lecciones aprendidas

## Criterios de éxito

- [ ] Las pruebas están escritas (preferiblemente antes de la implementación)
- [ ] La implementación hace que las pruebas pasen
- [] El código es razonablemente limpio y funcional.
- [] Las pruebas pasan antes de la confirmación.

## Producción

Devuelve un resumen de:
- Fase TDD completada
- Archivo de prueba creado/actualizado
- Archivo de implementación creado/actualizado
- Resultados de la prueba
- Notas de refactorización

## Ver también

- [openup-create-test-plan](../openup-artifacts/create-test-plan/SKILL.md) - Crear un plan de prueba integral
- [openup-complete-task](../complete-task/SKILL.md) - Completa la tarea después del ciclo TDD
- [openup-detail-use-case](../openup-artifacts/detail-use-case/SKILL.md) - Detallar casos de uso antes de escribir pruebas

# Transition Phase

This skill guides you through the Transition phase of OpenUP - deploying to users.

## When to Use

Use this skill when:
- Construction is complete and system is ready for deployment
- Preparing for beta or production release
- Conducting final testing and user acceptance
- Training users and support staff
- Checking if Transition phase is complete
- Getting guidance on next steps in Transition

## When NOT to Use

Do NOT use this skill when:
- Still implementing features (use `/openup-construction`)
- System is not stable enough for testing (continue Construction)
- Need to create specific artifacts (use artifact skills)
- Looking for deployment procedures (use DevOps/ops documentation)

## Success Criteria

After using this skill, verify:
- [ ] Phase status is clearly understood (initiated, in-progress, or complete)
- [ ] Deployment readiness is assessed
- [ ] Support materials are prepared
- [ ] User acceptance is documented
- [ ] Release decision is clear

## Transition Overview

**Goal**: Deploy the system to users and ensure user satisfaction
**Duration**: Typically 2-4 weeks
**Key Milestone**: Product Release

## Phase Objectives

1. Deploy the system to users
2. Train users and support staff
3. Fix defects found during testing
4. Complete user documentation
5. Obtain user acceptance

## Completion Criteria

- [ ] Product is ready for release
- [ ] All acceptance tests pass
- [ ] Deployment documentation complete
- [ ] Support materials ready
- [ ] Stakeholder sign-off obtained

## Process

### 1. Read Project Status

Read `docs/project-status.md` to:
- Confirm phase is `transition`
- Check iteration goals
- Review active work items

### 2. Based on Activity

**`initiate`**: Start Transition phase
- Update `docs/project-status.md` to set `phase: transition`
- Review test results from construction
- Create deployment checklist
- Update `docs/roadmap.md` with transition tasks

**`check-status`**: Review progress
- Check all completion criteria above
- List what's done and what remains
- Identify blockers

**`next-steps`**: Get recommendations
- Suggest next tasks based on current state
- Prioritize by deployment readiness

## Key Work Products

- **Deployment Documentation** - Installation and configuration guides
- **User Documentation** - Final user manuals
- **Support Materials** - Troubleshooting guides, FAQs
- **Test Results** - Final test reports
- **Release Notes** - What's new and changed

## Recommended Team

For Transition phase work, create a team with:
- **tester** - Lead final testing and validation
- **developer** - Fix deployment issues
- **project-manager** - Coordinate deployment
- Add **analyst** for user feedback and acceptance

## Deployment Activities

1. **Final Testing** - Comprehensive testing including:
   - Beta testing with real users
   - Performance testing
   - Security testing
   - User acceptance testing

2. **Deployment Preparation** - Prepare for release:
   - Create deployment scripts
   - Prepare production environment
   - Plan rollback procedures
   - Train support staff

3. **User Preparation** - Prepare users:
   - Create user documentation
   - Develop training materials
   - Conduct training sessions
   - Prepare communication materials

4. **Release** - Deploy to production:
   - Execute deployment plan
   - Monitor for issues
   - Provide support
   - Collect feedback

## References

- Transition Phase: `docs-eng-process/openup-knowledge-base/practice-management/risk_value_lifecycle/guidances/concepts/phase-transition.md`
- Tester Role: `docs-eng-process/openup-knowledge-base/core/role/roles/tester-5.md`
- Project Manager Role: `docs-eng-process/openup-knowledge-base/core/role/roles/project-manager-4.md`

## See Also

- [openup-phase-review](../../openup-workflow/phase-review/SKILL.md) - Check phase completion
- [openup-create-test-plan](../../openup-artifacts/create-test-plan/SKILL.md) - Final test planning
- [openup-construction](../construction/SKILL.md) - Previous phase
- [openup-log-run](../../openup-workflow/log-run/SKILL.md) - Document deployment

# Fase de transición

Esta habilidad lo guía a través de la fase de transición de OpenUP: implementación para los usuarios.

## Cuándo utilizar

Utilice esta habilidad cuando:
- La construcción está completa y el sistema está listo para su implementación.
- Preparación para el lanzamiento beta o de producción.
- Realización de pruebas finales y aceptación del usuario.
- Formación de usuarios y personal de soporte.
- Comprobar si la fase de transición está completa
- Obtener orientación sobre los próximos pasos en la transición

## Cuándo NO usarlo

NO uses esta habilidad cuando:
- Todavía implementando funciones (use `/openup-construction`)
- El sistema no es lo suficientemente estable para realizar pruebas (continuar construcción)
- Necesidad de crear artefactos específicos (usar habilidades de artefactos)
- Buscando procedimientos de implementación (use la documentación de DevOps/ops)

## Criterios de éxito

Después de usar esta habilidad, verifique:
- [ ] El estado de la fase se comprende claramente (iniciada, en curso o completa)
- [ ] Se evalúa la preparación para la implementación
- [ ] Se preparan materiales de apoyo.
- [ ] La aceptación del usuario está documentada.
- [] La decisión de liberación es clara.

## Descripción general de la transición

**Objetivo**: Implementar el sistema para los usuarios y garantizar su satisfacción.
**Duración**: normalmente de 2 a 4 semanas
**Hito clave**: Lanzamiento del producto

## Objetivos de la fase

1. Implementar el sistema para los usuarios.
2. Capacitar a los usuarios y al personal de soporte.
3. Reparar los defectos encontrados durante las pruebas.
4. Documentación de usuario completa
5. Obtener la aceptación del usuario

## Criterios de finalización

- [ ] El producto está listo para su lanzamiento.
- [] Todas las pruebas de aceptación pasan
- [] Documentación de implementación completa
- [ ] Materiales de apoyo listos
- [ ] Se obtuvo la aprobación de las partes interesadas

## Proceso

### 1. Leer el estado del proyecto

Lea `docs/project-status.md` para:
- Confirmar que la fase es "transición"
- Verificar los objetivos de iteración.
- Revisar elementos de trabajo activos.

### 2. Basado en la actividad

**`iniciar`**: Iniciar fase de transición
- Actualice `docs/project-status.md` para configurar `fase: transición`
- Revisar los resultados de las pruebas de construcción.
- Crear lista de verificación de implementación
- Actualizar `docs/roadmap.md` con tareas de transición

**`check-status`**: Revisar el progreso
- Verifique todos los criterios de finalización anteriores
- Enumerar lo que se hizo y lo que queda
- Identificar bloqueadores

**`próximos pasos`**: obtener recomendaciones
- Sugerir próximas tareas según el estado actual
- Priorizar según la preparación para la implementación

## Productos de trabajo clave

- **Documentación de implementación** - Guías de instalación y configuración
- **Documentación de usuario** - Manuales de usuario finales
- **Materiales de soporte** - Guías de solución de problemas, preguntas frecuentes
- **Resultados de las pruebas** - Informes finales de las pruebas
- **Notas de la versión** - Novedades y cambios

## Equipo recomendado

Para el trabajo de la fase de transición, cree un equipo con:
- **tester** - Liderar las pruebas y validación finales
- **desarrollador** - Solucionar problemas de implementación
- **gerente de proyecto** - Coordinar la implementación
- Agregue **analista** para recibir comentarios y aceptación de los usuarios.

## Actividades de implementación

1. **Pruebas finales** - Pruebas completas que incluyen:
   - Pruebas beta con usuarios reales.
   - Pruebas de rendimiento
   - Pruebas de seguridad
   - Pruebas de aceptación del usuario.

2. **Preparación para la implementación** - Prepárese para el lanzamiento:
   - Crear scripts de implementación
   - Preparar el entorno de producción.
   - Planear procedimientos de reversión
   - Capacitar al personal de apoyo.

3. **Preparación del usuario** - Preparar a los usuarios:
   - Crear documentación de usuario.
   - Desarrollar materiales de capacitación.
   - Realizar sesiones de formación.
   - Preparar materiales de comunicación.

4. **Lanzamiento** - Implementación en producción:
   - Ejecutar plan de implementación.
   - Monitorear problemas
   - Proporcionar apoyo
   - Recopilar comentarios

## Referencias

- Fase de transición: `docs-eng-process/openup-knowledge-base/practice-management/risk_value_lifecycle/guidances/concepts/phase-transition.md`
- Rol del probador: `docs-eng-process/openup-knowledge-base/core/role/roles/tester-5.md`
- Rol del Gerente de Proyecto: `docs-eng-process/openup-knowledge-base/core/role/roles/project-manager-4.md`

## Ver también

- [openup-phase-review](../../openup-workflow/phase-review/SKILL.md) - Verificar la finalización de la fase
- [openup-create-test-plan](../../openup-artifacts/create-test-plan/SKILL.md) - Planificación final de la prueba
- [openup-construction](../construction/SKILL.md) - Fase anterior
- [openup-log-run](../../openup-workflow/log-run/SKILL.md) - Implementación de documentos

# PDF Cleaner

Esta skill permite realizar un procesamiento por lotes de archivos PDF dentro de la solución para adecuarlos a la nueva marca "Caligrafía Mágica".

## Capacidades

1.  **Detección de PDFs**: Escanea `public/recursos` y `public/pdfs`.
2.  **Limpieza de Marca**: Cubre áreas de texto relacionadas con "Rubio".
3.  **Watermarking**: Añade "Caligrafía Mágica ®" en cada página.
4.  **Organización**: Clasifica cada salida en `public/processed/[nombre-original]/`.

## Scripts

- `scripts/process-pdfs.ts`: El motor principal de procesamiento.

## Uso Manual

```bash
# Para ejecutar desde la raíz
npx ts-node .agent/skills/pdf-cleaner/scripts/process-pdfs.ts
```

## Configuración

- **Texto de Marca**: Editar `process-pdfs.ts` para cambiar el texto decorativo.
- **Áreas de Redacción**: Por defecto, se aplican máscaras en la parte superior e inferior de las páginas si se detecta texto específico o se configura como patrón fijo.

# Limpiador de PDF

Esta habilidad permite realizar un procesamiento por lotes de archivos PDF dentro de la solución para adecuarlos a la nueva marca "Caligrafía Mágica".

## Capacidades

1. **Detección de PDFs**: Escanea `public/recursos` y `public/pdfs`.
2. **Limpieza de Marca**: Cubre áreas de texto relacionadas con "Rubio".
3. **Marcas de agua**: Agregue "Caligrafía Mágica ®" en cada página.
4. **Organización**: Clasifica cada salida en `public/processed/[nombre-original]/`.

## Guiones

- `scripts/process-pdfs.ts`: El motor principal de procesamiento.

##Manual de uso

```bash
# Para ejecutar desde la raíz
npx ts-node .agent/skills/pdf-cleaner/scripts/process-pdfs.ts
```

## Configuración

- **Texto de Marca**: Editar `process-pdfs.ts` para cambiar el texto decorativo.
- **Áreas de Redacción**: Por defecto, se aplican máscaras en la parte superior e inferior de las páginas si se detecta texto específico o se configura como patrón fijo.

# Async Patterns in Python

## When to use this skill

Routinely adhere to these patterns when you:
- Construct Fast APIs handling vast amounts of concurrent connections.
- Orchestrate networking requests (HTTP calls, crawling, WebSockets).
- Work deeply with database driver I/O bounding (asyncpg, motor).
- Bridge synchronous domains safely to the asynchronous realm.

## The Event Loop Core

`asyncio` implements cooperative multitasking. Instead of the OS handling threads, the code yields execution back to an Event Loop upon encountering IO-Wait blocks by using `await`.

Rule #1: **Never execute a lengthy computation or synchronous sleep in an async def function.** It freezes the entire execution universe.

```python
import asyncio
import time

# WRONG - Freezes every other async task.
async def bad_pattern():
    time.sleep(5)  # The loop stops matching other tasks here.

# RIGHT
async def good_pattern():
    await asyncio.sleep(5)
```

## Running Concurrent Work

Instead of resolving queries one by one, leverage `asyncio.gather` matching independent tasks concurrently.

```python
import asyncio

async def fetch_item(id: int):
    # Simulate DB lookup
    await asyncio.sleep(1)
    return f"Item {id}"

async def main():
    # Will take 1 second in total, not 3 seconds.
    results = await asyncio.gather(
        fetch_item(1),
        fetch_item(2),
        fetch_item(3)
    )
    print(results)
```

## Bridging Sync and Async Environments

If you *inevitably* need to invoke blocking routines (legacy libraries, cryptography hashing, requests module) offload them natively to worker threads without disrupting your Event Loop.

```python
import asyncio
import requests # Synchronous blocking library

def blocking_io_network_call():
    response = requests.get('https://example.com')
    return response.status_code

async def main():
    # Push the blocking execution into the built-in thread pool
    loop = asyncio.get_running_loop()
    status = await loop.run_in_executor(None, blocking_io_network_call)
    print(status)
```

## Using `anyio` or Custom Architectures
For robust library design without coupling strictly to `asyncio` built-ins, standardizing on frameworks like `anyio` provides compatibility over different backends like `trio` enforcing strict task-groups and timeouts.

# Patrones Asíncronos en Python

## Cuándo usar esta habilidad

Sigue estas directrices cuando:
- Entables la creación de endpoints robustos de alta demanda (p. ej. en FastAPI).
- Orquestes múltiples llamadas HTTP en paralelo o Scrapers Web.
- Interactúes con bases de datos adaptadas a I/O (asyncpg, acore).
- Necesites enlazar entornos estrictamente síncronos y costosos delegándolos a hilos.

## Multitarea Cooperativa en el Event Loop

`asyncio` introduce la multitarea cooperativa en Python. En lugar de ceder el poder al Sistema Operativo, tu propio código asume la responsabilidad de liberar paso al Event Loop mediante la palabra reservada `await`.

Regla Sagrada: **Jamás bloquees un proceso continuo y pesado carente del modificador await dentro de un bloque `async def`. Esta negligencia congela todo tu ecosistema concurrente.**

```python
import asyncio
import time

# TERRIBLE Y LETAL - Pausa todas las peticiones activas de tus usuarios.
async def mal_patron():
    time.sleep(5)  

# EXCELENTE - Permite a otros usuarios interactuar mientras se aguarda.
async def buen_patron():
    await asyncio.sleep(5)
```

## Disparando la Concurrencia

Si pretendes cargar tres páginas web que no dependen una de la otra, lanzalas a la vez y agrúpalas mediante `asyncio.gather`.

```python
import asyncio

async def consultar_usuario(id: int):
    # Simulacro red/DB
    await asyncio.sleep(1)
    return f"Usuario {id}"

async def principal():
    # Toma 1 solo segundo. Lanza y extrae los tres valores simultáneamente.
    resultados = await asyncio.gather(
        consultar_usuario(1),
        consultar_usuario(2),
        consultar_usuario(3)
    )
    print(resultados)
```

## Puentes al Infierno (Código Síncrono a Asíncrono)

Para encriptaciones costosas o librerías del pasado sin capa asíncrona (ej. el módulo `requests`), despácha la tara hacia el contenedor de Hilos propio (`threadpool`) evadiendo interrumpir el Event Loop principal de `asyncio`.

```python
import asyncio
import requests # Librería Síncrona

def bloquear_la_red():
    respuesta = requests.get('https://example.com')
    return respuesta.status_code

async def principal():
    # Offload al ThreadPool subyacente de Python
    loop = asyncio.get_running_loop()
    estado = await loop.run_in_executor(None, bloquear_la_red)
    print(estado)
```

## Control estricto
A largo plazo, considera abstraer en favor de librearías como `anyio` u operar usando TaskGroups (`asyncio.TaskGroup`) para controlar y detener flujos huérfanos que provocan fugas de memoria incontrolables.

# Python MCP Server Implementation

## When to use this skill

Activate this protocol when you:
- Construct Context and Tool providers for Claude Desktop or similar AI Agent frameworks.
- Implement specialized sub-systems acting as 'eyes and hands' for generic Language Models.
- Rely on standard SSE or stdio bridges over HTTP.

## The Model Context Protocol (MCP)

MCP stands for the ultimate decoupled bridging mechanism letting you write python capabilities mapped strictly into AI Agent inputs.

### Generating a Standard Server

Instead of building boilerplate, leverage the `mcp-server` fast-setup structures. 

```python
from mcp.server.fastmcp import FastMCP

# 1. Initialize FastMCP instance
mcp = FastMCP("Weather Server")

# 2. Expose a capability as an AI tool using the @mcp.tool decorator
@mcp.tool()
def fetch_weather(city: str) -> str:
    """Fetch the current weather forecasting for a given city."""
    return f"Weather in {city}: 21C, Sunny"

# 3. Start execution
if __name__ == "__main__":
    mcp.run()
```

## Bridging Architecture

Never mingle internal architecture variables directly to the Agent.
Isolate arguments. Validate payloads via `pydantic`. The MCP protocol relies on structured schemas to represent capabilities, and `FastMCP` translates Python hints to JSON Schema.

```python
from pydantic import BaseModel, Field

class AlertRequest(BaseModel):
    message: str = Field(description="The actual broadcast message content")
    urgency: int = Field(description="Urgency level from 1 to 5")

@mcp.tool()
def broadcast_alert(payload: AlertRequest) -> str:
    """Broadcast an urgent alert to the incident room."""
    print(f"[{payload.urgency}] ALERT: {payload.message}")
    return "Alert transmitted."
```

## Running the Server

If integrating via standard input/output (stdio), test your Python server simply by invoking it:

```bash
uv run my_server.py
```

Provide the executable to your Claude setup configuration:
```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["run", "my_server.py"]
    }
  }
}
```

# Generador de Servidores MCP en Python

## Cuándo usar esta habilidad

Activa este protocolo cuando:
- Construyas proveedores de Contexto y Herramientas para clientes de IA como Claude Desktop.
- Quieras implementar un subsistema especializado que actúe de 'ojos y manos' para tu Model Language.
- Te comuniques bajo un puente de canal estándar (stdio) o Server-Sent Events (SSE).

## El Standard MCP (Model Context Protocol)

MCP conforma un mecanismo desacoplado para trasladar capacidades desarrolladas en Python directamente a interfaces que la IA entiende y ejecuta.

### Servidor Estándar (FastMCP)

Para evitar el exceso de infraesctructura, despliega `FastMCP`:

```python
from mcp.server.fastmcp import FastMCP

# 1. Inicializar la instancia
mcp = FastMCP("Servidor Metereológico")

# 2. Exponer una función al agente de IA con el decorador @mcp.tool
@mcp.tool()
def obtener_tiempo(ciudad: str) -> str:
    """Busca y devuelve el tiempo metereologico de una ciudad en formato string."""
    return f"El tiempo en {ciudad}: 21C, Soleado"

# 3. Arrancar la pasarela
if __name__ == "__main__":
    mcp.run()
```

## Arquitectura de Interfaz o Pasarela (Bridging)

Separa con claridad la variable privada de la variable del Agente. Para mantener robustez y evitar vulnerabilidades provocadas por alucinaciones de la IA, consolida los argumentos entrantes usando validadores como `pydantic`. `FastMCP` transfiere el esquema Python a JSON Schema automáticamente.

```python
from pydantic import BaseModel, Field

class PeticionAlerta(BaseModel):
    mensaje: str = Field(description="El texto de la alerta")
    urgencia: int = Field(description="Nivel del 1 al 5")

@mcp.tool()
def enviar_alerta(peticion: PeticionAlerta) -> str:
    """Envía un mensaje urgente a la sala de operaciones del equipo."""
    print(f"[{peticion.urgencia}] ALERTA: {peticion.mensaje}")
    return "Alerta transmitida correctamente."
```

## Ejecución Pura

Si usas el entorno moderno con `uv` y tu comunicación subyacente es standard input/output (stdio), tu script es directamente inyectable al bloque de configuración JSON del cliente.

```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["run", "ruta/a/mi_server.py"]
    }
  }
}
```

# Python Architecture & Patterns

## When to use this skill

Activate this protocol when you:
- Need to refactor a large monolithic Python codebase into a clean architecture.
- Are defining domain models and need strict type definitions using `typing` or `pydantic`.
- Face complexity managing dependencies, applying Inversion of Control (IoC), and dependency injection in Python.

## Type Hints and Strict Checking

Modern Python relies heavily on Type Hints for developer experience and CI validation.

```python
from typing import List, Optional, Callable
from dataclasses import dataclass

@dataclass
class User:
    id: int
    username: str
    email: Optional[str] = None

def get_active_users(users: List[User], is_active: Callable[[User], bool]) -> List[User]:
    return [u for u in users if is_active(u)]
```

Always use tools like `mypy` or `pyright` in strict mode to ensure type safety across the domain layer.

## The Clean Architecture in Python

Separate your system into distinct layers indicating the dependency rule: Inner layers (entities) know nothing about outer layers (frameworks / databases).

### 1. Domain / Entities
Pure Python classes (`dataclasses` or standard classes). No knowledge of SQLAlchemy, Django, or FastAPI.

### 2. Use Cases (Application Business Rules)
Orchestrate the flow of data using Domain objects.

### 3. Adapters (Interfaces)
Repositories and controllers. Translate data between the use cases and external agencies.

```python
from abc import ABC, abstractmethod

# The Interface (Adapter Layer mapping)
class UserRepositoryLayer(ABC):
    @abstractmethod
    def get_user_by_id(self, user_id: int) -> User:
        pass

# The Use Case requiring it
class BlockUserUseCase:
    def __init__(self, repo: UserRepositoryLayer):
        self.repo = repo

    def execute(self, user_id: int):
        user = self.repo.get_user_by_id(user_id)
        # Apply business rule logic
        return user
```

### 4. Frameworks & Drivers
The outermost layer (Web API, DB connection). Construct dependencies here and pass them down (Dependency Injection).

## Standardized Error Handling

Do not scatter raw exceptions. Define custom domain-level exceptions and map them to appropriate HTTP/gRPC responses at the adapter boundary.

# Arquitectura y Patrones en Python

## Cuándo usar esta habilidad

Activa este protocolo cuando:
- Necesites refactorizar una base de código monolítica en Python hacia una "Clean Architecture".
- Estés definiendo modelos de dominio y requieras validaciones/definiciones estrictas de tipo usando `typing` o `pydantic`.
- Encaras complejidad inyectando dependencias o aplicando Inversión de Control (IoC) en un entorno Python.

## Type Hints (Sugerencias de Tipado)

El desarrollo moderno de Python confía intensamente en Type Hints (tipado) para mejorar la experiencia de desarrollo e implantar seguridad en CI.

```python
from typing import List, Optional, Callable
from dataclasses import dataclass

@dataclass
class Usuario:
    id: int
    nombre_usuario: str
    email: Optional[str] = None

def obtener_usuarios_activos(usuarios: List[Usuario], esta_activo: Callable[[Usuario], bool]) -> List[Usuario]:
    return [u for u in usuarios if esta_activo(u)]
```

Utiliza siempre verificadores estáticos como `mypy` o `pyright` en modo estricto.

## La Clean Architecture (Arquitectura Limpia) en Python

Separa tu sistema garantizando la regla de dependencia: Las capas internas (entidades) no deben conocer elementos de las exteriores (frameworks o BBDD).

### 1. Dominio / Entidades
Clases puras en Python, sin rastro de código SQLAlchemy, Django o FastAPI.

### 2. Casos de Uso (Reglas de Negocio)
Orquestan el movimiento de la información y la ejecución en el Dominio.

### 3. Adaptadores (Interfaces)
Controladores y repositorios. Traducen información desde/para el exterior.

```python
from abc import ABC, abstractmethod

# La interfaz que debe cumplir cualquier DB
class InterfazRepositorioUsuarios(ABC):
    @abstractmethod
    def obtener_por_id(self, user_id: int) -> Usuario:
        pass

# El caso de uso
class CasoDeUsoBloquearUsuario:
    def __init__(self, repo: InterfazRepositorioUsuarios):
        self.repo = repo

    def ejecutar(self, user_id: int):
        usuario = self.repo.obtener_por_id(user_id)
        # Lógica de dominio aquí
        return usuario
```

### 4. Frameworks & Drivers
Asegura que el Framework web (punto de entrada) sea el encargado de inyectar las piezas finales.

## Gestión de Errores Estandarizada

No provoques fallos abstractos; implementa excepciones de dominio ad-hoc que tus capas HTTP mapeen automáticamente a códigos estándar correctos.

# Python Performance Optimization

## When to use this skill

Use this skill when you need to:
- Identify and resolve CPU or memory bottlenecks in Python codebases.
- Enhance the execution speed of data processing pipelines or worker scripts.
- Select the most appropriate, performant data structures for critical loops.
- Use built-in or external profilers to pinpoint exact lines causing slowdowns.

## Essential Tools for Profiling

### CPU Profiling

Always rely on actual data rather than guesses. `cProfile` provides a C-extension based profiler:

```bash
python -m cProfile -s cumtime my_script.py
```

For line-by-line inspection, install `line_profiler` and mark targeted functions with `@profile`:

```bash
kernprof -l -v my_script.py
```

### Memory Profiling

If memory exhaustion or leaks occur, utilize `memory_profiler`:

```python
from memory_profiler import profile

@profile
def my_memory_intensive_function():
    # Large calculations
    pass
```

## Anti-Patterns and Best Practices

### 1. The Global Interpreter Lock (GIL) is Not Always Your Enemy
- **I/O Bound**: Use `asyncio` or `threading` (e.g. web scraping, file I/O). The GIL drops on I/O.
- **CPU Bound**: Use `multiprocessing` to run tasks on separate cores, bypassing the GIL completely.

### 2. Data Structures
- Avoid adding/removing elements from the middle of a `list`. Use `collections.deque` for O(1) operations.
- Avoid iterating through a `list` to check for element existence (`if x in my_list`). Use `set` for O(1) lookups.

### 3. Vectorization over Loops
Native loops in Python are interpreted and comparatively slow. Instead of `for` loops to modify lists of numbers, use `numpy` vectorization.
```python
# Slow
[x * 2 for x in data]

# Fast (with numpy)
data_array * 2
```

## String Concatenation

Avoid the `+` operator in loops, which creates a new string on each iteration.
```python
# Slower
result = ""
for char in data:
    result += char

# Optimal
result = "".join(data)
```

# Optimización de Rendimiento en Python

## Cuándo usar esta habilidad

Recurre a esta habilidad cuando necesites:
- Identificar y resolver cuellos de botella de CPU o memoria en proyectos Python.
- Mejorar la velocidad de ejecución de pipelines de datos o scripts recurrentes.
- Seleccionar las estructuras de datos más eficientes para bucles críticos.
- Usar perfiladores para identificar las líneas exactas que causan ralentizaciones.

## Herramientas Esenciales de Perfilado (Profiling)

### Perfilado de CPU

Evita siempre adivinar el origen de la ineficiencia. `cProfile` viene con Python y aporta métricas claras en C:

```bash
python -m cProfile -s cumtime mi_script.py
```

Para una inspección línea por línea, instala `line_profiler` y marca las funciones objetivo con `@profile`:

```bash
kernprof -l -v mi_script.py
```

### Perfilado de Memoria

Si sufres problemas de asignación de memoria o fugas, utiliza `memory_profiler`:

```python
from memory_profiler import profile

@profile
def funcion_intensiva_en_memoria():
    # Cálculos grandes
    pass
```

## Antipatrones y Mejores Prácticas

### 1. El Global Interpreter Lock (GIL) no siempre es el enemigo
- **Tareas de Red o Disco (I/O Bound)**: Utiliza `asyncio` o `threading`. El hilo en Python suelta el GIL mientras espera I/O.
- **Tareas Matemáticas (CPU Bound)**: Utiliza el módulo `multiprocessing` para operar en núcleos de CPU paralelos evadiendo el GIL.

### 2. Estructuras de Datos Eficientes
- Nunca modifiques o extraigas objetos por el comienzo de una lista (`list.pop(0)`). Utiliza `collections.deque` si prevees actuar como cola FIFO con un coste O(1).
- Evita verificar pertenencia contra listas (`if x in list:`). Realiza estos test unitarios O(1) convirtiendo tu contenedor a objeto `set`.

### 3. Vectorización en lugar de bucles for
La ejecución de un `for` en el intérprete de Python es significativamente lenta al arrastrar "overhead" en cada iteración.
```python
# Lento
[x * 2 for x in data]

# Altamente Eficiente (usando C detrás con numpy)
data_array * 2
```

## Concatenación de Cadenas (Strings)

Evita las uniones con el operador `+` en bucles, pues Python reconstruye en memoria una cadena tras otra.
```python
# Menos Optimo
resultado = ""
for caracter in data:
    resultado += caracter

# Óptimo (O(N))
resultado = "".join(data)
```

# Python Testing Patterns

## When to use this skill

Apply this skill when you:
- Construct robust testing suites for Python applications.
- Need to isolate external systems (APIs, Databases, S3) using `unittest.mock`.
- Manage reusable test data with Pytest fixtures.
- Embrace Test-Driven Development (TDD) for building deterministic code.

## Pytest Fixtures

`pytest` outshines `unittest` by providing composable and decoupled `fixtures` for dependency injection.

```python
import pytest

@pytest.fixture
def database_connection():
    # Setup
    conn = Database.connect(":memory:")
    yield conn
    # Teardown
    conn.disconnect()

def test_user_creation(database_connection):
    user = User(name="Alice")
    database_connection.save(user)
    assert database_connection.count() == 1
```

## Mocking External Dependencies

Calls overlapping the network boundaries must be mocked ensuring fast and repeatable tests.

```python
from unittest.mock import patch

def test_fetch_external_data():
    with patch("myapp.services.requests.get") as mock_get:
        mock_get.return_value.status_code = 200
        mock_get.return_value.json.return_value = {"id": 1, "name": "Fake"}
        
        result = myapp.services.fetch_user()
        assert result["name"] == "Fake"
        mock_get.assert_called_once()
```

## Test-Driven Development (TDD) Guidelines

1. **Red**: Write a minimal failing test addressing the behavior you intend to resolve.
2. **Green**: Write the bare minimum piece of code required to pass the test. No premature scaling.
3. **Refactor**: Clean layout, abstract shared fixtures, remove unneeded loops while ensuring the test keeps passing.

## Advanced Patterns

### Parametrize

Use `pytest.mark.parametrize` to avoid duplicating tests meant to assert the exact same function over diverse input parameters.

```python
@pytest.mark.parametrize("input_data, expected", [
    ("", False),
    ("valid@email.com", True),
    ("invalid_email", False),
])
def test_email_validation(input_data, expected):
    assert is_valid_email(input_data) is expected
```

# Patrones de Testing en Python

## Cuándo usar esta habilidad

Aplica este conjunto de reglas cuando:
- Entables la creación de una test-suite (batería de pruebas) blindada y robusta en Python.
- Necesites aislar servicios caóticos (APIs, Bases de datos, S3) mediante `unittest.mock`.
- Administres ciclos de inyección de datos reutilizables empleando Fixtures de Pytest.
- Implementes la filosofía Test-Driven Development (TDD) asumiendo una calidad determinista superior.

## Fixtures de Pytest

`pytest` brilla de manera excepcional frente a la librería genérica `unittest` al proveer `fixtures` inyectables que reemplazan la herencia tediosa de clase.

```python
import pytest

@pytest.fixture
def base_de_datos():
    # Arrange / Setup (Preparación)
    conexion = DataBase.connect(":memory:")
    yield conexion
    # Teardown (Destrucción / Limpieza)
    conexion.disconnect()

def test_creacion_de_usuario(base_de_datos):
    user = User(name="Alicia")
    base_de_datos.save(user)
    assert base_de_datos.count() == 1
```

## Mockeado de Dependencias Externas (Mocks & Patches)

Todo requerimiento que salte a la red externa debe falsearse simulando las respuestas (Mocks). Esto asegura pruebas veloces e impenetrables al clima externo.

```python
from unittest.mock import patch

def test_extraccion_datos_externos():
    with patch("miapp.servicios.requests.get") as mock_get:
        mock_get.return_value.status_code = 200
        mock_get.return_value.json.return_value = {"id": 1, "name": "Falso"}
        
        resultado = miapp.servicios.extraer_usuario()
        assert resultado["name"] == "Falso"
        mock_get.assert_called_once()
```

## Metodología Test-Driven Development (TDD)

1. **Rojo (Red)**: Escribe una única aserción que materialice tu objetivo y comprueba cómo falla.
2. **Verde (Green)**: Modifica tu código escribiendo la porción estricta de lógica orientada a solventar el fallo. Deténte ahí.
3. **Refactorización (Refactor)**: Reordena, limpia lógica repetida, reduce la indentación de tu código sin miedo y manteniendo el sistema Verde.

## Patrones Avanzados

### Testeo Parametrizado

Utiliza el decorador `@pytest.mark.parametrize` para evitar la proliferación y clonación injusta de códigos por el simple hecho de probar diferentes strings o valores atípicos.

```python
@pytest.mark.parametrize("entrada, esperado", [
    ("", False),
    ("correcto@email.com", True),
    ("email_mal.com", False),
])
def test_validacion_email(entrada, esperado):
    assert es_email_valido(entrada) is esperado
```

# Skill Creator

This skill provides a practical, spec-aligned workflow for creating and maintaining Agent Skills.

## Specification (Required Format)

### Directory structure

A skill is a directory containing at minimum a `SKILL.md` file:

```
skill-name/
└── SKILL.md
```

Optional directories: `scripts/`, `references/`, and `assets/`.

### SKILL.md frontmatter (required)

```
---
name: skill-name
description: A description of what this skill does and when to use it.
---
```

Optional fields:

```
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
compatibility: Requires git, python3, and internet access
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---
```

| Field           | Required | Constraints |
| --------------- | -------- | ----------- |
| `name`          | Yes      | 1-64 chars; lowercase letters, numbers, hyphens; no leading/trailing or consecutive hyphens; must match parent directory |
| `description`   | Yes      | 1-1024 chars; must describe what the skill does and when to use it |
| `license`       | No       | Short license name or reference to bundled license file |
| `compatibility` | No       | 1-500 chars; environment requirements if needed |
| `metadata`      | No       | Arbitrary key/value mapping |
| `allowed-tools` | No       | Space-delimited list of pre-approved tools (experimental) |

#### `name` field rules

- Must be 1-64 characters
- Only lowercase letters, digits, and hyphens (`a-z`, `0-9`, `-`)
- Must not start or end with `-`
- Must not contain `--`
- Must match the skill directory name

Valid:

```
name: pdf-processing
name: data-analysis
name: code-review
```

Invalid:

```
name: PDF-Processing
name: -pdf
name: pdf--processing
```

#### `description` field rules

- Must be 1-1024 characters
- Should include both what the skill does and when to use it
- Include keywords that help agents route relevant tasks

Good:

```
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDFs, forms, or document extraction.
```

Poor:

```
description: Helps with PDFs.
```

## Core Principles

### Be concise

The context window is shared across system prompt, conversation, skill metadata, and task input. Assume the agent is capable and only include non-obvious, high-value information.

### Set appropriate degrees of freedom

- **High freedom**: heuristics and decision guidance
- **Medium freedom**: pseudocode or scripts with parameters
- **Low freedom**: deterministic scripts and strict sequences

Use tighter constraints when tasks are fragile, error-prone, or require high consistency.

## Anatomy of a Skill

A skill includes a required `SKILL.md` plus optional bundled resources:

```
skill-name/
├── SKILL.md
├── scripts/        # Executable helpers
├── references/     # Docs loaded on demand
└── assets/         # Templates, images, data
```

### scripts/

Use for repeatable code or fragile operations that benefit from deterministic execution.

### references/

Use for large or detailed docs that should load only on demand (schemas, API docs, policies).

### assets/

Use for static resources that get copied or reused in outputs (templates, images, fonts, boilerplate).

### What not to include

Avoid extra docs that do not directly help an agent complete tasks (README.md, INSTALLATION_GUIDE.md, CHANGELOG.md, etc.).

## Progressive Disclosure

1. **Metadata** (name + description) always loads
2. **SKILL.md body** loads when the skill triggers
3. **Resources** load only when needed

Keep `SKILL.md` under 500 lines. Move deep references to `references/` and link them from SKILL.md.

### Patterns

**Pattern 1: High-level guide with references**

```
# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- Form filling: See references/FORMS.md
- API reference: See references/REFERENCE.md
- Examples: See references/EXAMPLES.md
```

**Pattern 2: Domain-specific organization**

```
bigquery-skill/
├── SKILL.md
└── references/
    ├── finance.md
    ├── sales.md
    ├── product.md
    └── marketing.md
```

**Pattern 3: Conditional details**

```
# DOCX Processing

## Creating documents

Use docx-js for new documents. See references/DOCX-JS.md.

## Editing documents

For simple edits, modify the XML directly.

For tracked changes: references/REDLINING.md
For OOXML details: references/OOXML.md
```

Guidelines:

- Keep references one level deep from `SKILL.md`
- Add a table of contents for reference files over ~100 lines

## Skill Creation Process

1. Understand the skill with concrete examples
2. Plan reusable contents (scripts, references, assets)
3. Initialize a new skill
4. Edit SKILL.md and bundled resources
5. Validate and package
6. Iterate based on real usage

### Step 1: Understand with examples

Gather representative user requests and clarify edge cases. Avoid too many questions per message; start with the highest-impact unknowns.

### Step 2: Plan reusable contents

For each example, identify what should be scripted, documented, or templated. Convert repeated logic into scripts or reusable assets.

### Step 3: Initialize the skill

Use the initializer script (from this skill directory):

```
./scripts/init_skill.py <skill-name> --path <output-directory>
```

The script creates a new skill folder with a template `SKILL.md` plus example `scripts/`, `references/`, and `assets/` directories. Remove any unused examples.

### Step 4: Edit the skill

Write concise, action-oriented instructions. Use imperative language. Ensure the frontmatter matches the spec and the directory name.

Consult references if you need patterns:

- `references/workflows.md`
- `references/output-patterns.md`

### Step 5: Validate

Preferred validator (spec reference library):

```
skills-ref validate ./my-skill
```

Quick local validator (bundled with this skill):

```
./scripts/quick_validate.py ./my-skill
```

### Step 6: Package

```
./scripts/package_skill.py <path/to/skill-folder> [output-directory]
```

The packager validates first, then creates `<skill-name>.skill` (zip format).

### Step 7: Iterate

Run the skill on real tasks, note failures or friction, and update SKILL.md or resources accordingly.

## File references

Use relative paths from the skill root:

```
See references/REFERENCE.md for details.
Run scripts/extract.py for extraction.
```

Avoid deeply nested reference chains.

# Creador de habilidades

Esta habilidad proporciona un flujo de trabajo práctico y alineado con las especificaciones para crear y mantener habilidades de agente.

## Especificación (formato requerido)

### Estructura del directorio

Una habilidad es un directorio que contiene como mínimo un archivo `SKILL.md`:

```
skill-name/
└── SKILL.md
```

Directorios opcionales: `scripts/`, `references/` y `assets/`.

### SKILL.md frontmatter (obligatorio)

```
---
name: skill-name
description: A description of what this skill does and when to use it.
---
```

Campos opcionales:

```
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
compatibility: Requires git, python3, and internet access
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---
```

| Campo | Requerido | Restricciones |
| --------------- | -------- | ----------- |
| `nombre` | Sí | 1-64 caracteres; letras minúsculas, números, guiones; sin guiones iniciales, finales o consecutivos; debe coincidir con el directorio principal |
| `descripción` | Sí | 1-1024 caracteres; debe describir qué hace la habilidad y cuándo usarla |
| `licencia` | No | Nombre corto de la licencia o referencia al archivo de licencia incluido |
| `compatibilidad` | No | 1-500 caracteres; requisitos ambientales si es necesario |
| `metadatos` | No | Mapeo arbitrario de clave/valor |
| `herramientas-permitidas` | No | Lista delimitada por espacios de herramientas preaprobadas (experimental) |

#### reglas del campo `nombre`

- Debe tener entre 1 y 64 caracteres
- Solo letras minúsculas, dígitos y guiones (`a-z`, `0-9`, `-`)
- No debe comenzar ni terminar con `-`
- No debe contener `--`
- Debe coincidir con el nombre del directorio de habilidades.

Válido:

```
name: pdf-processing
name: data-analysis
name: code-review
```

Inválido:

```
name: PDF-Processing
name: -pdf
name: pdf--processing
```

#### reglas del campo `descripción`

- Debe tener entre 1 y 1024 caracteres
- Debe incluir tanto lo que hace la habilidad como cuándo usarla.
- Incluir palabras clave que ayuden a los agentes a enrutar tareas relevantes.

Bien:

```
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDFs, forms, or document extraction.
```

Pobre:

```
description: Helps with PDFs.
```

## Principios básicos

### Sea conciso

La ventana de contexto se comparte entre los mensajes del sistema, la conversación, los metadatos de habilidades y la entrada de tareas. Suponga que el agente es capaz y solo incluya información no obvia y de alto valor.

### Establecer grados de libertad apropiados

- **Alta libertad**: heurística y orientación para la toma de decisiones
- **Libertad media**: pseudocódigo o scripts con parámetros
- **Baja libertad**: guiones deterministas y secuencias estrictas

Utilice restricciones más estrictas cuando las tareas sean frágiles, propensas a errores o requieran una alta coherencia.

## Anatomía de una habilidad

Una habilidad incluye un `SKILL.md` requerido más recursos incluidos opcionales:

```
skill-name/
├── SKILL.md
├── scripts/        # Executable helpers
├── references/     # Docs loaded on demand
└── assets/         # Templates, images, data
```

### guiones/

Úselo para código repetible u operaciones frágiles que se benefician de la ejecución determinista.

### referencias/

Úselo para documentos grandes o detallados que deben cargarse solo según demanda (esquemas, documentos API, políticas).

### activos/

Úselo para recursos estáticos que se copian o reutilizan en resultados (plantillas, imágenes, fuentes, texto estándar).

### Qué no incluir

Evite documentos adicionales que no ayuden directamente a un agente a completar las tareas (README.md, INSTALLATION_GUIDE.md, CHANGELOG.md, etc.).

## Divulgación progresiva

1. **Metadatos** (nombre + descripción) siempre se carga
2. **SKILL.md body** se carga cuando se activa la habilidad
3. **Recursos** se cargan solo cuando sea necesario

Mantenga `SKILL.md` por debajo de 500 líneas. Mueva referencias profundas a `references/` y vincúlelas desde SKILL.md.

### Patrones

**Patrón 1: Guía de alto nivel con referencias**

```
# PDF Processing

## Inicio rápido

Extraer texto con pdfplomber:
[ejemplo de código]

## Funciones avanzadas

- Llenado de formularios: Ver referencias/FORMS.md
- Referencia de API: ver referencias/REFERENCE.md
- Ejemplos: Ver referencias/EJEMPLOS.md
```

**Patrón 2: organización de dominio específico**

```
bigquery-skill/
├── SKILL.md
└── references/
    ├── finance.md
    ├── sales.md
    ├── product.md
    └── marketing.md
```

**Patrón 3: Detalles condicionales**

```
# DOCX Processing

## Creando documentos

Utilice docx-js para documentos nuevos. Ver referencias/DOCX-JS.md.

## Editar documentos

Para ediciones simples, modifique el XML directamente.

Para cambios rastreados: referencias/REDLINING.md
Para obtener detalles sobre OOXML: referencias/OOXML.md
```

Pautas:

- Mantenga las referencias a un nivel de profundidad desde `SKILL.md`
- Agregar una tabla de contenido para archivos de referencia de más de ~100 líneas

## Proceso de creación de habilidades

1. Comprender la habilidad con ejemplos concretos
2. Planificar contenidos reutilizables (guiones, referencias, activos)
3. Inicializar una nueva habilidad
4. Edite SKILL.md y los recursos incluidos
5. Validar y empaquetar
6. Iterar según el uso real

### Paso 1: entender con ejemplos

Reúna las solicitudes de los usuarios representativos y aclare los casos extremos. Evite demasiadas preguntas por mensaje; Comience con las incógnitas de mayor impacto.

### Paso 2: Planificar contenidos reutilizables

Para cada ejemplo, identifique qué se debe programar, documentar o crear una plantilla. Convierta la lógica repetida en scripts o activos reutilizables.

### Paso 3: inicializa la habilidad

Utilice el script inicializador (de este directorio de habilidades):

```
./scripts/init_skill.py <skill-name> --path <output-directory>
```

El script crea una nueva carpeta de habilidades con una plantilla `SKILL.md` más directorios de ejemplo `scripts/`, `references/` y `assets/`. Elimine los ejemplos no utilizados.

### Paso 4: Editar la habilidad

Escriba instrucciones concisas y orientadas a la acción. Utilice lenguaje imperativo. Asegúrese de que el frontmatter coincida con la especificación y el nombre del directorio.

Consultar referencias si necesitas patrones:

- `referencias/flujos de trabajo.md`
- `referencias/patrones-de-salida.md`

### Paso 5: Validar

Validador preferido (biblioteca de referencia de especificaciones):

```
skills-ref validate ./my-skill
```

Validador local rápido (incluido con esta habilidad):

```
./scripts/quick_validate.py ./my-skill
```

### Paso 6: Paquete

```
./scripts/package_skill.py <path/to/skill-folder> [output-directory]
```

El empaquetador valida primero y luego crea `<skill-name>.skill` (formato zip).

### Paso 7: Iterar

Ejecute la habilidad en tareas reales, observe fallas o fricciones y actualice SKILL.md o los recursos en consecuencia.

## Referencias de archivos

Utilice rutas relativas desde la raíz de la habilidad:

```
See references/REFERENCE.md for details.
Run scripts/extract.py for extraction.
```

Evite cadenas de referencia profundamente anidadas.