| name | perkcord-pr-merge-ready |
| description | Keep Perkcord PR work running until CI, review feedback, and manual preview needs are fully closed. |
| compatibility | opencode |
| metadata | {"audience":"maintainers","domain":"delivery"} |
Purpose
Perkcord PR tasks are not complete when the PR exists. They are complete when the branch is merge-ready.
Use this skill for any task that involves a branch, PR, CI, Greptile feedback, or preview deployment.
Default loop
- Create or switch to a fresh git worktree + branch.
- Implement the change in small, testable slices.
- Run the relevant local checks for the scope.
- Open the PR.
- Start the review / recycler loop:
- Prefer toolbox PR-watch tooling when available.
- Subscribe the implementing session in
act mode.
- Set the gate to require relevant reviewers, green checks, and handled acks.
- If the tooling is unavailable, emulate the same loop manually with GitHub + Greptile polling.
- Treat this whole review/check/watch cycle as part of the task, not optional follow-up.
- For every accepted review item:
- apply the smallest safe patch
- rerun the relevant checks
- react and/or reply on GitHub
- resolve the addressed thread before the next push
- Do not return to the user until one of these is true:
- the PR is merge-ready
- a real blocker needs user input
Review packet
Before acting on AI or human PR feedback, gather the whole packet in this order:
- PR title and description.
- Linked or clearly related issues.
- Any other already-known product / architecture context relevant to the change.
- The full diff for the PR, not just the latest comment target.
- Every feedback surface:
- review threads
- PR issue comments
- sticky AI summaries such as Greptile comments
- Current mergeability signals:
- required checks and their latest conclusions
- stale failed runs that may need rerun vs true current failures
- branch out-of-date / merge-conflict state against
main
- any GitHub UI merge blockers beyond tests (draft state, approvals, unresolved threads, etc.)
If the same packet is needed repeatedly, prefer investing in a deterministic script, command, or shared toolbox skill instead of manually reconstructing it every time.
Feedback triage
- Enumerate all incoming feedback, even low-priority or incidental notes.
- Evaluate every item critically. AI review comments are inputs, not truth.
- Treat low-confidence AI summaries as non-authoritative by default. If an automated reviewer reports below full confidence, do not treat the PR as merge-ready until the underlying concerns are checked manually.
- Score each suggestion against its complexity cost before accepting it: new helpers, abstractions, config, branching, and tests all need a concrete payoff.
- Prefer a systemic fix when several comments point at the same root cause; prefer the smallest local fix when the issue is isolated.
- Use repo search, docs, web research, Context7, and exploration tools when needed to judge whether feedback is valid.
- Ask the user a question only when the decision is truly blocked and cannot be resolved from product direction or repository context.
- Prefer implementation in the main working session; use subagents for exploration/research, not for the actual code changes.
Recycler execution loop
- Classify feedback into valid, invalid, unclear, or deferred.
- Bundle related valid items when it helps, but keep patches reviewable.
- Implement fixes one by one or in logical batches.
- Run the narrowest useful checks, then broader checks when appropriate.
- If checks fail, loop back through implementation and validation before pushing.
- Before each push, reply/react on addressed review comments and resolve those threads.
- For invalid or deferred feedback, leave a concise reply with the reasoning instead of silently ignoring it.
- If there was non-threaded review feedback that was handled, leave one concise acknowledgement comment when needed.
- Push, watch checks, and reread the full current review/comment set because sticky summaries may have changed.
- If a check failure looks stale or contradictory, confirm the failing run/job head SHA before deciding whether to fix code, rerun checks, or treat it as obsolete.
Merge-ready bar
A PR is merge-ready only when all of the following are true:
- required CI is green for the current head
- Greptile / other requested automated reviewers have reported, or there is durable evidence they did not run
- there are no stale red checks, outdated merge conflicts, or unresolved merge blockers in the GitHub UI for the current head
- all valid feedback is addressed
- addressed review threads have a reply/reaction and are resolved
- any required preview deployment has been refreshed and shared
- the latest sticky AI summary has been reread after the most recent push
Manual preview policy
PR branches do not auto-deploy to Vercel.
When a preview is needed, trigger it from the PR with either of these comments:
@perkcord preview/vercel-preview
Then capture the returned preview URL in the PR thread and use that deployment for UI review.
Notes
- Fresh-reviewer / recycler behavior is preferred over ending the task right after PR creation.
- If the toolbox repo is present, read
../basics-agentic-dogfooding/docs/opencode/pr-review-watch.md and ../basics-agentic-dogfooding/docs/opencode/supervisor-loop.md.
- When the user says a task should "iterate until merge ready," interpret that as an instruction to run this full loop automatically: watch checks, inspect merge blockers, fix valid CI/review issues, reply and resolve addressed comments before every push, and keep going until the PR is actually merge-ready rather than merely code-complete.
