SatcherInstitute/health-equity-tracker / .claude/skills/merge
merge
VerifiedForce-merge an open PR to main (bypassing review requirements), delete the local branch, pull the updated main, and push it to the personal fork remote. Use when the user wants to close out a PR without waiting for review, or run /merge.
/merge
Force-merge a PR, sync local main, and push to the personal fork.
The user may pass a PR number as an argument (e.g. /merge 4764). If none is given, detect the open PR from the current branch.
Step 1 — Identify the PR and derive fork remote
gh pr view [<number>] --json number,title,body,headRefName,baseRefName,state
Confirm:
stateisOPENbaseRefNameismain
If the PR is already merged or closed: print a message and stop.
Output one sentence describing what this PR does — plainest possible language, no jargon. Read the title and body to derive it. Say it as your first line of output so the user immediately knows you're merging the right thing.
Derive the personal fork remote:
GH_USER=$(gh api user -q .login)
FORK_REMOTE=$(git remote -v | grep -i "github.com[/:]${GH_USER}/" | head -1 | awk '{print $1}')
If FORK_REMOTE is empty, print a warning and ask the user to identify their fork remote with git remote -v. In a cloud session (CLAUDE_CODE_REMOTE=true) there is no fork to sync; skip Step 5 and say so in the final summary.
When the user explicitly passed a PR number with the /merge command, proceed without asking for confirmation. Only ask if the PR number was auto-detected from the current branch (i.e. no argument was given).
Step 1b — Final review check for delayed comments
Before merging, do one last check for new reviews or comments that may have arrived since /pr completed (CodeRabbit and other bots sometimes submit delayed reviews):
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
echo "=== reviews ===" && \
gh api repos/$REPO/pulls/<number>/reviews \
--jq '[.[] | {user: .user.login, state: .state, body: .body}]' && \
echo "=== inline comments ===" && \
gh api repos/$REPO/pulls/<number>/comments \
--jq '[.[] | {user: .user.login, path: .path, line: .line, body: .body}]'
If any new unresolved review threads or comments exist: stop and ask the user whether to address them before merging.
Step 1c — Check prod and dev CI health
Check the latest completed run of every non-PR workflow (main pushes and the dev deploy, release/prod deploys, scheduled crons and E2E, DAG runs):
gh run list --limit 300 --json workflowName,event,headBranch,conclusion,status,createdAt,url \
--jq '[.[] | select(.event != "pull_request" and .status == "completed")]
| group_by(.workflowName) | map(sort_by(.createdAt) | last)
| .[] | select(.conclusion != "success" and .conclusion != "skipped")
| {workflowName, event, headBranch, conclusion, createdAt, url}'
If anything comes back, alert the user up front with a short list (workflow name, branch, conclusion, date, link). Runs on the infra-test branch may be someone's in-progress backend test rather than a real dev failure; say so for those. This is an alert, not a gate: continue with the merge unless the user says otherwise. If nothing comes back, say "Prod/dev CI: all green" in one line.
Step 2 — Force-merge the PR
gh pr merge <number> --squash --admin --delete-branch
--admin: bypasses required review checks and branch protection rules--squash: squash all commits into one on main--delete-branch: deletes the remote branch after merge
If the merge fails: print the full error and stop. Do not proceed.
Step 3 — Delete the local branch (if applicable)
Check whether the branch exists locally:
git branch --list <headRefName>
If the branch exists and is not the currently checked-out branch: delete it.
git branch -d <headRefName>
If that fails (branch not fully merged in git's view due to squash): use force:
git branch -D <headRefName>
If we're currently on the feature branch: switch to main first, then delete.
git checkout main
git branch -D <headRefName>
Step 4 — Pull updated main
git fetch origin main
git reset --hard origin/main
After a squash merge, local main always diverges (N commits become 1 on origin), so --ff-only will always fail. reset --hard is correct and safe here — local commits are already represented in the squash on origin.
Step 5 — Push main to personal fork
git push $FORK_REMOTE main --force
Force-push is required after a squash merge because the fork's main still has the pre-squash commits.
Step 6 — Update linked issues on the project board
This repo's project board is SatcherInstitute org project number 5 (id PVT_kwDOBCaVcM4BeXhW), Status field id PVTSSF_lADOBCaVcM4BeXhWzhYyS0g, with options Backlog (f75ad846), Up Next (d6a0bd53), In Progress (47fc9ee4), Done (98236657).
GitHub's native "Item closed" project automation already moves an issue to Done the moment it closes via a recognized keyword (Closes #NNNN, Fixes #NNNN, etc). That case needs no action here — just identify it:
gh pr view <number> --json body,closingIssuesReferences \
--jq '{body, autoClosing: [.closingIssuesReferences[].number]}'
For every other bare #NNNN reference in the PR body that is not in autoClosing, read the issue and use judgement against the merged diff:
gh issue view <n> --json number,title,body,state
- Fully resolved but not tagged with a closing keyword (the PR body mentions
#NNNNin passing, but the diff clearly finishes what the issue describes): close it and move it to Done yourself.gh issue close <n> --comment "Resolved by #<pr_number>." ITEM_ID=$(gh api graphql -f query='{ organization(login: "SatcherInstitute") { projectV2(number: 5) { items(first: 100) { nodes { id content { ... on Issue { number } } } } } } }' -q ".data.organization.projectV2.items.nodes[] | select(.content.number == <n>) | .id") gh api graphql -f query="mutation { updateProjectV2ItemFieldValue(input: { projectId: \"PVT_kwDOBCaVcM4BeXhW\" itemId: \"$ITEM_ID\" fieldId: \"PVTSSF_lADOBCaVcM4BeXhWzhYyS0g\" value: { singleSelectOptionId: \"98236657\" } }) { projectV2Item { id } } }" - Not obviously resolved (referenced in passing, partial progress, a "found while working on this" aside): leave it — it's a candidate for Step 7, not a silent Done move. Don't guess.
Also check for issues never mentioned in the body at all. A PR body can be completely silent on the issue it was tackled from (no Closes, no bare #NNNN — this has happened: PR #5129 resolved #5127 without referencing it anywhere). Text-scanning the body alone misses this, so cross-check the board directly:
gh api graphql -f query='{ organization(login: "SatcherInstitute") { projectV2(number: 5) { items(first: 100) { nodes { id fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } } content { ... on Issue { number title state } } } } } } }' \
--jq '.data.organization.projectV2.items.nodes[] | select(.fieldValueByName.name == "In Progress") | .content'
For each "In Progress" issue, compare its title and scope against the merged PR's title and diff. A close title match or a diff that visibly implements the issue's stated scope is a candidate even with zero textual reference — use the same judgement as above (read the issue body, compare to the actual changed files) before closing it. Do not close on title similarity alone; confirm the diff actually does what the issue describes.
Step 7 — Confirm follow-up items with the user
Scan the PR body/diff and anything surfaced in Step 6 for deferred work: language like "follow-up", "out of scope", "revisit later", "TODO", "deferred," or a new problem noticed but not fixed while building this PR.
If candidates exist, ask the user with AskUserQuestion (multiSelect) before touching anything — this is a prioritization call, not a mechanical one:
gh issue edit <n> --add-assignee @me
gh api graphql -f query="mutation { updateProjectV2ItemFieldValue(input: { projectId: \"PVT_kwDOBCaVcM4BeXhW\" itemId: \"$ITEM_ID\" fieldId: \"PVTSSF_lADOBCaVcM4BeXhWzhYyS0g\" value: { singleSelectOptionId: \"d6a0bd53\" } }) { projectV2Item { id } } }"
Only run the assign/move mutation for items the user actually selected. If nothing reads as an obvious follow-up, skip this step and say so briefly rather than forcing a suggestion.
Step 7b — Refresh the ReadMe contributor recipes
If the merged PR touched frontend/src/ or frontend/.env*, invoke the update-recipes skill with the PR number (/update-recipes <number>). It syncs code tabs and highlights via scripts/readme_recipes/sync_recipes.py and flags prose drift. Local main is already at the merge commit (Step 4), so it reads the merged code. Otherwise skip this step.
Do not pre-check README_API_KEY to decide whether to invoke the skill. The script resolves the key from the environment or from .env.secrets at the repo root and reports a missing one as its own exit code. Testing the variable in a bash shell gives a false negative, which is how this step got skipped on PR #5311 and left the recipes drifted with nothing failing.
Step 8 — Flag a likely DAG rerun for backend data changes
Check which files the merged PR touched:
gh pr view <number> --json files --jq '.files[].path'
If any path is under python/datasources/ or python/ingestion/ and the change affects data output (not just a comment, type hint, or test-only change — read the diff if unsure), the merge likely needs a DAG rerun to actually refresh the deployed data, since merging alone only ships the code.
Map the touched datasource to its workflow: look for a .github/workflows/dag*.yml whose name or on.workflow_dispatch job references the same data source (e.g. age_adjust_cdc_hiv.py → dagCdcHiv.yml).
gh workflow list --all | grep -i dag
Ask the user before triggering anything:
"This PR touched
<file>, which looks like it changes data output. Want me to rerun<dag>.ymlagainst infra-test?"
If they decline or no backend-data files were touched, skip to Step 10.
Step 9 — Wait for the auto-deploy before rerunning the DAG
Merging to main automatically fires a DEPLOY MAIN CODE TO INFRA-TEST GCP (DEV SITE) workflow that redeploys the same het-infra-test-05 project the DAG will hit. Running the DAG before that deploy finishes hits the pre-merge container and fails or silently uses stale code — indistinguishable from the fix not having worked. Confirm the deploy has completed before triggering the DAG:
DEPLOY=$(gh run list --branch main --workflow "DEPLOY MAIN CODE TO INFRA-TEST GCP (DEV SITE)" --limit 1 --json databaseId,status,conclusion,createdAt)
DEPLOY_RUN_ID=$(echo "$DEPLOY" | jq -r '.[0].databaseId')
echo "$DEPLOY"
If status is not completed, wait for it with gh run watch "$DEPLOY_RUN_ID" launched via the Bash tool's run_in_background (the harness notifies on completion — don't sleep-poll) rather than proceeding immediately. Once it's done, trigger the DAG:
gh workflow run <dag>.yml --ref infra-test
Step 9b — Check for abandoned tables after the DAG run
A datasource change can rename or move tables, leaving the old ones behind. gh workflow run prints no run ID, so look it up first:
gh run list --workflow <dag>.yml --branch infra-test --limit 1 --json databaseId,status -q '.[0]'
Once that run finishes (watch it with gh run watch <run-id> via run_in_background; don't sleep-poll), check its dataset (the DAG's DATASET_NAME) in one call:
source .venv/bin/activate && python scripts/find_abandoned.py --env test --dataset <dataset> > /tmp/abandoned-test.txt 2>&1 || { echo "CHECK FAILED"; tail -5 /tmp/abandoned-test.txt; }; grep -E "^ (table|json)|^# " /tmp/abandoned-test.txt
If it prints CHECK FAILED, report "Abandoned: check failed" with the error lines in Step 10 (typically expired ADC credentials or a gh error), not "none". Otherwise, empty output means nothing abandoned; say nothing beyond the Step 10 summary. Otherwise list what it found in two or three lines and point to the delete commands in /tmp/abandoned-test.txt. Never run them. If the DAG run failed, skip this step: the script only judges against successful runs.
Step 10 — Confirm
Print a summary:
"Merged PR #. Local main is up to date with origin/main and pushed to $FORK_REMOTE/main. CI: <all green / failing workflows from Step 1c>. Board: <issues moved to Done, if any> <issues moved to Up Next, if any>. Recipes: <current/pushed/skipped>. DAG: <triggered/skipped/declined>. Abandoned: <none / N tables, M JSON groups / skipped / check failed>."
Notes
--adminbypasses all branch protection rules including required reviews. Use only when you have confirmed the PR is ready.- Never force-push to
origin/main(SatcherInstitute). The merge goes throughgh pr merge, not a direct push. - If the PR is on a non-main base branch: stop and warn the user.
- Step 6 only needs to run once per merge — don't re-derive the project/field/option IDs, they're fixed for this repo (same ones
/tackleuses). - Step 8/9 only apply when the PR touches
python/datasources/orpython/ingestion/with real data-output impact — most PRs (frontend, docs, skills) skip straight to Step 10.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |