GitHub Flow#

Convert plans, research, and implementation results into GitHub issues and PRs.

Topics#

TopicDescriptionGuideauth-scopegh CLI priority + account mapping + batch scope refresh + org-repo 404 checklistauth-scope.mdcommit-message-disciplineCommit message authoring, message update on amend, PUBLIC repo English enforcement, git operation type continuity, verb selection ( .md as source code)commit-message-discipline.mddependenciesManage native Issue Relationships (blocked-by/blocking) via addBlockedBy/removeBlockedBy GraphQL mutationsdependencies.mdepic-bundleBundle deferred review findings across multiple PRs into one Epic tracking issue (checklist + native sub-issues + epic label)epic-bundle.mdexpandDecide expand-vs-split when new findings emerge mid-work and update title/bodyexpand.mdidentity-authOwner-based gh account mapping for commit author identity + gh auth scope refresh + GH_TOKEN env fallback for org repo 404identity-auth.mdmergeCI success and AI review check then merge with commit cleanup, including pre-merge blockedBy verificationmerge.mdplan-to-issueConvert plan/research MD to GitHub issue body or commentsplan-to-issue.mdprCreate PR with structured body, test plan, and optional visual attachments. Every distinct PR number in an AskUserQuestion payload needs its own clickable URL — this is an authoring rule you apply yourself. resources/block-pr-url-gate.sh exists but is not currently registered in any hook config, so nothing enforces it at runtimepr.mdpublishPackage a working-tree change into its own branch + draft PR against a staging-base branch, watch CI, ready-transition, content-review ask, merge — the full repeated sequence in one topicpublish.mdpush-guardsBranch-change ask + push rejection ask + force-push CI status check + main/master push restriction + shared-branch direct-push restrictionpush-guards.mdregisterEvaluate duplicates and decide registration strategy (new issue vs comment vs sub-issue)register.mdreviewReview PR code and post structured review commentsreview.mdreview-applyApply deferred [REVIEW_FEEDBACK] items from fix_plan to code, update PR Summaryreview-apply.mdsanitizeHARD STOP scan for personal data before posting to PUBLIC repossanitize.mdupstream-issueRegister feature requests/bug reports on external open-source repos with duplicate check + draft + sanitizeupstream-issue.md

Topic Dependencies#

text

github-flow (issue/PR workflow)
  ├─→ plan-to-issue (issue body content)
  ├─→ epic-bundle (deferred findings across PRs → one Epic issue)
  │     ├─→ uses plan-to-issue (Epic body) + register (dup check) + dependencies (sub-issues)
  │     └─→ receives from: consolidate next step (auto-suggest when deferred findings accumulate)
  ├─→ register (evaluate duplicates and decide strategy)
  ├─→ pr (PR body content + visual attachments)
  ├─→ review (post structured review comments)
  ├─→ expand (mid-work scope expansion)
  ├─→ dependencies (Issue Relationships: blocked-by/blocking)
  │     └─→ used by merge step 5 (pre-merge blockedBy check)
  ├─→ merge (CI/Review/Test Plan/blockedBy verification → squash+merge)
  ├─→ review-apply (deferred [REVIEW_FEEDBACK] → code fix → Summary update)
  │     └─→ receives from: consolidate Step 7 (deferred registration)
  ├─→ sanitize (HARD STOP scan before posting to PUBLIC repos)
  └─→ upstream-issue (external repo feature request/bug report with duplicate check + draft + sanitize)

• dependencies → merge: dependencies adds blockedBy relationships. merge.md step 5 queries the same field to gate merge until predecessors are CLOSED
• plan-to-issue → dependencies: when a plan has frontmatter chain: declaring a sequential issue order, dependencies applies it to GitHub
• All topics → sanitize: any text published to PUBLIC repos (issue body, PR body, comments, review text) must pass sanitize HARD STOP first

Applicability#

This skill applies automatically when git remote get-url origin contains github.com. For non-GitHub remotes (GitLab, Bitbucket, etc.), this skill does not apply.

Core Rules#

1. Verification Plan Required#

Every issue body and PR body must include a verification/test plan section. This is shared with code-workflow's plan step.

2. No Internal Paths in Issues/PRs#

.ralph/docs/, .ralph/fix_plan.md, .omc/ and other internal working paths must never appear in GitHub issue body, comments, or PR body. These are local-only artifacts.

Instead of: "See .ralph/docs/generated/plan-180.md" Write: The actual content inline, or "See the implementation plan comment below"

3. Body vs Comment Selection#

Content TypeTargetReasonImplementation plan (confirmed)Issue body updateStable reference for the issueChecklist (impl/verify)Issue body updateTrackable via GitHub checkboxDiscussion items / open questionsIssue commentThreaded, time-stamped, doesn't clutter bodyProgress updatesIssue commentChronological recordReview feedback summaryIssue commentPreserves review history

4. Check for existing open PRs before starting repo-wide fix work (HARD STOP)#

Before starting work on a repo-wide or config-level problem (broken CI config, a stale/misconfigured file affecting many components, a systemic lint failure, etc.), run gh pr list -R <owner>/<repo> --state open and skim titles for the same problem. Someone (including a past session under your own account) may have already fixed it in an unmerged PR.

Why: independently re-deriving a fix that already exists in an open PR wastes the work, and — worse — if both land, the later one can silently supersede or conflict with the earlier one without either author knowing. Case: a claude-plugins CI-fix session spent significant work rebuilding release-please-config.json's packages list from scratch, unaware that PR #17 (same author, ~7 hours earlier) had already implemented the identical fix; PR #17 had to be closed as superseded once the duplication was discovered mid-review.

#Don'tDo1Jump straight into fixing a CI/config-level problem because it's clearly brokengh pr list --state open first — skim titles for the same file/problem area2Assume "I'd have noticed if this were already being worked on"Open PRs from earlier in the same day (even your own past sessions) are easy to miss without an explicit check3Only check open PRs when multiple sessions are known to be activeRun the check unconditionally before repo-wide fix work — it's a single gh pr list call