close-out

Files (1)

• SKILL.md

SKILL.md (first lines)

# /close-out — finish a piece of work properly

The recurring frustration: substantive work gets done but not *closed out* — no
PR, no papercuts filed, no full report in the brain of what actually happened,
no follow-up card. Run these steps automatically; don't ask permission for the
mechanical parts. Only stop for a genuine fork (branch base? dev vs prod? a
design choice).

Run the steps that apply to what you just did. Skip ones that don't. Do **not**
skip papercut filing, the full brain report, or the superseded-record pass on a
substantive session — those LastDB writes are why this loop exists. See
`preference-always-file-papercuts-in-brain` and
`preference-always-save-to-brain-when-done`.

This loop assumes two LastDB surfaces:
- **Brain** (`brain`) — long-lived notes: the *why*, settled decisions,
  the full closeout report of what was done, and papercuts.
- **Kanban** (`kanban`) — what's in flight: cards moving through columns.

(Adjust the CLI names if your brain/board tools differ.)

## 1. PR it — from a worktree, never the shared main checkout

If your changes are sitting in a shared main checkout, move them to a worktree
first — `git add -A` in a shared checkout can sweep sibling work into your
commit. Always work in an isolated worktree under
`${WORKTREES_DIR:-$HOME/.fkanban/worktrees}`, never inside the repo as
`<repo>/.worktrees`.

After moving, leave the shared checkout clean. Restore only the exact files you
edited, or run `last-stack-repark-shared-checkouts` so any multi-file leftover
state is parked on an attributable salvage branch instead of being abandoned in
the ambient checkout.

Before opening the review artifact, route the repo:

```bash
last_stack="${LAST_STACK_ROOT:-$HOME/.last-stack}"
route_json="$("$last_stack/bin/last-stack-pr-venue" --json <owner>/<repo> "$WT")"
venue="$(printf '%s\n' "$route_json" | jq -r .venue)"
```

Use GitHub `gh` (`gh pr create`, `gh pr merge <n> -R <owner>/<repo> --auto
--squash`, required check `ci-required`) when `venue=github`. This is the
default for every EdgeVector repo except `EdgeVector/lastgit`. Use the local
Forgejo SOP/API helper only when `venue=forgejo` (the `lastgit` repo). LastGit
is retired (brain `decision-2026-09-29-retire-lastgit-all-repos-to-github`): if
`venue=lastgit`, do not push to a `lastdb:///` remote; file a brain papercut.

Close-out/backstop hooks that check for local commits ahead of the canonical
remote should resolve the comparison ref through the same helper:

```bash
compare_ref="$("$last_stack/bin/last-stack-pr-venue" --compare-ref <owner>/<repo> "$WT")"
git -C "$WT" rev-list --count "$compare_ref"..HEAD
```

The helper compares against the upstream/origin ref of the resolved venue.

```bash
REPO="$HOME/code/<repo>"
WT="${WORKTREES_DIR:-$HOME/.fkanban/worktrees}/<short-name>"
BR="<branch>"
# preserve your edit, restore the shared checkout to clean, branch off origin/main
cp "$REPO/<changed-file>" /tmp/closeout.$$ 2>/dev/null || true
git -C "$REPO" fetch origin --quiet
git -C "$REPO" checkout -- <changed-file>        # only if this is your own shared-checkout edit
git -C "$REPO" worktree add "$WT" -b "$BR" origin/main
# re-apply your change into $WT, then:
git -C "$WT" add -A
git -C "$WT" commit -m "<type(scope): summary>

<body>"
git -C "$WT" push -u origin "$BR"
gh pr create --repo <owner>/<repo> --base main --head "$BR" --title "..." --body "..."
```

Proof lives on the **kanban card** (`VERIFY` / `END STATE`) and in the closeout
report below, not in a PR-body `## Proof` block. Those blocks and the fold
`proof-block` CI check were removed 2026-07-03 (Tom: merge-stall churn). Do not
write them, and do not block on their absence. Produce the proof at the tier
§3 demands.

## 2. Auto-merge and babysit to MERGED

Match your repo's merge policy (see the **wait-merge** / **kanban-agent**
skills). For a merge-queue repo use bare `--auto` (no strategy flag); for plain
auto-merge add `--squash` (or your preferred method):

```bash
gh pr merge <N> --repo <owner>/<repo> --auto
```

Then drive it to merged — don't hand off at auto-merge. `BLOCKED` / red checks /
queue churn = re-poll, NOT a failure. Use the `/wait-merge` skill, or
`gh pr checks <N> --watch` (sleepless — never chain `sleep`). Verify state via:

```bash
gh pr view <N> --repo <owner>/<repo> --json state,mergeStateStatus,autoMergeRequest
```

(Auto-merge can show `autoMergeRequest:null` even when enabled — confirm via the
`enabledAt` GraphQL field.)

On GitHub, `gh pr merge <n> -R <owner>/<repo> --auto --squash` is the arm step.
If GraphQL returns a 502, use
`gh api -X PUT repos/<owner>/<repo>/pulls/<n>/merge -f merge_method=squash`.
A red or missing `ci-required` check blocks; do not use `--admin` unless a
human explicitly clears that bypass.

## 3. Produce the relevant non-test proof

No-tests policy: `instructions/no-tests.md`; Situation
`no-tests-all-repos-20261009`. Do not add, restore, run, or require tests,
fixture suites, test mutation probes, or test coverage.

Match the proof to the change:

- **No behavior change** (refactor/rename/docs): review the source and state why

From EdgeVector/last-stack, MIT.

More from EdgeVector/last-stack