@tacuchi/agent-workflow-cli 11.0.0 → 12.0.0

package/skills/agent-workflow/references/orchestration.md

@@ -1,86 +0,0 @@
-# Orchestration
-
-Decision-support commands the lifecycle skill uses during planning and execution: when to plan, when the topic changed, which specialty to compose, what phase you are in, what the workspace stack looks like.
-
-## auto-plan-decide
-
-Decide whether an OBJETIVO needs full planning, lite planning, or skip-to-execution. Returns a recommendation plus an estimated effort in hours.
-
-```bash
-agent-workflow auto-plan-decide --objetivo "Bug: login redirect loop"
-agent-workflow auto-plan-decide --objetivo-file .workflow/sessions/sessionNNN-.../OBJETIVO.md
-```
-
-Output:
-
-```json
-{ "scope": "lite", "rationale": "...", "eta_hours": 2.0 }
-```
-
-`scope` is one of `skip` | `lite` | `full`.
-
-## topic-change-check
-
-Detect whether a fresh user request diverges from the active session's OBJETIVO. Used to suggest opening a new session instead of polluting the current one.
-
-```bash
-agent-workflow topic-change-check \
-  --objetivo-file .workflow/sessions/sessionNNN/OBJETIVO.md \
-  --request "Quiero refactorizar el módulo de pagos"
-```
-
-Both `--objetivo` (or `--objetivo-file`) and `--request` are required.
-
-## specialty-choose
-
-Recommend specialty skills (and whether to invoke them explicitly) for a given phase + OBJETIVO. The host plugin can register specialty workflows; this command surfaces the matches.
-
-```bash
-agent-workflow specialty-choose --phase execution --objetivo "Construir CRUD de productos"
-agent-workflow specialty-choose --phase planning --objetivo-file path/to/OBJETIVO.md
-```
-
-`--phase` is required. `--objetivo` (or `--objetivo-file`) is optional but recommended.
-
-## phase-detect
-
-Suggest the current session phase from the artifacts on disk (no mutation). Inspects which of `OBJETIVO.md`, `TASKS.md`, `DECISIONES.md`, `CHECKPOINT.md`, etc. are present and how complete they are.
-
-```bash
-agent-workflow phase-detect --code session035
-```
-
-## phase-next
-
-Advance the session phase to the next slot in the lifecycle (planning → execution → validation → closure). Mutates the project block. May emit two JSON objects: project-md upsert + phase-next result.
-
-```bash
-agent-workflow phase-next --code session035
-```
-
-## stack
-
-Detect the project stack — language, framework, database, build tool — by scanning the project root.
-
-```bash
-agent-workflow stack
-agent-workflow stack --project-dir /Users/me/Git/some-repo
-```
-
-## workflows
-
-Dump registered specialty workflows. Empty when no flow plugin is loaded; useful for diagnostics.
-
-```bash
-agent-workflow workflows
-```
-
-## skill-index
-
-Lazy-load the skill index of the host plugin (frontmatter only — does not load skill bodies).
-
-```bash
-agent-workflow skill-index --plugin-root /Users/me/Git/core-workflow-plugin
-agent-workflow skill-index --plugin-root /path --flow dev
-agent-workflow skill-index --plugin-root /path --exported-only
-```

package/skills/agent-workflow/references/profile-parametrization.md

