finalize-spec
Close a spec whose last task has merged — verify every task and main's CI from GitHub, review the whole spec's diff, write the retrospective and proposals, land one finalize pull request that moves the spec to done with its docs and changelog, watch main's CI for it, sync the backlog, and optionally prepare a release
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- finalize-spec
- description
- Close a spec whose last task has merged — verify every task and main's CI from GitHub, review the whole spec's diff, write the retrospective and proposals, land one finalize pull request that moves the spec to done with its docs and changelog, watch main's CI for it, sync the backlog, and optionally prepare a release
- argument-hint
- <spec-name> [--alias <word>] [--release] [--publish]
03 SKILL.md 正文
Finalize Spec
In MYTHHELM every task already lands as its own reviewed pull request, so a spec in specs/unfinalized/ is code on main. Finalizing closes it: a review of the whole spec rather than one task at a time, a retrospective that feeds the harness's learning loop, one pull request that files the record (specs/done/, docs, changelog, proposals), and a check that main stays green afterwards.
Every verdict here comes from scripts/harness/finalize.py, which reads git and GitHub; knowledge/finalize.md explains what each step protects against. A sub-agent's prose is never evidence.
Input
$ARGUMENTS: <spec-name> [--alias <word>] [--release] [--publish].
--alias: the short name in the spec's branch names and pull-request titles; reuse the one/run-specused (default: the spec name).--release: also run/finalize-spec-tagto prepare release notes.--publishpasses on to it: the maintainer's request to publish the release (/finalize-spec-tag§Publish).
Invocation contexts
- Slash command: runs Steps 0–8. The merges of the finalize pull request and of any fix pull request are this skill's own, and invoking it is the approval for them.
- Model-invoked: the same.
- Non-interactive: the same, with no questions; every escalation stops the run and returns the stop report. A finalizer that is itself a subagent receives no background notifications: it waits on CI and reviews in the foreground (
finalize.py ci --waitandgh pr checks --watchwith a raised Bash timeout), never by ending its turn.
Sub-skills
| Step | Skill | Writes |
|---|---|---|
| 1 | /finalize-spec-verify |
nothing |
| 2 | /finalize-spec-review |
## Review Summary in the spec's retrospective.md |
| 3 | /finalize-spec-retrospective |
the rest of retrospective.md; .claude/proposals/pending.md |
| 4 | /finalize-spec-publish (runs /finalize-spec-epic-rollup and /update-docs) |
the finalize pull request |
| 5 | /finalize-spec-verify-ci |
fix pull requests, when main turns red |
| 6 | /finalize-spec-pm |
approval requests for the backlog |
| 7 | /finalize-spec-tag (with --release) |
nothing public unless --publish |
Step 0 — Worktree
Finalizing never happens in the shared checkout: other sessions use its index and working tree, and a commit there can sweep their work into yours. Every later step reads and writes in the finalize worktree (<wt>).
First decide from GitHub, not from memory, whether this is a resumed run: git fetch origin, then gh pr list --state all --head docs/<alias>-finalize --json number,state,mergeCommit.
- Merged finalize pull request (the spec is in
specs/done/on origin/main): the record has landed. When the run-events log already holds this spec'slifecyclerowunfinalized -> donewithresult: ok(grepit in the main checkout's.claude/data/run-events.jsonl), the finalize is complete: report that and stop. Otherwise go straight to Step 5 with its merge commit, then Steps 6–8;finalize-spec-verifywould rightly refuse a spec already indone/. The log is local, so another machine re-runs Steps 5–6, which is safe: a green verdict re-verified is still green, andpm-sync-coreskips a card alreadyshipped. - Open finalize pull request: use its worktree, or recreate one from the branch (
git worktree add ../<repo>-<alias>-finalize docs/<alias>-finalize), and go straight to/finalize-spec-publishstep 7. - None, or only closed unmerged ones: a fresh run from Step 1, in a worktree that holds only this run's work:
- No branch
docs/<alias>-finalizeand no worktree at the path:git worktree add -b docs/<alias>-finalize ../<repo>-<alias>-finalize origin/main. - A stopped earlier run left them: reuse that worktree. Bring it current with
git -C <wt> merge origin/main; the steps rewrite everything they own (the Review Summary is replaced, the retrospective's sections rewritten). A branch without a worktree is recreated withgit worktree add ../<repo>-<alias>-finalize docs/<alias>-finalize. Never force-remove either one: a worktree holding changes this skill does not write is an escalation.
- No branch
Record the start: python3 scripts/harness/runspec.py event --spec <spec> --kind lifecycle --detail "finalize start".
Steps
- Verify —
/finalize-spec-verify <spec> --alias <alias>. Continue only onverdict=ready. - Review —
/finalize-spec-review <spec>. When it reports open critical findings, stop: each is fixed in its own pull request (below), thengit -C <wt> merge origin/mainand re-run from Step 1, passing the fix pull requests to/finalize-spec-reviewas--extra-pr. - Retrospective —
/finalize-spec-retrospective <spec>. - Publish —
/finalize-spec-publish <spec> --alias <alias>: move the spec todone/, roll up its epic, update the docs and the changelog, open the finalize pull request, answer its review, merge it onverdict=ready, confirm it on origin/main. - Verify CI —
/finalize-spec-verify-ci <spec> --sha <finalize merge commit> --alias <alias>. - Backlog —
/finalize-spec-pm <spec>. It runs after CI is green, because a card isshippedonly when the code is merged and main is green. - Release — with
--releaseonly:/finalize-spec-tag <spec> [--publish]. Without it, reportRelease: not requested. - Clean up and report. When the finalize worktree still exists:
git -C <wt> status --porcelainprints nothing, thengit worktree remove <wt>; when the local branch still exists,git branch -d docs/<alias>-finalize. After a squash merge-drefuses, because the branch's own commits never reachedmain: leave the branch and name it in the report for the maintainer, never force-delete it. Recordrunspec.py event --spec <spec> --kind lifecycle --detail "unfinalized -> done" --result ok, then print the report.
Fix pull requests
A confirmed critical review finding (Step 2) or a real CI failure (Step 5) is fixed like a task: one pull request per fix, by the agent that owns the files (knowledge/domains.md), dispatched with subagent_type and isolation: "worktree", following /implement Steps 3–9 but with no task entry. Title it fix: <what> (<alias> fix) so finalize.py verify sees it while it is open. Merge it on python3 scripts/harness/finalize.py publish-check --spec <spec> --pr <n> --fix printing verdict=ready, then confirm its merge commit on origin/main. Print dispatched=N returned=M failed=K for every batch of fix dispatches.
Escalations (the run stops)
finalize-spec-verifyis not ready for a reason no fix pull request can remove: a task incomplete, the spec in the wrong state, the required checks changed, the gate weakened.- A critical finding the fixer cannot resolve, or one that means the spec itself is wrong.
- Three review rounds leave the finalize pull request not ready.
/finalize-spec-verify-ciescalates: aninfraorunknownfailure, two fix cycles without green, or a wait budget spent.- A guard blocked this session, or a leak reached a title, body or pushed commit.
The stop report names the step, the evidence (verbatim, at most ten lines), what is in flight, and the decision needed. The spec stays where it is on origin/main; re-running /finalize-spec <spec> resumes.
Output
## Finalized: <spec>
Verify: verdict=ready (<tasks> tasks, last merge <sha7>, main green)
Review: <range>; findings critical N / important N / suggestion N; open critical 0; vendor <result>
Retro: specs/done/<spec>/retrospective.md; proposals <ids or none>
Publish: PR #<n> merged as <sha7>; epic <rolled up | no-op>; docs <files or none>; changelog <entries or none (reason)>
Verify CI: <green | green after fix PRs #.. | escalated: reason>
Backlog: <pm-sync lines | PM sync pending (reason)>
Release: <not requested | notes prepared at <path> | published vX.Y.Z>
dispatched=<N> returned=<M> failed=<K>
04 同仓库更多 Skills
mythhelm-deliver-backlog
Coordinate a MYTHHELM backlog run with the shared stage checks and maintainer checkpoints.
mythhelm-bootstrap
Orient a Grok Build session in the MYTHHELM repository before task or spec work.
vendor-consult
Run one advisory stage consult (premise-ground, spec-validate, task-review, change-review, stuck-oracle, dossier) with an optional external vendor, then adjudicate the answer at its anchors
update-docs
Bring README, docs/, knowledge/, WORKFLOW.md and CLAUDE.md in line with what a shipped spec or a merged change actually did — find every statement the change made stale, fix it where readers look, and add only the new facts they need
triage
Score an idea or a GitHub issue against the master spec's stages, gates and commitments, check it for duplicates, and recommend whether it becomes a backlog card; read-only
test-driven-development
Red-green-refactor for Go — use when implementing any feature, bug fix or behaviour change, before writing implementation code