gh-issue-pr-flow

GH Issue PR Flow

Purpose

Use GitHub issues as the working brief for this repo. This skill covers four related jobs:

1. pick the right issue to work on
2. rewrite vague issues into proper issues, epics, and sub-issues
3. implement issue-backed work on a fresh branch from dev
4. choose single-PR vs stacked-PR shape
5. open and maintain clean PRs with good GitHub hygiene

Do not treat every issue as immediately buildable. First decide whether it is a good leaf issue, a parent issue, a research item, or something that should be rewritten before coding.

Critical rules

• Treat the issue body as the initial problem statement or prompt.
• Read the full issue body, labels, state, linked metadata, and comments before coding. Do not rely on gh issue view --comments alone when deciding scope.
• Prefer actionable leaf issues over epics. Epics are containers unless the user explicitly asks for backlog cleanup or epic design work.
• If the user says “pick an issue” or “work on something manageable”, use the project board and the issue-selection rules in references/issue-selection.md before choosing.
• If an issue is mushy, multi-part, or mixes discovery with implementation, rewrite or split it before coding.
• When rewriting an existing issue, preserve the user's original text at the bottom under ## Original issue text as a blockquote.
• New or rewritten issues should follow the writing rules in references/issue-writing.md.
• If PR or release work touches GitHub Actions, artifact uploads, or release packaging, check references/actions-artifact-retention.md so workflow changes match the repo's storage policy.
• Start new work from fresh dev. For single PRs, create a normal branch from dev; for stacked work, initialize the stack with --base dev.
• Open PRs back into dev, not main, unless the user explicitly says otherwise. In stacked mode, the bottom PR ultimately targets dev and upper PRs target the layer below.
• If the issue asks for discussion first or is clearly not actionable yet, stop and explain instead of forcing implementation.
• Choose the PR shape deliberately: small related changes should usually become layers in a stack; big unrelated features should be separate PRs or separate stacks; GitHub epics usually become a stacked PR series rather than one giant PR.
• Use the gh-stack skill as the operating manual when stacked PR mode is selected; this skill owns the issue/PR policy and stack-vs-single decision.
• Only use auto-closing keywords such as Closes #123 for issues that are fully resolved by the PR. Use Refs #123 for anything partial. In stacked mode, use Refs on intermediate layers and reserve Closes for the layer/PR whose merge completes the issue.
• Before opening or updating a PR, update docs/changelog.md unless the PR is genuinely changelog-free. Err on the side of including user-visible fixes, dependency updates, packaging/release changes, website changes, and workflow changes. The changelog is optimistic: the top section is the current dev release and normally stays one version above latest stable.

When to use

• The user gives issue numbers like #123 or 123.
• The user sends issue or PR links.
• The user sends the GitHub project link or asks what should be worked on next.
• The user asks you to pick a manageable issue.
• The user asks you to rewrite, relabel, split, or organize issues.
• The user asks to create an issue from the current conversation.
• The user asks to open, update, or finish a PR with gh.
• The user asks to check or act on Codex review feedback.

Do not use when

• The task is explicitly local-only and not tied to GitHub.
• The issue is really a discussion starter, discovery task, or wishful idea that cannot be implemented yet.
• The request would need destructive repo actions beyond the normal branch and PR flow without explicit confirmation.
• The user wants a broad product strategy conversation with no intent to track or implement work yet.

Inputs expected

Required

• An issue number, issue URL, PR URL, project URL, or explicit request to create or rewrite issues.

Optional

• Related issues to close or reference.
• A preferred branch name or PR title.
• Review findings from the user's /review command.
• Existing Codex review comments on the PR.
• A preference such as “pick something small”, “pick a P0”, or “just clean up the issues”.

Prerequisites

• gh is authenticated for this repo.
• The repo has an up-to-date dev branch locally and on origin.
• Use gh for issue and PR operations unless the user explicitly wants browser-only handling.
• If the user asks for project-board triage, gh must also have project scopes.
• This repository's working branch is dev; open PRs into dev unless the user explicitly says otherwise.

Workflow

1. Resolve the work mode

1. If the user is describing a problem that should become tracked work, create or rewrite issues first.
2. If the user gives an issue number or link, use the fuller JSON issue command first so the body, labels, state, and comments are all visible; then read everything relevant.
3. If the user gives a PR link, read the PR state, description, and comments before acting.
4. If the user asks what should be worked on next, inspect the project board and apply references/issue-selection.md.

Useful commands:

gh issue view <number-or-url> --comments --json number,title,state,body,comments,labels,assignees,projects,milestone,url
gh pr view <number-or-url> --comments
gh project item-list 3 --owner IgorWarzocha --limit 100 --format json

Avoid the shorter gh issue view <number> --comments as the first read: it can make you skim comments/output and miss issue metadata or body details needed for triage.

2. Triage before coding

