Saltar a contenido

Patrones de composición

Un patrón de composición es una forma probada de combinar skills dentro de un plan. Hay siete. Cada uno resuelve un tipo de coordinación distinto: encadenar, paralelizar, derivar, validar, revisar, repetir y compartir contexto.

Esta guía explica cada patrón, cómo se escribe en un plan del engine y en qué planes reales se usa. La definición conceptual completa está en ARCHITECTURE.md (sección 3) del repo crowdar-qa-skills.


Resumen

# Patrón Para qué Cómo se escribe en el engine
3.1 Sequential Pipeline Encadenar skills, cada una con la salida de la anterior Pasos en orden + ${...}
3.2 Fan-out / Fan-in Ejecutar varias skills (o la misma sobre varios datos) al mismo tiempo for_each o parallel
3.3 Router / Dispatcher Elegir qué camino seguir según el input Modelo 2 (entre planes) o when (dentro del plan)
3.4 Validator / Guard Validar antes de pasar al siguiente paso guard y stop_unless
3.5 Reviewer Que otra skill, con contexto limpio, revise el resultado Un paso revisor + stop_unless
3.6 Loop con criterio de salida Repetir hasta cumplir un objetivo Dentro de la skill, con tope de iteraciones
3.7 Chain-of-Skills con contexto compartido Que un paso use datos de varios pasos anteriores output_to + ${...} sobre el contexto append-only

3.1 Sequential Pipeline

Qué es: skill A → skill B → skill C. Cada una toma la salida de la anterior.

Cuándo: cuando hay una dependencia lineal: no se puede planificar sin haber leído la historia, ni generar tests sin el plan.

steps:
  - skill: lippia-neo-read-user-story
    tools: [file]
    input:
      user_story: ${input.description}
    output_to: user_story
    guard: true

  - skill: lippia-neo-create-test-plan
    tools: [file]
    input:
      us_id: ${user_story.us_id}
      user_story: ${user_story.summary}
    output_to: test_plan
    guard: true

  - skill: lippia-neo-generate-test-suite
    tools: [file]
    input:
      manual_execution_report_path: "execution/${user_story.us_id}/${user_story.us_id}-scripted-execution-report.json"
    output_to: new_tests

A tener en cuenta:

  • Usá guard: true en cada paso cuya salida consuma el siguiente: si un paso devuelve algo mal formado, es mejor cortar ahí que arrastrar el error.
  • Las salidas tienen que ser datos estructurados (lo garantiza el output_schema de cada skill), no texto libre.

En planes reales: todos. feature-new-end-to-end (pasos 1 a 6), qa-bug-fix-verification (1 a 4), ui-selector-repair (1 a 3).


3.2 Fan-out / Fan-in

Qué es: se lanzan varias ejecuciones al mismo tiempo y después se juntan los resultados. Hay dos variantes:

Variante A — la misma skill sobre una lista (for_each)

steps:
  - skill: lippia-neo-create-test-plan
    for_each: ${input.user_stories}     # una lista
    tools: [file]
    input:
      user_story: ${item}               # el elemento actual
    output_to: test_plans               # queda una lista, en el mismo orden
    continue_on_error: true             # si una falla, siguen las demás

Si input.user_stories tiene tres historias, la skill se ejecuta tres veces en paralelo y test_plans queda como una lista con los tres resultados (null en la posición de una que falló, si hay continue_on_error).

Variante B — skills distintas al mismo tiempo (parallel)

steps:
  - parallel:
      - skill: lippia-neo-find-existing-tests
        tools: [file]
        input:
          source_summary: ${bug_summary}
        output_to: coverage
      - skill: lippia-neo-read-user-story
        tools: [file]
        input:
          user_story: ${bug_summary.related_user_story}
        output_to: related_story
    continue_on_error: false

  - skill: lippia-neo-review-test-coverage    # fan-in: usa las dos salidas
    tools: [file]
    input:
      existing_tests: ${coverage.existing_tests}
      related_us_summary: ${related_story}
    output_to: coverage_review

A tener en cuenta:

  • El engine hace como máximo 5 ejecuciones a la vez. Si la lista tiene 50 elementos, los procesa de a 5, para no saturar los límites de uso del proveedor de IA.
  • Los sub-pasos de un parallel no pueden leer la salida de otro sub-paso del mismo grupo: se ejecutan al mismo tiempo. Solo pueden usar datos de pasos anteriores.
  • Sin continue_on_error, si una ejecución falla, falla el paso entero.

En planes reales: ninguno de los planes actuales lo usa todavía. Es el candidato natural para generar planes de prueba de varias historias de una épica, o para ejecutar exploraciones independientes en paralelo.


3.3 Router / Dispatcher

Qué es: algo clasifica el input y lo deriva al camino correcto. El router tiene que informar qué tan seguro está, para poder escalar a un humano cuando duda.

En el engine hay dos niveles:

Nivel 1 — entre planes (Modelo 2)

Lo hace el engine solo, con neo run --input "<texto>": la skill lippia-neo-classify-task elige el plan y el engine escala a un humano si la confianza es menor a 0,7. Ver Modelos de orquestación en el engine.

