@tacuchi/agent-workflow-cli 15.1.0 → 16.0.0

package/skills/w/loops/plan-new-loop/SKILL.md

@@ -1,108 +1,138 @@
 ---
 name: plan-new-loop
 description: >-
-  Genera un plan de implementación rico (docs/plans/PPP-plan-<slug>.md) a
-  partir de un spec (docs/specs/NNN-spec-<slug>.md). Heir del chasis común de
-  los loops (loops/CHASSIS.md — motor gap-driven convergente, session única
-  con research inline, structured-choice, artefactos como log vivo); sus
-  deltas viven en el cuerpo:
-  el plan absorbe el nivel TECHNICAL-NOTE + Phases/Tasks con estado vivo,
-  research de mapeo código/impacto, gap taxonomy de planificación, y si el
-  plan incluye UI compone ui-design para autorar design SPECs por pantalla
-  (NNN-SPEC-<SLUG>.md). Si el spec no está refinado sugiere spec-refine antes.
-  Lo arranca /w:plan-new y es reanudable. Invocar cuando un spec deba
-  convertirse en un plan ejecutable antes de implementar.
+  Generates a rich implementation plan (docs/plans/PPP-plan-<slug>.md) from a
+  spec. Heir of the chassis (loops/CHASSIS.md). Deltas: the plan absorbs the
+  TECHNICAL-NOTE level + Phases/Tasks with live state, code/impact-mapping
+  research, planning gap taxonomy, and per-screen design SPECs via ui-design
+  when the plan includes UI. If the spec is not refined it suggests
+  spec-refine first. Started by /w:plan-new; resumable. Invoke when a spec
+  must become an executable plan.
 ---
 
 # plan-new-loop
 
-> **Heir** del chasis común — aquí **solo** los deltas de PLAN-new. El motor no se repite.
+> **Heir** of the common chassis — **only** the PLAN-new deltas live here. The engine is never repeated.
 
 ## Flow
 PLAN
 
 ## Layer
-2 — la IA lo corre entero.
+2 — the AI runs it end to end.
 
 ## Started by
-`/w:plan-new` — **reanudable** (mismo mecanismo del chasis, keyado off CHECKPOINT).
+`/w:plan-new` — **resumable** (same chassis mechanism, keyed off CHECKPOINT).
 
 ## Reads
-`docs/specs/NNN-spec-*.md` (glob — localiza el spec por número; o la ruta exacta del argumento del comando). **Refinado vs borrador** se distingue por la **presencia** de `## Refinement decisions` / `## Q&A traceability` en el spec: si faltan → **soft-suggest** correr `/w:spec-refine` primero (planificar sobre un spec sólido produce mejores planes), pero el usuario puede proceder.
+`docs/specs/NNN-spec-*.md` (glob — locates the spec by number; or the exact path from the command argument). **Refined vs draft** is distinguished by the **presence** of `## Refinement decisions` / `## Q&A traceability` in the spec: if missing → **soft-suggest** running `/w:spec-refine` first (planning over a solid spec produces better plans), but the user may proceed.
 
 ## Writes
-`docs/plans/PPP-plan-<slug>.md` (`generate`; **sobrescribe con confirmación** si existe). Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export. Si el plan **incluye UI**, además produce **design SPECs** (`NNN-SPEC-<SLUG>.md`) como artefactos **de su sesión** (ver *Delta 4* — no son `docs/`, no hay auto-export).
+`docs/plans/PPP-plan-<slug>.md` (`generate`; **overwrites with confirmation** if it exists). It writes only `docs/plans` — never other `docs/` folders, no auto-export. If the plan **includes UI**, it also produces **design SPECs** (`NNN-SPEC-<SLUG>.md`) as artifacts **of its session** (see *Delta 4* — they are not `docs/`, no auto-export).
 
-> **slug**: kebab-case corto derivado del Requirement del spec — solo `[a-z0-9-]`, ≤ ~5 palabras / ≤ 40 chars. El CLI solo devuelve el número `PPP`; el loop arma el nombre completo. Para localizar planes, glob `docs/plans/PPP-plan-*.md`.
+> **slug**: short kebab-case derived from the spec's Requirement — only `[a-z0-9-]`, ≤ ~5 words / ≤ 40 chars. `aw next-number docs/plans` returns JSON (field `next` = `PPP`); the loop builds the full name. To locate plans, glob `docs/plans/PPP-plan-*.md`.
 
 ## Inherits
 
-Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate), **siempre antes** de estos deltas.
+Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **always before** these deltas. *(If `../` does not resolve: `CHASSIS.md` next to this file — global layout rule, chassis § Reference resolution.)*
 
-## Internal sessions — instancia PLAN-new
+## Internal sessions — PLAN-new instance
 
-Doctrina completa en el chasis (§ *Internal sessions* + *Numeración*). La instancia de este loop:
+Full doctrine in the chassis (§ *Internal sessions* + *Numbering*). This loop's instance:
 
 | Session | When | Artifacts | Role |
 |---|---|---|---|
-| **plan session** `NNN-<slug>-plan-new/` | al arrancar el loop (o se reanuda) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` solo si difiere) | Dueña del run. Type = `refine`; descriptor `<slug>-plan-new` (el `<slug>` sale del spec de entrada). |
+| **plan session** `NNN-<slug>-plan-new/` | when the loop starts (or resumes) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` only if something is deferred) | Owns the run. Type = `refine`; descriptor `<slug>-plan-new` (the `<slug>` comes from the input spec). |
 
-## Delta 1 — Deliverable: PLAN RICO (`PPP-plan-<slug>.md`)
+## Delta 1 — Deliverable: the RICH PLAN (`PPP-plan-<slug>.md`)
 
-El plan absorbe el nivel `TECHNICAL-NOTE` **inline** (decisión del usuario) + roadmap:
+The plan absorbs the `TECHNICAL-NOTE` level **inline** (user decision) + the roadmap:
 
 ```markdown
 # Plan PPP — <slug>
 
-> Derivado de docs/specs/NNN-spec-<slug>.md · generado por plan-new-loop
-
-## Origin              spec fuente (o prompt, si se bootstrapeó vía spec-new)
-## Summary             el cómo, en 1–2 frases                                   (core)
-## Solution            explicación técnica/funcional de cómo se implementará    (core)
-## Impacted            FE · BE · BD (esquemas/tablas/funciones) · APIs · integr. (core)
-## Dependencies        docs / fuentes / bases / sesiones                        (opt.)
-## Current state (AS-IS)   wiring actual (interfaces y métodos), resumido        (opt.)
-## Target state (TO-BE)    wiring objetivo                                       (opt.)
-## Final behavior      cómo se comporta el flujo al final (alineado con criterios del spec) (core)
-## Phases              fases agrupadoras (complejidad XS–S)                      (core)
-## Tasks               tareas por fase (≤XS), con deps y estado vivo (- [ ])     (core)
-## Validations         validaciones / restricciones / lógica de negocio         (core)
-## Risks / impact      riesgos e impactos técnicos                              (opt.)
-## Assumptions         supuestos                                                (opt.)
-## Estimated time      sizing XS–XL (desarrollo + pruebas internas)             (opt.)
-## Open questions      pendientes                                               (core)
+> Derived from docs/specs/NNN-spec-<slug>.md · generated by plan-new-loop
+
+## Origin              source spec (or prompt, if bootstrapped via spec-new)
+## Summary             the how, in 1–2 sentences                                (core)
+## Solution            technical/functional explanation of the implementation  (core)
+## Impacted            FE · BE · DB (schemas/tables/functions) · APIs · integr. (core)
+## Dependencies        docs / sources / databases / sessions                   (opt.)
+## Current state (AS-IS)   current wiring (interfaces and methods), brief      (opt.)
+## Target state (TO-BE)    target wiring                                       (opt.)
+## Final behavior      how the flow behaves at the end (aligned with the spec criteria) (core)
+## Phases              grouping phases (complexity XS–S)                       (core)
+## Tasks               tasks per phase (≤XS), with deps and live state (- [ ]) (core)
+## Validations         validations / constraints / business logic              (core)
+## Risks / impact      technical risks and impacts                             (opt.)
+## Assumptions         assumptions                                             (opt.)
+## Estimated time      XS–XL sizing (development + internal testing)           (opt.)
+## Open questions      pending                                                 (core)
 ```
 
-> **Escala con complejidad:** las `(core)` van **siempre**; las `(opt.)` solo si el plan lo amerita — un plan chico puede omitir `Dependencies`, AS-IS/TO-BE, `Risks`, `Assumptions`, `Estimated time`. Conciso > exhaustivo.
+> **Scales with complexity:** the `(core)` sections go **always**; the `(opt.)` ones only when the plan warrants them — a small plan may omit `Dependencies`, AS-IS/TO-BE, `Risks`, `Assumptions`, `Estimated time`. Concise > exhaustive.
 
