Open PR

Open PR

Overview

Open a pull request for VibeSys changes without losing user work. Keep the scope narrow, recover the intended reason for the change, use the repository PR template, and make verification explicit.

Workflow

1. Inspect state:

   • Run git status --short --branch.
   • Identify the current branch and upstream with git branch --show-current and git remote -v.
   • Review unstaged, staged, and untracked files before editing, staging, or committing.
   • Preserve unrelated user changes. Stage only files that belong to the requested PR.

2. Create or confirm a branch:

   • If already on an appropriate feature branch, stay on it.
   • If on main, master, or a generic branch, create a focused branch with the default Codex prefix: vic/<short-topic>.
   • Do not overwrite or reset a branch unless the user explicitly asks.

3. Understand the diff:

   • Use git diff --stat, git diff, and git diff --staged as needed.
   • Check whether generated-looking artifacts changed and verify they are intentional.
   • For prompt or skill changes, read the affected prompt/skill content as user-visible behavior.

4. Reflect on intent:

   • Gather PR motivation from the existing conversation, user request, issue links, commit history, changed files, tests, and any docs touched by the diff.
   • Treat intent as the most important part of the PR description. The Problem section should explain why the change exists, not merely restate which files changed.
   • Separate known intent from inference. If the reason, target user, review concern, issue linkage, rollout risk, or correctness contract is uncertain, ask the user for clarification before writing or opening the PR.
   • Ask concise questions for anything material that cannot be recovered from context unless the user explicitly asks not to be contacted.
   • Do not invent motivation to make the PR body sound complete. Use "not applicable" or a clear limitation only when the uncertainty is minor and does not change reviewer understanding.

5. Run the smallest relevant checks:

   • Prefer narrow tests first, then broaden only when the change crosses boundaries.
   • Common checks:

./scripts/format.sh
./scripts/check_format.sh
./scripts/check_lint.sh
uv run pytest path/to/test.py
uv run pytest -k keyword
uv run pytest

6. Commit intentionally:

   • Stage only the PR's files.
   • Re-run git diff --staged before committing.
   • Use a concise imperative commit subject.
   • If checks could not run, keep the commit message normal and explain the gap in the PR body.

7. Push:

   • Push the current branch to the default remote, normally origin.
   • Set upstream on first push: git push -u origin <branch>.

8. Open the PR:

   • Prefer the GitHub app/tooling when available; use gh pr create only as a fallback.
   • Default to a draft PR unless the user explicitly asks for a ready PR.
   • Target the repository's default base branch unless the user specifies another base.
   • Use .github/pull_request_template.md and fill every section.
   • Apply labels at creation (gh pr create --label ... or gh pr edit --add-label right after). Pick from the repository's existing labels (gh label list); do not create new ones. Every PR gets exactly one kind label:
     • bug when the Problem section describes existing incorrect behavior, or the closing issue is labeled bug.
     • enhancement for new capability, a new surface, new tooling, or a redesign.
     • refactor for a structural change with no intended behavior change.
     • documentation for docs-only diffs. Mirror the closing issue's area labels (area/*, workload/*, app/*, and similar) when the PR closes an issue that carries them.
   • When opening a dependent series, create every PR with its complete body, then register the series as a native GitHub stack as described below.
   • When the PR is a follow-up to someone else's merged or open PR (a more robust fix for the same bug, a refactor that makes that bug unrepresentable, or a hardening of its tests), notify the original author. Link the original PR in the Problem section and @-mention its author there, then post a short FYI comment on the original PR with gh pr comment <original> --body ... that mentions the author, links the follow-up, and says in one or two sentences why it is the more robust fix. Keep the tone informational; it is a courtesy, not a request for changes.

Native GitHub Stacks

Use a native GitHub stack when two or more PRs form a true dependency chain in the same repository. Keep the bottom PR based on the trunk and each later PR based on the preceding PR's head branch. Do not stack PRs merely because they are related or opened together.

1. Ensure the official extension is available. Install it when missing: gh extension install github/gh-stack.
2. Open each PR normally so its title, draft state, and repository-template body are deliberate and complete.
3. Link the open PRs in bottom-to-top order: gh stack link --base <trunk> <bottom-pr> <...> <top-pr>. Pass PR numbers or URLs. Omit --open unless the user requested ready PRs.
4. Verify each direct base with gh pr view <pr> --json number,baseRefName,headRefName,isDraft,state,url.
5. Verify remote stack membership with gh api repos/{owner}/{repo}/pulls/<pr> --jq '.stack', then inspect the reported stack using gh api repos/{owner}/{repo}/stacks/<stack-number> and confirm its trunk and exact bottom-to-top PR order. gh stack view reflects local tracking and is not sufficient verification after gh stack link.

For every intentionally independent PR opened alongside stacked work, target the trunk, do not pass it to gh stack link, and verify that its remote .stack value is null.