1. Decide whether the work item is a leaf issue, epic, research item, or rewrite candidate.
2. If the user asked you to pick something, prefer Ready leaf issues, then apply priority and manageability rules from references/issue-selection.md.
3. If the issue explicitly calls for discussion first, or is obviously not implementable yet, stop and tell the user why.
4. If the issue is partially actionable, state the shippable subset before starting.
5. If the issue should be split or rewritten first, do that before opening a coding branch.

3. Rewrite or create issues when needed

1. Use the templates and rules in references/issue-writing.md.
2. Assign the right issue type: epic, feature, bug, or research.
3. Add area and priority labels.
4. If rewriting an existing issue, keep the original text at the bottom under ## Original issue text.
5. If a parent-child structure is needed, create the children and link them.
6. Update project fields so the board stays meaningful:
   • Ready means real next work
   • Backlog means valid but not next
   • epics are usually containers, not active implementation cards

4. Choose PR shape, then branch from dev

1. Fetch remotes, switch to dev, and fast-forward from origin/dev.
2. Decide whether this work should be a single PR, a stacked PR series, or separate independent PRs/stacks.
3. Use single PR mode only for tiny self-contained leaf work where a stack would be empty ceremony.
4. Use stacked PR mode for small related changes that form one cohesive story with reviewable dependency layers. Treat most GitHub epics this way: split the epic into bottom-to-top PR layers instead of making one huge branch.
5. Use separate PRs/stacks for big features that can merge independently or belong to different product stories.

Decision tree:

Is this local-only or not issue-backed? → leave this skill.
Is the issue not actionable yet? → rewrite/split/research first.
Is it one tiny self-contained leaf change? → one normal PR from dev.
Is it small related changes or one cohesive feature/epic with dependent layers? → stacked PRs, base dev.
Are the parts big, independent, or unrelated? → separate PRs or separate stacks.
Would a stack only add ceremony? → one normal PR.

Useful commands for single PR mode:

git fetch origin
git switch dev
git pull --ff-only origin dev
git switch -c <branch-name>

Useful commands for stacked PR mode:

git fetch origin
git switch dev
git pull --ff-only origin dev
gh stack init --base dev -p issue-123 foundation
# commit foundation layer
gh stack add api
# commit next layer
gh stack add ui
# commit top layer
gh stack submit --auto

Branch naming should be issue-oriented and easy to trace. For stacks, prefer a shared prefix such as issue-123 with short layer suffixes.

5. Implement the work

1. Treat the issue as the brief.
2. Make the requested changes.
3. If the issue scope shifts materially, call that out before continuing.
4. If you discover the issue was not actually leaf-sized, stop and split or rewrite the backlog instead of quietly sprawling.

6. Run the review loop

1. When implementation is done, expect the user to run their internal /review command.
2. Fix the issues that review finds.
3. Repeat until the review comes back clean or the remaining tradeoffs are explicitly accepted.
4. If the user shares review findings in chat instead of rerunning the command, resolve them the same way.

6.5. Refresh the changelog before PR submission

1. Before opening or updating a PR, check whether docs/changelog.md needs a bullet.
2. Usually update it for user-visible changes, bug fixes, dependency updates, packaging/release changes, website changes, and workflow changes. Do not talk yourself out of a useful bullet just because the change feels small.
3. The changelog is optimistic: the top section is the current dev release and should normally be one version above latest stable. Add bullets to that existing top section unless the user is explicitly preparing a new release section.
4. Keep bullets short, concrete, and in Igor's voice: plain English, a little human, no corporate release-note sludge. See docs/AGENTS.md and the current top changelog section for tone.
5. Skip the changelog only for genuinely invisible changes such as tests-only edits, docs-only edits outside release notes, or internal cleanup with no practical user/release impact. If skipped, mention that in the PR body.

7. Open clean PRs with good hygiene

1. Push the branch or submit the stack if needed.
2. In single PR mode, create one PR targeting dev.
3. In stacked mode, create/update the stack with gh stack submit --auto; verify with gh stack view --json.
4. Write detailed PR bodies with:
   • a concise summary of the change
   • notable implementation details if they matter to reviewers
   • any validation or review loop summary worth preserving
   • whether docs/changelog.md was updated or why it was skipped
   • Closes #n for fully resolved issues
   • Refs #n for related but not fully closed issues
5. Prefer a squash-merge-ready PR description from the start.
6. If the PR changes Actions workflows, artifact uploads, or release triggers, validate it against references/actions-artifact-retention.md before opening or updating the PR.

Useful commands:

# single PR
git push -u origin <branch-name>
gh pr create --base dev --fill
gh pr edit <pr-number> --body-file <file>

# stacked PRs
gh stack submit --auto
gh stack view --json
# edit individual PR bodies with gh pr edit as needed

Stacked PR body guidance:

• Intermediate layers usually use Refs #n.
• The final/completing layer may use Closes #n if merging that layer resolves the issue.
• For epic stacks, child issue PRs can close their child issues; parent epics should usually be referenced until the full epic is complete.

8. Ask Codex for review

Post this exact PR comment after a normal PR is up:

@codex please review this PR and give me 10-20 issues if any. Categorize findings as required, recommended, or optional.

