PR Merge Ready

PR Merge Ready (one pass, then validate once)

It follows the same merge-ready loop (threads resolved, reviewers done, CI green) with a speed contract:

1. Triage every open thread before editing any file.
2. Apply every Fix in one pass (group by file; one file is opened/edited once).
3. Validate once, after all edits, scoped to the files you touched — never after each comment.
4. One commit, one push per iteration. Extra pushes cost ~6–7 min of CI each and re-trigger bot reviewers.
5. Comments first, CI second. Never sit in a CI wait while unresolved actionable threads exist.

Do not auto-fix decisions that belong to a human. Product/architecture/scope/intent trade-offs are Escalate — pause, ask with options grounded in existing patterns, wait. Never guess.

This repo is public. Commit messages, code comments, and fixtures written while fixing feedback follow the root CLAUDE.md rule: no customer/org names, org IDs, emails, or private ticket/Slack links — describe triggers generically.

Absolute rule: never reply on PR threads

Never post a reply or comment on any PR review thread — no addPullRequestReviewThreadReply, no gh pr comment, no posted text of any kind. Where you would otherwise reply (declines, decided escalations), resolve the thread silently and surface the rationale to the user in chat. Resolving a thread is a status change, not a reply, and is allowed.

Which reviewers auto-resolve their own threads

Not every reviewer needs a manual resolveReviewThread call. Some bots re-scan the pushed commit and close their own thread once the flagged issue is gone; calling resolveReviewThread on those threads yourself is redundant, and for weave-checks it's actively wrong — it marks a thread resolved against a code state the bot never re-verified.

Identify the author(s) from each unresolved_comments entry's authors field (or the <!-- weave-check: --> marker in body) during triage, and carry that classification into the resolve step.

Reading a weave-checks finding against its own criteria. The marker's <slug> maps to a repo-local .weave-checks/<slug>.md if one exists, else to the default check starter-checks/<slug>.md in weave-os/checks at the release tag pinned in .github/workflows/weave-checks.yml (this repo runs with use-default-checks: true). When triaging a weave-checks[bot] thread, read that file — "Do Not Flag"/"Exclusions" is the fastest false-positive check:

REF=$(sed -nE 's#.*weave-os/checks/.github/workflows/weave-checks.yml@(v[0-9]+\.[0-9]+\.[0-9]+).*#\1#p' .github/workflows/weave-checks.yml)
gh api "repos/weave-os/checks/contents/starter-checks/<slug>.md?ref=$REF" -H 'Accept: application/vnd.github.raw'

Collapsed threads and mixed authorship: pr-fix-plan collapses same-location threads into one entry with a deduplicated authors list and a separately deduplicated thread_ids list — the two are not positionally paired. Apply the auto-resolving-bot exception only when every entry in authors is one of the three auto-resolving bots. If mixed, resolve all of that entry's thread_ids manually.

Prerequisites

• GitHub CLI authenticated: gh auth status
• jq 1.6+ installed
• Stacked PRs: gh stack extension
• On the PR branch locally, or provide PR number
• Use the bundled analyzer at ./.claude/skills/pr-merge-ready/scripts/pr-fix-plan.sh; do not assume pr-fix-plan.sh is installed on PATH
• Go toolchain; golangci-lint is optional locally (reported as blocked by scripts/agent_checks.py when missing — CI still runs it)

Commit workflow

NEVER git add -A. Stage only files you changed.

1. Lint/format autofix on changed files (included in the one validation pass, Step 4)
2. git add <specific files>
3. git commit -m "message"
4. git push (in a stack: gh stack submit --auto --open)

If the branch is out of date: git push --force-with-lease only after verifying you don't overwrite someone else's work. Never raw git push --force.

High-level loop

