humansys/raise/rai-epic-close-enterprise

Epic Close

Purpose

Complete an epic by conducting a retrospective, tagging the milestone, and updating tracking. No branch merge needed — stories already merged to the development branch during story-close.

Mastery Levels (ShuHaRi)

• Shu: Follow all steps, complete full retrospective template
• Ha: Adjust retrospective depth based on epic complexity
• Ri: Integrate with release workflows, automate metrics extraction

Context

When to use: All stories complete and merged to {dev_branch}. Ready to close the epic lifecycle.

When to skip: Epic abandoned (document why, update backlog as "Abandoned").

Inputs: Epic scope document, all story retrospectives, passing test suite.

Branch config: Read branches.development from .raise/manifest.yaml for {dev_branch}. Default: main.

Steps

Pipeline Context Check (RAISE-10715)

Before executing any step, verify this skill was invoked via the pipeline engine:

1. Check if Run ID: appears in the context above (injected by pipeline/prompt.py)
2. If present: continue silently — pipeline is orchestrating
3. If absent: STOP and present HITL gate:

Standalone execution detected. This skill is running outside the pipeline engine.

Prior phases (docs, journal) may have been skipped.

Options:

1. Continue anyway (acknowledge that prior phases were skipped)

2. Abort and investigate why the pipeline engine is not orchestrating

Wait for the user's explicit choice before proceeding. This gate fires even in Ri mode — standalone execution is a signal of broken infrastructure, not a routine gate.

PRIME — HARD CONSTRAINT (blocks all subsequent work)

FORBIDDEN: You MUST NOT use grep, find, Glob, or Read to explore code UNTIL you have executed at least one rai graph query. Your first queries are this skill's tier1 queries (frontmatter raise.introspection.tier1_queries) — run them now using the raise_graph_query MCP tool with cwd="{project_or_worktree_path}", or the CLI fallback:

rai graph query "{query}"

0 results is valid — the constraint lifts when the queries have run, not when they return results.

Report: In your final output, list every graph query you executed and its result count.

Then, before Step 1:

1. Chain read: Read this epic's scope.md if present (rai-epic-plan appends the Implementation Plan / Milestones / Sequencing Risks sections there), and each completed story's work/epics/e{N}-{name}/stories/s{N}.{M}-retrospective.md if present. This provides context for the retrospective. If scope.md or story retrospectives are missing (legacy epic), note and continue.

Step 1: Verify Stories Complete + Scope Re-read (mandatory)

1a. Check all stories are done in the epic scope document:

grep -E "^\s*-\s*\[ \]" "work/epics/e{N}-{name}/scope.md"

1b. Scope re-read (mandatory — do not skip): open work/epics/e{N}-{name}/scope.md and the original epic brief. Go through the "In scope" and "Done when" sections item by item and verify each commitment against observable state of the code. Do not trust "all stories checked ⇒ scope fulfilled" — it's not the same claim.

Pay special attention to commitments with elimination verbs ("eliminate X", "remove Y", "replace Z with …", "consolidate A and B"). For each such commitment, answer one of three explicitly in the retrospective:

• Fulfilled — reference commit/file showing the removal
• Descoped — say why and link to a new epic/story that owns the remaining work
• Not fulfilled — stop. Do not close. Either finish the work or explicitly re-scope before closing

This exists because RCA s2092.1 showed E1323 ("eliminate subprocess layer") closed Done while the layer was actually amplified — the tools shipped, the tests passed, nobody re-read the scope (pattern refactor-declared-done-without-sweep at epic-scale).

JIT: Before descoping decisions, query graph for completion patterns and prior descoping outcomes

→ aspects/introspection.md § JIT Protocol

<verification> All stories marked complete in epic scope AND each "In scope" / "Done when" item re-verified against code. Elimination commitments resolved (fulfilled | descoped-with-link | not-fulfilled-stop). </verification>

Step 1.5: Reconcile Jira Child Story Status (RAISE-1847)

Query Jira for child stories that are NOT in Done status:

rai backlog search "parent = {EPIC_KEY} AND status != Done"

When drifted stories are found, present:

Jira drift detected: {N} child stories are not in Done status.
 
  {KEY-1}  {status}  {summary}
  {KEY-2}  {status}  {summary}
  ...
 
