All posts

From GitHub issue to verified pull request: a handoff checklist

Scope an issue, name the acceptance evidence and review the resulting pull request while retaining merge ownership.

· CodePress

A good issue-to-PR handoff names observable behavior, repository context, non-goals and the evidence needed to judge completion. Choose a bounded task, establish its baseline and ask for a reviewable PR that identifies checks and unresolved limits. Opening the PR is one step; a human still owns the decision to accept and merge the change.

GitHub's task kickoff guide documents starting Copilot work from an issue or prompt and bringing changes to a PR. Its UI, account eligibility and environment choices belong to GitHub's offering. Use the handoff principles below across tools, and check the selected product's current prerequisites before trying its specific controls.

1. Pick a task with a knowable finish

Choose something important enough to exercise the real application, but narrow enough that another engineer can state what “working” means. A reproducible validation defect is a useful candidate. “Improve onboarding” needs a product decision before it becomes a reliable implementation assignment.

Record the repository, intended base branch and baseline revision. Reproduce the existing behavior or explain why you cannot. Note relevant failures already present at that baseline. Without this distinction, the implementer may spend the task repairing an unrelated environment problem, or attribute an old failure to the new code.

2. Write the issue as a completion contract

Hypothetical issue template: this fictional profile-form defect is an example to adapt, not a task that was assigned or run. Paths are illustrative; replace them with the actual repository locations after checking its documentation.

Title: Explain a blank display-name rejection
Repository/base: identify repo and base branch
Baseline: record full commit before work
Trigger: enter spaces in Profile > Display name
Before: Save gives no visible explanation
After: inline message explains the invalid value
Acceptance:
- Empty and whitespace-only names show the message
- Existing form values remain available for correction
- A valid name still saves and survives reload
- Keyboard users can find the validation feedback
Context: form docs and existing error pattern
Candidate paths: profile form and validation tests
Permissions: test data; branch and PR creation
Non-goals: redesign, auth changes, deployment
Evidence: relevant tests, browser check, tested commit
Reviewer: name the review and merge owner

Agree on message wording if it is part of the requirement. Define whether validation occurs before submission or after a server response using the existing form contract. Specify the affected roles and how a test account reaches the form. These details prevent an implementer from silently choosing a different product behavior.

Add constraints that affect the design: existing validation helpers, localization, accessibility patterns or API compatibility. Point to the authoritative docs. Avoid prescribing a new library unless that decision is deliberate; a small message change should not acquire an unexplained dependency or a broader rewrite.

3. Check access and environment prerequisites

  • Confirm the integration can access the intended repository and base branch, with authority for the requested branch and PR actions.
  • Identify the supported runtime, dependency installation, required services and existing instructions for starting the application.
  • Provide a permitted synthetic fixture and test account. Name required secrets without placing their values in the issue or evidence.
  • State which external actions require separate approval. This form task does not need production data, a deployment or a live customer submission.
  • Choose the task record for follow-up instructions and designate who resolves scope questions.

Check how the chosen integration receives later context. For example, GitHub's kickoff documentation says issue assignment takes the existing issue content and comments, and directs later updates to the PR. Do not assume every integration watches every subsequent message.

4. Follow the artifacts through implementation and QA

Ask the implementer to summarize the changed behavior and explain any expansion of scope. Inspect the diff before relying on the result. Then compare the evidence against the issue's acceptance criteria using a matching checklist.

PR requirement Evidence to request for the hypothetical form change
Traceable scope Issue reference, base and current head, changed paths and explanation.
Invalid input handled Test output for empty and whitespace-only names; actual command and revision.
Valid behavior preserved Successful save and reload check with a permitted fixture.
Usable feedback Browser interaction showing the message, preserved input and keyboard path.
Review and limits Findings, repairs, current-head rechecks and explicit unperformed checks.

Every entry above is a requested artifact, not a reported pass. Screenshots help inspect appearance; they do not prove persistence or keyboard behavior on their own. See how to select verification evidence for a fuller method. If review finds that the new message disappears immediately, carry the finding and expected recheck through the repair loop.

5. Resume from missing setup or evidence

A task that cannot start the application is blocked on setup. A task with an implementation but no relevant check has a verification gap. Keep the branch and useful investigation, record the missing prerequisite, name an owner and specify the next step. Do not convert either state into a successful outcome because a PR exists.

When work resumes, compare the current head with the tested revision and review intervening edits. Recheck affected criteria after a repair. Preserve earlier reports as history; do not relabel them as evidence for code they never exercised.

6. Keep completion and merge ownership explicit

The reviewer should be able to answer: did this solve the specified problem, what was actually verified, and what risk remains? A review-ready result may still need a wording decision, accessibility expertise or a release owner. Passing checks is evidence for that decision, not permission to deploy or merge.

CodePress's software factory overview describes taking understood engineering work through implementation, QA, review and repair to a PR with human merge control. For teams starting from existing agents, its CLI page describes commit-specific verification and an independent verdict before review. Those public descriptions do not establish that this illustrative issue was completed.

Use your completed issue contract to evaluate one bounded repository workflow. Judge the resulting PR against the agreed evidence, and keep the merge decision with the named owner.