For stacked PRs, post this variant on each PR in the stack:

@codex please review this PR as one layer in a stacked PR series. Focus on this layer's diff and call out cross-layer issues only when they affect correctness. Categorize findings as required, recommended, or optional.

Useful command:

gh pr comment <pr-number-or-url> --body-file <review-request-file>

9. Triage Codex feedback on request

1. Do not wait by default after posting the Codex review request.
2. Return the PR link to the user once the PR and comment are up.
3. Only inspect new PR comments or review events when the user explicitly asks you to check feedback.

Useful command:

gh pr view <pr-number-or-url> --comments

10. Triage Codex feedback

1. Read all Codex findings.
2. Fix the ones that are clearly correct and immediately actionable.
3. Ignore or flag the ones that are weak, irrelevant, or based on a bad assumption.
4. After fixes, summarize which items were addressed and which were dismissed, with brief reasons for the dismissals.
5. If the fixes are meaningful, go through the review loop again before declaring the PR ready.

References

• references/issue-selection.md — how to choose manageable work and when to leave items alone
• references/issue-writing.md — how this repo wants issues, epics, labels, and original-text preservation handled
• references/actions-artifact-retention.md — how this repo wants GitHub Actions artifact retention, dev artifacts, PR packaging validation, and release uploads handled

Validation

• If the user asked for issue selection, the chosen issue is a manageable leaf issue rather than an epic or mushy umbrella issue.
• If the user asked for issue cleanup, the rewritten issues follow the house format and preserve original text.
• The issue or PR was fully read before action.
• New single-PR work started from a branch created off current dev; stacked work was initialized with --base dev.
• The PR targets dev explicitly, or the stack bottom ultimately targets dev with upper PRs targeting the layer below.
• The PR body clearly distinguishes Closes from Refs.
• The user's /review findings were addressed or explicitly called out.
• docs/changelog.md was updated for practical user/release-facing changes, or the PR body explains why it was skipped.
• If the flow touched GitHub Actions workflows, artifact retention and upload behavior still match references/actions-artifact-retention.md.
• Codex was asked for review; in stacked mode, each layer received the stack-aware review request.
• The PR link was returned to the user after posting the review request.
• Codex feedback was triaged instead of accepted blindly when the user asked for feedback handling.

Error handling

Error: issue is not actionable yet

Action: explain why, outline the blocker, and stop instead of opening a coding branch.

Error: user asked to “pick an issue” but nothing is clearly ready

Action: do not guess blindly. Return a short ranked shortlist and explain what makes each option manageable or blocked.

Error: issue is too broad, mushy, or mixed-purpose

Action: rewrite or split it first using references/issue-writing.md.

Error: dev is behind or diverged

Action: sync dev first. Do not branch from stale state.

Error: PR accidentally points to main

Action: correct the PR base to dev immediately.

Error: Codex does not reply yet

Action: only check when the user asks. If there is still no reply, report that clearly.

Error: Codex reports low-value issues

Action: do not churn on them. Fix the real ones, then note why the others were dismissed.

Output contract

The completed flow should leave:

• a clearly chosen or clearly rewritten issue when the request was about backlog triage
• an issue-backed implementation branch from dev, or a stack initialized with --base dev
• a PR targeting dev, or a stacked PR series whose bottom targets dev
• a detailed PR description with correct closing references
• a Codex review request comment on the PR
• the PR link returned to the user
• a short triage summary of which review findings were fixed and which were dismissed when feedback triage was requested

Examples

Example 1

User says: "Take care of #182."

Expected behaviour:

1. Read issue #182 and its comments.
2. Confirm it is actionable.
3. Branch from fresh dev.
4. Implement the change.
5. Work through the /review loop.
6. Open a PR to dev that closes #182.
7. Ask Codex for review and triage the response.

Example 2

User says: "Create an issue for this bug, then fix it."

Expected behaviour:

1. Create the issue from the conversation.
2. Write it as a proper issue rather than dumping raw chat text.
3. Read back the created issue as the working brief.
4. Branch from fresh dev.
5. Implement, review, open the PR, and continue the normal flow.

Example 3

User says: "Pick a manageable issue and work on it."

Expected behaviour:

1. Inspect the project board.
2. Prefer Ready leaf issues over epics and research items.
3. Choose a P0/P1 issue that is clearly actionable now.
4. Explain briefly why it was chosen.
5. Continue the normal implementation flow.

Example 4

User says: "These issues are a mess. Rewrite them into proper issues and sub-issues."

Expected behaviour:

1. Read the existing issues.
2. Split epics from leaf work.
3. Rewrite titles and bodies using the issue-writing reference.
4. Preserve the original text at the bottom of rewritten issues.
5. Update labels, parents, and project fields so the board makes sense.

Example 5

User says: "Check Codex feedback on this PR and handle the good points only."

Expected behaviour:

1. Read the PR comments and review state.
2. Separate actionable findings from weak ones.
3. Fix the worthwhile items.
4. Summarize what was fixed and what was dismissed.