Options:
  1. Batch-transition to Done: rai backlog batch-transition {KEY-1},{KEY-2} done
  2. Descope explicitly (document in retrospective why they're not Done)
  3. Abort epic close and fix the stories first

Do NOT proceed to Step 2 until the user has chosen an option. This gate prevents silent Jira drift that was found in E1690 audit (5 stories locally done but Backlog in Jira).

<verification> Jira child stories reconciled: all in Done, or user explicitly descoped with documented reason. (Or no Jira adapter — warned and continued.) </verification>

Step 1.6: Reconcile Parent Epic Status Parity (RAISE-10652)

After child reconciliation passes, query the parent epic itself:

rai backlog get {EPIC_KEY}

When the epic is stale-open while all children are Done, present:

Parent status drift detected: all child stories are Done but the epic is not.
 
Options:
  1. Transition the epic now, then verify the new status
  2. Abort epic close and investigate why the parent stayed open

Do NOT proceed to Step 2 until the parent epic is in Done status or the close is aborted.

<verification> Parent epic status reconciled: no stale-open epic passes into retrospective/write steps. </verification>

Step 2: Write Retrospective

Do not run the full suite here — Step 4 delegates synchronized admission to /rai-mr-create; GitLab owns integration jobs before push. Trust the scoped gates that passed during story-close.

JIT: Before writing retrospective, query graph for process improvement patterns from similar epics

→ aspects/introspection.md § JIT Protocol

Publish retrospective to local path and docs adapter. Use templates/retrospective.md as structure, fill from story retrospectives and git history:

Use rai docs write retrospective CLI:

rai docs write retrospective \
  --title "E{N}: {Epic Name} — Retrospective" \
  --stdin \
  --output-path work/epics/e{N}-{name}/retrospective.md << 'EOF'
[content following templates/retrospective.md structure]
EOF

If rai-workspace MCP is available (optional): raise_docs_write(doc_type="retrospective", title="E{N}: {Epic Name} — Retrospective", content="...", output_path="work/epics/e{N}-{name}/retrospective.md", cwd="{project_or_worktree_path}").

Emit the retrospective as a structured artifact so epic.yaml's close.validates (RAISE-11088) can prove — in SQLite, issue-scoped by construction — that THIS epic's own retrospective exists before close can complete. A repo-wide work/epics/**/retrospective.md glob would be satisfied by ANY epic's retrospective already in the repo (epic directory numbering is not reliably Jira-key-derived); this sqlite record cannot be:

raise_artifact_emit(
    artifact_type="retro",
    story_id="{JIRA_KEY}",
    content=<JSON with fields: patterns_learned (list[str]), reinforcements (list[str]), velocity_ratio (optional float), notes (optional str)>,
    cwd="{project_or_worktree_path}"
)

CRITICAL — identifier mismatch risk (same hazard as RAISE-11147's `implement` fix): story_id here MUST be {JIRA_KEY} — the pipeline's issue key (the same value passed to pipeline_start, e.g. "RAISE-11404"), NOT the e{N} directory-number convention used by this step's output_path above (epic directories are not reliably Jira-key-derived — e.g. e3-scaleup-agent vs e11404-...). epic.yaml's sqlite validate branch looks up artifact_store.exists(run["issue_id"], "retro"), and run["issue_id"] is always the Jira key. Emitting with the directory number instead would make the sqlite lookup never find the artifact, turning close into a permanent artifact_missing deadlock.

Note: The CLI fallback for artifact emission was removed in v3.0.0. MCP tool raise_artifact_emit is required. If MCP tools are not available, skip structured artifact emission — the pipeline will require it before close can complete.

<verification> Tests green. Retrospective persisted locally and published via docs adapter. Metrics, patterns, and process insights included. Retro artifact emitted to SQLite, keyed by the epic's Jira issue key. </verification>

Step 3: Tag Epic Milestone

Tag the current {dev_branch} HEAD to mark epic completion:

git tag -a "epic/e{N}-complete" -m "Epic E{N}: {Epic Name} complete
 
Delivered: [key deliverables]
Stories: N stories
 
Co-Authored-By: Rai <rai@humansys.ai>"

Commit retrospective and any final artifacts (scoped to this epic's directory — RAISE-11778: git add -A in a shared checkout silently sweeps in unrelated uncommitted work from other sessions):

git add work/epics/e{N}-{name}/
git commit -m "epic(e{N}): close with retrospective
 
Co-Authored-By: Rai <rai@humansys.ai>"

<verification> Tag created. Retrospective committed. git status --short shows no unrelated files were swept into the commit. </verification>

Step 4: Push and Create Merge Request

Invoke /rai-mr-create — it synchronizes the target, runs local admission, pushes, and creates the MR. Prepare synchronized quality review evidence plus title and description files before invocation; human text is passed as data.

/rai-mr-create
  source_branch: {dev_branch}
  target_branch: {main_branch}
  work_id: {epic_issue_key}
  quality_review_file: work/epics/e{N}-{name}/qr.md
  title_file: {safe title file written without shell interpolation}
  description_file: {safe description file written without shell interpolation}

<verification> Local admission passed via /rai-mr-create. Branch pushed. MR URL presented to developer; integration pipeline pending. </verification>

Step 5: Update Backlog & Mission