humansys/raise/rai-bugfix-close

Bugfix Close

ℹ DEFAULT VARIANT (ADR-134 v2) — si cambias lógica [R]/[G] en rai-bugfix-close, propaga aquí.

Fuente: work/epics/e14770-lean-methodology/skill-audit.md §rai-bugfix-close

Lean residue: 12 pasos [R9, G1, I2] de 26 en enterprise (54% ceremonia eliminada).

Asume siempre pipeline-orchestrated — requiere run_id en el pointer prompt.

Pipeline Context Check

Verificar que este skill fue invocado vía pipeline engine (RAISE-10715):

• Si Run ID: aparece en el contexto → continuar silenciosamente.
• Si ausente → STOP: "standalone execution detected — prior phases may have been skipped. Options: 1) continue anyway, 2) abort."

Objetivo

Push del branch de bug, crear MR, y sincronizar Jira.

Inputs: Bug ID, run_id (inyectado por el orquestador), {dev_branch}.

Pasos

0. Emitir señal de inicio

rai signal emit-work bugfix {bug_key} --event start --phase close

1. Verificar artifacts via rai pipeline status [R]

rai pipeline status "{run_id}"

Construir mapa {phase_id → status}. Para cada artifact:

• scope.md (fase: start/diagnose) → si fase skipped: ok; si fase ran + archivo ausente: STOP
• analysis.md (fase: analyse) → si fase skipped: ok
• plan.md (fase: plan) → si fase skipped: ok
• retro.md (fase: review) → si fase skipped: ok

En lean, analyse/plan/review siempre son skipped → solo scope.md es obligatorio.

2. Verificar árbol limpio [R]

git status --short

Si hay cambios uncommitted → commitarlos antes de push.

3. AR gate [R]

rai gate check gate-ar-bugfix

Escape hatch para XS/docs:

RAISE_AR_SKIP_REASON="<razón>" rai gate check gate-ar-bugfix

Si falla sin escape hatch → STOP: el AR debe existir antes del close.

3.2. Resolver dev_branch desde el worktree [R]

DEV_BRANCH="${RAISE_DEVELOPMENT_BRANCH:-$(rai worktree context --field merge_target 2>/dev/null || true)}"
[ -n "$DEV_BRANCH" ] || DEV_BRANCH="$(rai manifest env | python3 -c "import json,sys; print(json.load(sys.stdin)['branches']['development'])")"

Lee el merge_target pre-registrado en la BD al crear el worktree — fuente de verdad única, sin re-derivación del manifest. Evita silenciosamente apuntar a manifest.branches.development (línea activa) en worktrees con target bugfix-only (RAISE-17889). Usar $DEV_BRANCH como valor de {dev_branch} en los pasos siguientes.

3.5. Detectar Path A (bugfix epic-scoped, RAISE-15901) [R]

CURRENT_BRANCH="$(git branch --show-current)"

Si $CURRENT_BRANCH empieza con epic/ → este bugfix corrió Path A en rai-bugfix-start: no existe branch bug/{issue_key}/{slug} dedicada, los commits del fix viven directamente en la epic branch. Saltar los pasos 4-5 (push + MR) y el paso 9 (delete de branch) — no hay branch de bug que pushear, MRear ni borrar. Esos commits se integran cuando la epic misma cierra (/rai-epic-close), no por bugfix individual. Emitir advertencia visible: ⚠ Path A detectado ($CURRENT_BRANCH) — bugfix close se detiene antes de push/MR/branch-delete; estos commits se integran vía el MR de la epic. Continuar con los pasos 6 (fixVersion), 8 (verificación Jira) y 10-11 (bind + señal de cierre).

Si $CURRENT_BRANCH NO empieza con epic/ → Path B, comportamiento sin cambios, continuar normalmente.

4-5. Push + Crear MR [G] (Path B únicamente — ver paso 3.5)

Write the title and human-readable description to files without shell interpolation. Invoke /rai-mr-create with these required inputs:

• source_branch: current bug/{issue_key}/{slug} branch
• target_branch: {dev_branch}
• work_id: {bug_key}
• quality_review_file: work/bugs/{bug_key}/qr.md
• title_file: file containing the exact MR/PR title
• description_file: file containing the exact human-readable body

GitLab uses THIN admission. GitHub retains the local full-gate path until equivalent remote enforcement exists. Neither provider permits manual push or MR/PR creation outside /rai-mr-create.

If /rai-mr-create fails (sync conflict, gate failure, push rejection), STOP. Do not assign fixVersion, advance the pipeline, or clean up. There is no remote branch/MR result to finalize: returning a successful close would allow the pipeline to transition Jira despite an unvalidated commit.

6. fixVersion — delegada al engine [R]

No asignar fixVersion manualmente — el engine lo hace automáticamente en el siguiente pipeline_advance: tras la transición a done y antes de after:bug:close, finalize_post_transition escribe el mismo fixVersion que verifica gate-close-jira-sync (assign_close_fix_version, resuelto desde la release line destino del branch — RAISE-18975). Asignar desde el branch name produce un conflicto con gate-close-jira-sync (RAISE-16614).

8. Verificación post-transición delegada (blocking) [R]

No ejecutar gate-close-jira-sync directamente desde el skill: Jira todavía no está en Done. Al devolver control, el siguiente pipeline_advance aplica primero target_status: done y después ejecuta el gate en after:bug:close.

Si el avance devuelve gate_failed para after:bug:close → FAIL el close. No log-and-continue ni escape implícito. Corregir Jira y re-run.

9. Worktree-aware cleanup [R] (Path B únicamente — ver paso 3.5)

if [ "$(git rev-parse --git-common-dir)" != "$(git rev-parse --git-dir)" ]; then
  echo "Worktree — cleanup diferido a /rai-worktree-close"
else
  git checkout {dev_branch}
  git branch -D bug/{issue_key}/{slug}
fi

10. Bind result [I]

rai session bind RAISE_SESSION_JIRA_KEY "{bug_key}" 2>/dev/null || true

11. Emitir outcome + señal de cierre

Emitir bloque outcome antes de devolver control:

outcome:
  verdict: PASS  # PASS | FAIL | BLOCKED
  route: standard  # standard | escape | blocked
  blocked_reason: null  # string if BLOCKED, null otherwise

rai signal emit-work bugfix {bug_key} --event complete --phase close

Fin. Devolver: MR URL, gate-close-jira-sync status, cleanup realizado sí/no.

Backlog tracker

Engine behavior (RAISE-16987): The engine checks ExecutionContext to determine mode:

• mode: pipeline — engine active; apply_phase_transition moves the tracker. No skill call required.
• mode: standalone — no active run; tracker is not moved automatically.

If standalone (mode == standalone via ExecutionContext):

rai backlog transition {key} --point after:bugfix:close