gh-issue-pr-flow

name	gh-issue-pr-flow
description	Runs this repository's GitHub issue, branch, PR, Changesets, release, and review workflow. Use when filing or implementing issues, preparing package changes, opening or updating PRs, or handling review feedback.

GitHub Issue and PR Flow

Use this repository-specific workflow instead of the generic fallback. Explicit user direction and AGENTS.md still take precedence.

Operating rules

• Use gh for GitHub operations.
• Read the relevant issue, PR, comments, reviews, repository instructions, and current implementation before acting.
• Inspect the working tree, current branch, upstream, origin/main, and intended PR base before branch or history operations.
• Keep unrelated local changes out of the work. Proceed around them when safe; ask only when they block the requested result.
• Infer ordinary workflow details. Ask only when ambiguity would change scope, target a surprising base, rewrite shared history, or produce an unintended external result.
• Treat implied workflow actions as authorized: “open a PR” includes focused branch creation, commit, push, and PR creation; “update this PR” includes committing and pushing in-scope fixes.
• Do not create unrelated GitHub side effects. Filing an issue does not authorize implementation.
• Never use plain --force. Use --force-with-lease only for a branch whose rewrite is clearly intended and safe.

Route the request

File or update an issue

1. Turn the request into a concrete title, context, scope, and completion conditions.
2. Check templates and likely duplicates when useful.
3. Apply labels, projects, milestones, or assignees only when repository policy or the user establishes them.
4. Create or update the issue, return its link, and stop unless implementation was also requested.

Implement work and open a PR

1. Establish a clean focused branch from current main, unless the current branch is already dedicated to the work.
2. Implement only the agreed scope and run validation chosen from the changed surface.
3. For shipped package work, read references/release-and-repository-hygiene.md before finalizing release artifacts.
4. Review the diff and branch history, stage only intended files, and commit the completed result.
5. Push and open the PR against main; return the link.

Open or update a PR for existing work

1. Inspect the intended diff, commit history, base, and any existing PR.
2. Repair stale or mixed history before presenting it. Do not launder already-merged commits into a new PR.
3. Revalidate the changed surface, push, and create or update the PR.
4. Update the body when scope, validation, issue linkage, risk, or follow-up information changed materially.

Handle review feedback

1. Read all feedback and current code; verify each finding against the PR goal and repository rules.
2. Fix required findings unless factually wrong or out of scope. Apply recommended findings when clearly beneficial and in scope.
3. Avoid optional churn. Ask when a suggestion would materially change product behavior or agreed scope.
4. Revalidate, commit, push, and summarize what was fixed, rejected, or deferred and why.

Branch and history hygiene

• Fetch/prune before choosing a base or repairing history.
• Before using long-lived dev for a PR, reset it onto origin/main and cherry-pick only intended pending commits. Never merge main into dev.
• Do not stash, reset, overwrite, or include unrelated local changes merely for convenience.
• Do not amend or rewrite published shared history. If a push is rejected, inspect divergence before choosing rebase, reset, merge, or lease-protected force push.

GitHub writing

• Write issue and PR bodies for the next human: goal, material context, actual change, validation, and unresolved risk without routine command narration.
• Use Closes #123 only when the PR fully resolves the issue; otherwise use Refs #123.
• For multiline bodies and comments, write Markdown to a temporary file and pass --body-file. Do not pass shell strings containing \n.
• Follow repository templates, removing placeholders that do not apply.
• Do not invent labels, milestones, release history, or certainty unsupported by repository evidence.

Use this concise PR body when no more specific template applies:

## Summary
- ...

## Validation
- `...`

## Release
- Changeset: yes/no
- Packages: `@howaboua/...` or none
- Aggregates: generated by release automation

Codex review

When opening a PR, post the standard review request unless the user says not to. Do not repost it after every update.

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

Post it with --body-file.

Failure handling

• gh is unauthenticated: report the visible authentication or permission failure and the relevant login step.
• Base remains unclear: inspect remote defaults, current PR conventions, and repository instructions; ask before targeting a surprising branch.
• Unrelated work blocks branch operations: explain the exact collision and ask how to preserve it.
• History repair could affect another contributor: stop before reset, rebase, deletion, or force push.
• Review findings conflict: explain the evidence instead of mechanically satisfying every reviewer.

Finish

Return links for changed GitHub artifacts. Summarize the material result, relevant validation, branch or PR state, changed packages, and changeset status. Do not report successful sponsor checks or pad the result with routine hygiene narration.