finishing-a-development-branch
Use after execution is complete or intentionally stopped — decide whether to merge back, publish a PR branch, keep the execution checkout, or discard it, and record that disposition in HOTL state.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- finishing-a-development-branch
- description
- Use after execution is complete or intentionally stopped — decide whether to merge back, publish a PR branch, keep the execution checkout, or discard it, and record that disposition in HOTL state.
03 SKILL.md 正文
Finishing A Development Branch
Use this after loop-execution, executing-plans, or subagent-execution when the run already has a run_id and you need to decide what happens to the execution branch/worktree next.
Core Idea
HOTL distinguishes between:
- Authoring checkout — where the workflow was written (
source_branch,source_head) - Execution checkout — where the workflow ran (
branch,execution_root,worktree_path)
Finishing is the stage that closes that loop intentionally. Do not silently merge, delete, or abandon the execution worktree.
Step 1: Read Execution Provenance
Run:
hotl-rt summary <run-id> --json
Surface these fields before presenting options:
statussource_branchbranchexecution_rootworktree_pathfinish.disposition(if already recorded)- controller owner/status and receipt reasons
If finish.disposition is already set, stop and tell the user the run is already finished.
A successful execution must be ready_to_finish before merge or publish. ready_to_finish means execution evidence is complete but the run is not yet completed. Keep the existing controller lease active and retain HOTL_OWNER_TOKEN; if a different controller is finishing, use explicit owner handoff/takeover rules from resuming first. Run owner heartbeat before a long finish operation.
Step 2: Present The 4 Finish Options
Use these options:
- Merge back locally
- Default target:
source_branchwhen present and different from the execution branch - Fallback target:
mainormaster
- Default target:
- Publish branch / create PR
- Push the execution branch to a remote
- If
ghis available and the user wants a PR, create it against the chosen target branch
- Keep as-is
- Preserve the execution branch/worktree for later review or follow-up changes
- Discard
- Remove the execution branch/worktree after explicit confirmation
Explain the target branch explicitly when merge or PR target is inferred from source_branch.
Step 3: Authorize External Effects
For publish/PR, record one bounded external_write with the exact target publish <branch> to <remote> (append and create PR against <target-branch> when --create-pr is used), pass --idempotency-key <stable-key>, obtain human action decide ... approved --mode human, and pass the returned action id and key to the helper. If a merge is classified as production_change, use the exact target merge <branch> into <target-branch>. The helper verifies kind, target, key, approval, and not-started status; it then performs action begin immediately before the effect and action complete with observed evidence before recording finish.
Approval is not effect evidence. If the helper stops after a push, PR attempt, or merge may have started, leave the action unresolved, inspect the target, and use action reconcile. Never rerun the helper while the effect is in_progress or uncertain.
Step 4: Execute Via The Helper
Use the repo-owned helper:
scripts/hotl-finish-execution.sh --run-id <run-id> --mode <keep|merge|publish|discard> ...
Mappings:
- Keep →
--mode keep - Merge locally →
--mode merge [--target-branch <branch>] - Publish / PR →
--mode publish [--remote origin] [--target-branch <branch>] [--create-pr] - Discard →
--mode discard --confirm discard
For an approved merge/publish effect, also pass --effect-action-id <id> --idempotency-key <key>. The helper records intent with action begin, executes the bounded effect, persists action complete evidence, then records the finish disposition with hotl-rt finish .... It enforces safety checks around branch switching, merging, cleanup, and destructive discard. HOTL_OWNER_TOKEN must remain in the helper environment.
Step 5: Report The Outcome
After the helper succeeds, show:
- Finish disposition
- Target branch / PR URL if applicable
- Whether the execution worktree was kept or removed
- Where the durable report lives
Then run owner release and derive a fresh receipt. Claim completion only when the run is completed and sufficiency.sufficient is true. A failed helper must leave finish unset; use action reconcile before another attempt when an external effect may have occurred.
Important behavior:
- Merge and discard preserve
.hotl/state/<run-id>.jsonand.hotl/reports/<run-id>.mdback into the repo checkout before removing an isolated execution worktree - Publish keeps the execution worktree by default so review follow-ups can continue on the same branch
- Shared-checkout same-branch runs are intentionally conservative; discard and merge may require manual handling if automation would be ambiguous or destructive
Guardrails
- Do not auto-merge after execution just because tests passed
- Do not auto-delete work without explicit user confirmation
- Do not create a PR unless the user chose the publish/PR path
- If merge conflicts occur, stop and leave the execution branch/worktree intact
- If a chosen PR operation cannot run because
ghis unavailable or fails after push, do not silently downgrade the approved target. Leave finish unset, reconcile the observed push, and ask whether the user wants a new bounded push-only action.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.