47 skills disponibles

DevSkills Hub

Catálogo interactivo de skills para agentes de IA.
Explora, previsualiza y descarga skills listas para usar.

47 Skills
6 Categorías
732 KB totales
ESC

Skills Disponibles

47 de 47
Imagen de astro-improvements
📦 General Private

astro-improvements

Audit an Astro application and propose prioritized improvements across performance & islands, architecture, SEO/accessibility/meta, and DX/TypeScript quality. Produces a report with severity, ranked findings, and before/after refactor recipes. Use when reviewing, refactoring, or onboarding into an Astro codebase.

2 archivos
11.0 KB
Descargar .zip
📦 General

astro-improvements

# 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.
Descargar skill completa (11.0 KB)
Imagen de dotnet-api-design
🟣 .NET Core Private

dotnet-api-design

Diseña APIs públicas estables y compatibles usando principios de diseño extend-only. Gestiona compatibilidad de API, de wire y de binario, y versionado para paquetes NuGet y sistemas distribuidos.

2 archivos
6.9 KB
Descargar .zip
🟣 .NET Core

dotnet-api-design

# 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)
Descargar skill completa (6.9 KB)
Imagen de dotnet-architecture
🟣 .NET Core Private

dotnet-architecture

Diseña o revisa la arquitectura de soluciones .NET abarcando monolitos modulares, clean architecture, vertical slices, microservicios, DDD, CQRS y límites cloud-native sin sobre-ingeniería.

4 archivos
15.1 KB
references
Descargar .zip
🟣 .NET Core

dotnet-architecture

# .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
Descargar skill completa (15.1 KB)
Imagen de dotnet-code-review
🟣 .NET Core Private

dotnet-code-review

Analiza Pull Requests en proyectos .NET Core realizando revisión de código automatizada. Evalúa calidad, seguridad, rendimiento, convenciones y tests. Genera un informe detallado con puntuación y recomendaciones accionables. Úsala para revisiones de PRs o auditorías de código.

2 archivos
6.6 KB
Descargar .zip
🟣 .NET Core

dotnet-code-review

# .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
Descargar skill completa (6.6 KB)
Imagen de dotnet-coding-standards
🟣 .NET Core Private

dotnet-coding-standards

Escribe código C# moderno y de alto rendimiento usando records, pattern matching, value objects, async/await, Span<T>/Memory<T> y patrones de diseño de API. Enfatiza programación funcional con C# 12+.

6 archivos
20.2 KB
Descargar .zip
🟣 .NET Core

dotnet-coding-standards

# 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/
Descargar skill completa (20.2 KB)
Imagen de dotnet-concurrency
🟣 .NET Core Private

dotnet-concurrency

Elige la abstracción de concurrencia correcta en .NET — desde async/await para I/O hasta Channels para productor/consumidor y Akka.NET para gestión de entidades con estado. Evita locks y sincronización manual.

3 archivos
9.6 KB
Descargar .zip
🟣 .NET Core

dotnet-concurrency

# .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".
Descargar skill completa (9.6 KB)
Imagen de dotnet-database-performance
🟣 .NET Core Private

dotnet-database-performance

Patrones de acceso a base de datos para rendimiento. Separa modelos de lectura/escritura, evita queries N+1, usa AsNoTracking, aplica límites de filas y nunca hagas joins en la aplicación. Funciona con EF Core y Dapper.

2 archivos
7.4 KB
Descargar .zip
🟣 .NET Core

dotnet-database-performance

# 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
Descargar skill completa (7.4 KB)
Imagen de dotnet-efcore-patterns
🟣 .NET Core Private

dotnet-efcore-patterns

Buenas prácticas de Entity Framework Core incluyendo NoTracking por defecto, query splitting para colecciones de navegación, gestión de migraciones, servicios dedicados de migración y errores comunes a evitar.

2 archivos
8.1 KB
Descargar .zip
🟣 .NET Core

dotnet-efcore-patterns

# 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;
```
Descargar skill completa (8.1 KB)
Imagen de dotnet-minimal-apis
🟣 .NET Core Private

dotnet-minimal-apis

Diseña e implementa Minimal APIs en ASP.NET Core usando endpoints handler-first, route groups, filtros y composición ligera adaptada a servicios .NET modernos.

4 archivos
13.8 KB
references
Descargar .zip
🟣 .NET Core

dotnet-minimal-apis

# 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)
Descargar skill completa (13.8 KB)
Imagen de dotnet-refactor
🟣 .NET Core Private

dotnet-refactor

Analiza y refactoriza código .NET Core aplicando principios SOLID, código limpio y patrones de diseño. Detecta malos olores de código, propone mejoras estructurales y genera el código refactorizado. Úsala al limpiar deuda técnica o mejorar mantenibilidad.

2 archivos
5.3 KB
Descargar .zip
🟣 .NET Core

dotnet-refactor

# .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
Descargar skill completa (5.3 KB)
Imagen de dotnet-testcontainers
🟣 .NET Core Private

dotnet-testcontainers

Escribe tests de integración usando TestContainers para .NET con xUnit. Cubre testing de infraestructura con bases de datos reales, colas de mensajes y cachés en contenedores Docker en lugar de mocks.

4 archivos
10.0 KB
Descargar .zip
🟣 .NET Core

dotnet-testcontainers

# 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
Descargar skill completa (10.0 KB)
Imagen de dotnet-unit-tests
🟣 .NET Core Private

dotnet-unit-tests

Genera y gestiona tests unitarios en proyectos .NET Core usando xUnit, NSubstitute y FluentAssertions. Aplica patrones AAA, nomenclatura estándar y cobertura mínima. Úsala cuando necesites crear, ampliar o auditar tests en soluciones .NET.

2 archivos
4.8 KB
Descargar .zip
🟣 .NET Core

dotnet-unit-tests

# .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
```
Descargar skill completa (4.8 KB)
Imagen de dotnet-wiki-generator
🟣 .NET Core Private

dotnet-wiki-generator

Genera documentación wiki estructurada a partir de código fuente .NET Core. Extrae XML docs, analiza arquitectura, y produce páginas Markdown para GitHub Wiki o Confluence. Úsala para documentar APIs, dominios y decisiones de arquitectura.

2 archivos
5.2 KB
Descargar .zip
🟣 .NET Core

dotnet-wiki-generator

# .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
Descargar skill completa (5.2 KB)
Imagen de openup-assess-completeness
🔄 OpenUP Private

openup-assess-completeness

Lightweight readiness assessment before task completion or phase transition

2 archivos
3.0 KB
Descargar .zip
🔄 OpenUP

openup-assess-completeness

# 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
Descargar skill completa (3.0 KB)
Imagen de openup-complete-task
🔄 OpenUP Private

openup-complete-task

Mark a task as complete, update roadmap, commit changes, and prepare traceability logs

3 archivos
4.5 KB
Descargar .zip
🔄 OpenUP

openup-complete-task

# 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
Descargar skill completa (4.5 KB)
Imagen de openup-construction
🔄 OpenUP Private

openup-construction

Initialize and manage Construction phase activities - build the system incrementally

2 archivos
3.8 KB
Descargar .zip
🔄 OpenUP

openup-construction

# 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
Descargar skill completa (3.8 KB)
Imagen de openup-create-architecture-notebook
🔄 OpenUP Private

openup-create-architecture-notebook

Genera o actualiza la documentación de arquitectura a partir de la plantilla

2 archivos
3.4 KB
Descargar .zip
🔄 OpenUP

openup-create-architecture-notebook

# 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
Descargar skill completa (3.4 KB)
Imagen de openup-create-documentation
🔄 OpenUP Private

openup-create-documentation

Genera documentación legible para humanos a partir de código y artefactos

2 archivos
2.7 KB
Descargar .zip
🔄 OpenUP

openup-create-documentation

# 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
Descargar skill completa (2.7 KB)
Imagen de openup-create-iteration-plan
🔄 OpenUP Private

openup-create-iteration-plan

Planifica la iteración basándose en el estado actual y la hoja de ruta

2 archivos
3.2 KB
Descargar .zip
🔄 OpenUP

openup-create-iteration-plan

# 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
Descargar skill completa (3.2 KB)
Imagen de openup-create-pr
🔄 OpenUP Private

openup-create-pr

Crea un pull request con descripción estructurada vinculada al contexto de la tarea en la hoja de ruta

2 archivos
4.2 KB
Descargar .zip
🔄 OpenUP

openup-create-pr

# 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
Descargar skill completa (4.2 KB)
Imagen de openup-create-risk-list
🔄 OpenUP Private

openup-create-risk-list

