finish-epic

<skill_overview> The final step in the build chain. After execute-plan has completed all tasks, this skill runs a comprehensive verification pass, confirms every success criterion has evidence of completion, closes the epic, and reports what was accomplished.

Core contract: the epic only closes when every success criterion has evidence. </skill_overview>

<rigidity_level> MEDIUM FREEDOM — The verification gate and evidence-based success criteria checks are non-negotiable. How you run verification and what you include in the summary adapts to context. </rigidity_level>

<when_to_use>

• All tasks in a br epic are closed
• User says "finish the epic", "we're done", "close it out", "wrap this up"
• execute-plan step 4 detects all success criteria appear met
• User references an epic ID and wants to close it out

Don't use for:

• Tasks still need implementation (use execute-plan)
• Epic doesn't exist yet (use brainstorm then write-plan)
• Git operations — merge, PR, push (user handles these)

</when_to_use>

<critical_rules>

1. All tasks must be closed — don't close open tasks to force epic closure
2. All automated checks must pass — tests, linting, hooks
3. All success criteria need evidence — verify and cite, don't self-certify
4. Stop on failure — report what's missing, don't close a failing epic
5. No git operations — no merge, no PR, no push; user handles integration

</critical_rules>

<the_process>

Step 1: Verify

Run cape epic verify <epic-id> to check all tasks are closed and automated checks pass:

cape epic verify <epic-id>

• verified: true — proceed to step 1b
• openTasks not empty — report which tasks are still open and stop
• checksPassed: false — report failures and stop

---

Step 2: Audit

Run three additional verification passes. All must pass before closing.

Checkpoint state

Before running sub-passes, load checkpoint state to skip work that already passed at the current commit.

1. Get the current HEAD SHA: git rev-parse HEAD
2. If the epic's design field contains a previous ## Outcome section (epic was reopened), delete the state file to force a full re-run:

   rm -f ".beads/<epic-id>/verify.json"
   

3. Read .beads/<epic-id>/verify.json if it exists. The file maps pass names to SHAs:

   { "criteria-audit": "<sha>", "code-review": "<sha>", "manual-verification": "<sha>" }
   

   If the file is missing or malformed, proceed with all passes — never error on bad state.
4. Create the directory if needed: mkdir -p ".beads/<epic-id>"

After each sub-pass succeeds, write the current HEAD SHA for that pass to the state file. Use jq or equivalent to update a single key without clobbering others.

2a: Success criteria audit

Always run this pass — never skip it, even if the SHA matches. It is cheap and catches regressions in non-code outputs like missing files.

Read the epic's success criteria. For each criterion, find concrete evidence that it's met — test output, file existence, behavior you can demonstrate.

Present a checklist:

## Success criteria audit — <epic-id>

- [x] Criterion 1 — Evidence: [what proves it]
- [x] Criterion 2 — Evidence: [what proves it]
- [ ] Criterion 3 — NOT MET: [what's missing]

If any criterion is not met, report what's missing and stop. The user can create a new task with br create and load cape:execute-plan with the Skill tool to address the gap before retrying finish-epic.

After the audit passes, record the SHA in .beads/<epic-id>/verify.json under the key criteria-audit. Read the existing file (or start from {}), set the key to the current HEAD SHA, and write it back.

2b: Code review

Checkpoint gate: If .beads/<epic-id>/verify.json records a code-review SHA that matches the current HEAD, skip this pass and report: "Code review already passed at HEAD — skipping."

Otherwise, dispatch cape:code-reviewer with the epic ID and the full branch diff. Pass only the contract (requirements, anti-patterns, success criteria) — not task implementation notes. The reviewer judges what was built against what was required, not what was intended. Address any critical findings before proceeding.

After the review passes, record the SHA (same pattern as 2a, using key code-review).

2c: Manual verification

Checkpoint gate: If .beads/<epic-id>/verify.json records a manual-verification SHA that matches the current HEAD, skip this pass and report: "Manual verification already passed at HEAD — skipping."

Otherwise, if the epic specifies manual verification steps (e.g., "run the app and confirm X works", "verify the CLI outputs Y"), execute them and record the results.

Skip this pass if the epic has no manual verification steps.

After manual verification passes (or is skipped because no steps exist), record the SHA (same pattern as 2a, using key manual-verification).

---

Step 3: Summarize

Append an Outcome section to the epic:

cat <<'EOF' | cape br design <epic-id> "Outcome"
**Completed:** YYYY-MM-DD
**Tasks:** [N tasks completed]
**Summary:** [2-3 sentences: what was built, key decisions, divergences from original design]
**Verification:** All tests passing, all success criteria met[, manual verification passed]
EOF

---

Step 4: Commit, close, and report

Load cape:commit with the Skill tool to commit any remaining changes before closing.

cape br close <epic-id>

Present a completion report:

## Epic complete — <epic-id>: <title>

**Summary:** [What was built]
**Tasks completed:** [N]
**Success criteria:** [All N met]
**Verification:** Tests passing, linter clean[, manual checks passed]

Epic closed.

Optionally load `cape:find-test-gaps` to verify test coverage before shipping.
Load `cape:pr` when the user is ready to open a pull request.

</the_process>

All tasks done, everything passes

Epic cape-abc has 4 tasks, all closed. Success criteria: "CLI validates input", "tests pass", "README updated."

1. br list --status open --parent cape-abc — no open tasks
2. Run tests — all pass. Run linter — clean.
3. Audit: CLI validates input (test at cli_test.go:42 confirms), tests pass (just ran), README updated (diff shows new section). All criteria met.
4. Append Outcome to epic, close, present report.

Tasks done but a success criterion isn't met

Epic has 3 tasks, all closed. Success criteria include "integration tests cover all endpoints." Audit reveals two endpoints have no integration tests.

Wrong: Close the epic — "the tasks are done so the epic must be done." Success criteria exist to catch exactly this gap.

Right: Report: "Success criterion not met: integration tests cover all endpoints. Missing coverage for POST /users and DELETE /users/:id. Epic stays open."

Open tasks remain

User says "let's wrap up the epic" but br-7 is still open.

Wrong: Close br-7 to unblock epic closure. The task isn't done — closing it loses the work signal.

Right: "br-7 (Add rate limiting) is still open. Finish or close it before wrapping up the epic."

<key_principles>

• The outcome is the record — future sessions read it to understand what shipped
• Completeness over speed — rushing closure creates debt in the next epic

</key_principles>