-> **Implicación de catálogo:** `TECHNICAL-NOTE` deja de ser artefacto de session y se vuelve **secciones del plan-doc**. Reconciliado en [`plan-exec-loop`](../plan-exec-loop/SKILL.md): la única plan-exec session **no** lleva `TECHNICAL-NOTE` ni `TASKS` propios; el detalle técnico y el progreso viven inline en el plan-doc (living).
+> **Catalog implication:** `TECHNICAL-NOTE` stops being a session artifact and becomes **sections of the plan-doc**. Reconciled in [`plan-exec-loop`](../plan-exec-loop/SKILL.md): the single plan-exec session carries **no** `TECHNICAL-NOTE` nor its own `TASKS`; the technical detail and the progress live inline in the plan-doc (living).
 
-## Delta 2 — Gap taxonomy (de "plan")
+## Delta 2 — Gap taxonomy (of "plan")
 
-Reemplaza la gap taxonomy de spec por una orientada a planificación:
+Replaces the spec gap taxonomy with a planning-oriented one:
 
 | Gap | Signal | Resolved by |
 |---|---|---|
-| Approach/Solution sin definir | el cómo es vago | research / humano |
-| Componentes sin identificar | impacto FE/BE/BD desconocido | **research** (mapea el código) |
-| Wiring AS-IS desconocido | no se sabe el estado actual | **research** |
-| Fase muy grande | complejidad > S | humano (re-partir) |
-| Tarea no atómica | complejidad > XS | la IA re-parte |
-| Deps faltantes | orden no claro | research / humano |
-| Criterios del spec sin cubrir | tareas no trazan a acceptance criteria | la IA deriva + humano confirma |
-| Riesgos sin atender | riesgos técnicos sin mitigar/declarar | humano |
-| UI sin design SPEC *(si aplica)* | el plan incluye UI (FE/pantallas en `Impacted`, `## UI spec` en el spec, o tareas UI) sin `NNN-SPEC-*.md` en la sesión | **capacidad `ui-design`** |
+| Approach/Solution undefined | the how is vague | research / human |
+| Components unidentified | FE/BE/DB impact unknown | **research** (maps the code) |
+| AS-IS wiring unknown | current state unknown | **research** |
+| Phase too large | complexity > S | human (re-split) |
+| Task not atomic | complexity > XS | the AI re-splits |
+| Missing deps | order unclear | research / human |
+| Spec criteria uncovered | tasks don't trace to acceptance criteria | the AI derives + human confirms |
+| Unaddressed risks | technical risks unmitigated/undeclared | human |
+| UI without design SPEC *(if it applies)* | the plan includes UI (FE/screens in `Impacted`, `## UI spec` in the spec, or UI tasks) without `NNN-SPEC-*.md` in the session | **`ui-design` capability** |
 
 ## Delta 3 — What research investigates here
 
-El research **inline** del chasis se especializa: mapear **código/impacto** — componentes FE/BE/BD afectados, wiring AS-IS, dependencias. Alimenta las secciones `Solution`, `Impacted`, `Current state (AS-IS)`. La regla BD del chasis aplica igual (queries read-only a `SCRIPTS.sql`, MCP elegido vía pregunta de contenido si >1 sin default).
+The chassis' **inline** research specializes: mapping **code/impact** — affected FE/BE/DB components, AS-IS wiring, dependencies. It feeds the `Solution`, `Impacted`, `Current state (AS-IS)` sections. The chassis DB rule applies unchanged (read-only queries into `SCRIPTS.sql`, MCP chosen via a content question when >1 without default).
 
-## Delta 4 — Design SPECs (si el plan incluye UI)
+## Delta 4 — Design SPECs (when the plan includes UI)
 