@@ -1,88 +0,0 @@
-# Profile parametrization — guía para los 10 skills sensibles a empresa
-
-Este documento centraliza qué campos de `profile.json` (resuelto por `src/application/profile/profile-service.ts`) drivean el comportamiento de cada skill parametrizado.
-
-Profile cascade (de mayor a menor precedencia):
-1. Flag `--profile <path>`
-2. Env `AW_PROFILE`
-3. `~/.config/agent-workflow/profile.json` (XDG-ish, user-level)
-4. `<cwd>/.<namespace>/profile.json` (workspace-level)
-5. `DEFAULT_PROFILE` embebido (todos los campos en valores agnósticos)
-
-Schema completo en `src/application/profile/profile-service.ts:Profile`.
-
-## Skills parametrizados (10)
-
-### 5 antes-QTC (D4 ampliado — session082)
-
-#### 1. `doctrine/project-init/`
-- **Campo**: `profile.claude_md_block` (default `AW-PROJECT`; QTC profile: `QTC-PROJECT`).
-- **Behavior**: el bloque insertado en `CLAUDE.md`/`AGENTS.md` lleva el marker `<!-- <claude_md_block>-START -->` / `<!-- <claude_md_block>-END -->`.
-- **Detección legacy**: `<!-- QTC-WORKFLOW-START -->` (pre-v0.8) se detecta sin importar el profile; si presente, recomendar `/agent-workflow:migrate`.
-
-#### 2. `doctrine/hub-init/`
-- Idem `project-init` para el marker del bloque hub.
-- Adicional: detección de "modo hub vs project" sigue siendo agnóstica.
-
-#### 3. `doctrine/doctor/`
-- **Campo**: `profile.mcp_databases[]`.
-- **Behavior**: la sección "MCP connectivity check" itera sobre `profile.mcp_databases[]`. Si el array está vacío, la sección se omite ("no MCP configured, skip BD section").
-
-#### 4. `doctrine/migrate/`
-- **Campo**: `profile.migrate_legacy_rules[]`.
-- **Behavior**: la lista de reglas legacy → moderno se carga del profile. Profile QTC trae ~10 reglas (`.claude/sessions/` → `.workflow/sessions/`, ES headers → EN, `QTC-WORKFLOW` → `claude_md_block`, etc.). Profile vacío → migrate es no-op.
-- **Reglas hard-coded en el skill**: cero. Lo que migre depende 100% del profile.
-
-#### 5. `doctrine/rules/`
-- **Campo**: `profile.custom_anchors[]`.
-- **Behavior**: el bundle de anchors universales (`agent-workflow:commits-policy`, `agent-workflow:sandbox-readonly`, etc.) se renderiza siempre. Los anchors del profile se agregan al final del bundle bajo "## Anchors específicos del profile". Profile QTC inyecta `qtc:mcp-readonly` (legacy alias) automáticamente si `profile.mcp_databases[]` no está vacío.
-
-### 5 ambiguos (parametrizados por contexto)
-
-#### 6. `specialties/analyze-investigate/`
-- **Campo**: `profile.mcp_databases[]`.
-- **Behavior**: la fase "BD investigation" enumera las MCPs disponibles desde el profile. Si vacío, advierte "no MCP configured, skip BD section" y prosigue con read-only de código.
-
-#### 7. `standards/coding-standards/`
-- **Campo**: `profile.mcp_databases[]` (sección BD) + `profile.examples_path` (ejemplos override).
-- **Behavior**: sección "BD vía MCP" se renderiza dinámicamente desde el profile. Las secciones Angular/Spring/Node + FE-BE R1-R6 son agnósticas; profile.examples_path permite override de ejemplos para empresas que no usan Angular/Spring.
-
-#### 8. `exports/export-arq/`
-- **Campo**: `profile.mcp_databases[]` (paso 4 BD esquemas).
-- **Behavior**: el paso "Resolución BD" extrae esquemas iterando sobre `profile.mcp_databases[]`. C4 model conceptual es agnóstico.
-
-#### 9. `exports/export-report/`
-- **Campo**: `profile.lexicon_path` (default `null` = sin lexicon).
-- **Behavior**: si `profile.lexicon_path` apunta a un archivo, se carga como léxico empresa-específico y se aplica a la prosa del export. Profile QTC apunta a su archivo de léxico; profile vacío → no se aplica léxico.
-
-#### 10. `specialties/refactor/`
-- **Campo**: `profile.examples_path` (override de ejemplos Strangler Fig).
-- **Behavior**: la doctrina (Strangler Fig + 4 fases) es agnóstica. Los ejemplos en cada fase se cargan desde `profile.examples_path` si está definido. Profile QTC carga ejemplos QTC; profile vacío → ejemplos genéricos.
-
-## Hook adicional
-
-#### `hooks/hooks.template.json` — `sql-mutation-guard` matcher
-- **Campo**: `profile.mcp_databases[]`.
-- **Behavior**: el matcher `mcp__<db>__execute_sql` se compila dinámicamente desde el profile. Sin profile → matcher disabled, hook no se registra (skip silencioso).
-
-## Cómo cargar el profile en un skill (para devs)
-
-Patrón canónico en TypeScript:
-
-```typescript
-import { resolveProfile } from "../../application/profile/profile-service.js";
-
-const resolved = await resolveProfile(fs, env, { flagPath: args.values.get("profile") });
-if ("code" in resolved) {
-  // PROFILE_NOT_FOUND / PROFILE_INVALID_JSON / PROFILE_INVALID_SCHEMA
-  return errorResult(resolved);
-}
-const { profile, source, path } = resolved;
-// Use profile.mcp_databases, profile.claude_md_block, etc.
-```
-
-Para skills en markdown (sin código), referenciar este documento en el frontmatter o en una sección "## Profile parametrization" del SKILL.md específico.
-
-## Anchors legacy
-
-Los anchors `qtc:<topic>` se mantienen como alias permanentes en `references/legacy-anchors.md` para que CLAUDE.md históricos no rompan. Anchor canónico nuevo: `agent-workflow:<topic>`.

