Pull Request

Pull request: open, verify, and pass review

End-to-end flow for turning the current change into a pull request that passes this repo's automated quality gate, fixing review feedback in a loop until green. When green, it also flags changes worth a blog post and offers to file a blog issue (Phase 6).

The quality gate has three layers:

1. Local gate you run before pushing: cargo fmt, cargo clippy, cargo build, cargo test.
2. GitHub Actions — ci.yml (fmt, typos, config schema, clippy, test, build, msrv, cargo-deny, coverage with --fail-under thresholds), and web.yml for web/** changes. The two are mirror images: ci.yml ignores web/**, docs/** and **.md, web.yml runs only for web/**, so a docs-only PR legitimately shows very few checks. machete.yml is not part of the gate — it is advisory and runs weekly on a schedule, never on a pull request.
3. AI reviewers that run as PR status checks and post review threads:
   • CodeRabbit (coderabbitai[bot])
   • cubic · AI code reviewer (cubic-dev-ai[bot])

"Green" = every check passes and no unresolved review threads from those bots. The loop below drives toward that state.

When to use

• The user wants a change opened as a PR and taken through to merge-ready.
• The user wants existing review comments addressed and pushed until checks pass.
• Any user-visible (UI) change that should ship with visual evidence.

Environment — gh CLI or GitHub MCP tools

This skill runs in two environments that reach GitHub in incompatible ways. Determine which one you are in before Phase 3, because roughly half the commands below do not exist in the other:

command -v gh      # no output => remote environment, gh is unavailable

• Local / terminal sessions — gh is installed. Use the gh commands as written; review-status.sh works and is the fastest way to read the gate.
• Claude Code on the web / remote sessions — gh is not installed and there is no direct GitHub API access. Use the mcp__github__* tools instead. review-status.sh shells out to gh, so it cannot run there; reproduce it with the MCP calls below (Phase 4 step 1 spells out the sequence).

There is no MCP equivalent of gh pr checks --watch: poll pull_request_read (method: "get_check_runs") instead, leaving ~30s between polls. Do not sleep in a loop to wait — if PR events are subscribed, they wake the session on their own.

git itself behaves identically in both environments, so the commit and push steps never change.

Prerequisites (check, don't assume)

• Local only: gh auth status is logged in. If not, stop and ask the user to gh auth login. In the remote environment there is nothing to check — the MCP tools carry their own auth, and a failure there means the repository is out of scope, not that a login is missing.
• Working tree changes are the ones intended for this PR (git status, git diff).
• For UI verification: script/ui-run.sh setup has been run once and xdotool is installed (see docs/agent-ui-verification.md). If they're missing and the change is UI-facing, ask the user to install them rather than skipping evidence.

The two helper scripts live next to this file:

• scripts/review-status.sh [PR#] — prints checks + unresolved AI threads, exits 0 green / 1 blocked / 2 error. Requires gh; exits 2 with a pointer to the MCP path when it is missing.
• scripts/attach-screenshots.sh <slug> <png...> — publishes images to the pr-assets branch and prints Markdown embeds. Pure git, so it works in both environments.

Phase 1 — Branch and local quality gate

1. Never commit on develop or main. Check git rev-parse --abbrev-ref HEAD. If on a protected branch, create a topic branch first (descriptive, e.g. git switch -c fix-project-panel-crash).
2. Run the local gate and fix everything it reports before pushing — this is cheaper than a review round-trip:

   cargo fmt --all
   cargo clippy --all-targets -- -D warnings
   cargo build
   cargo test

   (For GUI code, build with the linker path from ui-run.sh setup: RUSTFLAGS="-L $HOME/.local/devlibs" cargo build --features gui --bin nohrs.)
3. Follow the repo's Rust guidelines (CLAUDE.md): no unwrap()/panics, no silent let _ = on fallible calls, propagate errors with ?. The AI reviewers flag these, so getting them right now saves a loop iteration.

Phase 2 — UI verification (only if the change is user-visible)

If the diff touches layout, panels, navigation, previews, or anything rendered, verify it for real and capture evidence. Full workflow: docs/agent-ui-verification.md.

# Build, launch, screenshot the relevant states.
RUSTFLAGS="-L $HOME/.local/devlibs" cargo build --features gui --bin nohrs
./script/ui-run.sh launch                      # prints WINDOW / DISPLAY / PID
./script/ui-run.sh shot /tmp/before.png        # then Read the PNG to confirm state
# Drive the UI with xdotool, re-shoot after each step (coordinates are absolute):
DISP=$(./script/ui-run.sh display); WIN=$(./script/ui-run.sh win)
DISPLAY=$DISP xdotool windowactivate "$WIN" mousemove X Y sleep 0.4 click 1 sleep 1.2
./script/ui-run.sh shot /tmp/after.png         # Read it; verify the expected change
./script/ui-run.sh stop

Read each PNG back yourself and confirm the change actually happened — a clean build is not evidence. Keep the PNGs that best show before/after for the PR. Mind the gotchas in the doc (pkill -x nohrs, find window by PID, black-first-frame).

Phase 3 — Open or update the PR

1. Commit with a clear message and push the branch:

   git add -A && git commit -m "<imperative summary>"
   git push -u origin HEAD

   End commit messages with the trailer: Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2. If a PR for this branch already exists, update it instead of opening a new one — gh pr view, or list_pull_requests with head: "<owner>:<branch>" and state: "open".

3. Attach screenshots (UI changes only) before writing the body, so you have the embed URLs:

   .claude/skills/pull-request/scripts/attach-screenshots.sh ui-change /tmp/before.png /tmp/after.png

   Paste the printed ![...](...) lines into the PR body under the ## Testing heading. (Images go to the pr-assets branch, so they never appear in the code diff the AI reviewers read.)

4. Open the PR honoring PR hygiene (CLAUDE.md):

   • Imperative, correctly-capitalized title, no conventional-commit prefix (fix:/feat:), no trailing punctuation. Optionally prefix with the crate name when one crate is the clear scope (e.g. git_ui: Add history view).
   • Body ends with a Release Notes: section — blank line after the heading, one bullet: - Added ... / - Fixed ... / - Improved ..., or - N/A for docs-only / non-user-facing changes.

   The base branch is develop, not main.

   gh pr create --base develop --title "<title>" --body "$(cat <<'EOF'
   ## Summary
   
   <what changed and why>
   
   ## Changes
   
   - <notable change>
   
   ## Testing
   
   - [x] `cargo fmt --all --check`
   - [x] `cargo clippy --all-targets -- -D warnings`
   - [x] `cargo test`
   
   <screenshot embeds, or "N/A" for non-UI changes>
   
   Release Notes:
   
   - <Added/Fixed/Improved ...  or  N/A>
   EOF
   )"

   Without gh, the same PR via create_pull_request:

   {
     "owner": "noh-rs", "repo": "nohrs",
     "base": "develop", "head": "<branch>",
     "title": "<title>",
     "body": "## Summary\n\n…\n\n## Changes\n\n- …\n\n## Testing\n\n- [x] …\n\nRelease Notes:\n\n- <…>"
   }

   .github/PULL_REQUEST_TEMPLATE.md is only auto-filled for PRs opened through the web UI — both paths above bypass it, so reproduce its sections yourself: ## Summary, ## Changes, ## Testing (tick the three gate checkboxes you actually ran), then ## Release Notes. Put screenshot embeds under ## Testing.