-El gap **UI sin design SPEC** se resuelve **componiendo** la capacidad **`ui-design`** (default built-in [`ui-spec`](../../roles/ui-spec/SKILL.md); rebindeable vía `.workflow/skills.toml`; `off` → degrada a humano / `Open questions`): autora **un design SPEC por pantalla** como artefacto de la sesión — `NNN-SPEC-<SLUG>.md` (`001-SPEC-MODAL-EXPORT.md`, `002-SPEC-ADMIN-DASHBOARD.md`; numeración local a la sesión, ver [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)). **Deriva** de la sección `## UI spec` del spec si existe (la parte por pantalla y la eleva a detalle ejecutable); si no, autora desde el `Requirement` (design-system/tema/ambigüedades vía *structured-choice*, cuenta en el batch). Las **Tasks UI del plan referencian** la ruta de su SPEC — esa referencia es la fuente de verdad — y `plan-exec-loop` los lee como referencia de diseño. Es el mismo tercer modo de resolución de gap del chasis (junto a *research* y *humano*).
+The **UI without design SPEC** gap is resolved by **composing** the **`ui-design`** capability (built-in default [`ui-spec`](../../roles/ui-spec/SKILL.md); rebindable via `.workflow/skills.toml`; `off` → degrades to human / `Open questions`):
+
+- It authors **one design SPEC per screen** as a session artifact: `NNN-SPEC-<SLUG>.md` (numbering local to the session — see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
+- It **derives** from the spec's `## UI spec` section when present (splits it per screen and raises it to executable detail); otherwise it authors from the `Requirement` (design system/theme/ambiguities via *structured-choice*, counts in the batch).
+- The plan's **UI Tasks reference** their SPEC's path — that reference is the **source of truth** — and `plan-exec-loop` reads them as the design reference.
+- It is the same third gap-resolution mode of the chassis (next to *research* and *human*).
+
+## Sequence
+
+```
+plan-new-loop(spec):
+  input = glob(docs/specs/NNN-spec-*.md) | argument path
+  if the spec does NOT have ## Refinement decisions + ## Q&A traceability:
+    soft-suggest /w:spec-refine (the user may proceed anyway)
+  session = create_or_resume("<slug>-plan-new")               # CLI prepends global NNN
+  seed SESSION.Success criteria = coherence-gate checklist      # verification-first, BEFORE
+  work = plan skeleton (Delta 1) derived from the spec (+ checkpoint progress if resuming)
+  repeat:                                                      # chassis engine
+    gaps = detect_gaps(work)  (Delta 2 taxonomy)  minus the exhausted ones
+    if gaps == ∅: break
+    batch ≤3 → seed CHECKPOINT.Pending/Next → resolve each gap:
+      research (maps code/impact — Delta 3) · human (structured-choice) · ui-design (Delta 4)
+    integrate + update CHECKPOINT                              # artifact-first cycle
+  coherence gate (read-only) = Success criteria green:
+    - every spec acceptance criterion traces to a phase/task
+    - Final behavior covers the criteria
+    - phases XS–S · tasks XS · deps without cycles · Impacted consistent with Solution
+    - (UI) every screen/UI task traces to its design SPEC and does not contradict ## UI spec
+    whatever fails → comes back as a gap
+  structured_choice(content: [Guardar plan, Preguntar algo más], flow: [Compactar, Cerrar])
+  Guardar → write docs/plans/PPP-plan-<slug>.md (confirmation if it exists)
+finalize: CHECKPOINT persisted (+ BACKLOG only if something is deferred) + close session + report
+```
 
 ## Convergence / exit
 
-Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; es el "convergence gate" del chasis para PLAN-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`; y si el plan incluye UI: cada pantalla/tarea UI **traza a su design SPEC** (`NNN-SPEC-*.md`) y los SPECs no contradicen el `## UI spec` del spec (si existe). Lo que falle **vuelve como gap** — la trazabilidad criterio→tarea es una **invariante chequeada**, no una sección aparte. Si pasa → *structured-choice* (contenido: `Guardar plan` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, escribe `docs/plans/PPP-plan-<slug>.md` (con confirmación si existe) → `finalize` (persiste `CHECKPOINT`, y `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.
+- **No material gaps** → **coherence gate** (the *Sequence* checklist; the PLAN-new instance of the chassis convergence gate). Criterion→task traceability is a **checked invariant**, never a separate section.
+- Passes → `Guardar plan` (writes with confirmation if it exists) → `finalize`.
+- `Cerrar` at any time → `finalize` (persists `CHECKPOINT`; `BACKLOG` only if something is deferred; closes the session, reports).
 
-> **Después de generar:** el plan puede ir directo a `plan-exec`, o —si surgen cambios antes de ejecutar (nuevos requerimientos, ajustes de alcance)— pasar por [`plan-refine-loop`](../plan-refine-loop/SKILL.md) (`/w:plan-refine`, auxiliar y **no obligatorio**), que lo refina in place.
+> **After generating:** the plan can go straight to `plan-exec`, or — if changes arise before executing (new requirements, scope adjustments) — pass through [`plan-refine-loop`](../plan-refine-loop/SKILL.md) (`/w:plan-refine`, auxiliary and **not mandatory**), which refines it in place.

package/skills/w/loops/plan-refine-loop/SKILL.md

@@ -1,99 +1,123 @@
 ---
 name: plan-refine-loop
 description: >-
-  Refina un plan existente (docs/plans/PPP-plan-<slug>.md) editándolo IN
-  PLACE, como paso auxiliar y NO obligatorio del flujo PLAN antes de plan-
-  exec. Es a plan-new lo que spec-refine es a spec-new. Heir del chasis común
-  de los loops (loops/CHASSIS.md — motor gap-driven, session única con
-  research inline, structured-choice, artefactos como log vivo); reusa la gap
-  taxonomy y el coherence gate de plan-new-loop, agrega Refinement
-  decisions/Q&A traceability al plan
-  (traza, sin gating), y si el refine toca UI compone ui-design y
-  produce/actualiza design SPECs por pantalla. Lo arranca /w:plan-refine;
-  reanudable y re-corrible a demanda. Invocar cuando un plan ya generado deba
-  ajustarse antes de ejecutarlo.
+  Refines an existing plan (docs/plans/PPP-plan-<slug>.md) by editing it IN
+  PLACE — an auxiliary, NOT mandatory step before plan-exec. Heir of the
+  chassis (loops/CHASSIS.md). Deltas: reuses plan-new-loop's gap taxonomy and
+  coherence gate, adds Refinement decisions / Q&A traceability (trace, no
+  gating), and produces/updates design SPECs via ui-design when the refine
+  touches UI. Started by /w:plan-refine; resumable and re-runnable on demand.
+  Invoke when an already generated plan must be adjusted before executing it.
 ---
 
 # plan-refine-loop
 
-> **Heir** del chasis común — aquí **solo** los deltas de PLAN-refine. El motor no se repite.
+> **Heir** of the common chassis — **only** the PLAN-refine deltas live here. The engine is never repeated.
 
-> **Relación con los otros loops de PLAN:** `plan-new-loop` **genera** el plan desde el spec; `plan-refine-loop` **lo refina in place** (opcional); `plan-exec-loop` **lo ejecuta**. plan-refine es a plan-new lo que spec-refine es a spec-new.
+> **Relation to the other PLAN loops:** `plan-new-loop` **generates** the plan from the spec; `plan-refine-loop` **refines it in place** (optional); `plan-exec-loop` **executes it**. plan-refine is to plan-new what spec-refine is to spec-new.
 
 ## Flow
 PLAN
 
 ## Layer
-2 — la IA lo corre entero.
+2 — the AI runs it end to end.
 
-## Auxiliar / NO obligatorio
-`plan-exec` corre **cualquier** plan, refinado o no — **no** hay gate que exija plan-refine. Este loop existe para incorporar cambios (nuevos requerimientos, ajustes de alcance, deps/riesgos detectados al releer) **antes** de ejecutar, sin re-generar el plan desde cero.
+## Auxiliary / NOT mandatory
+`plan-exec` runs **any** plan, refined or not — there is **no** gate requiring plan-refine. This loop exists to incorporate changes (new requirements, scope adjustments, deps/risks spotted on re-read) **before** executing, without regenerating the plan from scratch.
 
 ## Started by
-`/w:plan-refine` — **reanudable** (mismo mecanismo del chasis, keyado off CHECKPOINT) y **re-corrible a demanda** (ver *Compact / resume*).
+`/w:plan-refine` — **resumable** (same chassis mechanism, keyed off CHECKPOINT) and **re-runnable on demand** (see *Compact / resume*).
 
 ## Reads
-`docs/plans/PPP-plan-*.md` (glob — localiza el plan por número; o la ruta exacta del argumento del comando). **Siempre el plan mismo**: este loop lo edita in place, no hay un archivo "refined" aparte.
+`docs/plans/PPP-plan-*.md` (glob — locates the plan by number; or the exact path from the command argument). **Always the plan itself**: this loop edits it in place; there is no separate "refined" file.
 
 ## Writes
-Actualiza `docs/plans/PPP-plan-<slug>.md` **in place** (cuando el usuario elige `Guardar plan refinado`): completa/ajusta secciones y **agrega** `## Refinement decisions` + `## Q&A traceability`. Como sobrescribe un doc existente, **con confirmación** del usuario. Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export. Si el refine **toca UI**, además produce/actualiza **design SPECs** (`NNN-SPEC-<SLUG>.md`) como artefactos **de su propia sesión** (ver *Delta 4* — no son `docs/`, no hay auto-export).
+Updates `docs/plans/PPP-plan-<slug>.md` **in place** (when the user picks `Guardar plan refinado`): completes/adjusts sections and **adds** `## Refinement decisions` + `## Q&A traceability`. Since it overwrites an existing doc, it asks the user's **confirmation**. It writes only `docs/plans` — never other `docs/` folders, no auto-export. If the refine **touches UI**, it also produces/updates **design SPECs** (`NNN-SPEC-<SLUG>.md`) as artifacts **of its own session** (see *Delta 4* — they are not `docs/`, no auto-export).
 
 ## Inherits
 
-Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate), **siempre antes** de estos deltas.
+Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **always before** these deltas. *(If `../` does not resolve: `CHASSIS.md` next to this file — global layout rule, chassis § Reference resolution.)*
 