Nivel 2 — dentro de un plan (when)

Un paso clasifica y devuelve los datos que deciden el camino; los pasos siguientes usan when para ejecutarse solo si les corresponde:

steps:
  # El clasificador: decide de dónde sale la historia
  - skill: lippia-neo-resolve-user-story-source
    tools: [file]
    input:
      user_story: ${input.description}
    output_to: resolved_source
    guard: true

  # Camino A: solo si es un ticket de Jira. `file` es para que la skill lea su references/jira.md
  - skill: lippia-neo-fetch-user-story
    when: ${resolved_source.fetch_url_jira}
    tools: [jira, file]
    input:
      story_ref: ${resolved_source.fetch_url_jira}
      provider: jira
    output_to: jira_fetch

  # Camino B: solo si es un work item de Azure DevOps. `file` es para que la skill lea su references/azure-devops.md
  - skill: lippia-neo-fetch-user-story
    when: ${resolved_source.fetch_url_azure_devops}
    tools: [azure-devops, file]
    input:
      story_ref: ${resolved_source.fetch_url_azure_devops}
      provider: azure-devops
    output_to: azure_fetch

Los dos caminos usan la misma skill de fetch, con un provider fijo distinto: como skill: no puede ser una referencia, cada rama es un paso propio. Si la historia es un archivo local, ninguno de los dos caminos se ejecuta y el plan sigue con el paso siguiente.

A tener en cuenta:

  • when evalúa una referencia, no una expresión: ${x.confidence > 0.7} no funciona. La skill clasificadora tiene que devolver directamente el dato que decide (un booleano, una URL o una lista que puede venir vacía).
  • El nombre de la skill (skill:) no puede ser una referencia: el engine no soporta skill: ${clasificacion.tipo}. Cada camino posible se escribe como un paso con su when.

En planes reales: feature-new-end-to-end (pasos 1a → 1b Jira | 1c Azure DevOps); qa-bug-coverage (el paso 1.5 se ejecuta solo si el bug referencia una historia).


3.4 Validator / Guard

Qué es: un control entre dos pasos, para no pasar downstream algo inválido.

El engine tiene dos controles, que se combinan:

Control Valida Si falla
guard: true El formato: que la salida cumpla el output_schema de la skill El plan termina en failed
stop_unless: ${...} El contenido: que el dato indique que se puede seguir El plan termina en stopped (corte previsto, no error)
steps:
  - skill: lippia-neo-read-user-story
    tools: [file]
    input:
      user_story: ${input.description}
    output_to: user_story
    guard: true                              # formato correcto
    stop_unless: ${user_story.can_continue}  # la historia tiene lo mínimo para seguir

  - skill: lippia-neo-create-test-plan
    tools: [file]
    input:
      us_id: ${user_story.us_id}
      user_story: ${user_story.summary}
    output_to: test_plan
    guard: true
    stop_unless: ${test_plan.scenarios}      # sin escenarios, no tiene sentido explorar

También se puede poner una skill validadora como paso propio, entre el productor y el consumidor, y cortar con su resultado:

  - skill: validar-gherkin                 # skill validadora (ejemplo)
    input:
      draft: ${draft}
    output_to: validation
    guard: true
    stop_unless: ${validation.valid}

A tener en cuenta:

  • Los errores de una skill validadora tienen que ser accionables ("línea 5: Given sin Then"), no genéricos.
  • Si la validación se reintenta, siempre con un tope de intentos.

En planes reales: todos usan guard. stop_unless aparece en feature-new-end-to-end (pasos 1d y 2), qa-bug-coverage (paso 4: corta si el bug no se reproduce) y qa-bug-fix-verification (paso 2: corta si no hay tests que cubran el bug).


3.5 Reviewer (revisión con contexto limpio)

Qué es: una variante del validador donde el control lo hace otra skill con juicio de IA, en lugar de reglas. La clave es que el revisor tenga contexto limpio: el que produjo el resultado tiende a defenderlo.

En el engine, cada paso es una invocación independiente que solo ve lo que recibe en su input. Un paso revisor tiene contexto limpio por diseño. Además, conviene usar un modelo distinto al del productor:

steps:
  - skill: lippia-neo-create-test-plan
    tools: [file]
    input:
      user_story: ${user_story.summary}
    output_to: test_plan
    guard: true

  - skill: revisar-plan-de-pruebas          # skill revisora (ejemplo)
    model: anthropic/claude-sonnet-4-5      # otro modelo que el productor
    input:
      user_story: ${user_story.summary}     # solo lo necesario para juzgar
      test_plan: ${test_plan}
    output_to: plan_review
    guard: true
    stop_unless: ${plan_review.approved}

A tener en cuenta:

  • Pasale al revisor solo lo que necesita para juzgar, no el historial del productor.
  • No es un mecanismo propio del engine: se arma con un paso más, model y stop_unless. Requiere que exista la skill revisora con un output_schema que devuelva el veredicto.

En planes reales: ninguno de los planes actuales lo usa todavía.


3.6 Loop con criterio de salida