0. Identify or create PR; align checkout with the PR's base repository and head SHA
0b. WEAVE-CHECKS PREFLIGHT: read weave-checks criteria for the files in play
1. Fetch fresh state
2. If DONE → exit
3. If actionable threads:
   a. TRIAGE ALL threads first (Fix / Decline / Skip / Escalate)
   b. Surface Escalates in one AskQuestion batch; wait if they block
   c. APPLY ALL Fixes in one pass (group by file)
   d. Resolve all Declines (and decided Escalates) silently
   e. Validate ONCE, scoped to touched files (Step 4) + re-run weave checks
   f. One commit + one push
   g. Go to step 1 — do NOT wait for CI yet
4. Else (zero actionable threads):
   a. Foreground CI-wait with cheap comment sentinel (Step 6)
   b. New comment → abort CI wait, go to Step 1
   c. CI all green + DONE → exit

DONE conditions (ALL must hold against the LATEST head SHA)

Exit only when every condition is true on the same poll, after CI has dispatched for the current head SHA:

1. No actionable review comments — unresolved_comments is empty, or every remaining entry is Skip, is_outdated: true, or the issue no longer applies (code_context). For any thread in the skip ledger (an auto-resolving-bot thread left open under the exception): if the bot has closed it, count DONE; if the bounded fallback has not yet fired (≥2 pr-fix-plan polls AND ≥5 min), do not count DONE and do not force-resolve — wait for the bot. Only after that window, if the thread is still open, force-resolve, surface the deviation, then count DONE. Escalate threads awaiting a user decision block DONE. Unapplied Fix nits from top_level_comments (including advisory review bodies) also block DONE. If reviews_fetch_failed or conversation_comments_fetch_failed is true, feedback is incomplete and DONE is blocked.
2. All required CI checks for the head SHA are present and concluded.
3. No CI pending/running — checks_summary.pending == 0 and checks_fetch_failed is absent. If checks_fetch_failed: true, CI is unknown — do not count as done.
4. No REVIEW_REQUESTED — reviewRequests is empty.
5. No CHANGES_REQUESTED — reviewDecision is not CHANGES_REQUESTED; each latestReviews state is APPROVED, COMMENTED, or DISMISSED.

Execution

Step 0: Identify or create the PR and align the local branch

Single-PR scoped. Use the user's PR number, else infer from the current branch. If the branch has no PR yet, create one before fetching review state:

1. Ensure the intended changes are committed. Stage only the changed files; never use git add -A.
2. Push the branch, using git push -u origin HEAD when it has no upstream.
3. Open a ready-for-review PR with gh pr create --base main (do not pass --draft unless the user explicitly asks).
4. Capture the resulting PR number and continue with the same workflow below.

If there are no changes to publish and no PR exists, stop and ask the user what should be reviewed.

Resolve OWNER/REPO to the PR's base repository from the current repository context. The head owner/repository identify the fork containing the code; do not pass those values to the analyzer, which queries the PR in its base repository.

read -r OWNER REPO < <(gh repo view --json owner,name --jq '[.owner.login, .name] | @tsv')
gh pr view "${PR_NUMBER:-}" --repo "$OWNER/$REPO" \
  --json number,headRepositoryOwner,headRepository,headRefName,headRefOid \
  -q '{number: .number, head_owner: .headRepositoryOwner.login, head_repo: .headRepository.name, branch: .headRefName, sha: .headRefOid}'

If the base repository cannot be resolved from the checkout, use the base repository explicitly; never substitute the fork's head repository.

For a mid-stack PR (gh stack view --short), run gh stack checkout <headRefName> when needed, then verify git rev-parse HEAD equals the PR's headRefOid. For a non-stack PR, use the PR number and base repository so GitHub CLI can select the correct fork ref; do not check out by branch name alone:

# Stop rather than switching away from uncommitted work.
test -z "$(git status --porcelain)" || { echo "Working tree is dirty" >&2; exit 1; }
gh pr checkout "$PR_NUMBER" --repo "$OWNER/$REPO" --branch "pr-${PR_NUMBER}-${HEAD_SHA:0:12}"
test "$(git rev-parse HEAD)" = "$HEAD_SHA" || { echo "PR head SHA mismatch" >&2; exit 1; }