-## Internal sessions — instancia PLAN-refine
+## Internal sessions — PLAN-refine instance
 
-Doctrina completa en el chasis (§ *Internal sessions* + *Numeración*). La instancia de este loop:
+Full doctrine in the chassis (§ *Internal sessions* + *Numbering*). This loop's instance:
 
 | Session | When | Artifacts | Role |
 |---|---|---|---|
-| **refine session** `NNN-<slug>-plan-refine/` | al arrancar el loop (o se reanuda/reabre) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` solo si difiere) | Dueña del run. Type = `refine`; descriptor `<slug>-plan-refine` (el `<slug>` sale del plan de entrada). |
+| **refine session** `NNN-<slug>-plan-refine/` | when the loop starts (or resumes/reopens) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` only if something is deferred) | Owns the run. Type = `refine`; descriptor `<slug>-plan-refine` (the `<slug>` comes from the input plan). |
 
-## Delta 1 — Deliverable: el PLAN, editado in place
+## Delta 1 — Deliverable: the PLAN, edited in place
 
-El plan usa el **mismo esqueleto** que produce [`plan-new-loop`](../plan-new-loop/SKILL.md) (en instalaciones aplanadas: la copia hermana `w-plan-new-loop/SKILL.md`) (§ *Delta 1 — PLAN RICO*: `Summary`/`Solution`/`Impacted`/`Phases`/`Tasks`/`Validations`/`Final behavior`/… con secciones `(core)` siempre y `(opt.)` según complejidad). plan-refine **no** cambia el esquema: **completa/ajusta** las secciones existentes **in place** y **agrega** dos de traza:
+The plan uses the **same skeleton** [`plan-new-loop`](../plan-new-loop/SKILL.md) produces (§ *Delta 1 — RICH PLAN*: `Summary`/`Solution`/`Impacted`/`Phases`/`Tasks`/`Validations`/`Final behavior`/… with `(core)` sections always and `(opt.)` by complexity). plan-refine does **not** change the schema: it **completes/adjusts** the existing sections **in place** and **adds** two trace sections:
 
 ```markdown
-## Refinement decisions   ← NEW (se AGREGA)
-Qué se ajustó al refinar y por qué (nuevos requerimientos, cambios de scope,
-deps/riesgos). Incluye lo resuelto vía research inline (ref a las CONCLUSIONS
-de la session).
+## Refinement decisions   ← NEW (ADDED)
+What was adjusted while refining and why (new requirements, scope changes,
+deps/risks). Includes what inline research resolved (ref to the session's
+CONCLUSIONS).
 
-## Q&A traceability       ← NEW (se AGREGA)
-Cada duda preguntada al humano + la respuesta elegida.
+## Q&A traceability       ← NEW (ADDED)
+Every doubt asked to the human + the chosen answer.
 ```
 