package/skills/agent-workflow/references/self.md

@@ -1,68 +0,0 @@
-# Self — manage the CLI itself
-
-`agent-workflow self <subcommand>` covers tasks that target the CLI binary itself: namespace inspection, install diagnostics, in-place upgrade, and skill installation.
-
-```bash
-agent-workflow self <namespace|doctor|update|install-skill>
-```
-
-## self namespace
-
-Print the resolved namespace and the source it came from (env / flag / config / default).
-
-```bash
-agent-workflow self namespace
-
-# Result:
-# { "namespace": "workflow", "source": "env", "expected_paths": { "user_dir": "~/.workflow", "workspace": ".workflow" } }
-```
-
-Use this when paths look wrong — it tells you exactly which override won the precedence chain.
-
-## self doctor
-
-Health check the CLI install: binary location, Node version, namespace config, expected paths, and whether the skill is installed under `~/.claude/skills/agent-workflow/`.
-
-```bash
-agent-workflow self doctor
-```
-
-Returns a structured report. Non-zero exit when something is broken.
-
-## self update
-
-Wraps `npm install -g @tacuchi/agent-workflow-cli@latest`. Confirms interactively when stdout is a TTY.
-
-```bash
-agent-workflow self update
-```
-
-Skips confirmation in non-TTY contexts. Failures from the underlying `npm` invocation propagate.
-
-## self install-skill
-
-Copy the bundled skill (shipped inside the CLI tarball) to `~/.claude/skills/agent-workflow/`. After installation the skill is auto-discovered by Claude Code on next session start.
-
-```bash
-# Default — copy from the bundled location inside the CLI tarball
-agent-workflow self install-skill
-
-# Override the source (local checkout, fork)
-agent-workflow self install-skill --from /Users/me/Git/agent-workflow-cli/skills/agent-workflow
-
-# Overwrite an existing install
-agent-workflow self install-skill --force
-
-# Print the plan without executing
-agent-workflow self install-skill --dry-run
-```
-
-Flags:
-
-| Flag | Default | Notes |
-|---|---|---|
-| `--from <path>` | bundled location inside the CLI tarball | Accepts a local filesystem path only. Remote URLs are no longer supported — the skill is bundled-only. |
-| `--force` | off | Required to overwrite an existing `~/.claude/skills/agent-workflow/` directory. |
-| `--dry-run` | off | Print the resolved source/destination and exit without copying. |
-
-The installer validates that the source contains a `SKILL.md` with valid frontmatter (`name`, `description`) before copying.

package/skills/agent-workflow/references/session-mgmt.md

