GitHub
Raw gh first when you know the command; the scripts replace only the flows
agents repeatedly get wrong. Scripts run TS directly (node ≥ 22.18, or ≥ 23.6 on older lines), no deps.
Modes
- GitHub operations: Use the optimized scripts and gotchas below for PR state, review threads, and GitHub Actions failures.
- Commit: Mandatory before every
git commit, unless the user says otherwise. Read references/commit.md and follow it. It owns message style, validation, selective staging, hooks, and final status checks.
- Merge conflicts: Read references/merge-conflicts.md and follow it for unresolved merge, rebase, or cherry-pick conflicts. This mode uses Git directly and does not require a GitHub PR.
Scripts
| script |
use for |
scripts/pr-snapshot.ts [pr] [-R o/r] |
full PR state in one call: meta, mergeability, checks, files, reviews, comments, thread counts. Use instead of hand-assembling pr view --json field sets or chaining view/checks/comments calls. |
scripts/pr-threads.ts [pr] [-R o/r] [--all] [--author X] [--since ISO] |
the full review conversation: review bodies, issue comments, and unresolved inline threads (resolution state porcelain gh cannot get). Resolved/outdated threads are hidden by default, counted in the header; --all includes them. Read-only: never reply to or resolve threads unless explicitly told to. |
scripts/ci-failures.ts [run-id] [--pr N] [--list] [-R o/r] |
failing checks → failing jobs/steps → log snippet each; full logs saved to files (paths printed); rg those instead of re-fetching. --list [--workflow W] [-L n] shows recent runs with conclusions; use it to find the failing run id instead of gh run list --json field sets. |
Rule of thumb: pr-snapshot answers "what's the state of this PR", pr-threads
answers "what did reviewers write". Neither replaces the other.
All scripts: --json for structured output, --help for usage (includes the
--json shape). Omit the PR number to use the current branch's PR. Default
output is sized for context; pass --full only when a truncation marker
([…+N chars]) hides something you need. They exit 0 when the report
succeeds even if CI is red or threads are unresolved.
Gotchas (each one burned real sessions repeatedly)
- Never pipe gh into
head: SIGPIPE can kill gh mid-write (spurious nonzero
exit, shell-dependent) or silently truncate large output.
Redirect to a file and read that, or trim with --jq '.[0:20]'.
gh pr diff has no --stat and no positive pathspec (--name-only and
-e/--exclude globs exist in gh ≥ 2.95). Per-file stats:
gh api 'repos/{owner}/{repo}/pulls/N/files' --jq '.[]|[.filename,.additions,.deletions]|@tsv'
Full diff: gh pr diff N > "$TMPDIR/pr.diff" once, then rg/sed the file.gh pr checks exits 1 = failing, 8 = pending by design; append || true, read the table.- File at any ref, no base64 dance:
gh api 'repos/{owner}/{repo}/contents/PATH?ref=SHA' -H 'Accept: application/vnd.github.raw'
gh api fills {owner}/{repo} from the cwd repo (GH_REPO=o/r overrides).
Quote any api path containing ? (zsh globs it), or use -X GET -F per_page=100
(any -f/-F silently flips the request to POST without -X GET).--paginate on any list endpoint (/comments, /files, /reviews); --jq
already runs per page; don't add --slurp.- PR/comment bodies:
--body-file file.md or a quoted heredoc. Never inline
--body "..." containing backticks.
- Field cheat-sheet: CI status on a PR =
statusCheckRollup (pr view); steps
live under gh run view N --json jobs; gh search prs fields ≠ gh pr view fields.
- gh has no
-C; pass -R owner/repo to every command, or cd first.
- Branch rules live at
gh api 'repos/{owner}/{repo}/rulesets' on modern repos;
/branches/main/protection 404s unless classic protection is on AND you have
admin ("Branch not protected" or plain "Not Found" both mean check rulesets;
neither is a path error).
- Branch drift:
gh api 'repos/{owner}/{repo}/compare/BASE...HEAD' --jq '{ahead_by,behind_by}'
- jq beyond one line: write the program to a file and
jq -f prog.jq; inline
zsh quoting breaks.
- Don't sleep-poll runs or checks;
gh run watch ID and
gh pr checks N --watch --fail-fast exist; let the harness background them.
1---2name: github3description: GitHub and Git work: validated commits, GitHub Actions CI failures, non-trivial gh commands, and merge/rebase/cherry-pick conflict resolution. Load before every `git commit`. Use for 'commit', 'write a commit message', 'commit changes', GitHub PR inspection, unresolved review threads, GitHub CI logs, 'fix merge conflicts', 'resolve conflicts', or a conflicted branch.4---56# GitHub78Raw `gh` first when you know the command; the scripts replace only the flows9agents repeatedly get wrong. Scripts run TS directly (node ≥ 22.18, or ≥ 23.6 on older lines), no deps.1011## Modes1213- **GitHub operations**: Use the optimized scripts and gotchas below for PR state, review threads, and GitHub Actions failures.14- **Commit**: Mandatory before every `git commit`, unless the user says otherwise. Read [references/commit.md](references/commit.md) and follow it. It owns message style, validation, selective staging, hooks, and final status checks.15- **Merge conflicts**: Read [references/merge-conflicts.md](references/merge-conflicts.md) and follow it for unresolved merge, rebase, or cherry-pick conflicts. This mode uses Git directly and does not require a GitHub PR.1617## Scripts1819| script | use for |20|---|---|21| `scripts/pr-snapshot.ts [pr] [-R o/r]` | full PR state in one call: meta, mergeability, checks, files, reviews, comments, thread counts. Use instead of hand-assembling `pr view --json` field sets or chaining view/checks/comments calls. |22| `scripts/pr-threads.ts [pr] [-R o/r] [--all] [--author X] [--since ISO]` | the full review conversation: review bodies, issue comments, and unresolved inline threads (resolution state porcelain gh cannot get). Resolved/outdated threads are hidden by default, counted in the header; `--all` includes them. Read-only: never reply to or resolve threads unless explicitly told to. |23| `scripts/ci-failures.ts [run-id] [--pr N] [--list] [-R o/r]` | failing checks → failing jobs/steps → log snippet each; full logs saved to files (paths printed); rg those instead of re-fetching. `--list [--workflow W] [-L n]` shows recent runs with conclusions; use it to find the failing run id instead of `gh run list --json` field sets. |2425Rule of thumb: pr-snapshot answers "what's the state of this PR", pr-threads26answers "what did reviewers write". Neither replaces the other.2728All scripts: `--json` for structured output, `--help` for usage (includes the29`--json` shape). Omit the PR number to use the current branch's PR. Default30output is sized for context; pass `--full` only when a truncation marker31(`[…+N chars]`) hides something you need. They exit 0 when the report32succeeds even if CI is red or threads are unresolved.3334## Gotchas (each one burned real sessions repeatedly)3536- Never pipe gh into `head`: SIGPIPE can kill gh mid-write (spurious nonzero37 exit, shell-dependent) or silently truncate large output.38 Redirect to a file and read that, or trim with `--jq '.[0:20]'`.39- `gh pr diff` has no `--stat` and no positive pathspec (`--name-only` and40 `-e/--exclude` globs exist in gh ≥ 2.95). Per-file stats:41 `gh api 'repos/{owner}/{repo}/pulls/N/files' --jq '.[]|[.filename,.additions,.deletions]|@tsv'`42 Full diff: `gh pr diff N > "$TMPDIR/pr.diff"` once, then rg/sed the file.43- `gh pr checks` exits 1 = failing, 8 = pending by design; append `|| true`, read the table.44- File at any ref, no base64 dance:45 `gh api 'repos/{owner}/{repo}/contents/PATH?ref=SHA' -H 'Accept: application/vnd.github.raw'`46- `gh api` fills `{owner}/{repo}` from the cwd repo (`GH_REPO=o/r` overrides).47 Quote any api path containing `?` (zsh globs it), or use `-X GET -F per_page=100`48 (any `-f`/`-F` silently flips the request to POST without `-X GET`).49- `--paginate` on any list endpoint (`/comments`, `/files`, `/reviews`); `--jq`50 already runs per page; don't add `--slurp`.51- PR/comment bodies: `--body-file file.md` or a quoted heredoc. Never inline52 `--body "..."` containing backticks.53- Field cheat-sheet: CI status on a PR = `statusCheckRollup` (pr view); steps54 live under `gh run view N --json jobs`; `gh search prs` fields ≠ `gh pr view` fields.55- gh has no `-C`; pass `-R owner/repo` to every command, or cd first.56- Branch rules live at `gh api 'repos/{owner}/{repo}/rulesets'` on modern repos;57 `/branches/main/protection` 404s unless classic protection is on AND you have58 admin ("Branch not protected" or plain "Not Found" both mean check rulesets;59 neither is a path error).60- Branch drift: `gh api 'repos/{owner}/{repo}/compare/BASE...HEAD' --jq '{ahead_by,behind_by}'`61- jq beyond one line: write the program to a file and `jq -f prog.jq`; inline62 zsh quoting breaks.63- Don't sleep-poll runs or checks; `gh run watch ID` and64 `gh pr checks N --watch --fail-fast` exist; let the harness background them.
davesnx