-> **Sin contrato de gating** (a diferencia de spec↔plan): la presencia de `## Refinement decisions`/`## Q&A traceability` en el plan es solo **traza de auditoría** — `plan-exec` **no** la exige ni la chequea (corre cualquier plan). Sirve para (a) distinguir un plan re-refinado de uno recién generado en el resume, y (b) dejar registro de qué cambió y por qué.
+> **No gating contract** (unlike spec↔plan): the presence of `## Refinement decisions`/`## Q&A traceability` in the plan is **audit trace only** — `plan-exec` neither requires nor checks it (it runs any plan). It serves to (a) distinguish a re-refined plan from a freshly generated one on resume, and (b) record what changed and why.
 
-> El plan **no muta por ejecución** (eso lo trackea plan-exec en las Tasks del plan-doc) — solo por un (re-)refine.
+> The plan **never mutates by execution** (plan-exec tracks that in the plan-doc's Tasks) — only by a (re-)refine.
 
-## Delta 2 — Gap taxonomy (de "plan")
+## Delta 2 — Gap taxonomy (of "plan")
 
-Reusa **íntegra** la gap taxonomy de [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 2*): Approach/Solution vago, componentes sin identificar, wiring AS-IS desconocido, fase muy grande, tarea no atómica, deps faltantes, criterios del spec sin cubrir, riesgos sin atender, UI sin design SPEC. **Diferencia de foco:** plan-new **construye** el plan desde cero; plan-refine **detecta qué cambió** respecto del plan ya escrito (o respecto del spec, si el spec se re-refinó) y cierra **esos** gaps — típicamente menos y más localizados. Un gap extra propio del re-refine:
+Reuses plan-new-loop's gap taxonomy **in full** ([`plan-new-loop`](../plan-new-loop/SKILL.md) § *Delta 2*): vague Approach/Solution, components unidentified, AS-IS wiring unknown, phase too large, task not atomic, missing deps, spec criteria uncovered, unaddressed risks, UI without design SPEC. **Focus difference:** plan-new **builds** the plan from scratch; plan-refine **detects what changed** against the written plan (or against the spec, if the spec was re-refined) and closes **those** gaps — typically fewer and more localized. One extra re-refine gap:
 
 | Gap | Signal | Resolved by |
 |---|---|---|
-| Deriva plan↔spec | el spec se re-refinó y el plan quedó desalineado | **research** (re-lee el spec) / **humano** |
+| Plan↔spec drift | the spec was re-refined and the plan fell out of line | **research** (re-reads the spec) / **human** |
 
 ## Delta 3 — What research investigates here
 
-Igual que plan-new (mapea código/impacto: componentes FE/BE/BD, wiring AS-IS, deps), pero **acotado al delta**: re-verifica solo lo que el cambio toca (no re-mapea todo el plan). Regla BD del chasis igual (read-only a `SCRIPTS.sql`, MCP vía pregunta si >1 sin default).
+Same as plan-new (maps code/impact: FE/BE/DB components, AS-IS wiring, deps), but **scoped to the delta**: it re-verifies only what the change touches (never re-maps the whole plan). Chassis DB rule unchanged (read-only into `SCRIPTS.sql`, MCP via a question when >1 without default).
 
-## Delta 4 — Design SPECs (si el refine toca UI)
+## Delta 4 — Design SPECs (when the refine touches UI)
 
-Mismo mecanismo que [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 4*: capacidad **`ui-design`** → `NNN-SPEC-<SLUG>.md` por pantalla, ver [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)), **acotado al delta**: solo las pantallas **nuevas o cambiadas** por el refine reciben design SPEC. El SPEC actualizado se escribe en **la sesión propia** del plan-refine (cada loop maneja los artefactos de SU sesión — no edita los de la sesión de plan-new) y el plan **re-apunta** la referencia de la Task UI al SPEC vigente. Pantallas no tocadas conservan su SPEC original.
+Same mechanism as [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 4*: the **`ui-design`** capability → per-screen `NNN-SPEC-<SLUG>.md`, see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)), **scoped to the delta**: only the screens **new or changed** by the refine get a design SPEC. The updated SPEC is written in **plan-refine's own session** (each loop manages ITS session's artifacts — it never edits plan-new's) and the plan **re-points** the UI Task reference to the current SPEC. Untouched screens keep their original SPEC.
 
 ## Compact / resume
 
