humansys/raise/rai-epic-start

Epic Start

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

Fuente: work/epics/e14770-lean-methodology/skill-audit.md §rai-epic-start

Lean residue: 3 pasos [R2, G1] de 9 en enterprise (67% ceremonia eliminada).

Solo pasos [R]+[G] — sin ShuHaRi, sin directory collision explanation, sin quality checklist.

Objetivo

Crear el epic_dir con brief.md + scope.md y registrar en backlog. Inputs: Epic ID, slug, Jira key opcional. Expected state: árbol limpio, en dev branch.

Pasos

0. Emitir señal de inicio

rai signal emit-work epic {jira_key} --event start --phase start

1. Verificar working tree [R]

git status --short
git branch --show-current

Si hay cambios uncommitted → STOP: "blocked: working tree not clean". NUNCA git reset --hard, git clean -fd, ni git stash sin confirmación explícita del developer.

2. Crear brief.md + scope.md [G]

Read governance/guardrails.md before drafting (graceful degradation: if absent, continue without blocking). Factor guardrails into rabbit holes and scope decisions.

Crear work/epics/{epic_dir}/ y escribir dos artefactos:

raise_docs_write(
    doc_type="epic-brief",
    title="{epic_id}: {epic-name} brief",
    content="[hipótesis, success metrics, appetite, rabbit holes]",
    output_path="work/epics/{epic_dir}/brief.md",
    cwd="{cwd}"
)
raise_docs_write(
    doc_type="epic-scope",
    title="{epic_id}: {epic-name} scope",
    content="[objetivo, in/out scope, historias planeadas, done criteria, jira_key si aplica]",
    output_path="work/epics/{epic_dir}/scope.md",
    cwd="{cwd}"
)

Si cualquier result.status != "ok" → STOP: "Epic artifact write failed: {error}". No continuar sin artefacto.

Commit (solo el epic_dir — nunca git add -A):

git add work/epics/{epic_dir}/
git commit -m "epic({epic_id}): initialize {epic-slug}
 
Objetivo: {1-line}
 
Co-Authored-By: Rai <rai@humansys.ai>"

3. Capturar portfolio metadata [G]

Si el argumento --skip-portfolio está presente en los argumentos del skill → saltar este paso.

Preguntar al developer (respuesta en texto libre):

• `components_touched`: lista de IDs de componentes del manifest (ej: portfolio,storage,gates)
• `change_mode`: uno de additive | evolutionary | breaking

Si jira_key no está vacío y el developer responde:

rai portfolio epic-profile create {jira_key} \
  --components {components_touched_comma_separated} \
  --change-mode {change_mode} \
  --project .

Si el developer pasa --skip-portfolio o prefiere no responder → continuar sin persistir (best-effort; no bloquear epic start).

4. Actualizar backlog [I]

Backlog transition is engine-owned (RAISE-15034) — no skill-initiated call. Engine transitions epic to Implement via apply_phase_transition at phase completion. Standalone-mode notice (RAISE-16988): When no pipeline run is active, the tracker is not moved — apply_phase_transition requires the engine. In standalone execution, report explicitly:

"⚠️ Tracker not updated: this skill ran standalone (no active pipeline run). Backlog status unchanged. Run the pipeline or update the tracker manually."

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

• mode: pipeline — apply_phase_transition moves the tracker. No skill call required or allowed.
• mode: standalone — tracker is not moved. Report explicitly:

> "⚠️ Tracker not updated: this skill ran standalone (no active pipeline run). Backlog status unchanged. Run the pipeline or update the tracker manually."

To force a transition standalone: rai backlog transition {key} --point {workflow_point}

Persistir jira_key en scope.md si no está ya.

5. 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 epic {jira_key} --event complete --phase start

STOP. Devolver: epic_dir creado, brief.md path, scope.md path.