@@ -1,109 +0,0 @@
-# Session management
-
-Commands that create, list, resume, and close sessions, plus the consolidated artifact dump.
-
-A session lives at `<workspace>/.<namespace>/sessions/sessionNNN-<flow>-<slug>/` and is registered as a row in `<workspace>/.<namespace>/HISTORY.md` plus an entry in the `<NS>-PROJECT` block of `CLAUDE.md` / `AGENTS.md`.
-
-## sessions
-
-List sessions with state counts and the next correlative number.
-
-```bash
-agent-workflow sessions
-agent-workflow sessions --state active
-agent-workflow sessions --state closed
-agent-workflow sessions --all                # alias of --state all
-agent-workflow sessions --include-legacy     # also walk .claude/.codex legacy folders
-agent-workflow sessions --verbose            # include extra metadata per session
-```
-
-Output (truncated):
-
-```json
-{
-  "namespace": "agent-workflow",
-  "next_number": 36,
-  "active": [{ "code": "session035", "folder": "...", "flow": "dev" }],
-  "closed_count": 34,
-  "total": 35
-}
-```
-
-## session-create
-
-Create a new session: scaffolds the folder, writes a stub `OBJETIVO.md`, adds a row to `HISTORY.md`, and registers the session in the project block. Returns the upserted project block JSON.
-
-```bash
-agent-workflow session-create \
-  --flow dev \
-  --name fix-login-loop \
-  --objetivo "Resolver redirect loop tras login en producción"
-
-# With phased / refactor metadata:
-agent-workflow session-create --flow dev --name normalize-codusuario \
-  --tipo refactor \
-  --branches "core:feature/normalize,solicitud:feature/normalize"
-
-# Origen handoff (this session continues from a previous one):
-agent-workflow session-create --flow dev --name aw-skill-repo \
-  --from "design:034"
-```
-
-Flags:
-
-| Flag | Required | Notes |
-|---|---|---|
-| `--flow <core\|dev\|design\|analyze>` | yes | Determines slug prefix and downstream specialty composition. |
-| `--name <slug>` | yes | Kebab-case; becomes the session slug suffix. |
-| `--objetivo <text>` | yes | Free-form requirement description that lands in `OBJETIVO.md`. |
-| `--branches <alias:branch[,alias:branch]>` | no | Pre-fills the work branch table. |
-| `--from <flow:NNN>` | no | Records origin handoff. |
-| `--tipo <feature\|refactor\|bugfix>` | no | Persisted in `OBJETIVO.md` for dev sessions. |
-| `--modalidad <tecnica\|datos\|incidente>` | no | Persisted for analyze sessions. |
-
-## session-resume
-
-Load the resume payload (objetivo + phase) for a session.
-
-```bash
-agent-workflow session-resume                      # active session in workspace
-agent-workflow session-resume --code session035    # explicit code
-```
-
-Use this for the cold-start flow when you do not have a CHECKPOINT.md yet (newer sessions: prefer `checkpoint-read` + `resume-summary`).
-
-## session-close
-
-Close a session: marks the HISTORY row as closed and removes the entry from `<NS>-PROJECT`. Emits two JSON objects on stdout (project-md upsert first, then close result), mirroring the legacy Python contract.
-
-```bash
-agent-workflow session-close --code session035
-agent-workflow session-close --code session035 \
-  --graduated-decisions "DEC-007,DEC-009" \
-  --graduated-plan "TASKS" \
-  --graduated-scripts "019" \
-  --refs "[CHECKPOINT](.workflow/sessions/session035-dev-aw-skill-repo/CHECKPOINT.md)"
-```
-
-Flags:
-
-| Flag | Notes |
-|---|---|
-| `--code <sessionNNN>` | Required if multiple active sessions. |
-| `--graduated-decisions <list>` | Comma-separated DEC-NNN ids that were promoted to `docs/decisiones/`. |
-| `--graduated-plan <slug>` | Marks plan graduation (typically `TASKS`). |
-| `--graduated-scripts <NNN>` | SQL release bundle correlative if applicable. |
-| `--graduated-design <slug>` | Design entrega graduation. |
-| `--graduated-propuesta <slug>` | Propuesta graduation. |
-| `--refs <markdown>` | Replace the auto-generated Refs cell in HISTORY.md. |
-
-## session-artifacts
-
-Consolidated dump of a session's artifacts (OBJETIVO + TASKS + flags). Useful for prompt context or for debugging when you want everything at once.
-
-```bash
-agent-workflow session-artifacts --code session035
-agent-workflow session-artifacts --code session035 --verbose
-```
-
-Flags: `--code <sessionNNN>`, `--verbose`.

package/skills/agent-workflow/references/sources.md

