perkcord-pr-merge-ready

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

1. Create or switch to a fresh git worktree + branch.
2. Implement the change in small, testable slices.
3. Run the relevant local checks for the scope.
4. Open the PR.
5. 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.
6. 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
7. 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:

1. PR title and description.
2. Linked or clearly related issues.
3. Any other already-known product / architecture context relevant to the change.
4. The full diff for the PR, not just the latest comment target.
5. Every feedback surface:
   • review threads
   • PR issue comments
   • sticky AI summaries such as Greptile comments
6. 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

1. Classify feedback into valid, invalid, unclear, or deferred.
2. Bundle related valid items when it helps, but keep patches reviewable.
3. Implement fixes one by one or in logical batches.
4. Run the narrowest useful checks, then broader checks when appropriate.
5. If checks fail, loop back through implementation and validation before pushing.
6. Before each push, reply/react on addressed review comments and resolve those threads.
7. For invalid or deferred feedback, leave a concise reply with the reasoning instead of silently ignoring it.
8. If there was non-threaded review feedback that was handled, leave one concise acknowledgement comment when needed.
9. Push, watch checks, and reread the full current review/comment set because sticky summaries may have changed.
10. 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.