Commit PR

/commit-pr

Commit pending changes and open or update a PR, then watch CI and the automated review bots through to green and resolved. Adapted for NewsBlur from the Tavus skillshare commit-pr skill; the CI and review-thread loop is the same, the repo specifics are NewsBlur's.

Goal: what "done" means

The goal is a verified-clean PR, not a pushed branch. Immediately before ending the turn, re-run the live checks and confirm all of the following on the current head SHA:

1. Every required check is green (gh pr checks).
2. Zero unresolved Claude/Codex review threads (the GraphQL query in section 6, run fresh; never trust a result from before the last push).
3. The PR is marked ready for review. Draft is this skill's starting state, never its ending state, unless the user explicitly asked for a draft in this run.

Review-task state, not a fixed delay, decides when the review wait is over. Ending the turn while a review workflow is queued or running, or while an unresolved automated review thread exists, is a failure of this skill. If no review check is pending for the current head, run the final thread query immediately; do not wait out a timer. Every wait is on a known action: each pending check belongs to a workflow whose recent run durations are queryable (section 5), so size the wait from that record, never from a guessed interval.

If genuinely blocked (a review check is stuck, CI is broken by something outside this PR, a comment needs a decision only Sam can make), end the turn by stating exactly what is unresolved and why. Never imply the PR is clean when the final verification did not run or did not pass.

NewsBlur specifics

Workflow

0. Identify where you are and what CI will check

git rev-parse --show-toplevel
git branch --show-current
ls .github/workflows/

Cache these for the run. If the branch is main, stop: propose a branch name and create it before committing (see Notes).

Visual evidence for UI changes. If the change is visible on screen, capture before/after screenshots and attach them with gh pr create --attach 'path.png#Alt text' (or gh pr edit --attach on an existing PR; gh 2.99+ uploads and rewrites the body). For a web change the headless helper .agents/skills/investigate-forum/screenshot.py captures a logged-in worktree stack without a browser; the claude-in-chrome tools work too when Sam has asked for browser use. Backend-only PRs show the failing-then-passing test output instead.

1. Pre-flight: run what CI runs

Django Tests runs python manage.py test apps (see tests.yml); locally run the modules the diff touches, from the worktree's own web container:

docker exec -t newsblur_web_<worktree> python manage.py test apps.<app>.<module>.<TestClass> --noinput -v 1
docker exec -t newsblur_web_<worktree> sh -c "black --check --line-length 110 <changed .py files>; isort --check-only --profile black <changed .py files>; flake8 --max-line-length 110 --select=E9,F63,F7,F82,F821 <changed .py files>"

If the worktree stack is stopped, make worktree from the worktree brings it back. iOS and Android changes follow the build commands in CLAUDE.md and clients/ios/CLAUDE.md; at minimum the compile-only check must pass. Fix failures before committing.

2. Stage and commit

Group modified files by logical change into separate commits. Stage specific files per commit, not git add -A, so stray files never ride along. Subject: one imperative sentence that says what changes for a user or reader, with the forum topic in parentheses when there is one, for example Never ration a forbidden feed shared by active readers by their proxy budget (forum #13832). Body: why, wrapped at 72 characters, then the attribution trailers. Make all commits first, then push once.

3. Push

git push -u origin "$(git branch --show-current)"    # first push
git push                                             # after that

If the branch is behind main, rebase (git pull --rebase origin main), never merge. Never force-push a PR branch unless Sam explicitly asks.

4. Create or update the PR

gh pr view --json number,title,url,isDraft 2>/dev/null

No PR yet: create it as a draft with the caller's body (or the generic default below), title equal to the main commit subject, at most 70 characters, no trailing period, and any requested labels:

gh pr create --draft --label forum --title "<title>" --attach "screenshots/before.png#Before" --attach "screenshots/after.png#After" --body "$(cat <<'EOF'
<body>
EOF
)"

Draft keeps early CI churn out of the review queue; section 5.5 promotes it in this same run.

PR exists: the push already updated it. Edit the body only if the scope changed (gh pr edit <n> --body ...).

Write the body for a reviewer walking in cold: what changed and why, what to check, exact test commands with before and after output, deploy notes (make deploy, make celery, or both; migrations; Celery restart). Cut author process notes.

5. Watch CI

gh pr checks --watch

Size waits from the workflows' own history, not a guessed timer:

gh run list --workflow=tests.yml --status completed --limit 5 --json startedAt,updatedAt,conclusion

Run the watch in the background or check back near the expected finish; check state ends the wait, never elapsed time. Never end the turn while a check is queued or running.

If a check fails:

1. Read the log: gh run view <run-id> --log-failed | grep -E "FAIL:|ERROR:|Traceback|AssertionError|FAILED \(".
2. Classify: a regression from this PR (fix it); a failure that is also red on main at the merge base (gh run list --branch main --limit 10 --json name,conclusion,headSha), which is fixed when small and self-contained, such as a test that depends on DNS or a missing mock, and otherwise reported; or a transient failure (network, runner), which gets gh run rerun <run-id> --failed.
3. Fix locally, repeat the pre-flight, commit as a new focused commit, push. Never amend or force-push to fix CI on an open PR.
4. Watch again.

Known NewsBlur failure mode: test_*_records_no_error style tests in Test_ScrapingBeeProxy fail on the GitHub runner when a test feed's hostname cannot be resolved, because FetchFeed.fetch records a 401 before the path under test. The fix is @patch("utils.feed_fetcher.validate_public_url") on the test.

Local gate before every push that touches apps/rss_feeds/models.py, apps/reader/models.py, or utils/feed_fetcher.py: the full apps suite, not just the touched module, since those files reach every app. Run it in the foreground (a run started with run_in_background is killed under host memory pressure; a foreground run that outlives its window is moved to the background and survives). Never run two test invocations against the same worktree at once: they collide on the test database and the second stalls on DROP DATABASE. Stop the worktree stack (make worktree-stop) while waiting on CI and start it again for the next round.

The Django CI job aborts the test step at 7 minutes (timeout --signal=ABRT 420). The suite takes 3 to 4 minutes on a normal runner and the faulthandler dump shows where it was; if the abort hit the suite still progressing normally, the runner was slow: rerun once before looking for a cause.

The Claude review check (claude-review) currently fails on every PR before any model output (is_error:true, one turn, zero cost: its API call is rejected). The action also skips itself on any PR that changes its own workflow file, so a workflow fix only shows on the next PR after it merges. Report it, do not chase it, and do not treat it as a blocker when Sam says the rest is green.