@@ -1,102 +0,0 @@
-# Sources, branches, project block, multi-root
-
-Workspace state lives in the `<NS>-PROJECT` block of `CLAUDE.md` / `AGENTS.md`. These commands read or update that state, plus surface git context for declared sources.
-
-## sources
-
-List sources from the project block, enriched with git status (current branch, dirty flag, ahead/behind).
-
-```bash
-agent-workflow sources
-agent-workflow sources --no-git                    # skip git enrichment (fast)
-agent-workflow sources --session session035        # constrain to sources of a session
-agent-workflow sources --scope core,dev,design     # filter by alias
-agent-workflow sources --flow dev                  # heuristic source filtering by flow
-agent-workflow sources --verbose
-```
-
-## check-branch
-
-Verify a source branch matches the expected work branch declared in the project block.
-
-```bash
-agent-workflow check-branch --source core                       # by alias
-agent-workflow check-branch --path /Users/me/Git/foo            # by path
-agent-workflow check-branch --file /Users/me/Git/foo/src/x.ts   # by descendant file
-agent-workflow check-branch --source core --strict              # exit 2 on mismatch
-agent-workflow check-branch --source core --session session035
-agent-workflow check-branch --source core --flow dev
-```
-
-Returns `{ match: true|false, expected, current, ... }`. `--strict` makes mismatch cause a non-zero exit.
-
-## workspace-mode
-
-Read the workspace mode (`project` vs `hub`) plus declared sources and current working branches.
-
-```bash
-agent-workflow workspace-mode
-agent-workflow workspace-mode --verbose
-```
-
-`hub` mode means the workspace coordinates ≥2 sources (the project block has a `Mode: hub` marker). Otherwise `project`.
-
-## project-md-upsert
-
-Read or update the `<NS>-PROJECT` block.
-
-```bash
-# Read mode
-agent-workflow project-md-upsert --read
-agent-workflow project-md-upsert --read --verbose
-
-# Init the block (creates it if missing)
-agent-workflow project-md-upsert --init --proyecto "Marketplace" --mode hub
-
-# Add a session entry
-agent-workflow project-md-upsert --add-session sessionNNN-dev-foo \
-  --phase planning --branches "core:feature/foo,dev:feature/foo"
-
-# Update the phase of an existing session
-agent-workflow project-md-upsert --update-phase --add-session sessionNNN-dev-foo --phase execution
-
-# Remove a session
-agent-workflow project-md-upsert --remove-session sessionNNN-dev-foo
-
-# Set a working branch
-agent-workflow project-md-upsert --working-branch "core:feature/custom-CLI"
-```
-
-Operations are mutually exclusive — pick one of `--read | --init | --add-session | --remove-session | --update-phase`.
-
-## upgrade-hub-mode
-
-Detect when ≥2 sources are declared in a workspace stuck in `project` mode and apply the `Mode: hub` upgrade.
-
-```bash
-agent-workflow upgrade-hub-mode --dry-run    # preview only
-agent-workflow upgrade-hub-mode              # apply
-```
-
-## attach-multiroot
-
-Configure multi-root visibility for the host harness (Claude Code + Codex CLI). Useful when a hub workspace coordinates folders that live outside the primary root.
-
-```bash
-agent-workflow attach-multiroot --from-sources                 # use declared sources
-agent-workflow attach-multiroot --path /Users/me/Git/core --path /Users/me/Git/dev
-agent-workflow attach-multiroot --paths "/Users/me/Git/core,/Users/me/Git/dev"
-agent-workflow attach-multiroot --from-sources --global        # write to user-level config
-agent-workflow attach-multiroot --from-sources --workspace foo # named workspace slot
-agent-workflow attach-multiroot --from-sources --skip-codex    # only Claude Code
-```
-
-## detach-multiroot
-
-Reverse of `attach-multiroot`.
-
-```bash
-agent-workflow detach-multiroot --from-sources
-agent-workflow detach-multiroot --path /Users/me/Git/core
-agent-workflow detach-multiroot --global --workspace foo
-```

package/skills/agent-workflow/specialties/README.md