Qué es: repetir algo hasta cumplir un objetivo (por ejemplo, que todos los tests pasen), con un tope de vueltas y detección de estancamiento.

En el engine, el ciclo vive dentro de la skill, no en el plan. El plan solo le da el presupuesto:

  - skill: lippia-neo-run-and-heal
    tools: [file, shell]
    loop:
      max_iterations: 100        # presupuesto del agente: cuántas veces puede usar herramientas
    input:
      config:
        max_iterations: 3        # tope del ciclo: ejecutar → reparar → ejecutar
        run_label: post-fix
    output_to: heal_summary
    guard: true

lippia-neo-run-and-heal ejecuta la suite, repara lo que falla y vuelve a ejecutar, hasta que todo pase, se llegue al tope o detecte que dejó de mejorar. Su salida dice cómo terminó (por ejemplo green, plateau_abort o max_iter_abort), y el paso siguiente puede usar ese dato.

A tener en cuenta:

  • El tope de iteraciones no es opcional: sin él, un ciclo puede no terminar nunca y consumir créditos sin límite.
  • Hay que detectar el estancamiento: si dos vueltas seguidas no mejoran, conviene salir y escalar.
  • El engine no tiene un loop "evaluador" genérico a nivel de plan; si lo necesitás, el ciclo va dentro de una skill.

En planes reales: feature-new-end-to-end (paso 5), qa-bug-fix-verification (paso 3) y ui-selector-repair (paso 3), siempre a través de lippia-neo-run-and-heal.


3.7 Chain-of-Skills con contexto compartido

Qué es: varias skills trabajan sobre un mismo contexto, cada una le agrega información, y un paso puede leer datos de cualquier paso anterior, no solo del último.

steps:
  - skill: lippia-neo-read-user-story
    tools: [file]
    input:
      user_story: ${input.description}
    output_to: user_story

  - skill: lippia-neo-run-manual-testing
    tools: [browser, file]
    input:
      test_plan_path: "test-plans/${user_story.us_id}-test-plan.md"
    output_to: exploration

  - skill: lippia-neo-run-and-heal
    tools: [file, shell]
    input:
      config:
        run_label: feature-e2e
    output_to: heal_summary

  - skill: lippia-neo-write-test-report
    tools: [file]
    input:                                   # lee de tres pasos distintos
      us_id: ${user_story.us_id}
      manual_results: ${exploration}
      automation_results:
        - label: feature-e2e
          run: ${heal_summary}
    output_to: report

A tener en cuenta:

  • El contexto es append-only: cada output_to agrega una clave nueva y reusar una clave ya escrita corta el plan. Así cada dato tiene un único origen.
  • Todo lo que se escribe en el contexto queda en la auditoría (audit.db, tabla context): el historial del contexto es el historial de la ejecución.

En planes reales: feature-new-end-to-end (el paso 6 lee los pasos 1d, 3 y 5), qa-bug-coverage (el paso 5 lee los pasos 2, 3 y 4) y qa-bug-fix-verification (el paso 4 lee los pasos 1 y 3).


Qué patrón usar

flowchart TD
    A{¿Las skills son<br/>independientes entre sí?} -- Sí --> B{¿Hay que juntar<br/>los resultados?}
    B -- Sí --> FO[3.2 Fan-out / Fan-in]
    B -- No --> SEP[Planes o pasos separados]
    A -- No --> C{¿La dependencia<br/>es lineal?}
    C -- Sí --> D{¿La salida puede<br/>ser inválida?}
    D -- Sí --> SV[3.1 Sequential + 3.4 Guard<br/>o 3.5 Reviewer]
    D -- No --> S[3.1 Sequential]
    C -- No --> E{¿Hay un criterio<br/>de salida claro?}
    E -- Sí --> L[3.6 Loop con criterio]
    E -- No --> CH[3.7 Contexto compartido]

Y si el camino depende del input (Jira o Azure, hay tests o no los hay), sumá un 3.3 Router con when.


Ejemplo real completo: feature-new-end-to-end

El plan que se ejecuta hoy en el CI con el label feature combina cinco de los siete patrones:

Paso Skill Patrones
1a lippia-neo-resolve-user-story-source 3.1, 3.3 (clasifica el origen), 3.4
1b lippia-neo-fetch-user-story (provider: jira) 3.3 (when: solo Jira), 3.4
1c lippia-neo-fetch-user-story (provider: azure-devops) 3.3 (when: solo Azure DevOps), 3.4
1d lippia-neo-read-user-story 3.1, 3.4 (stop_unless: can_continue)
2 lippia-neo-create-test-plan 3.1, 3.4 (stop_unless: scenarios)
3 lippia-neo-run-manual-testing 3.1, 3.4
4 lippia-neo-generate-test-suite 3.1, 3.4
5 lippia-neo-run-and-heal 3.1, 3.4, 3.6 (ciclo ejecutar → reparar)
6 lippia-neo-write-test-report 3.4, 3.7 (lee 1d, 3 y 5)

El YAML completo está en plans/feature-new-end-to-end.yaml del repo crowdar-engine-mvp, comentado paso por paso.