If that unique local branch already exists at a different commit, choose another unused local name rather than resetting it. Before editing or pushing, verify the local branch tracks the PR head ref from head_owner/head_repo. If the checkout or upstream cannot be verified safely, stop and ask. Fixes always go on the PR's own head branch.

Step 0b: Weave-checks preflight (once, before any triage or edit)

Read the weave-checks criteria (repo-local .weave-checks/*.md, else the pinned starter-checks/*.md — see "Reading a weave-checks finding" above) that apply to the files this PR touches, plus the CLAUDE.md guide of each touched package. Reviewer asks that contradict those guides (layering, magic provider strings, logging keys, tautological tests) are Decline or Escalate, not Fix.

Step 1: Fetch fresh PR state (every iteration)

Re-fetch every iteration. Never reuse stale data. Do not hand-roll GraphQL for review threads.

./.claude/skills/pr-merge-ready/scripts/pr-fix-plan.sh "$PR_NUMBER" --owner "$OWNER" --repo "$REPO" --max-comments 0 --json
gh pr view "$PR_NUMBER" --json headRefOid,reviewDecision,reviewRequests,latestReviews

--max-comments 0 = no display cap. pr-fix-plan paginates all review threads (fails loudly past 20 pages / 2,000 threads). GitHub orders threads oldest-first and resolved threads never leave the connection — a single-page first:100 fetch goes permanently blind past 100 total threads.

pr-fix-plan --json returns:

• head_branch, head_sha, and is_checked_out — is_checked_out means the local HEAD SHA equals the PR head SHA; if false, use Step 0's safe checkout rather than checking out by branch name alone
• changed_files — do NOT re-derive via git diff
• unresolved_comments — unresolved, collapsed. Each has file, line, start_line, authors, body, urls, thread_ids, is_outdated, collapsed_count, code_context, related_lines_in_pr, thread_comments
• top_level_comments — omitted when empty
• pattern_summary
• checks / checks_summary — if checks_fetch_failed: true, the empty list is NOT trustworthy
• reviews_fetch_failed / conversation_comments_fetch_failed — if true, feedback is incomplete and DONE is blocked

Skip is_outdated: true entries when counting actionable work. Also skip any whose code_context shows the issue is already addressed.

top_level_comments are not line-anchored. Triage them the same Fix/Decline/Escalate/Skip way, but they have no thread_ids to GraphQL-resolve — Fix by editing, Decline/Skip by noting in chat only.

Advisory review bodies are nitlists. Bots such as workweave-bot post COMMENTED reviews with zero threads and a body listing several nits across files; these arrive as top_level_comments entries with source: "review". Split each body into one item per nit and triage each individually — an empty unresolved_comments does not mean "no feedback". Track which nits you've applied across iterations (by review URL + nit) so an already-applied body isn't re-triaged; it stays on the PR forever.

Comment-first: any non-Skip entry whose issue still applies → Steps 2–5 immediately. Do not wait for CI, even if checks are running or failed.

CI-wait: only when zero actionable comments → Step 6.

Step 2: Triage ALL unresolved threads before touching code

Walk every actionable unresolved_comments entry before any edit. Produce a batch plan:

Fix     : [thread ids / files]
Decline : [thread ids + one-line rationale]
Escalate: [thread ids]
Skip    : [thread ids]

Announce this list to the user, then execute. Do not drip-triage (classify one, edit, classify next).

Fix vs Escalate. Fix = one objectively-correct resolution matching existing patterns. Escalate signals:

• Product / UX / behavior change
• Architectural trade-off with lasting consequences
• Scope expansion beyond the PR
• Ambiguous intent only the author knows
• Conflicting reviewers
• Risk / blast radius (security, data integrity, billing, migrations)

When in genuine doubt between Fix and Escalate, Escalate. (Low-stakes mechanical nits still default to Fix.)

Bot suggestion blocks are authoritative. When a bot (workweave-bot, greptile-apps[bot], cubic-dev-ai[bot], …) offers a fenced ```suggestion replacement — especially comment-length / doc-brevity nits — it is a Fix: apply the replacement verbatim. Don't paraphrase or skip because the existing wording seems fine. Only decline if applying it would break the build or contradict a package CLAUDE.md rule. Free-form bot feedback without a suggestion block is triaged like any other comment.

Step 3: Apply the whole Fix set in one pass

Do not validate, commit, or push inside this step.

1. Group Fix threads by file. Open each file once.
2. Use code_context and related_lines_in_pr instead of re-reading the diff / grepping. Open the file only for surrounding context.
3. Apply every requested change in that file, including every related_lines_in_pr site (fix the pattern once, everywhere it appears in the PR).
4. Move to the next file.
5. Independent files may be edited in parallel (multiple Edit/Write calls in one turn). Dependent edits (same file, or A must land before B compiles) stay serial.

Guidelines: only the changes requested; no unrelated refactors.

Decline

No code change, no PR reply. Resolve in Step 5. Collect one concise chat line each: what was asked, why you're declining (1–3 sentences, specific).

Skip

Leave alone.

Escalate → Step 3.5

Never change code or resolve on your own.

1. Investigate first (referenced file/line, surrounding code, how similar cases are handled).
2. Frame each thread: reviewer ask + link; why it needs a human; 2–4 options grounded in existing patterns with trade-offs; your recommendation.
3. Present all escalations in one AskQuestion batch.
4. If the user has not responded and the only remaining work is escalations, stop the loop — do not spin or sit in CI wait. Resume from Step 1 when they answer.
5. Once they choose, treat the chosen option as a Fix (fold into the current pass if you haven't validated yet; otherwise a new iteration). Resolve silently. If they defer, leave unresolved — the PR is blocked on it.

Do not auto-resolve an escalated thread. Do not let it slip through as a Fix because asking felt slower.

Step 4: Validate ONCE, scoped to what you touched

Run this after every Fix in this iteration is applied, and never per comment. Skip the whole step if this iteration was all-Decline (no files changed).

Scope to this iteration's uncommitted edits.

CHANGED_FILES=()
while IFS= read -r -d '' file; do
  [[ -f $file ]] && CHANGED_FILES+=("$file")
done < <({
  git diff --name-only -z
  git diff --cached --name-only -z
  git ls-files --others --exclude-standard -z
})

Autofix first (so formatting lands in the same commit)

Format only existing Go paths from this iteration's CHANGED_FILES; do not run a repository-wide write formatter here.

GO_FILES=()
for f in "${CHANGED_FILES[@]}"; do [[ $f == *.go ]] && GO_FILES+=("$f"); done
((${#GO_FILES[@]})) && gofmt -w -- "${GO_FILES[@]}"

Regenerate if a generator input changed

Generated files must land in the same commit, or CI fails on drift. Never hand-edit internal/sqlc/ or AGENTS.md.

Then run the scoped checks

# Tests for the touched Go packages only (whole-module `go test ./...` is CI's job)
if ((${#GO_FILES[@]})); then
  GO_PKGS=($(for f in "${GO_FILES[@]}"; do echo "./$(dirname "$f")"; done | sort -u))
  go vet "${GO_PKGS[@]}" && go test -count=1 "${GO_PKGS[@]}"
fi
# Request-path / dispatch / policy / provider edits:
make inference-boundary
# Discover any other suites the touched paths select (docs, lint, install, frontend, smoke):
python3 scripts/agent_checks.py plan --paths "${CHANGED_FILES[@]}"

Run the non-Go suites the planner selects that are cheap and local (docs, install, lint if golangci-lint is installed; cd frontend && npm run typecheck && npm run lint for frontend/). Suites the planner marks integration: true (smoke, database) are left to CI — say so in chat; never report them as passed.