Crea o actualiza el documento de evaluación de riesgos a partir de la plantilla

2 archivos
3.1 KB
Descargar .zip
🔄 OpenUP

openup-create-risk-list

# 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
Descargar skill completa (3.1 KB)
Imagen de openup-create-test-plan
🔄 OpenUP Private

openup-create-test-plan

Genera casos de prueba y plan de pruebas a partir de casos de uso y requisitos

9 archivos
19.7 KB
skill-creator
Descargar .zip
🔄 OpenUP

openup-create-test-plan

# 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
Descargar skill completa (19.7 KB)
Imagen de openup-create-use-case
🔄 OpenUP Private

openup-create-use-case

Crea una especificación de caso de uso a partir de la plantilla

2 archivos
3.2 KB
Descargar .zip
🔄 OpenUP

openup-create-use-case

# 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
Descargar skill completa (3.2 KB)
Imagen de openup-create-vision
🔄 OpenUP Private

openup-create-vision

Genera un documento de visión a partir de la plantilla

2 archivos
3.1 KB
Descargar .zip
🔄 OpenUP

openup-create-vision

# 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
Descargar skill completa (3.1 KB)
Imagen de openup-deploy-team
🔄 OpenUP Private

openup-deploy-team

Deploy an OpenUP agent team to work on the current iteration

2 archivos
3.0 KB
Descargar .zip
🔄 OpenUP

openup-deploy-team

# 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
Descargar skill completa (3.0 KB)
Imagen de openup-detail-use-case
🔄 OpenUP Private

openup-detail-use-case

Transform a high-level use case into detailed scenarios with test cases

2 archivos
4.5 KB
Descargar .zip
🔄 OpenUP

openup-detail-use-case

# 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
Descargar skill completa (4.5 KB)
Imagen de openup-elaboration
🔄 OpenUP Private

openup-elaboration

Initialize and manage Elaboration phase activities - establish architecture baseline

2 archivos
3.7 KB
Descargar .zip
🔄 OpenUP

openup-elaboration

# 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
Descargar skill completa (3.7 KB)
Imagen de openup-export-skills-pdf
🔄 OpenUP Apache-2.0

openup-export-skills-pdf

Genera un documento PDF con la documentación completa de todas las skills del repositorio. Escanea los directorios de skills, extrae metadatos y contenido SKILL.md, y los compila en un PDF estructurado con portada, índice y sección por skill. Usar cuando se necesite documentar, compartir o revisar el catálogo completo de skills del proyecto.

4 archivos
24.6 KB
scripts
Descargar .zip
🔄 OpenUP

openup-export-skills-pdf

# 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.
Descargar skill completa (24.6 KB)
Imagen de openup-inception
🔄 OpenUP Private

openup-inception

Initialize and manage Inception phase activities - define scope, vision, and feasibility

2 archivos
3.7 KB
Descargar .zip
🔄 OpenUP

openup-inception

# 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
Descargar skill completa (3.7 KB)
Imagen de openup-init
🔄 OpenUP Private

openup-init

One-command project setup for OpenUP - interactive initialization wizard

2 archivos
5.3 KB
Descargar .zip
🔄 OpenUP

openup-init

