File Pr

File PR

MUST: the adversarial review runs before the PR is filed

Before filing, the branch diff has had an adversarial code quality review: the code-quality-review skill, dispatched to a reviewer context that did not write the code. If it has not run, run it now and act on its findings first.

Violating the letter of this gate is violating the spirit of it. The review exists to be run by someone who did not write the code; a session that reasons its way past it has produced the exact outcome the gate prevents.

Honor an explicit user waiver or superseding repository process. Otherwise the following cases do not require a new review:

• The branch changes no code. Documentation, comments, and config-only edits with no behavior change. Measured on the diff, not on how routine the work felt.
• The review already ran on this diff. It was dispatched, it came back, and its findings were acted on. Loading this skill is not a reason to run it a second time. Record its revision and dispositions; verify direct corrections. Material changes to behavior, design, or risk need focused independent follow-up. Repeat a full review only if subsequent work broadly invalidated it.

Nothing else is an exemption. Not a deadline, not a reviewer waiting, not a branch that has been open a long time, not the user asking for the PR directly. If the gate cannot be satisfied, say so and ask; do not file and mention it afterward.

What the exemptions are not

Red flags: stop and dispatch the review

• Reaching for a synonym of "trivial" to describe a diff that changes code.
• Counting your own pass over your own diff as the review.
• Counting an earlier review without checking whether later changes invalidate it.
• Treating urgency, a waiting reviewer, or a direct "open the PR" as a waiver.
• Filing as a draft to defer the gate.

Each of these means: dispatch the review, then file.

File a finished branch as a PR and see it through: a template-true body, gh pr create, then an autonomous tend loop that fixes red CI (via the fix-ci skill) and merge conflicts until the PR is green and mergeable, or reports precisely why it stopped.

When to use

The work on the current branch is ready for a PR and this session is authorized to push and open one. Missing authorization and missing access are different gaps. Finish local reviewable preparation, then report the exact delivery step needing permission or access; do not ask again for authority already given.

The two rules that make the body right

1. The body must stand alone. Reviewers arrive with no access to this session, so the summary and every field are derived from the branch diff and the ticket, never from "what we discussed this session."
2. The PR body belongs to the repo, not to this skill: follow its template, never replace it. If the repo ships a PR template, the body is that template filled in: its exact headings, order, checkboxes, and hidden <!-- markers -->, with additions only when governing instructions require them, such as a host attribution footer. The built-in skeleton below is a last resort for repos that have no template; never emit it, or its Summary / Ticket / Caveats headings, when a template exists.

Steps

Prepare

1. Detect branch and base. git branch --show-current; base defaults to main unless the repo says otherwise. Summarize the change from `git diff

2. Sync with the base before filing. Fetch the latest base. If the branch is behind and conflicts, merge the base into the branch and resolve. Mechanical conflicts (imports, adjacent edits, formatting) resolve confidently; a semantic collision, where both sides changed the same logic with different intent, stops the skill. Report it as a decision; do not guess. Never rebase published commits and never force-push.

3. Run focused local checks and required local gates. Discover what this repo gates a PR on rather than assuming a toolchain: read its CI workflow definitions, hook config, build/package script targets, and contributor docs. Run the fast static checks (format, lint, type-check) separately from the tests; they are usually the cheapest to fail: against the freshly-synced base. Run affected tests; full suites normally run in PR CI. A wider local run needs an explicit local gate or a specific unresolved integration risk, not merely the existence of a CI job. If any commit bypassed hooks (--no-verify), the formatter and linter never ran on it, establish their result manually unless unchanged relevant evidence already covers them. Fix in-scope failures before filing and disclose baseline issues. A PR opened on a known-red baseline wastes the tend loop's bounded attempts. Record the exact commands and results for the report.

4. Identify the ticket. Scan the branch name, commit messages, and any existing description for a ClickUp / Linear / Jira id or URL. Exactly one candidate → carry its full link (never synthesize a URL from a bare id). Multiple candidates → ask. None → proceed without and note the absence in the report, asking only if the repo's template has a required ticket field.

5. Find the repo's PR template (match filenames case-insensitively): .github/pull_request_template.md / .github/PULL_REQUEST_TEMPLATE.md, any file under .github/PULL_REQUEST_TEMPLATE/, and the same names in the repo root and under docs/. Multiple templates → pick the one matching the branch's intent and record why. Record the search outcome as found (path) or none-found-after-search before building anything; the fallback is allowed only after a recorded empty search.

6. Build the body. If a template was found, fill it verbatim with the same headings, order, every checkbox, comment markers preserved; map content into the fields it already has; tick [x] only what was actually verified; leave unfillable fields blank rather than fabricating. Before finalizing, check your headings against the template's: same set, same order, none added or renamed; if they differ, you replaced the template, redo the body. Required host attribution may follow the template without a new section. If there is no template, use the minimal fallback:

   Summary

   <what changed and why, grounded in the diff>

   Ticket

   <ticket link(s), or omit the section if none>

   Caveats / follow-ups

   <anything the reviewer should know; "none" if none>

7. Conform to enforced conventions. If the repo enforces PR-title or branch-name patterns (a title linter, commit-lint, a branch rule), discover the pattern from the linter / CI config and conform: don't guess a prefix that gets the PR rejected.

File

8. Push and open. Push the branch per the repo's conventions (pull first; use its push skill if it ships one), then gh pr create --base <base> --head <branch> with the title and body. Report the PR URL as soon as it exists: the tending continues after.

See it through

9. Watch to a verdict. Checks run through the fix-ci skill's loop; it owns the failing-log diagnosis, flake-vs-fault triage, minimal in-session fixes, the two-attempt cap, and the never-weaken-a-check rule. Watching always runs in a separate Opus agent on Claude or gpt-5.6-sol agent on Codex, never Astra/Fable or the parent; accept only results for the target SHA and required checks. Mergeability comes from gh pr view --json mergeable,mergeStateStatus.
10. If the base moves and conflicts appear, merge the base in again, resolve, and push: at most two re-syncs; a base that keeps moving is reported, not chased. Semantic collisions stop the loop here too.
11. Stop when the PR is green and mergeable, or when a cap is hit, and report either way.

Output

Verdict-first report:

• PR URL and end state: green and mergeable / still red / conflicted / blocked.
• Validation provenance: the discovered gate commands and each result, by kind (format / lint / type-check / tests); this lives in the report, and lands in the PR body only where the template has a testing/QA field for it.
• Ticket link, template used (path, or "none: fallback"), fixes applied (files + commits), attempts and re-syncs used.
• If stopped early: the diagnosis and the recommended next step.

Boundaries

• Files and tends the PR; never merges it, never enables auto-merge, never closes or re-targets it.
• Never force-pushes, rebases published commits, or rewrites history: conflict resolution is merge-based.
• Never deletes, skips, or weakens a failing check to get to green; a red check that encodes an intended-behavior question is reported as a decision for the user.
• Keep substantive PR text focused on the change. Include attribution required by governing host/user/repository instructions; do not invent extra footers.
• Hard caps: fix-ci's two fix attempts for CI, two base re-syncs for conflicts; after that, report rather than thrash.
• Semantic merge collisions and product decisions are never resolved by guessing. They end the loop with a plain report.