GitHub Flow
Convert plans, research, and implementation results into GitHub issues and PRs.
Topics
| Topic | Description | Guide |
|---|---|---|
| auth-scope | gh CLI priority + account mapping + batch scope refresh + org-repo 404 checklist | auth-scope.md |
| commit-message-discipline | Commit message authoring, message update on amend, PUBLIC repo English enforcement, git operation type continuity, verb selection (.md as source code) |
commit-message-discipline.md |
| dependencies | Manage native Issue Relationships (blocked-by/blocking) via addBlockedBy/removeBlockedBy GraphQL mutations | dependencies.md |
| epic-bundle | Bundle deferred review findings across multiple PRs into one Epic tracking issue (checklist + native sub-issues + epic label) | epic-bundle.md |
| expand | Decide expand-vs-split when new findings emerge mid-work and update title/body | expand.md |
| identity-auth | Owner-based gh account mapping for commit author identity + gh auth scope refresh + GH_TOKEN env fallback for org repo 404 | identity-auth.md |
| merge | CI success and AI review check then merge with commit cleanup, including pre-merge blockedBy verification | merge.md |
| plan-to-issue | Convert plan/research MD to GitHub issue body or comments | plan-to-issue.md |
| pr | Create 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 runtime |
pr.md |
| publish | Package 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 topic | publish.md |
| push-guards | Branch-change ask + push rejection ask + force-push CI status check + main/master push restriction + shared-branch direct-push restriction | push-guards.md |
| register | Evaluate duplicates and decide registration strategy (new issue vs comment vs sub-issue) | register.md |
| review | Review PR code and post structured review comments | review.md |
| review-apply | Apply deferred [REVIEW_FEEDBACK] items from fix_plan to code, update PR Summary | review-apply.md |
| sanitize | HARD STOP scan for personal data before posting to PUBLIC repos | sanitize.md |
| upstream-issue | Register feature requests/bug reports on external open-source repos with duplicate check + draft + sanitize | upstream-issue.md |
Topic Dependencies
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 Type | Target | Reason |
|---|---|---|
| Implementation plan (confirmed) | Issue body update | Stable reference for the issue |
| Checklist (impl/verify) | Issue body update | Trackable via GitHub checkbox |
| Discussion items / open questions | Issue comment | Threaded, time-stamped, doesn't clutter body |
| Progress updates | Issue comment | Chronological record |
| Review feedback summary | Issue comment | Preserves 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't | Do |
|---|---|---|
| 1 | Jump straight into fixing a CI/config-level problem because it's clearly broken | gh pr list --state open first — skim titles for the same file/problem area |
| 2 | Assume "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 check |
| 3 | Only check open PRs when multiple sessions are known to be active | Run the check unconditionally before repo-wide fix work — it's a single gh pr list call |