# 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
```
Descargar skill completa (5.3 KB)
Imagen de openup-log-run
🔄 OpenUP Private

openup-log-run

Create traceability logs (markdown + JSONL) for the current agent run

2 archivos
3.0 KB
Descargar .zip
🔄 OpenUP

openup-log-run

# 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
Descargar skill completa (3.0 KB)
Imagen de openup-phase-review
🔄 OpenUP Private

openup-phase-review

Check phase completion criteria and prepare for phase review

2 archivos
3.9 KB
Descargar .zip
🔄 OpenUP

openup-phase-review

# 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
Descargar skill completa (3.9 KB)
Imagen de openup-plan-feature
🔄 OpenUP Private

openup-plan-feature

Generate iteration plan and roadmap entry for a feature idea

2 archivos
9.3 KB
Descargar .zip
🔄 OpenUP

openup-plan-feature

# 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
Descargar skill completa (9.3 KB)
Imagen de openup-quick-task
🔄 OpenUP Private

openup-quick-task

Fast iteration mode for small changes - simplified workflow with minimal overhead

2 archivos
3.7 KB
Descargar .zip
🔄 OpenUP

openup-quick-task

# 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
Descargar skill completa (3.7 KB)
Imagen de openup-request-input
🔄 OpenUP Private

openup-request-input

Create an input request document for asynchronous stakeholder communication

2 archivos
2.7 KB
Descargar .zip
🔄 OpenUP

openup-request-input

# 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
Descargar skill completa (2.7 KB)
Imagen de openup-retrospective
🔄 OpenUP Private

openup-retrospective

Generate iteration retrospective with feedback and action items

2 archivos
3.0 KB
Descargar .zip
🔄 OpenUP

openup-retrospective

# 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
Descargar skill completa (3.0 KB)
Imagen de openup-shared-vision
🔄 OpenUP Private

openup-shared-vision

Crea una visión técnica compartida para la alineación del equipo

2 archivos
5.4 KB
Descargar .zip
🔄 OpenUP

openup-shared-vision

# 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
Descargar skill completa (5.4 KB)
Imagen de openup-start-iteration
🔄 OpenUP Private

openup-start-iteration

Begin a new OpenUP iteration with proper phase context and task selection

2 archivos
4.2 KB
Descargar .zip
🔄 OpenUP

openup-start-iteration

# 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
Descargar skill completa (4.2 KB)
Imagen de openup-tdd-workflow
🔄 OpenUP Private

openup-tdd-workflow

Guide Test-Driven Development cycle adapted for AI agents with a pragmatic approach

2 archivos
2.4 KB
Descargar .zip
🔄 OpenUP

openup-tdd-workflow

# 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
Descargar skill completa (2.4 KB)
Imagen de openup-transition
🔄 OpenUP Private

openup-transition

Initialize and manage Transition phase activities - deploy to users

2 archivos
4.0 KB
Descargar .zip
🔄 OpenUP

openup-transition

# 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
Descargar skill completa (4.0 KB)
Imagen de pdf-cleaner
🛠️ Utilidades Private

pdf-cleaner

Skill para procesar cuadernillos en PDF, eliminando marcas de agua o texto de "Rubio", añadiendo una marca registrada personalizada y organizando los resultados por carpetas. Útil para limpieza de materiales históricos y rebranding.

3 archivos
2.3 KB
scripts
Descargar .zip
🛠️ Utilidades

pdf-cleaner

# 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.
Descargar skill completa (2.3 KB)
Imagen de python-async-patterns
📦 Python Private

python-async-patterns

Guidelines for asynchronous programming in Python with Asyncio, concurrency handling, and avoiding blocking patterns.

2 archivos
2.9 KB
Descargar .zip
📦 Python

python-async-patterns

# 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.
Descargar skill completa (2.9 KB)
Imagen de python-mcp-server-generator
📦 Python Private

python-mcp-server-generator

Best practices for implementing Model Context Protocol (MCP) servers in Python. Integrate Agentic AI capabilities efficiently.

2 archivos
2.8 KB
Descargar .zip
📦 Python

python-mcp-server-generator

# 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"]
    }
  }
}
```
Descargar skill completa (2.8 KB)
Imagen de python-patterns-architecture
📦 Python Private

python-patterns-architecture

Advanced software development principles, type hints, clean architecture, and maintainable structure in Python.

2 archivos
2.8 KB
Descargar .zip
📦 Python

python-patterns-architecture

# 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.
Descargar skill completa (2.8 KB)
Imagen de python-performance-optimization
📦 Python Private

python-performance-optimization

Master profiling and optimization in Python (cProfile, memory_profiler, CPU optimization, and efficient data structures).

2 archivos
2.7 KB
Descargar .zip
📦 Python

python-performance-optimization

# 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)
```
Descargar skill completa (2.7 KB)
Imagen de python-testing-patterns
📦 Python Private

python-testing-patterns

Comprehensive testing strategies in Python using Pytest, fixtures, mocking, and TDD methodology.

2 archivos
2.8 KB
Descargar .zip
📦 Python

python-testing-patterns

# 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
```
Descargar skill completa (2.8 KB)
✨ Meta Apache-2.0

skill-creator

Guide for creating or updating Agent Skills using the standardized SKILL.md specification, including naming rules, optional frontmatter fields, validation, packaging, and best practices for structuring scripts, references, and assets.

8 archivos
19.2 KB
references, scripts
Descargar .zip
✨ Meta

skill-creator

# 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.
Descargar skill completa (19.2 KB)
JP

Jesús P.

Líder Técnico .NET Core @ UNIR