@@ -1,14 +0,0 @@
-# specialties/
-
-Kinds graduables al cerrar sesión. Cada specialty declara cómo se materializa el artefacto final y su routing (hub vs fuente).
-
-Contenido esperado (T2 PR2):
-
-- `decision.md` — decisión arquitectónica (hub).
-- `manual.md` — manual técnico (fuente).
-- `script.md` — script SQL/bash (fuente).
-- `especificacion.md` — spec de feature/system (hub).
-- `conclusion.md` — conclusión de analyze (hub).
-- `release.md` — release notes (fuente).
-
-Routing automático lo provee `agent-workflow graduation-routing` según `workspace_mode` y kind. Sólo estos 6 graduan al cerrar — el resto queda en sesión.

package/skills/agent-workflow/specialties/analyze-conclude/SKILL.md

@@ -1,175 +0,0 @@
----
-name: analyze-conclude
-description: "Produce CONCLUSIONS.md como cierre del análisis para las 3 modalidades (technical/incident/data). Una sola estructura: summary + conclusions con evidencia + recommendations con responsable + traceability. Vive en la sesión, no se gradúa por defecto. Invocado al final de execution en sesiones analyze cuando ya existe FINDINGS.md. Reemplaza a analyze-rfc, analyze-data y analyze-postmortem."
-version: 2.1.0
----
-
-# analyze-conclude — qtc v2.1+
-
-Specialty skill **analyze**: produce el cierre del análisis para cualquier modalidad (technical / incident / data). Última fase de execution para sesiones analyze.
-
-> **v2.0+ unifica el output**: reemplaza a `analyze-rfc`, `analyze-data` y `analyze-postmortem`. Las 3 modalidades comparten una sola estructura (`CONCLUSIONS.md`) con la sección `## Modality` embebida. La diferencia entre modalidades queda en el contenido de Conclusions / Recommendations, no en archivos separados.
-
-## Cuándo se invoca
-
-- Composición desde `agent-workflow:session` al final de execution si OBJECTIVE declara `## Modality: technical|incident|data` (legacy: `## Modalidad: tecnica|incidente|datos`) y existe `FINDINGS.md` (legacy: `HALLAZGOS.md`).
-- NL del usuario: "armá las conclusiones", "cerrá el análisis", "documentá las recomendaciones", "armá la propuesta", "spec final del análisis", "armá el post-mortem", "armá el informe".
-
-## Acción
-
-Producir `.workflow/sessions/<folder>/CONCLUSIONS.md` con la estructura canónica única.
-
-### Estructura canónica de CONCLUSIONS.md
-
-```markdown
-# Conclusions — sessionNNN-analyze-<slug>
-
-## Modality
-
-<technical | incident | data>
-
-## Summary
-
-[1-3 oraciones: qué se investigó, qué se concluyó, qué hacer al respecto.]
-
-## Conclusions
-
-- **C1**: <conclusión + link a evidencia (`EVIDENCE.md#section` o `FINDINGS.md#patron`)>
-- **C2**: <conclusión + evidencia>
-- **C3**: ...
-
-## Recommendations
-
-- **R1**: <acción concreta + responsable + cuándo (fecha objetivo o ventana)>
-- **R2**: <acción + responsable + cuándo>
-- **R3**: ...
-
-## Traceability
-
-- EVIDENCE: `.workflow/sessions/<folder>/EVIDENCE.md`
-- FINDINGS: `.workflow/sessions/<folder>/FINDINGS.md`
-- queries/: lista de archivos si aplica
-- Decisiones derivadas: <DEC-NNN si aplica> (en DECISIONS.md de la sesión)
-
-## Open (gaps)  [opcional]
-
-- <pregunta sin respuesta que requiere más investigación>
-- <hipótesis sin probar>
-```
-
-### Reglas comunes a las 3 modalidades
-
-- **Conclusions con evidencia**: cada `**CN**` enlaza al artefacto que lo sustenta (EVIDENCE o FINDINGS). Sin evidencia no se afirma.
-- **Recommendations accionables**: cada `**RN**` declara responsable (persona/equipo, no "alguien") y cuándo (fecha objetivo o ventana, no "pronto").
-- **Sin código de implementación**: el documento describe QUÉ hacer, no CÓMO. La implementación es de flow=dev (otra sesión, vía handoff `--from analyze:NNN`).
-- **Honest gaps**: si quedan preguntas sin responder, va `## Open (gaps)`. No esconder debilidades del análisis.
-- **Modality embebida**: la sección `## Modality` declara el sabor (technical / incident / data). El contenido del cuerpo se modula por modalidad pero la estructura no cambia.
-
-## Modulación por modalidad
-
-La estructura es única. Lo que cambia es el peso y el contenido de cada sección.
-
-### Modality: technical (propuesta tradicional)
-
-- **Summary**: qué decisión técnica se recomienda y por qué.
-- **Conclusions**: opciones evaluadas con tradeoffs (pros/cons/costo S/M/L). Cada CN puede ser una opción descartada con su razón o la opción recomendada con su justificación.
-- **Recommendations**: típicamente una `**R1**` que describe la decisión final + acciones de seguimiento (handoff a dev, ajustes de doctrina).
-- **Open**: dependencias externas, decisiones que dependen de otra sesión.
-
-Reglas específicas:
-- **3 opciones es óptimo**: si el espacio es claro, 2 alcanza. Si hay ambigüedad alta, hasta 4. Más es ruido.
-- **Tradeoffs explícitos**: nunca "ventaja: bueno". Cada Pro/Con específico.
-- **Costo estimado obligatorio**: S/M/L de implementación.
-- **Decisión recomendada con justificación**: no presentar opciones sin elegir. Si genuinamente no hay una mejor, declararlo y describir cómo decidir (ej. "depende de tolerancia a downtime: A si 0, B si <1h").
-
-### Modality: incident (post-mortem tradicional)
-
-- **Summary**: qué pasó, cuándo, impacto, causa raíz, qué se hizo. Incluir severidad declarada (SEV1/2/3/4) con justificación de 1 línea.
-- **Conclusions**: timeline (`**C1**`: timeline), causa raíz (`**C2**`: causa raíz), impacto cuantificado (`**C3**`: impacto), lo que funcionó / no funcionó (`**C4**`/`**C5**`).
-- **Recommendations**: acciones inmediatas hechas (`**R1**`), acciones preventivas con owner + fecha (`**R2**`/`**R3**`/...). Priorizar P1 = bloqueo de SEV similar futuro; P2 = reduce probabilidad; P3 = mejora detección/respuesta.
-- **Open**: lecciones aprendidas pendientes de socializar.
-
-Reglas específicas:
-- **Sin culpas**: foco en sistemas y procesos, no personas. "El deploy no tenía smoke test" > "Juan deployó sin testear".
-- **Timeline en hora local + UTC si cross-timezone**.
-- **Acciones preventivas con owner + fecha**: vagueness mata follow-up.
-- **Honest about gaps**: si no se sabe la causa raíz exacta, decirlo.
-
-Para detalles de severidad, impacto cuantitativo y timeline de comunicación, ver `references/incident-classification.md`.
-
-### Modality: data (informe de análisis)
-
-- **Summary**: qué se midió, qué se encontró, qué hacer al respecto.
-- **Conclusions**: hallazgos numéricos con valor + comparación + tendencia (`**C1**`: métrica X = ..., +33% vs período anterior, link a query). Interpretación en contexto del negocio.
-- **Recommendations**: acciones SUGERIDAS basadas en los datos (técnicas, de producto/proceso, investigación adicional).
-- **Traceability**: agregar `queries/*.sql` con cada métrica enlazada a la query que la produjo.
-- **Open**: limitaciones del análisis (sample size, sesgos conocidos, datos faltantes).
-
-Reglas específicas:
-- **Números siempre con unidad y contexto**: "2.4M" sin más es ruido; "2.4M solicitudes en Q1 2026 (vs 1.8M Q4 2025, +33%)" tiene contenido.
-- **Citar queries**: cada métrica enlaza a la query que la produjo. Reproducibilidad.
-- **Metodología documentada**: tamaño de muestra, ventana, manejo de nulos, outliers, tests de hipótesis si aplican. Sin metodología los números son indefendibles.
-- **Limitaciones honestas**: si hay sample bias, datos faltantes, ventana corta, decirlo en `## Open`.
-- **Acciones SUGERIDAS, no ordenadas**: el informe propone; el usuario/equipo decide qué accionar.
-
-#### Metodología estadística (modality=data)
-
-Decisiones metodológicas que el documento debe declarar al elegir modality=data:
-
-- **Tamaño de muestra**: `n = X (universo|sample, ventana <fecha>–<fecha>)`. Para sampling: `n ≥ 384` para 95% confianza, ±5% margen sobre proporción 0.5 (peor caso).
-- **Intervalos de confianza**: default 95%. Reportar como `valor ± margen` o `[lower, upper]`. Wilson/Clopper-Pearson para proporciones; t-Student si n<30; Poisson exact CI para conteos.
-- **Manejo de nulos**: excluir (<5% sin bias), imputar (<15% con justificación), reportar separado (≥15% o estado-nulo informativo), o bloquear análisis si invalida conclusiones.
-- **Outliers**: IQR (default), z-score (normal), percentil 1/99 (robustez), o domain rule. Reportar cuántos hay y su impacto.
-- **Tests de hipótesis** (opcional): H0/H1 explícitas, p-value + tamaño de efecto, α=0.05 default, Bonferroni si múltiples comparaciones.
-
-## Loop de iteración
-
-1. Primer draft de CONCLUSIONS.md.
-2. Mostrar al usuario.
-3. Iterar (Edit, no recreación) hasta que el usuario confirme: "OK, lo dejo así".
-
-## Cierre y graduación
-
-**Default: no graduar.** CONCLUSIONS.md vive en la sesión (`.workflow/sessions/<folder>/CONCLUSIONS.md`). La sesión cierra y el artefacto queda como referencia consultable; las recommendations accionables se ejecutan vía sesiones de handoff (`--from analyze:NNN`) o quedan en backlog informal.
-
-**Si el usuario pide graduarlo explícitamente**: usar `kind = conclusion` (uno de los 6 kinds del modelo nuevo):
-
-```
-agent-workflow graduate --kind conclusion --session <CODE> --slug <kebab>
-```
-
-Destino:
-- **workspace_mode=hub** → `<hub>/docs/conclusiones/NNN-<slug>.md`.
-- **workspace_mode=project** → `<project>/docs/conclusiones/NNN-<slug>.md`.
-
-La regla canónica DEC-002 manda destino sin prompt por sesión: hub mode → hub root; project mode → cwd. Sin override.
-
-Sugerir handoff post-cierre: `/agent-workflow:session --from analyze:NNN "<acción de implementación>"`.
-
-> Regla canónica de routing: `agent-workflow/skills/session/references/graduacion-routing.md`.
-
-## Composición con otras skills
-
-| Skill | Cuándo |
-|---|---|
-| `analyze-synthesize` | pre-requisito (FINDINGS.md debe existir) |
-| `analyze-investigate` | si surge nueva pregunta durante el cierre, retroceder con queries adicionales |
-| `agent-workflow:session --from analyze:NNN` | post-cierre, para implementar acciones |
-
-## Sandbox read-only
-
-Reglas universales en `../session/references/sandbox-readonly-rules.md`. En plan mode esta skill describe en el plan file:
-
-- **Path destino**: `.workflow/sessions/<folder>/CONCLUSIONS.md`.
-- **Modality declarada** en OBJECTIVE (`technical`/`incident`/`data` requerido; legacy ES `tecnica`/`incidente`/`datos` se normaliza). Si falta o es otra, plan dice "preguntar al usuario".
-- **Esqueleto de CONCLUSIONS.md**: secciones canónicas (Modality, Summary, Conclusions, Recommendations, Traceability, Open opcional). Modulación según modalidad.
-- **Investigación previa requerida**: si hay sub-preguntas pendientes en FINDINGS, listar para que el usuario decida si invoca `analyze-investigate` antes.
-
-NO ejecuta: `Write` sobre CONCLUSIONS.md, queries MCP costosas (>10k filas estimadas), `agent-workflow graduate`.
-
-## Recursos
-
-- **`references/incident-classification.md`** — severidad SEV1/2/3/4, impacto cuantitativo, timeline de comunicación, trazabilidad de acciones (aplica a modality=incident).
-- shared-contract §10 — handoff `--from analyze:NNN`.
-- shared-contract §11 — convención `## Modality`.
-- shared-contract §14 — fase execution del lifecycle universal.