-El resume **keya off el `CHECKPOINT`** de la refine session, no de un archivo "refined". Tres casos al ejecutar `/w:plan-refine` sobre un plan:
+Resume **keys off the `CHECKPOINT`** of the refine session, never a "refined" file. Three cases when `/w:plan-refine` runs over a plan:
 
-1. **En curso** (existe `CHECKPOINT.md` en la refine session) → reanuda desde el avance (gaps resueltos, Q&A, `attempts`, research inline en curso).
-2. **Sin avance** (no hay CHECKPOINT y el plan **no** tiene `Refinement decisions`/`Q&A traceability`) → arranca desde cero leyendo el plan (`PPP-plan-*.md`).
-3. **Ya refinado / re-refine on demand** (no hay CHECKPOINT abierto pero el plan **ya tiene** `Refinement decisions`/`Q&A traceability`) → **operación de primera clase**: mientras el flujo siga en PLAN, re-correr `/w:plan-refine` sobre el mismo plan **cuantas veces haga falta** está soportado. `create_or_resume` detecta la refine session existente —típicamente **cerrada** tras converger— por descriptor + `## Origin` y la **reabre** (ver chasis § *Internal sessions*: detección con `aw sessions --state all` / `aw resume-summary --include-recent-closed`, reapertura con `aw session-resume --code <NNN> --reopen`); re-refinamiento incremental leyendo el **plan mismo**; al `Guardar`, edita in place con confirmación.
+1. **In progress** (a `CHECKPOINT.md` exists in the refine session) → resume from the recorded progress (resolved gaps, Q&A, `attempts`, in-flight inline research).
+2. **No progress** (no CHECKPOINT and the plan does **not** have `Refinement decisions`/`Q&A traceability`) → start from zero reading the plan (`PPP-plan-*.md`).
+3. **Already refined / re-refine on demand** (no open CHECKPOINT, but the plan **already has** the 2 sections) → **first-class operation**, as many times as needed while the flow stays in PLAN:
+   - `create_or_resume` finds the existing refine session (typically **closed** after convergence) by descriptor + `## Origin` and **reopens** it: `aw session-resume --code <NNN> --reopen` (detection: `aw sessions --state all`).
+   - Incremental re-refinement reading the **plan itself**; on `Guardar`, edits in place with confirmation.
 
