| 1 | --- |
| 2 | name: gh-find-prs |
| 3 | description: "Survey open CodeWhale PRs and triage each for mergeability and disposition against the real landing branch." |
| 4 | --- |
| 5 | |
| 6 | # gh-find-prs |
| 7 | |
| 8 | Survey the open PR queue and assign each PR a disposition — backed by code, tests, and checks, never by title — testing real mergeability against the actual release branch (often local-only, e.g. `<release-branch>`), not the main-based GitHub flag. |
| 9 | |
| 10 | ## When to use |
| 11 | |
| 12 | - A maintainer asks "what's in the PR queue?", "what can we land?", or "triage open PRs". |
| 13 | - Before a release cut, to sweep community contributions into the active release branch. |
| 14 | - Whenever you need a per-PR DIRECT-MERGE / HARVEST / DEFER / CLOSE-WITH-NOTE call with credit attached. |
| 15 | |
| 16 | This is read-and-recommend. You do NOT merge, close, tag, or publish. You surface evidence and a proposed disposition; the maintainer approves. |
| 17 | |
| 18 | ## Workflow |
| 19 | |
| 20 | 1. **Inventory the queue.** One call, structured: |
| 21 | ``` |
| 22 | gh pr list --repo Hmbown/CodeWhale --state open \ |
| 23 | --json number,title,author,headRefName,baseRefName,isDraft,mergeStateStatus,statusCheckRollup |
| 24 | ``` |
| 25 | Note `mergeStateStatus` (CLEAN / BLOCKED / DIRTY / UNKNOWN) but treat it as a hint only — it is computed against `main`, and the real landing target is usually a different branch. |
| 26 | |
| 27 | 2. **Identify the real landing branch.** The release head is frequently local-only: |
| 28 | ``` |
| 29 | git branch --list 'codex/v0.8*' 'codex/v0.9*' |
| 30 | git log --oneline -1 <release-branch> |
| 31 | ``` |
| 32 | Use that ref, not `main`, for every mergeability test below. |
| 33 | |
| 34 | 3. **Read each candidate from code, not title.** For every non-trivial PR: |
| 35 | ``` |
| 36 | gh pr view <N> --repo Hmbown/CodeWhale \ |
| 37 | --json files,additions,deletions,statusCheckRollup,body,comments |
| 38 | gh pr diff <N> --repo Hmbown/CodeWhale |
| 39 | ``` |
| 40 | Read the diff. A "fix(exec): ..." can be a no-op or a regression; a "chore" can be the real fix. Judge the change, the tests it adds, and any review comments. |
| 41 | |
| 42 | 4. **Decode check failures — distinguish trivial from real.** In `statusCheckRollup`, find each `conclusion: FAILURE` and read its job. CodeWhale's CI jobs are `Lint`, `Test (ubuntu-latest|macos-latest|windows-latest)`, `Version drift`, `gate` (Contribution gate), `npm wrapper smoke`, `Mobile runtime smoke`, `Documentation`, `GitGuardian Security Checks`. |
| 43 | - A `Lint` failure that is only `cargo fmt` drift is trivial — harvestable, fix on landing with `cargo fmt --all`. |
| 44 | - A failing `Test (...)` or `clippy` under Lint is real — read the log before trusting it. |
| 45 | - `Version drift` failing on a community PR is expected (they bumped, or didn't); not a blocker for harvest. |
| 46 | ``` |
| 47 | cargo fmt --all -- --check && cargo clippy --workspace --all-targets |
| 48 | ``` |
| 49 | |
| 50 | 5. **Test-merge against the real release head.** The `mergeStateStatus` flag lies for local branches. Probe the actual merge: |
| 51 | ``` |
| 52 | git merge-tree --write-tree --messages <release-branch> origin/pr/<N> # if PR ref is fetched |
| 53 | git merge-tree --write-tree --messages <release-branch> <pr-head-sha> |
| 54 | ``` |
| 55 | Exit 0 and no `CONFLICT` lines → clean against the release branch (DIRECT-MERGE candidate even when GitHub shows BLOCKED/DIRTY). Conflicts printed → HARVEST or DEFER. This is read-only; it writes objects to the object store, not to any branch or working tree. |
| 56 | |
| 57 | 6. **Assign a disposition with required credit.** Per PR, recommend exactly one: |
| 58 | - **DIRECT-MERGE** — diff is sound, checks are green or trivially-fixable, `merge-tree` is clean against the release head. Land via cherry-pick to preserve the original author automatically. |
| 59 | - **HARVEST** — the change is good but conflicts, needs fmt/rebase, or is entangled with the release work. Reimplement on the release branch and credit with trailers (cherry-pick is not preserving authorship here): |
| 60 | ``` |
| 61 | Co-authored-by: Name <email> |
| 62 | Harvested-from: PR #<N> by @handle |
| 63 | ``` |
| 64 | The `Harvested-from:` trailer lets the auto-close-at-main workflow close the PR with credit once the change reaches main. |
| 65 | - **DEFER** — sound but blocked by an open question, missing tests, or a release freeze. Leave a positive, specific comment; do not close. |
| 66 | - **CLOSE-WITH-NOTE** — superseded, duplicated, or out of scope. Propose the close to the maintainer with a crediting, appreciative note; never close it yourself. |
| 67 | |
| 68 | 7. **Report, don't act.** Output a compact table: PR | author | landing-branch verdict | check summary | disposition | credit line. Stop there for maintainer approval. |
| 69 | |
| 70 | ## Red flags / don't |
| 71 | |
| 72 | - **Don't judge by title.** "fix(...)" / "feat(...)" / emoji-prefixed test PRs prove nothing. Open the diff every time. |
| 73 | - **Don't trust `mergeStateStatus` for the real target.** CLEAN/BLOCKED/DIRTY are vs `main`; always confirm with `git merge-tree <release> <pr-head>`. |
| 74 | - **Don't conflate trivial and real check failures.** A fmt-only `Lint` red is harvestable; a failing `Test (...)` is not — read the log. |
| 75 | - **Don't drop credit.** Every harvest carries `Co-authored-by:` + `Harvested-from:`; every cherry-pick keeps the original author. No silent reimplementation. |
| 76 | - **Don't merge, close, retarget, tag, publish, or release.** Recommend; the maintainer decides. |
| 77 | - **Don't post negative or nitpicking comments.** GitHub-facing comments are positive and crediting; keep critique in your internal report to the maintainer. |
| 78 | - **Don't modify the working tree or any branch.** `git merge-tree --write-tree` is the only "write" allowed — it touches the object store only. |
| 79 |