GitHub Issue To PR

Execute a reliable issue-implementation workflow for repositories hosted on GitHub using gh and git.

Required Inputs

• owner/repo (upstream repository)
• issue_number
• Local parent directory for clones

Workflow

1. Verify environment and read issue context.
2. Reuse the current checkout when already in the target repository; otherwise clone or fork only when needed based on upstream push access.
3. Create an issue-specific branch.
4. Implement changes and run relevant checks.
5. Commit local changes.
6. Run $code-review on the branch diff and address material findings.
7. Push branch to origin.
8. Open a PR with issue linkage.

Step 1: Verify and Load Context

Run:

gh auth status
gh issue view <issue_number> --repo <owner/repo> --json number,title,body,labels,assignees,url

Parse acceptance criteria, constraints, and edge cases from the issue before coding.

Step 2: Clone and Conditionally Fork

Detect current GitHub login, whether the authenticated user can push to the upstream repository, and whether the current working directory is already a checkout for the target repository:

gh auth status
gh api user -q .login
gh api repos/<owner>/<repo> -q '.permissions.push'
git rev-parse --show-toplevel
git remote get-url origin
git remote get-url upstream

If the current working directory is already the target checkout, stay in that repository and skip clone/fork. Treat either of these as an existing target checkout:

• origin points to <owner>/<repo>
• upstream points to <owner>/<repo> (for an existing fork checkout)

If git rev-parse or the remote checks fail, treat the current working directory as not already being the target checkout.

If the current working directory is not already the target checkout and .permissions.push is true, clone the upstream repository directly even when <owner> is different from current login:

cd <parent_dir>
gh repo clone <owner/repo>
cd <repo_name>

Use origin as the base remote for fetch/rebase/push/PR head.

If the current working directory is not already the target checkout and .permissions.push is false, fork first:

cd <parent_dir>
gh repo fork <owner/repo> --clone --remote=true
cd <repo_name>

In fork mode, ensure:

• origin -> personal fork
• upstream -> original <owner/repo>

If upstream is missing in fork mode:

git remote add upstream https://github.com/<owner/repo>.git

Step 3: Create Branch

Detect default branch:

gh repo view <owner/repo> --json defaultBranchRef -q .defaultBranchRef.name

If running in fork mode, branch from latest upstream/<default_branch>:

git fetch upstream
git checkout -B <default_branch> upstream/<default_branch>
git checkout -b issue-<issue_number>-<short-slug>

If running with direct push access to upstream, branch from latest origin/<default_branch>:

git fetch origin
git checkout -B <default_branch> origin/<default_branch>
git checkout -b issue-<issue_number>-<short-slug>

Step 4: Implement Issue

• Keep scope strictly aligned with issue requirements.
• Avoid unrelated refactors unless required to complete the issue.
• Add or update tests for behavior changes.
• Run project checks (lint/test/build) relevant to changed code.

Capture key verification results for PR description.

Step 5: Commit Locally

Use clear, issue-linked commits:

git add -A
git commit -m "Fix #<issue_number>: <short summary>"

If there are multiple logical changes, split into separate commits.

Step 6: Run $code-review Before PR

Invoke $code-review on the diff between <default_branch> and issue-<issue_number>-<short-slug>.

Review expectations:

• Report findings with severity and file/line evidence.
• Treat P0 and P1 findings as blockers.
• Resolve blocker findings and rerun relevant checks.
• For unresolved P2/P3, document rationale in the PR body.

Step 7: Push Branch

Push only after local checks and blocker review findings are resolved:

git push -u origin issue-<issue_number>-<short-slug>

Step 8: Create Pull Request

If running in fork mode, open PR from <your-github-login>:issue-... to upstream:

gh pr create \
  --repo <owner/repo> \
  --head <your-github-login>:issue-<issue_number>-<short-slug> \
  --base <default_branch> \
  --title "Fix #<issue_number>: <short summary>" \
  --body "<problem/solution/testing summary>"

If running with direct push access to upstream, open PR from branch in the same repository:

gh pr create \
  --repo <owner/repo> \
  --head issue-<issue_number>-<short-slug> \
  --base <default_branch> \
  --title "Fix #<issue_number>: <short summary>" \
  --body "<problem/solution/testing summary>"

PR body must include:

• Issue link and closing keyword (Closes #<issue_number>)
• Summary of what changed
• Testing/validation performed
• $code-review summary (blockers fixed, remaining risks if any)
• Known limitations or follow-ups (if any)

Failure Handling

• Missing permissions to fork/push: report exact gh/git error and stop.
• Issue lacks clear acceptance criteria: summarize ambiguity and request clarification before implementation.
• Failing checks: do not create PR until failures are addressed or explicitly documented and accepted.
• Unresolved $code-review blockers (P0/P1): do not create PR.

Output Contract

Return:

• Repo URL and fork URL (if fork was created)
• Branch name
• Commit SHA(s)
• PR URL
• Short test/check summary
• $code-review outcome summary (fixed blockers + any accepted residual risks)