-> **Continuidad inter-turno** (chasis, fila 2): un **comando de flujo** abre "nueva línea de trabajo" (sesión nueva) — **salvo re-correr el mismo flujo sobre la misma entrada** (mismo plan), que hace `create_or_resume` (reanuda/reabre en vez de duplicar).
+> **Inter-turn continuity** (chassis, row 2): a flow command opens a "new work line" (new session) — **except re-running the same flow over the same input** (same plan), which does `create_or_resume` (resumes/reopens instead of duplicating).
+
+## Sequence
+
+```
+plan-refine-loop(plan):
+  input = glob(docs/plans/PPP-plan-*.md) | argument path       # always the plan itself (in place)
+  session = create_or_resume("<slug>-plan-refine")             # reopens if it exists (see Compact / resume)
+  seed SESSION.Success criteria = coherence-gate checklist     # verification-first, BEFORE
+  work = read(plan) (+ the spec if realignment is needed; + checkpoint progress if resuming)
+  repeat:                                                      # chassis engine
+    gaps = detect_gaps(work)  (plan-new taxonomy + plan↔spec drift)  minus the exhausted ones
+    if gaps == ∅: break
+    batch ≤3 → seed CHECKPOINT.Pending/Next → resolve each gap:
+      research (scoped to the delta — Delta 3) · human (structured-choice) ·
+      ui-design (Delta 4, only new/changed screens)
+    integrate + update CHECKPOINT                              # artifact-first cycle
+  coherence gate (read-only) = Success criteria green:
+    - plan-new checklist (criterion→task · Final behavior · XS–S/XS · deps · Impacted↔Solution · UI→current SPEC)
+    - re-refine's own check: the plan is REALIGNED with what changed
+    whatever fails → comes back as a gap
+  structured_choice(content: [Guardar plan refinado, Preguntar algo más], flow: [Compactar, Cerrar])
+  Guardar → edit in place (with confirmation) + insert/update Refinement decisions + Q&A traceability
+finalize: CHECKPOINT persisted (+ BACKLOG only if something is deferred) + close session + report
+```
 
 ## Convergence / exit
 
-Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; el "convergence gate" del chasis para PLAN, mismo que plan-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`, si hay UI cada pantalla/tarea UI **traza a su design SPEC vigente**, y —propio del re-refine— **el plan quedó realineado** con lo que cambió. Lo que falle **vuelve como gap**. Si pasa → *structured-choice* (contenido: `Guardar plan refinado` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, edita `docs/plans/PPP-plan-<slug>.md` in place (con confirmación) + inserta `Refinement decisions`/`Q&A traceability` → `finalize` (persiste `CHECKPOINT`; `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.
+- **No material gaps** → **coherence gate** (the *Sequence* checklist; plan-new's gate + the re-refine's own realignment check).
+- Passes → `Guardar plan refinado` (edits in place with confirmation) → `finalize`.
+- `Cerrar` at any time → `finalize` (persists `CHECKPOINT`; `BACKLOG` only if something is deferred; closes the session, reports).