open-pr

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Open PR

Create a PR that a reviewer can understand and start reviewing without
reconstructing the work from the branch. Finish with the PR open for review by
default.

Review-ready means the PR's scope and evidence support meaningful review, with
remaining limitations explicit and no review blockers. It does not mean every
hosted check has settled or the branch has earned a current-head acceptance
verdict. `$babysit-pr` owns full-branch review, repeated repair coverage,
review feedback, hosted-check
convergence, and the final `READY`, `NOT READY`, or `INCONCLUSIVE` verdict.

Read and follow the [GitHub transport contract](../jesus-mode/references/codex-compatibility.md#github-transport) for every PR operation.

## Authorization

An explicit invocation of `$open-pr`, or a direct request to make, create, open,
update, or prepare a PR, authorizes commits, a non-force push to the intended
branch, creating or updating that PR, and marking it ready for review, including
a draft from an earlier workflow. Honor an explicit request to keep the PR in
draft or limit the task to a narrower edit. Existing draft state alone does not
require another user prompt to open it for review. Automatic model selection
does not grant publishing authority. Keep force pushes, remote history rewrites,
retargeting, public comments, review-thread actions, closing, and merging behind
separate user authorization.

## Review blockers

Keep the PR in draft for a known required-check failure, an unmet explicit
verification requirement, or an evidence gap that prevents assessing a material
behavior or usability claim. Name the requirement or claim each blocker affects.
A missing screenshot blocks only when explicitly required or needed to
substantiate a material claim. If an optional capture or upload fails, omit the
image and disclose the limitation when the remaining evidence suffices.
Additional captures and presentation polish do not block meaningful review.

Repository and linked-issue acceptance requirements remain binding, including
specified native journeys. Record any user-approved alternative evidence or
scope change in the PR. Reporting a required journey as unverified does not
waive it, and this skill's evidence flexibility does not authorize that change.

## Workflow

1. Resolve the repository, base branch, head branch, linked issue, worktree
   state, and any existing PR. Preserve unrelated work.
2. Inspect the complete intended diff against the base once as a bounded PR
   preflight. Include staged and unstaged work plus enough surrounding code to
   confirm the scope, describe it accurately, remove accidental churn, and fix
   clear in-scope problems. This is preparation, not an exhaustive review loop.
3. Run the checks required by the change, repository, and linked issue. Verify
   the behavior on the most faithful practical surface.
4. Gather direct evidence for every material claim in the PR. Use the evidence
   rules below. Reuse evidence collected during implementation after confirming
   it still covers the prepared change. Collect missing or stale evidence needed
   to close a review blocker. If a before image is needed, reproduce the base in
   an isolated checkout when practical or use the labeled historical baseline
   described below. Narrow or remove unsupported claims and disclose remaining
   gaps; apply the review-blocker criteria before deciding draft state.
5. Commit coherent implementation units using repository conventions. Apply
   the evidence storage rules below before staging artifacts. Reuse current
   review results when they already exist, but do not
   start or extend a model-review coverage chain solely to open the PR.
6. Push non-destructively to the intended head branch. Confirm the remote OID
   matches the prepared local OID.
7. Create or update the PR. Write the body from the prepared diff and collected
   evidence, including the [model contributions](#model-contributions) record,
   not from memory or the commit titles alone. Create new PRs ready
   for review unless the user requested a draft or a review blocker remains.
8. Read the remote PR back through the CLI or GitHub plugin. Confirm its head SHA
   matches the prepared local head and its title, body, and links are correct.
   Verify native screenshot attachments and inline image rendering through the
   GitHub transport contract. Fix leftover local paths, repository-image targets,
   and link-only substitutes for required screenshots before calling the PR
   review-ready.
9. For any remaining draft, run `gh pr ready` or the GitHub plugin equivalent
   after every review-blocking evidence gap is closed, unless the user requested
   draft state or a narrower edit. Pending hosted checks do not block this
   transition, but a known required-check failure on the current head does. Read
   the PR back and confirm the same head is now open for review.
10. Return the PR URL, head SHA, verification and artifact summary, current check
    state, and any evidence gaps. Begin `$babysit-pr` only when the user
    explicitly asked to babysit, shepherd, or finish the PR. If Babysit is
    already active, return to that run.

Keep this workflow bounded. Use focused verification after any preflight fix,
then finish the PR presentation. Repeated model review, repair-delta review,
review-thread triage, and waiting for checks to converge belong to
`$babysit-pr`.

## PR body contract

Use these sections:

```markdown
## What
<The behavior or result that changed.>

## How
<The implementation approach and important design choices.>

## Why
<The problem, constraint, or decision that motivated the change.>

## Evidence
<Direct proof for the claims above.>

## Model contributions

| Role | Model | Scope and result |
| --- | --- | --- |
| Implementation | <model> | <Changes authored, including repairs.> |
| Review | <model> | <Review type, covered revision or range, and result.> |
| QA | <model> | <User journeys exercised, revision or build, and result.> |
| Verification | <model> | <Tests or checks run, covered revision, and result.> |
| PR preparation | <model> | <PR creation or description update.> |
```

Add risks, rollout notes, or reviewer guidance when they help. Keep the five

From gutierrezje/jstack, MIT.

More from gutierrezje/jstack