// Use when reviewing, triaging, or landing pull requests — especially batches of open PRs that need inspection, fixes, and merging. Also triages open issues after the PR queue is clear.
Use when preparing a Freshell release — before bumping versions, writing release notes, tagging, etc on GitHub.
Use when interacting with Freshell panes, panels, or tabs from the CLI for tmux-style automation and multi-pane workflows, outside external-browser automation tasks.
Use when installing, creating, or setting up Freshell extensions — from GitHub repos, local directories, or from scratch as custom panes.
Use when producing screen-recorded demos that need scenario-specific pane layouts, live interaction walkthroughs, and machine-readable timecodes for automated video editing.
Use when producing screen-recorded demos that need scenario-specific pane layouts, live interaction walkthroughs, and machine-readable timecodes for automated video editing.
| name | reviewing-prs |
| description | Use when reviewing, triaging, or landing pull requests — especially batches of open PRs that need inspection, fixes, and merging. Also triages open issues after the PR queue is clear. |
Systematic PR review workflow: assess, recommend, gate on user approval, fix issues, merge, and leave a signed comment. After the PR queue is clear, triage open issues. Uses a worktree for isolation, fresheyes for independent review, and processes PRs oldest-to-newest to minimize conflicts.
We never push work back onto contributors. Our goal is to harvest good ideas first, and code second. A PR with a great idea but rough implementation is more valuable than no PR at all — we take the idea, implement it properly ourselves, and give the contributor credit (in commit messages, PR comments, and closing notes). A PR with good code that we can merge directly is a bonus.
git worktree add .worktrees/pr-review --detach origin/main
gh pr listcd .worktrees/pr-review
git fetch origin && git switch --detach origin/main
gh pr checkout <N>
Always reset the worktree to latest origin/main before each PR.
git diff origin/main...HEAD
Read and understand every change before proceeding.
Start every PR review with this header (use gh pr view <N> to get details):
## PR #<N> — <title>
Submitted by <author>, <relative time>
<PR URL>
Then present to the user:
Do not proceed until the user explicitly approves. This is the most important step. The user decides whether to take the PR, not the reviewer.
What counts as approval: The user says words like "yes", "approve", "merge it", "go ahead", "LGTM", or "proceed" in direct response to the assessment. Nothing else counts.
What does NOT count: Ambiguous signals, instructions about other topics, general enthusiasm, or approval of a different action (e.g., "do it now" about a skill edit is not PR approval). When in doubt, ask.
Run build and fresheyes simultaneously:
go build ./... (or the project's equivalent)Review the changes between main and this branch using git diff origin/main...HEAD.Present build, test, and fresheyes results to the user. Include:
Do not merge or fix until the user approves. The user may want to reject, request changes, discuss findings, or fix things themselves. This is the second hard gate.
Address all fresheyes findings and test failures before merging:
Prefer GitHub merge:
gh pr merge <N> --merge
If GitHub's merge state is stale (common after rebase/force-push):
refresh the PR branch on origin/main, force-push it with --force-with-lease, and use GitHub merge after the merge state updates. Do not merge locally into main or push main directly.
If conflicts exist: rebase the PR branch on origin/main, resolve, rebuild, retest, force-push with --force-with-lease, then merge through GitHub.
Leave an effusive comment summarizing:
— Codex CLIgh pr comment <N> --body "..."
Then ensure the PR is closed:
# Check if still open; close if needed
gh pr view <N> --json state -q '.state' | grep -q OPEN && gh pr close <N>
Once all PRs are landed and there is no unfinished work, clean up:
# Remove the pr-review worktree
git worktree remove .worktrees/pr-review
Only do this when the PR queue is empty and all merges succeeded. If there is any unfinished work, leave the worktree in place.
Once all PRs are processed (or if there were none), check for open issues:
gh issue list --state open
If there are no open issues, report that the issue queue is clear and proceed to teardown.
If there are open issues, process them newest-first, one at a time, using the same assess-then-gate pattern as PRs.
gh issue view <N>
Read the full issue body, comments, and labels. Understand the problem or request before assessing.
Start every issue review with this header:
## Issue #<N> — <title>
Opened by <author>, <relative time>
<Issue URL>
Labels: <labels or "none">
Then present to the user:
Do not take action until the user explicitly approves. The same approval rules apply as for PRs — only explicit words like "yes", "fix it", "close it", "skip", or "next" count. Ambiguity means ask.
The user may respond with:
— Codex CLIorigin/main.— Codex CLIgh issue close <N> --comment "..."
Always sign the comment — Codex CLI.
| Step | Command / Action | Blocks on |
|---|---|---|
| Checkout | gh pr checkout <N> | — |
| Diff | git diff origin/main...HEAD | — |
| Assess | Summary, pros/cons, recommendation | User approval (Gate 1) |
| Build | go build ./... | — |
| Fresheyes | fresheyes skill | — |
| Tests | go test ./... (targeted) | — |
| Present results | Build/test/fresheyes summary | User approval (Gate 2) |
| Fix | Commit + show diff + get approval before push | Build + tests green |
| Merge | gh pr merge | All fixes landed + user says merge |
| Comment + Close | gh pr comment + gh pr close if still open | Merge complete |
| Reset | git checkout --detach origin/main | Before next PR |
| Teardown | git worktree remove .worktrees/pr-review | Queue empty, all landed |
| Issue list | gh issue list --state open | PRs done (or none) |
| Issue read | gh issue view <N> | — |
| Issue assess | Summary, status, scope, recommendation | User approval |
| Issue fix | Branch, implement, build, test, show diff | User says "fix it" |
| Issue close | gh issue close <N> --comment | User says "close it" |
If you catch yourself thinking any of these, you are about to violate a gate:
| Thought | Reality |
|---|---|
| "The user said 'do it' so that's approval" | Was it a direct response to your assessment? If not, it's not approval. Ask. |
| "Everything passed, obviously I should merge" | Green build ≠ merge approval. Present results and wait for Gate 2. |
| "The user said to fix things, so I'll push too" | "Fix" ≠ "push to main." Show the diff, ask before pushing. |
| "I'll just merge quickly and move on" | Speed is not a goal. Consent is. |
| "The user seems impatient, I should go faster" | Impatience is not approval. Ambiguity means ask. |
| Mistake | Fix |
|---|---|
| Proceeding without user approval | There are TWO hard gates. Always wait at both. |
| Treating ambiguous signals as approval | Only explicit approval words count. When in doubt, ask. |
| Merging after build+fresheyes without asking | Gate 2 requires presenting results and waiting for go/no-go. |
| Pushing fixes without showing diff | Show the diff first. Get approval before any push to the PR branch. |
| Merging with fresheyes FAILED | Fix all findings first. Never merge a failed review. |
| Forgetting to update worktree between PRs | Stale base causes unnecessary conflicts. Always reset to origin/main. |
Pushing directly to main | main mirrors origin/main. Use PR branches and GitHub merge. |
| Signing comment as "Codex" or "Claude" | Always sign as — Codex CLI. |
| Processing PRs newest-first | Oldest-first minimizes cascading conflicts since earlier PRs often touch files later ones depend on. |
| Processing issues oldest-first | Issue triage is newest-first so the most recent reports and follow-ups are evaluated first. |